Re: [ANNOUNCE] GIT 1.5.3-rc4

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 4, 2007, 04:38 UTC
Message-ID: <7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <46B3F762.1050306@midwinter.com>

Steven Grimm <koreth@midwinter.com> writes:

Show 8 quoted lines

> How attached are we to asciidoc? Every time I do a clean build and sit
> there twiddling my thumbs waiting for xmlto to do its thing, I think
> to myself, "If this were a dedicated Perl script to do the syntax
> transformations directly to man and html formats, it would blast
> through all the .txt files in a second or two total." It seems
> outlandish to me that it takes longer to build the (relatively small)
> documentation than it does to build the actual code. Plus we
> constantly run into this sort of problem.

I cannot say that I am really happy with the current situation. In my unscientific tests, it appears that we are spending about 50% of the time in asciidoc and 50% in xmlto for man backend (total about 5 seconds for producing git.7 on my private box). For xhtml11 backend, git.html takes about 2.3 seconds (for xhtml11 backend, the output is written directly by asciidoc).

Show 12 quoted lines

> Do we want to keep using asciidoc (e.g., so people can easily export
> to other asciidoc-supported formats), or is a dedicated renderer
> something we'd consider switching to? I have a flight from China back
> to the US coming in a couple weeks; this could be a perfect little
> project to keep me occupied between in-flight movies. It doesn't look
> like the syntax transformations are very hard, and it'd be easy enough
> to verify correctness by just comparing against the existing asciidoc
> output.
>
> Am I correct in observing that "*roff -man" and HTML are the only two
> output formats we care about, or do people use other formats in their
> private branches?

I obviously do not speak for others, but the only format I care about personally is the *.txt one. We picked asciidoc primarily because the source language was readable.

Unfortunately, AsciiDoc 8 requires authors to quote more "special characters" we would rather be able to use as literals (most importantly, plus sign '+') than AsciiDoc 7, and I am afraid the trend to hijack more non alphabet letters as "special" may continue.

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

There is an obvious maintenance cost and risk with such a fork.

 * 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.
   This already is the case, as our documentation source is
   written for AsciiDoc 7 and we use asciidoc7compatible support
   when running with AsciiDoc 8.

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

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

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

I have a mild suspicion that a clone/fork of AsciiDoc is not a way to go.

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.