Re: [ANNOUNCE] GIT 1.5.3-rc4

Bruce Korb <bkorb@gnu.org> writes:

Well, one problem I find that the documentation of both Asciidoc and the connected Docbook toolchain is horribly subpar.

One part of the problem is that asciidoc.txt is written in Asciidoc, and so you can't pick apart markup from content in the explanations when reading the "readable in itself" documents.

Another problem is that most of the details of conversion to Docbook, and what results in what XML output, are completely glossed over. And then there are further problems in that downstream Docbook processors are documented even worse.

Then there is the problem that the markup can be redefined: the sectioning underlines explained in the asciidoc documentation differ from that _used_ in the documentation and again from that used in the git documentation.

Now I can, in fact, use docbook2x-texi --info --to-stdout user-manual.xml >user-manual.info and get a working info file: not just basically working, but quite fine (missing an index, though).

So there are "minor details" to fill in, like generated file names and info directory entries. Would you think that there is _any_ way of finding out how to represent this in Docbook, or if you find out that, how to get it from Asciidoc into Docbook?

Forget it.

Or things like including the manual pages in an appendix or elsewhere. Any chance for that? Slim, at least for me.

Texinfo source certainly looks less pretty than Asciidoc, but then makeinfo can produce plain text output from it looking quite like Asciidoc. And whatever you may think about Texinfo as a format and the generated info files and their readers: it is damn well documented.

Asciidoc is quite readonly in many respects at the moment for me, and I don't even know where to start in order to fix that.

And it does not help that there are multiple conversions involved with a pretty opaque in-between XML representation. In contrast, Texinfo has a single well-documented source format and direct converters to the target formats.

And its syntax is straightforward enough to write additional converters if one wants to (makeinfo can even produce Docbook output, so perhaps I may have a chance to reverse-engineer some required information from there).

Whatever. It is pretty clear that Texinfo is not going to be interesting enough to maintain for most git developers to continue this particular thread, as it won't progress beyond a simple and ugly advocacy and name-calling thread.

Anyway, the necessary structural information (indexing, directory info etc) presumably can be spliced into Asciidoc documents once somebody finds out how to do this, and then Texinfo can be _generated_ from it for those who need it.