Git Texinfo indices missing

Question

I have installed the official Git documentation in Texinfo format on my computer and for Emacs. But when I try to search for something with I in the info buffer (C-h-i d m git) it reports no indices. I'm new to Texinfo and is it because the official documentation doesn't include indexing facilities or because I didn't do something right? I need this feature because I find it quite useful. Here's how I build the official doc:

1. Install asciidoc and docbook2X.

   $ sudo dnf install asciidoc docbook2X
   

2. Download the Git repository. These instructions assume that you want the latest, bleeding edge. Replace “master” with an appropriate tag like “v2.20.1”.

   $ wget https://github.com/git/git/archive/master.tar.gz
   $ tar xf master.tar.gz
   $ cd git-master/Documentation
   

3. Build the info files.

   $ make git.info gitman.info
   

   • Error: docbook2x-texi: command not found

     SUBDIR ../
     make[1]: 'GIT-VERSION-FILE' is up to date.
     DB2TEXI user-manual.texi
     /bin/sh: line 1: docbook2x-texi: command not found
     make: *** [Makefile:413: user-manual.texi] Error 127
     

     This is the docbook to texi converter from the docbook2X package (which has not been updated since 2007). For Red Hat and Fedora, the EPEL package repo provides docbook2X. However, the name of the script is changed because there is a newer docbook package. So, in the git source directory, edit the file "Documentation/Makefile" and change one line:

     DOCBOOK2X_TEXI = db2x_docbook2texi
     

4. Install the info files into "~/.local/share/info".

   $ mv git.info gitman.info ~/.local/share/info
   $ cd ~/.local/share/info
   $ install-info git.info dir
   $ install-info gitman.info dir
   

5. Add "~/.local/share/info" to the variable "Info-additional-directory-list" to make the directory acessible to Emacs.

   (add-to-list 'Info-additional-directory-list "~/.local/share/info")
   

6. Restart Emacs to initialize the info files.

Answer 1

The issue is caused by the git documentation not being indexed (which needs to be done manually — adding good index terms is not entirely trivial).

In principle, asciidoc, which is what git uses, supports having an index. So does DocBook — the intermediate format (the full pipeline for the main manual, is user-manual.txt (asciidoc) → user-manual.xml (DocBook) → user-manual.texi (Texinfo) → git.info, and similarly for gitman.info).

In case you want to be convinced that an index could be added (though in itself, this is obviously completely useless), add (as a "dummy" indexed term):

indexterm:[knight, Knight of the Round Table, Lancelot] 

somewhere in the middle of user-manual.txt (the exact location is unimportant; the text is taken from the asciidoctor documentation (asciidoctor is mostly compatible with asciidoc)). Also add:

[index]
= Index

at the very end of user-manual.txt (this is needed for an index to be actually created). Now re-generate git.info and open in Emacs (you can open it in Emacs as an Info manual, without "installing" it, by using C-u C-h i path/to/the/manual/git.info).

is it because the official documentation doesn't include indexing facilities or because I didn't do something right

Technically, from a tooling point of view, the source documentation does support indexing, but the git project simply doesn't use it, possibly because they've decided it's not worth the effort. (You didn't do anything wrong.)

Answer to comment (for better readability)

What do you mean when you say "though in itself, this is obviously completely useless"?

I just wanted to emphasise the fact that the example was purely for illustrative purposes, and wasn't a solution to your problem (sorry for belabouring the obvious!).

Are your referring to indexing being useless? If so then why?

No, I agree with you that indices are useful.

Are there better ways to list the search results of keywords other than indexing in Emacs?

Not that I'm aware of.

As a very partial workaround, in case you weren't aware, you could use g to easily navigate to a node, but that's extremely coarse-grained. Unfortunately, occur (M-s o) doesn't work well with info, as it searches only in the current node, not the entire manual.

Do I need to add the indexing tags (in asciidoc format) one by one manually in the source documentation to generate the indices? Or are they already present?

Yes, you would need to add the indexing tags manually, one-by-one, to the source documentation in asciidoc format, so it's not really a feasible solution. (I'm not aware of any way of automating the generation of the indexing tags themselves.)