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

From: Mark Lodato <lodatom@gmail.com>
Date: Mar 7, 2010, 17:27 UTC
Message-ID: <ca433831003070927h4c3e24e1m75c7be88355f9663@mail.gmail.com>
In-Reply-To: <m3r5nzw05p.fsf@hase.home>

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

Show 8 quoted lines

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