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

From: Kalle Olavi Niemitalo <kon@iki.fi>
Date: Dec 14, 2008, 14:30 UTC
Message-ID: <87ljuiu8wf.fsf@Astalo.kon.iki.fi>
In-Reply-To: <86ir7tc5xk.fsf@lola.quinscape.zz>

David Kastrup <dak@gnu.org> 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.