Re: [PATCH] Fix break in git-rev-list.txt

[Junio C Hamano <gitster@pobox.com>]

Quy Tonthat <qtonthat@gmail.com> writes:

> diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
> index cbbc234..a0c611e 100644
> --- a/Documentation/git-rev-list.txt
> +++ b/Documentation/git-rev-list.txt
> @@ -298,8 +298,8 @@ used in the output.  When the starting commit is specified as
>  'commit@{now}', output also uses 'commit@\{timestamp}' notation
>  instead.  Under '\--pretty=oneline', the commit message is
>  prefixed with this information on the same line.
> -+
> -Cannot be combined with --reverse.
> +
> +Cannot be combined with '\--reverse'.

Hmph.  Interesting.  The text around this is:

	-g, --wark-reflogs::

        	Indented first paragraph...
	+
        With '\--pretty' fromat ... second paragraph ...
	prefixed with this information on the same line.
	+
        Cannot be combined with --reverse.

And its formatted form looks like either (without your patch):

	<listitem>
        <simpara>
        	Indented first paragraph...
	With <emphasis>--pretty</emphasis> format ...
	</simpara>
        <simpara>Cannot be combined with --reverse.</simpara>

        </listitem>	

or (with):

	<listitem>
        <simpara>
        	Indented first paragraph...
	With <emphasis>--pretty</emphasis> format ...
	Cannot be combined with --reverse.
	</simpara>

        </listitem>	

So it looks as if the only place that needs the ugly '+'
continuation marker is between the first and the second
paragraph.  And it also appears that the manpage backend does
not pay attention to the paragraph break there (HTML backend
places a <br /> before "With <em>--pretty</em>").

Is it just me, or the more we look at it, everybody doubts if
AsciiDoc was such a good choice?

It was a major plus that the input format is mostly readable as
straight text, but this was one of the sore points in our
formatting.  In the description part of a definition list, we
indent the first paragraph but append the second paragraph and
later with '+' without indenting (we would rather keep the
second and subsequent paragraphs aligned with the first one).
However, it appears that the definition has to be a single
paragraph and not any longer in such a list anyway.

Hmmmm.

In any case, I'd appreciate feedbacks from people who recently
reported formatting breakages on this patch.