[PATCH] Fix indentation problem in git-ls-files(1)

[PATCH] Fix indentation problem in git-ls-files(1)

[Andreas Schwab]

The nested list in the description of the -t option wasn't properly
indented.  Additionally, make it a horizontal labeled list since the
labels are all short.

Signed-off-by: Andreas Schwab <schwab@linux-m68k.org>
---
 Documentation/git-ls-files.txt |   15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..c0dc3ec 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -108,13 +108,14 @@ OPTIONS
 -t::
 	Identify the file status with the following tags (followed by
 	a space) at the start of each line:
-	H::	cached
-	S::	skip-worktree
-	M::	unmerged
-	R::	removed/deleted
-	C::	modified/changed
-	K::	to be killed
-	?::	other
+[horizontal]
+	H:::	cached
+	S:::	skip-worktree
+	M:::	unmerged
+	R:::	removed/deleted
+	C:::	modified/changed
+	K:::	to be killed
+	?:::	other
 
 -v::
 	Similar to `-t`, but use lowercase letters for files
-- 
1.7.0.1


Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Junio C Hamano]

Andreas Schwab <schwab@linux-m68k.org> writes:

> The nested list in the description of the -t option wasn't properly
> indented.  Additionally, make it a horizontal labeled list since the
> labels are all short.
>
> Signed-off-by: Andreas Schwab <schwab@linux-m68k.org>
> ---

Thanks.

>  Documentation/git-ls-files.txt |   15 ++++++++-------
>  1 files changed, 8 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index 3521637..c0dc3ec 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -108,13 +108,14 @@ OPTIONS
>  -t::
>  	Identify the file status with the following tags (followed by
>  	a space) at the start of each line:
> -	H::	cached
> -	S::	skip-worktree
> -	M::	unmerged
> -	R::	removed/deleted
> -	C::	modified/changed
> -	K::	to be killed
> -	?::	other
> +[horizontal]
> +	H:::	cached
> +	S:::	skip-worktree
> +	M:::	unmerged
> +	R:::	removed/deleted
> +	C:::	modified/changed
> +	K:::	to be killed
> +	?:::	other

Both [horizontal] and three colons are something we never have used in the
existing documentation set.  How confident are you that various versions
of deployed AsciiDoc people would use all support this?

I am not _complaining_; I am just being cautious to see if I have to look
into the issue myself (if your answer is "not at all") or not (otherwise).

Cf. http://thread.gmane.org/gmane.comp.version-control.git/139014/focus=139339

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Andreas Schwab]

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

> Both [horizontal] and three colons are something we never have used in the
> existing documentation set.  How confident are you that various versions
> of deployed AsciiDoc people would use all support this?

I'm sorry, but I have no idea.  I just looked at the user guide on the
asciidoc home page, which contais no version information.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Mark Lodato]

On Fri, Mar 5, 2010 at 5:08 AM, Andreas Schwab <schwab@linux-m68k.org> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Both [horizontal] and three colons are something we never have used in the
>> existing documentation set.  How confident are you that various versions
>> of deployed AsciiDoc people would use all support this?
>
> I'm sorry, but I have no idea.  I just looked at the user guide on the
> asciidoc home page, which contais no version information.

Yes, the documentation is lacking here.  I believe we official support
AsciiDoc 8.2.7 - this is what the builds on kernel.org use.  Here's a
cheatsheet for that version:

	http://powerman.name/doc/asciidoc-827

Hopefully the following will clarify things for the future:

Use ';;' instead of ':::' for a nested list.  The former was added in
AsciiDoc 5.0.9; the latter in 8.3.5.

For horizontal lists, put the term and definition on the same line
*and* prefix it with [horizontal].  Before 8.3.0, horizontal lists
were specified by placing the definition on the same line as the term
(which mimics the output).  After 8.3.0, this formatting does not
matter, and the choice of vertical vs horizontal is determined by the
presence of [horizontal].  If you do both, I think it looks fine on
both.

Here's an example showing a normal, vertical list, with a nested,
horizontal list in the second item.

---- 8< ----
a::
	The first letter.
b::
	The second letter.
+
[horizontal]
	B;; The capital letter.
	beta;; The greek equivalent.
c::
	The third letter.
---- >8 ----

Perhaps it would be a good idea to add an Asciidoc section to
Documentation/CodingGuidelines?  This could clear up these sorts of
questions, and also cover conventions used in the manual: what name to
give metavariables, when to use backticks, when to use single quotes,
etc.

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Junio C Hamano]

Mark Lodato <lodatom@gmail.com> writes:

> On Fri, Mar 5, 2010 at 5:08 AM, Andreas Schwab <schwab@linux-m68k.org> wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> Both [horizontal] and three colons are something we never have used in the
>>> existing documentation set.  How confident are you that various versions
>>> of deployed AsciiDoc people would use all support this?
>>
>> I'm sorry, but I have no idea.  I just looked at the user guide on the
>> asciidoc home page, which contais no version information.
>
> Yes, the documentation is lacking here.  I believe we official support
> AsciiDoc 8.2.7 - this is what the builds on kernel.org use.

FYI, the machine documentation set is autogenerated at k.org uses 8.2.5
right now, not 8.2.7..

> Here's a cheatsheet for that version:
>
> 	http://powerman.name/doc/asciidoc-827

Thanks for a link.

> Hopefully the following will clarify things for the future:
> ...
> Perhaps it would be a good idea to add an Asciidoc section to
> Documentation/CodingGuidelines?  This could clear up these sorts of
> questions, and also cover conventions used in the manual: what name to
> give metavariables, when to use backticks, when to use single quotes,
> etc.

