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

Johannes Schindelin [off-list ref] writes:

Hi,

On Fri, 16 Nov 2007, Sergei Organov wrote:

quoted

+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 :(

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