threads / patch / 9607

patchFix break in git-rev-list.txt

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

## tl;dr

6 messages between Aug 22, 2007 and Aug 22, 2007. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Quy Tonthat· Aug 22, 2007, 08:18 UTC · lore
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(-)
Show changes to Documentation/git-rev-list.txt +3 −3
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
Junio C Hamano· Aug 22, 2007, 10:01 UTC · re: Quy Tonthat · lore

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

Quy Tonthat <qtonthat@gmail.com> writes:
Show 12 quoted lines
> 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.

David Kastrup· Aug 22, 2007, 10:58 UTC · re: Junio C Hamano · lore

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

Junio C Hamano <gitster@pobox.com> writes:
Show 8 quoted lines
> 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
Quy Tonthat· Aug 22, 2007, 14:37 UTC · re: Junio C Hamano · lore

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

Junio C Hamano wrote:
Show 34 quoted lines
> 
> 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
Quy Tonthat· Aug 22, 2007, 15:29 UTC · re: Junio C Hamano · lore

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

Junio C Hamano wrote:
Show 8 quoted lines
> 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
Quy Tonthat· Aug 22, 2007, 16:45 UTC · re: Junio C Hamano · lore

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

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

← back to recent threads