The only rule we had so far is "try to mimic existing text around what you
are changing", and "don't try to be original nor fancy by using features
that are not used in existing text anywhere", I agree it would be helpful
to have more concrete tips on what to avoid, and conventions on what
particular typesetting conventions we chose for various parts of speech.

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Andreas Schwab]

The nested list in the description of the -t option wasn't properly
indented.  Additionally, make it a horizontal labeled list since the
labels are all short.

Signed-off-by: Andreas Schwab <schwab@linux-m68k.org>
---
 Documentation/git-ls-files.txt |   15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..d39d8b8 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -108,13 +108,14 @@ OPTIONS
 -t::
 	Identify the file status with the following tags (followed by
 	a space) at the start of each line:
-	H::	cached
-	S::	skip-worktree
-	M::	unmerged
-	R::	removed/deleted
-	C::	modified/changed
-	K::	to be killed
-	?::	other
+[horizontal]
+	H;;	cached
+	S;;	skip-worktree
+	M;;	unmerged
+	R;;	removed/deleted
+	C;;	modified/changed
+	K;;	to be killed
+	?;;	other
 
 -v::
 	Similar to `-t`, but use lowercase letters for files
-- 
1.7.0.2

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Junio C Hamano]

Hmm, http://www.methods.co.nz/asciidoc/newlists.html seems to say that
[horizontal] is new at 8.3.0, and earlier I think I said we use 8.2.5 in
order to prepare http://www.methods.co.nz/asciidoc/newlists.html, so the
patch looks a bit scary to me.

Sadly even with 8.2.7, "git help ls-files" shows something like this:

       -t
           Identify the file status with the following tags (followed by a
           space) at the start of each line: [horizontal]

           H   cached
           S   skip-worktree
           M   unmerged

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Johannes Sixt]

Andreas Schwab schrieb:
> The nested list in the description of the -t option wasn't properly
> indented.  Additionally, make it a horizontal labeled list since the
> labels are all short.

IMHO, converting a vertical list to a horizontal list is a step in the
wrong direction, even if the labels are short. It is far easier to scan a
vertical list for a match than a horizontal list.

-- Hannes

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Andreas Schwab]

Johannes Sixt <j.sixt@viscovery.net> writes:

> Andreas Schwab schrieb:
>> The nested list in the description of the -t option wasn't properly
>> indented.  Additionally, make it a horizontal labeled list since the
>> labels are all short.
>
> IMHO, converting a vertical list to a horizontal list is a step in the
> wrong direction, even if the labels are short. It is far easier to scan a
> vertical list for a match than a horizontal list.

The linebreak after the label is useless when all labels are much
shorter than the indentation.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Johannes Sixt]

Andreas Schwab schrieb:
> Johannes Sixt <j.sixt@viscovery.net> writes:
> 
>> Andreas Schwab schrieb:
>>> The nested list in the description of the -t option wasn't properly
>>> indented.  Additionally, make it a horizontal labeled list since the
>>> labels are all short.
>> IMHO, converting a vertical list to a horizontal list is a step in the
>> wrong direction, even if the labels are short. It is far easier to scan a
>> vertical list for a match than a horizontal list.
> 
> The linebreak after the label is useless when all labels are much
> shorter than the indentation.

I use Junio's man pages, and they look like so:

       -t
           Identify the file status with the following tags
           (followed by a space) at the start of each line:

           H   cached
           S   skip-worktree
           M   unmerged
           R   removed/deleted
           C   modified/changed
           K   to be killed
           ?   other

and the HTML version at
http://www.kernel.org/pub/software/scm/git/docs/git-ls-files.html looks OK
as well. I see nothing that needs fixing in either case.

-- Hannes

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Andreas Schwab]

Johannes Sixt <j.sixt@viscovery.net> writes:

> Andreas Schwab schrieb:
>> Johannes Sixt <j.sixt@viscovery.net> writes:
>> 
>>> Andreas Schwab schrieb:
>>>> The nested list in the description of the -t option wasn't properly
>>>> indented.  Additionally, make it a horizontal labeled list since the
>>>> labels are all short.
>>> IMHO, converting a vertical list to a horizontal list is a step in the
>>> wrong direction, even if the labels are short. It is far easier to scan a
>>> vertical list for a match than a horizontal list.
>> 
>> The linebreak after the label is useless when all labels are much
>> shorter than the indentation.
>
> I use Junio's man pages, and they look like so:
>
>        -t
>            Identify the file status with the following tags
>            (followed by a space) at the start of each line:
>
>            H   cached
>            S   skip-worktree
>            M   unmerged
>            R   removed/deleted
>            C   modified/changed
>            K   to be killed
>            ?   other

That's not what I see.

       -t
           Identify the file status with the following tags (followed by a
           space) at the start of each line:

           H
               cached

           S
               skip-worktree

           M
               unmerged

           R
               removed/deleted

           C
               modified/changed

           K
               to be killed

           ?
               other


Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [PATCH] Fix indentation problem in git-ls-files(1)

[Junio C Hamano]

Andreas Schwab <schwab@linux-m68k.org> writes:

> That's not what I see.

It could be version differences of AsciiDoc-to-xmlto toolchain.  I think
I've listed the versions I use (and the ones currently used to format the
copies people get from k.org) elsewhere in this thread.  If you are using
anything newer, perhaps we are seeing an issue waiting to materialize and
you are being a useful coalmine canary.

If the output you showed is the best we could achieve without using
constructs that break the versions that are older than what you used but
are still in use (e.g.  "[horizontal]" and "three-colons"), I would say we
have to live with it.  It might be suboptimal but it still is readable.

Of course if you can come up with a patch that formats better without
breaking older tools, that is an entirely different story.  It would be
very much appreciated.