Re: [ANNOUNCE] GIT 1.5.3-rc4

Linus Torvalds [off-list ref] writes:

On Sun, 5 Aug 2007, David Kastrup wrote:

quoted

You are still unable to focus on anything but name-calling and editors
rather than documentation formats.

No, it's the same thing.

I started out by saying that Texinfo is horrible. It's horrible
because it doesn't *buy* you anything.

No, that's not what makes it horrible.

The only thing it buys you (the "info" format) is totally
irrelevant, which I tried to explain.

By calling everybody names that would dare using it.  That's not
really an explanation.

AsciiDoc is much nicer. It does everything that Texinfo does for us,
and it's readable on its own as plain text, something Texinfo isn't.

Readable plain text can be generated from Texinfo, so that is a red
herring.

So by advocating Texinfo, you're advocating something that is
OBJECTIVELY WORSE than what we have now.

And I tried to explain why, by pointing out that info files (which
was the case you tried to push as an advantage) aren't actually an
advantage to any normal user.

Linus, your "normal user" does not get any documentation that can
usefully be employed for navigating a large body of documentation.

Anyway, this particular flame feast might be somewhat irrelevant: I
have read up a bit on AsciiDoc and Docbook, and it would appear that
quite a lot of what is needed for putting the required information for
indexes and nodes and other structural information is there in both
formats, and there is a tool called docbook2X that can presumably
convert to Texinfo (currently it barfs on the usermanual).  So
basically a lot can be achieved by structuring the existing
documentation into book form in AsciiDoc and peppering it with
indexing (apparently only a single index is possible) and other
structural information.

This will make the AsciiDoc sources less readable, while improving the
structural information content of the generated output, presumably
also when not going via Texinfo conversion.

Restructuring the available documentation into something that _can_ be
used as a coherent book, whether as a single PDF, single or multiple
HTML pages or even (avaunt!) info is probably not too horrible a
long-term prospect, and if info gives you the heebies, just don't call
"make info install-info", and you'll never get contaminated with it.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum