Re: [PATCH] Add support for an info version of the user manual

David Kastrup [off-list ref] posted to the git mailing list in 2007:

awk is used for patching up sub-par file and directory information in
the Texinfo file.  It would be cleaner to place the respective info
straight into user-manual.txt or the conversion configurations, but I
find myself unable to find out how to do this with Asciidoc/Texinfo.

I found how to do this, but it's not worth the trouble.

Apparently, there are two ways to specify the description for the
Info directory entry generated by docbook2X 0.8.3:

(a) Set it in the docbook2x-texi command line, with the option:

    -g description="A fast distributed revision control system"

    This could easily be placed in the Makefile.

(b) Add a /book/bookinfo/abstract[@role="texinfo-node"] element:

    <abstract role="texinfo-node"><simpara>A fast distributed
    revision control system</simpara></abstract>

    docbook2x-0.8.3/xslt/texi/menudescrip.xsl claims that the role
    should be "make-texinfo-node", but the template in that file
    actually looks for role="texinfo-node".  docbook2X 0.8.8
    documents the role correctly.

    The /book/bookinfo element currently comes from the [header]
    section in docbook.conf of AsciiDoc.  That docbook.conf does
    not currently provide a way to add an abstract like that.
    So, Git would have to override the whole header, unless
    such a feature were added to AsciiDoc.

Then, docbook2x-texi would take the title "Git User's Manual (for
version 1.5.3 or newer)" and convert it to "Git User_s Manual
[for version 1_5_3 or newer]", presumably to avoid some reserved
characters in Info.  To get a prettier title like "Git" in the
Info directory entry:

(a) A Git-specific XSL template could read the entry title from
    /book/bookinfo/titleabbrev, which would also have to be added
    to the header in the AsciiDoc configuration.

(b) Alternatively, the template could use a command-line parameter.
    Makefile would provide -g info-dir-title="Git", and the
    template would then use $info-dir-title.

Finally, to make the Info directory entry link to the right file,
one would have to add -g output-file=git to the docbook2x-texi
invocation.

In summary, it is certainly possible to make AsciiDoc and
docbook2X together generate the right kind of directory entry,
but I suspect the current Perl hack is more likely to survive
toolchain upgrades than a more proper implementation would be.
If the necessary features were added to the upstream AsciiDoc
and docbook2X, then things would be different, but I guess Git
wouldn't dare require new versions until after a year or so.