patchFix indentation problem in git-ls-files(1)

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(-)

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

Thanks.

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

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

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.

On Fri, Mar 5, 2010 at 5:08 AM, Andreas Schwab <schwab@linux-m68k.org> wrote:

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.

Mark Lodato <lodatom@gmail.com> writes:

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

Thanks for a link.

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.

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(-)

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

Andreas Schwab schrieb:

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

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

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

Andreas.

Andreas Schwab schrieb:

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

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

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> writes:

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.