[gentoo-dev] Info Pages

[Chad M. Huneycutt]

In trying to get the info pages to work, I learned a few things and 
thought I would pass them on.  I just threw down the thoughts, so there 
are probably typos, etc. and the formatting is terrible.  If there is 
interest, I will xml-ify it.  Just let me know.

Chad Huneycutt
aka Bab5

---
Here is a quick tutorial on making info pages work:

In order for the info page of foo to display after typing 'info foo', 
the following two conditions must be met
1. the info file (.info or .info.gz) must be in the info path 
(/usr/share/info in gentoo)
2. *** there must be an entry in the dir file for that particular info 
directory (/usr/share/info/dir in gentoo)

#2 is the important one it seems.  Most programs that have info pages 
get the page put in the right place, but some fail to get the entry 
registered in the dir file.

There are 3 options for fixing this:
1. edit the source .texi file - This is the best solution, as this is 
what foo's developer will need to do in order to fix it 
correctly.Replace the fields in square brackets appropriately.  I think 
that the punctuation is very important (periods, colons, etc.)

     Here is how to do this (NOTE: this is different than my previous 
e-mail)
Somewhere near the top of the file (like right after the @ifinfo), add 
the following lines:
@dircategory [category]
@direntry
* [name]: ([name]).          [Short Description].
@end direntry

Replace the fields in square brackets appropriately.  I think that the 
punctuation is very important (periods, colons, etc.)

The only problem with this solution is if foo's developer does not 
provide the .texi file or if the .texi file is ignored (check the 
Makefile install target).  If the .texi file is not provided, goto 
option 2.  If the .texi file is ignored, then you can either patch it 
and run a makeinfo yourself or goto step 2).

2. edit the info file - This is a stop-gap solution, but will work if 
option 1 will not.

What happens to the lines above [that would have been inserted into the 
.texi file] is that they are transformed to the following, so place it 
somewhere near the top of the file

START-INFO-DIR-ENTRY
* [name]: ([name]).        [Short Description].
END-INFO-DIR-ENTRY

Replace the fields in square brackets appropriately.  I think that the 
punctuation is very important (periods, colons, etc.)

3. The last option is the trickiest - edit the dir file and add the 
appropriate entry.  This is only recommended as a last resort, but here 
is how it works.  In gentoo the dir file is /usr/share/info/dir.  You 
will see a bunch of lines that begin with an * of the same format as the 
above two examples.  Just find the right section and add the entry just 
as I have above, paying close attention to punctuation.  This is not an 
operation for the faint of heart to attempt inside of an ebuild!