Bruce Korb <bkorb@gnu.org> writes:

quoted text
> Linus Torvalds wrote:
>
>> AsciiDoc is *also* a source format. But the source format is
>> already readable IN ITSELF. Which is the whole point!
>
> Readable, just not writable.  It's markup language is a bunch of
> special characters that require familiarity to understand.

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.

-- 
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