Re: [ANNOUNCE] GIT 1.5.3-rc4

From: David Kastrup <dak@gnu.org>
Date: Aug 4, 2007, 12:19 UTC
Message-ID: <85zm17h4pn.fsf@lola.goethe.zz>
In-Reply-To: <46B45B1E.5020104@midwinter.com>

Steven Grimm <koreth@midwinter.com> writes:

Show 14 quoted lines

> Sam Ravnborg wrote:
>> Never looked at Ascii-doc... but how about finding the loopholes
>> in Ascii-doc to make it 10x faster?
>> That would benefit a larger user-base than just doing-it-ourself.
>>   
>
> Because AsciiDoc is only half of the toolchain we use. (Though in your
> defense, I made the mistake of only mentioning AsciiDoc by name,
> rather than "the AsciiDoc toolchain.") We run asciidoc's output
> through xmlto, which is just as slow and is a highly general piece of
> software for doing arbitrary transformations of XML documents. I won't
> say it's impossible to speed up xmlto as well, of course, but it's
> probably an order of magnitude more work than implementing a new
> parser/renderer for our .txt files.

Personally, I think it would make sense to move to a different documentation system, or at least a different organization. The problem with the current layout is that it is basically flat.

A system such as info, in contrast, is hierarchical, and organized with indexes and cross references making it much easier to find things. More importantly, it makes it possible to put things into perspective: which commands are porcelain, which are plumbing? What do you do in a typical workflow? What are the related internal data structures? Where are they documented? Can I print or navigate a complete PDF document explaining the whole system?

The manual pages of git have a high quality, but they remain manual pages: they are all standalone, not putting the tool into a context or hierarchy. While the user manual is a place to start, it is more or less added as an afterthought: it does not structure the available documentation.

For Texinfo there is a large number of backends, and there are also usable reader plugins (Tkinfo, and the presumably embeddable GNOME "yelp" also displays info files and the embedded links, and of course the wonderful Emacs info browser) for things like git-gui.

It may be that the asciidoc/Docbook workflow also contains ways to get similarly useful stuff out: comments welcome. I am just more acquainted with Texinfo myself.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum