Re: [ANNOUNCE] GIT 1.5.3-rc4

[Steven Grimm <koreth@midwinter.com>]

Junio C Hamano wrote:
> If I read you correctly, what you are proposing to offer is a
> clone of asciidoc, perhaps AsciiDoc 7, with only xhtml11 and man
> backends.  It is a subset in the sense that you will do only two
> backends, but otherwise is a clone in the sense that you are
> going to implement the input language we use (one thing I
> personally care about while probably other people do not is the
> conditional compilation "ifdef::stalenotes[]" in git.txt).
>   

Yes and no. I am not offering to clone *all* of AsciiDoc, just whatever 
subset is necessary to format the git documentation. (Of course, having 
looked at this very little so far, perhaps that really is all of 
AsciiDoc -- but it's certainly not all of xmlto.)

>  * You would need to duplicate the AsciiDoc 7 manual and
>    maintain it as well; otherwise, when later versions of
>    AsciiDoc comes, people who update our documentation will
>    refer to asciidoc website to learn the syntax, and find out
>    that your dialect does not match what is described there.
>   

Actually, I disagree with this. If we were to fork our own document 
formatter (or rather "implement" -- "fork" implies starting with the 
existing code base) we would explicitly say its input was expected to be 
in the "git documentation human-readable text format" rather than "git's 
implementation of the AsciiDoc format." Then we could freely tweak 
whatever parts of AsciiDoc we're not happy with, and precise 
compatibility would be a total non-issue.

>  * How much can we really rely on your fork to be kept
>    maintained?  When we need newer mark-up that is not offered
>    by AsciiDoc 7 clone, is it our plan to model that after
>    AsciiDoc X (X > 7), or we just come up with an extension of
>    our own?
>   

My thought would be to come up with our own syntax; that's a logical 
result of me not considering this anything but "a formatter whose input 
looks suspiciously like AsciiDoc".

While I agree that that's extra work, it also seems to be the case that 
(a) git hasn't actually needed new markup very often, and (b) we've 
spent far more time dealing with AsciiDoc version-to-version 
incompatibilities than it would likely take to implement whatever new 
markup we needed.

>  * What would happen when xhtml11 goes out of fashion and we
>    would want to switch to newer formats?
>   

If I do this I'll try to structure the code in such a way that new 
formats could be added without huge pain. Will it be as flexible and 
configurable as xmlto? Absolutely not, which is kind of the point of the 
exercise. Adding a substantially different output format might require 
logic changes to the formatter depending on the details, given that the 
optimization here will be for speed rather than extreme flexibility.

On the other hand, I don't think that's a short-term enough concern to 
be worth worrying too much about; it'll be a long, long time before 
XHTML is completely replaced by anything else, just because of its 
gargantuan installed base of existing documents. And it's not like we 
can't decide to switch to another formatter down the road if we want to. 
(Once we all have 64-core machines on our desktops, "make -j64" will 
cause AsciiDoc/xmlto to be sufficiently fast!)

>  * What to do with the user manual, which formats to docbook
>    "book" output?
>   

Ah, that's a sticking point, and an answer to my "are there other output 
formats?" question. I never pay attention to that file when I'm doing 
builds -- forgot it even existed. I'll ask one question first: is that 
Docbook output actually necessary, or would people be happy enough just 
having the user manual in XHTML?

Assuming we really need a Docbook manual, it's tempting to say, "keep 
using AsciiDoc" but then my assertion that we aren't really using 
AsciiDoc's input format kind of flies out the window. I wonder if it's 
possible to go from one of my proposed script's *output* formats to 
Docbook format -- is there software to take well-formed XHTML and turn 
it into that format? (Possibly that software is called "xmlto"...) I 
think the transformation from .txt to .html is likely to be pretty 
lossless, so it should be theoretically possible, anyway.

> It might be more worthwhile to research what other "Text-ish
> lightweight mark-up" systems are availble, and if there is one
> that is more efficient and can go to at least html and man,
> one-time convert our documentation source to that format using
> your Perl magic.  The minimum requirements are:
>
>  * The source is readable without too much mark-up distraction;
>
>  * Can go to roff -man;
>
>  * Can go to html.
>   

I will look around and see what I can find. You're quite right, better 
to use already-existing code than reinvent the wheel.

-Steve