Re: [ANNOUNCE] GIT 1.5.3-rc4

From: Steven Grimm <koreth@midwinter.com>
Date: Aug 4, 2007, 06:11 UTC
Message-ID: <46B418AA.4070701@midwinter.com>
In-Reply-To: <7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net>

Junio C Hamano wrote:

Show 8 quoted lines

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

Show 6 quoted lines

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

Show 6 quoted lines

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

Show 12 quoted lines

> 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