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

[Junio C Hamano <gitster@pobox.com>]

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.