Re: [ANNOUNCE] GIT 1.5.3-rc4

From: David Kastrup <dak@gnu.org>
Date: Aug 5, 2007, 19:06 UTC
Message-ID: <85y7gphkdd.fsf@lola.goethe.zz>
In-Reply-To: <alpine.LFD.0.999.0708051118590.5037@woody.linux-foundation.org>

Linus Torvalds <torvalds@linux-foundation.org> writes:

Show 9 quoted lines

> On Sun, 5 Aug 2007, David Kastrup wrote:
>> 
>> 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.

Show 6 quoted lines

> 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