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

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

[Quy Tonthat]

Also fix some innocent missing of quotes.

Signed-off-by: Quy Tonthat <qtonthat@gmail.com>
---
 Documentation/git-rev-list.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

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'.
 
 --merge::
 
@@ -375,7 +375,7 @@ By default, the commits are shown in reverse chronological order.
 --reverse::
 
 	Output the commits in reverse order.
-	Cannot be combined with --walk-reflogs.
+	Cannot be combined with '\--walk-reflogs'.
 
 Object Traversal
 ~~~~~~~~~~~~~~~~
-- 
1.5.3.rc5.1q

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

[Junio C Hamano]

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.

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

[David Kastrup]

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

> 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?

I don't think you should overgeneralize right now.  Every input format
will need some massaging, possibly resulting in ugliness.

AsciiDoc _can_ be converted to plain text without markup.  Whether
this is worth doing depends on just how many people actually access
the .txt files, and how much they are disturbed by things that are
just there for leading AsciiDoc on the right path.

One can also cater for particular patterns in the configuration files
rather than in the source files.

However, there are some things which can't be ironed out: adding
useful indexing information will certainly disturb perusing the .txt
files as text.  And I consider good indexing important.

There also is the problem that AsciiDoc works with a format _chain_
that makes it painful to achieve a certain result.

However, the resulting quality of this format chain is good: proper
Docbook output, even proper Texinfo output, well-formatted manual
pages, nice-looking HTML.  In most of those areas, the Texinfo
toolchain, in contrast, falls on its face.

If one does not want to sacrifice quality, it might still make sense
to cut Asciidoc out of the equation and use Docbook instead.
Markup-free .txt-files can presumably generated from Docbook.  I think
it should also be possible to generate manpages from it, and it
converts nicely into Texinfo.

As long as we have no dedicated Asciidoc wizard working for git, this
might make changing the structure of the documentation or adding new
features much easier.

But it might frighten people from correcting the straight text of the
documentation.

It is certainly a multi-edged sword, and without doing an extensive
poll among those who contribute to documentation, a change in policy
would not appear appropriate.

I know that the combined Asciidoc/Docbook challenge has kept me up to
now from succeeding in a restructuring that would include the manual
pages in the user manual as an appendix.

I have no doubt from the Docbook and Asciidoc documentation I have
digged through that this is possible, and with not too many lines of
code, but it is still quite beyond me given the time I can spend on
it.

The question is how often Asciidoc will keep people from contributing
useful changes, and how often Docbook would.

I have no idea how the numbers would turn out.  I consider it more
likely that people will contribute text changes to Asciidoc
documentation, but structural changes are likely quite easier to do
with Docbook.

-- 
David Kastrup

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

[Quy Tonthat]

Junio C Hamano wrote:
> 
> 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>	
> 

Well, it goes differently on my system here (asciidoc 8.1.0), as shown
in the diff bellow:

	--- git-rev-list.xml.bad	2007-08-23 00:08:58.000000000 +1000
	+++ git-rev-list.xml.good	2007-08-23 00:10:20.000000000 +1000
	@@ -509,16 +509,15 @@
	         When this option is used you cannot specify commits to
	         exclude (that is, <emphasis>&#94;commit</emphasis>, <emphasis>commit1..commit2</emphasis>,
	         nor <emphasis>commit1&#8230;commit2</emphasis> notations cannot be used).
	-<literal>
	 With <emphasis>--pretty</emphasis> format other than oneline (for obvious reasons),
	 this causes the output to have two extra lines of information

	 taken from the reflog.  By default, <emphasis>commit@{Nth}</emphasis> notation is
	 used in the output.  When the starting commit is specified as

	 instead.  Under <emphasis>--pretty=oneline</emphasis>, the commit message is

	 prefixed with this information on the same line.

	-</literal>

	-Cannot be combined with --reverse.

	 </simpara>

	+<simpara>Cannot be combined with --reverse.</simpara>

	+

	 </listitem>

	 </varlistentry>

	 <varlistentry>


Note the extra <literal></literal> which what xmlto has problems with as
in its error messages

/work/devel/git/git.git/Documentation/git-rev-list.xml:512: element literal: validity error : Element emphasis is not declared in literal list of possible children

I'll have a look at asciidoc as soon as I have some time.

Quy

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

[Quy Tonthat]

Junio C Hamano wrote:
> 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.

For your info (not implying what is "wrong" or "right"), without
the second '+' it will generate new paragraph with correct indentation
on my system here.

Quy

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

[Quy Tonthat]

Junio C Hamano wrote:
> In any case, I'd appreciate feedbacks from people who recently
> reported formatting breakages on this patch.

I was not aware this problem had been reported/discussed in another
thread (lack of time lately). I would not have had created this
thread otherwise. Sorry for making more noise (than necessary)
and any confusion this may cause.

Anyway, reports/comments will be appreciated.

Quy