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

[Thomas Rast <trast@student.ethz.ch>]

[-- Attachment #1.1: Type: text/plain, Size: 2818 bytes --]

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.

> 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



[-- Attachment #1.2: make-test-repo --]
[-- Type: application/x-shellscript, Size: 882 bytes --]

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]