Steven Grimm <koreth@midwinter.com> writes:

quoted text
> 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
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html