Re: [RFC PATCH] Documentation: rev-list-options: clarify history simplification with paths

From: Thomas Rast <trast@student.ethz.ch>
Date: Aug 11, 2008, 23:51 UTC
Message-ID: <200808120151.56067.trast@student.ethz.ch>
In-Reply-To: <7vprofwat0.fsf@gitster.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> wrote:

Thanks for taking the time to look into this!

> What was the meaning of the double-dash at the beginning of line in
> AsciiDoc markup?  I forgot.

I wish I knew. I simply copied that from elsewhere in the docs to make it shut up about an error. It would seem that it is required to end the list before a title, except if there's already an 'if' doing the split, unless on a full moon, except if it's wednesday. I've tried to make the patches compile with asciidoc (8.2.5 here), but that's about as far as it goes.

I haven't found any mention of the magic features of '^--' in the user manual, though the cheat sheet

  http://powerman.name/doc/asciidoc

has nice examples how to interrupt lists, which I used for the upcoming patch contents.

> Please draw it a bit more consistently with pictures in other existing
> documentation, perhaps like this:

Hmm. I've tried to give the new examples a more compact and round appearance, like in your example. Tell me if that works for you.

Show 7 quoted lines

> I'd rather make this the part of the base text.  In other words, remove
> the "--prune-merges" header, dedent the description and start the sentence
> with "By default, parents of a merge is rewritten with the following
> rules:".
> 
> Then before listing the options, say something like "You can influence how
> simplification works using the following options".

I dropped the "--prune-merges" since it would be a new option. However, I would like to keep some sort of "Default mode" header (not necessarily as a list header, if you have better ideas). Otherwise, upon encountering "--full-history ... differs from the default", the reader would have to (tediously) scan several paragraph breaks to discover where the default begins.

I completely rewrote it along the outlines given in my own followup. I also devised a better example that shows the differences between all-TREESAME merges, one-TREESAME merges, and (!)TREESAME commits. I am open for further suggestions of course. (I'm also violating the "no patches after midnight" rule, so feel free to point out obvious mistakes too.)

I furthermore split the patch into two halves:

* 2/3 applies on top of master, so that it is independent of
  --simplify-merges.

* 3/3 replaces the docs coming with --simplify-merges with an extra
  paragraph in 'History Simplification'.

I hope that's the right way to proceed. This does mean you will get a merge conflict when merging jc/post-simplify, but it's a fairly obvious one.

1/3 is just a one-character typo that I discovered along the way.

Finally, I'm attaching a script that generates a repository with the history used in the example.

- Thomas

-- 
Thomas Rast
trast@student.ethz.ch