From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 11 Oct 2011 17:49:15 GMT
Subject: Re: [PATCHv5/RFC 1/6] Documentation: Preparation for gitweb manpages
Message-ID: <7vvcrvfmg4.fsf@alter.siamese.dyndns.org>
In-Reply-To: <201110111739.49967.jnareb@gmail.com>

Jakub Narebski <jnareb@gmail.com> writes:

> On Tue, 11 Oct 2011, Junio C Hamano wrote:
>
>> I probably do not have time to look into this, but just FYI my trial merge
>> to 'pu' of this topic is failing like this:
>> 
>> asciidoc: ERROR: gitweb.conf.txt: line 484: illegal style name: Default: ()
>> asciidoc: ERROR: gitweb.conf.txt: line 494: illegal style name: Default: 300
>
> Damn, I thought I have fixed that.  This probably depends on AsciiDoc
> version ("make doc" on 'master' generates a few _warnings_ for me related
> to similar situation), but the problem is with
>
>   [Default: <value>]
>
> that was copied from gitweb/README.  But [<sth>] is an attribute list
> (style name in simplest form), used more often in newer AsciiDoc.
>
> So either we have to escape '[' and ']', i.e. use {startsb} and {endsb},
> which would reduce human-friendliness, or move to different way of marking
> default values, e.g. _italic_.
>
> What do you think?

What do the other documents in the directory this file lives say?  I think
we explain what the variables does, and add "defaults to false" or
somesuch in the text, without any funny mark-up.