Re: [msysGit] Re: WIP: asciidoc replacement

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Oct 3, 2007, 11:50 UTC
Message-ID: <Pine.LNX.4.64.0710031239410.28395@racer.site>
In-Reply-To: <7vprzwhkgd.fsf@gitster.siamese.dyndns.org>

Hi,

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

Show 17 quoted lines

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