Hi Eric,
I generally agree with all of your comments, so I won't reply to
everything you said. Some replies below:
Actually, the current configuration uses ReStructuredText...
(I still wonder what we're doing
about the mathy bits, but I'm sure somebody's got that worked out).
Whatever the merits of markdown or ReStructuredText might be, I think it
would be sensible to use the same format for the wiki and the manual.
No problem. I just need someone to show me how to do the math bits. It's
hard to explain patch theory without ^{-1}.
+ <td>How do you make a branch?</td>
+ <td><pre>cp -r dir1 dir2</pre></td>
darcs get is the preferred approach to this
Hmm... Even if my example is not the preferred method, it conveys the
nature of darcs branches very clearly.
I guess it would make sense nowadays to target SVN and git users
instead. One thing I remember seeing on the net once was somebody
complaining that he found git more intuitive than darcs. I'd be
curious to see why, or if it it was a matter of "it's intuitive
because I'm used to it"
Sure.
I can't imagine any good reason why git could be considered more
intuitive than darcs. Perhaps people are intimidated by 'Theory of
Patches'? Hard to say. It's probably something subconscious. People
might feel that to "understand darcs" they have to understand the Theory
of Patches, and because they don't understand the latter, then darcs is
not intuitive. I don't think anybody thinks this consciously, but I can
easily imagine that thought process happening in the background.
+Example 1: Your first merge
+===========================
+Suppose that we are working on a recipe for scrambled eggs. We have the file
+`recipe.txt`:
Nice example.
:-)
+<center>*The ability to turn B into B' reliably and predictably is the
core<br/>
+feature of darcs' Smart Patches*</center>
I especially like the word "predictably" here.
:-)
+Example 2: Where other SCMs fear to thread
+==========================================
Let's not get cocky
I understand. I'm open to suggestions. Without being cocky, I do want to
show an example of something that most SCMs get wrong and Darcs gets
right. I think it is hard to argue that Darcs' Theory of Patches has
value if we can't give an example of something it does better.
+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?"
"You don't need to know Patch Theory to use darcs. But if you are keen
to know the theory behind darcs, we'll be happy to tell you all about it".
+Remember matrices from school?
+==============================
+Did you learn matrix algebra in school? If you liked it, you can think of patch
+theory as being similar to matrix algebra. If you didn't like it, don't read
+this paragraph. :-)
I would phrase that very last bit differently. It's great that we've
got a friendly tone. I wonder if we can balance that with a sort of
professional coolness. Know what I'm getting at?
Absolutely. I have the fortune to have learnt writing from a really good
editor (while I was the lead of the OpenOffice user guide project). One
thing I learnt is that one has to be careful with humour in a technical
document. Not only does humour often translate poorly, but it can easily
distract the reader from the content of your message. So in general you
want to go for a friendly but professional tone.
Another thing which may be useful to convey is this idea that it doesn't
really matter what the primitive patches are. You could invent a whole
other revision control system, for example, for managing XML trees, and
the only thing you need change is what kinds of primitive patches you
support. Or maybe that would just confuse people.
At this early stage, I think it would confuse people. This is an
introductory page. But what you said could be included in a later, more
advanced page.
+Rules for patches
+=================
+**Theorem 1**: The inverse of the composition of two patches is given by
+$(AB)^{-1} = B^{-1}A^{-1}$
+
+**Exercise**: Prove theorem 1.
That's interesting. Do we want exercises in our reference
documentation? It depends on what we want the reference
documentation to be, I suppose!
It's certainly debatable. In the OpenOffice guide we didn't add
exercises. But it seemed useful in this case. The exercises I chose are
strategic. They all come in handy in the following page (Examples
Revisited).
I think over time we've established that it's a sort of notational best
practice to just use subscripts to represent commuted variants of
patches because over time the primes get messy and you also run out.
(X'''''). (Ah, but here you're using them for pieces of a megapatch).
Gah, making up notation is hard
It is indeed. A common solution to this problem is that after two primes
you use a superscript in round brackets (so it is distinguished from an
exponent). So you have:
X' -> X'' -> X^(3) -> X^(4) -> ...
+At this point all that is left to do is to define commutation for primitive
+patches. We do this by defining commutation for every pair of primitive
+*patch types* - for example, a `Hunk` and a `Hunk`, or a `Hunk` and a `Move`.
It does seem like a good idea to give an example of a commutation rule
indeed. It's important to me that we hammer home this idea that while
darcs patch theory is smart, for the most part, it is neither
complicated nor magical.
Yeah, that's what I was thinking.
Also, I
wonder if it would make sense to start with a Hunk and Move commutation,
as it's the most straightforward?
Perhaps. I chose Hunk-Hunk because I use it in the following page, and I
don't use Hunk-Move. But it could be an exercise instead. On the other
hand, you could argue that if Hunk-Hunk is tricky and is needed in the
next page, then perhaps the document should explain Hunk-Hunk.
+**Exercise**: How would you write the invest of a Hunk?
Typo
Ooops.
Daniel.
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
