Re: [PATCH] Documentation: fix git-clone manpage not to refer to itself

From: Sergei Organov <osv@javad.com>
Date: Nov 19, 2007, 19:18 UTC
Message-ID: <87mytayrgu.fsf@osv.gnss.ru>
In-Reply-To: <Pine.LNX.4.64.0711191430460.16728@wbgn129.biozentrum.uni-wuerzburg.de>

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Show 11 quoted lines

> Hi,
>
> On Fri, 16 Nov 2007, Sergei Organov wrote:
>
>> +ifndef::git-clone[]
>
> It is laudable that you want to fix the _generated_ documentation, but 
> there are two things to keep in mind:
>
> - it does _nothing_ to help readers of the sources, and asciidoc was 
>   chosen purposely because the source is human-readable, and

I wonder if C sources are human-readable? No #ifdefs whatsoever? ;)

And please notice that asciidoc is much worse than C preprocessor in this regard :(

Show 9 quoted lines

>
> - it makes writing the perl script to do a very tiny subset of asciidoc 
>   formatting much harder.  We encounter enough problems with the different 
>   versions of asciidoc/docbook combinations that I think this perl script 
>   would be actually useful.
>
> I know that the user manual uses some advanced features, too, but it did 
> not use ifdef in the main text, for example, let alone nested ifdefs, 
> which your patch would encourage much more than the source before.

Unfortunately I don't see better solution than using ifdef in this particular case, though I'm open for suggestions.

What I really do care about is the quality of the documentation that user reads. For example, when the first option of git-format-*patch* described in the manual is "-p Generate *patch*...", well..., what does it generate without -p???

-- 
Sergei.