Re: [msysGit] Re: WIP: asciidoc replacement

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi,

On Tue, 2 Oct 2007, Junio C Hamano wrote:

> 
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > So here it is: a perl script that does a good job on many .txt files 
> > in Documentation/, although for some it deviates from "make man"'s 
> > output, and for others it is outright broken.  It is meant to be run 
> > in Documentation/.
> >
> > My intention is not to fix the script for all cases, but to make 
> > patches to Documentation/*.txt themselves, so that they are more 
> > consistent (and incidentally nicer to the script).
> 
> How you spend your time is up to you, but I need to wonder...
> 
>  - Is "man" format important for msysGit aka Windows
>    environment?  I had an impression that their helpfile format
>    were closer to "html" output.

I wanted something that can output both "man" and "html" output (and if 
some suck^Wlos^Wtexi-fan wants to provide it, also a "texi" or even "info" 
backend).

IMHO "man" needs a stricter framework in place, so I went with that.

>  - Does it make sense in the longer term for us to maintain
>    in-house documentation tools?  Can we afford it?

In the long run, I expect only few bugs (and I will try hard to squash 
them when they crop up, _and_ make this beast more maintainable whenever 
somebody has an idea how to do that).

However, it should definitely help keeping the docs clean, as now nobody 
has an excuse to test doc changes a la "I do not have asciidoc, so I do 
not know if it works, so please test".

> It appears that we heard about breakages for every minor docbook 
> updates, and it is really appealing if we do not have to rely on xsl 
> toolchain for manpage generation.

Exactly.

> But if patching the text means making it compatible with the in-house 
> script _and_ incompatible with AsciiDoc, hmmm...

No, I do not want it _incompatible_.  I want it _stricter_.  For example, 
you can do this in asciidoc:


    This is some paragraph that is indented,
    but the funny thing is:

This paragraph:
---------------

	is indented all the same!


So one thing I absolutely detest here is that you are free to use one, 
two, three or more spaces, or tabs, and asciidoc does the DWIMery of 
handling them the same.  But _not_ if there was any indentation before 
that with _less_ spaces and/or tabs!

Therefore I'd like to enforce strict rules here: Tab it is.  One tab per 
indentation level.  No spaces, no ambiguities.

Ciao,
Dscho