[darcs-users] darcs patch: Edit Front Page (and 9 more)

[Stephen J. Turnbull]

Eric Kow writes:

 > ----------------------------------------------------------------------
 > Add Smart Patches page.
 > ----------------------------------------------------------------------
 > Ah OK, now we're starting to approach the bit I'm most interested in

Indeed.

I'm uncomfortable with the label "smart patches", it's too breezy and
marketroidy.  The patches aren't smart, Darcs is.  (If you want "smart
patches", you use the makepatch utility.)  And it's way too imprecise,
exactly where we want to emphasize precision and reliability.

 > > +<center>*Darcs will **always** find the smallest set of patches needed to
 > > +satisfy dependencies.*</center>
 > > +<center>*Darcs does not need to ask you what other patches it needs.*</center>

This is false.  Sometimes the set is *too small*.  That's what the
--ask-deps switch is about.

 > > +<center>*The idea of transforming patches (e.g. F to F')
 > > depending on context<br/> +is the key idea behind darcs' Smart
 > > Patches.*</center>

Regardless of you spell "theory of patches", the spelling of the
possessive of "Darcs" is "Darcs's".  The only "Darc" I know is
Ste. Jeanne.

 > Well, we used to use this to justify treating identical patches as
 > conflicts.  Now we no longer do this (in darcs-2-format repositories).
 > So we would still need other examples.  I guess our examples would
 > basically fit into three categories
 > 
 >  - cases where other systems doesn't get that a merge is doable
 >  - cases where other systems get the wrong result in merging
 >  - cases where other systems allow a merge to happen, which the
 >    should not...

Cases 3 and 4 do exist, but as I explain in my other post, they are
not very interesting at this point because superficially similar cases
where snapshot-based systems (like git) do it better than Darcs are
sure to exist, and (until Darcs understands the semantics of the texts
it stores) it will be a matter of personal preference and sense of
what a "perverse" project looks that determines which outcome is
preferred as default by users.

What would be marketing pluses here would be (a) if Darcs is able to
warn you about "dangerous" merges, and (b) the way that Darcs handles
"mv" and "darcs mv" differently, and therefore allows the user to
specify the semantics (in a way that git certainly cannot, since the
only way it recognizes renames is by checking the index of content
similarity -- "git mv a b" has no additional semantics beyond "mv a b;
git rm a; git add b", it does not create a "mv patch").

 > ----------------------------------------------------------------------
 > Add Path Theory Index page.
 > ----------------------------------------------------------------------
 > > +You don't need to know Patch Theory to use darcs. Patch Theory
 > > is just for geeks +who want to know the theory behind darcs
 > > amazing Smart Patches.
 > 
 > I understand the sentiment, not too sure about the phrasing.  Maybe
 > something more positive, like "want to know more?"

Indeed.  Again, I don't want to be amazed by my VCS.  Mostly, I don't
want to notice it all.

I also think that patch theory documentation should be left up to the
folks who do abstract algebra for fun and profit.  What we want on the
front page and anything linked from it is simply to drip with absolute
confidence that for any sane project Darcs will always do the right
thing, and remark that the reason for this confidence is a logically
rigorous mathematical theory.