patchAdd support for an info version of the user manual

These patches use docbook2x in order to create an info version of the git user manual. No existing Makefile targets (including "all") are touched, so you need to explicitly say

make info sudo make install-info

to get git.info created and installed. If the info target directory does not already contain a "dir" file, no directory entry is created. This facilitates $(DESTDIR)-based installations. The same could be achieved with

sudo make INSTALL_INFO=: install-info

explicitly.

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.

Signed-off-by: David Kastrup <dak@gnu.org>
---
 Documentation/Makefile |   28 ++++++++++++++++++++++++++++
 Makefile               |    6 ++++++
 2 files changed, 34 insertions(+), 0 deletions(-)

[Cc: David Kastrup <dak@gnu.org>, git@vger.kernel.org]

David Kastrup wrote:

[...]

[...]

First, a note on patch: please use $(AWK) instead of 'awk', just in case.

It would be nice to add a paragraph about build requirements for info version of Git User's Manual in the INSTALL file.

In the future we would probably want configure.ac to support --with-info or something like that to install documentation in info format (it does support --infodir), perhaps with awk autodetection and docbook2x autodetection.

David Kastrup <dak@gnu.org> posted to the git mailing list in 2007:

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.