FreeBSD Porter's Handbook
Prev		Next

Chapter 11 Info files

The new version of texinfo (included in 2.2.2-RELEASE and onwards) contains a utility called install-info to add and delete entries to the dir file. If your port installs any info documents, please follow these instructions so your port/package will correctly update the user's PREFIX/info/dir file. (Sorry for the length of this section, but is it imperative to weave all the info files together. If done correctly, it will produce a beautiful listing, so please bear with me!)

First, this is what you (as a porter) need to know:

    % install-info --help
    install-info [OPTION]... [INFO-FILE [DIR-FILE]]
      Install INFO-FILE in the Info directory file DIR-FILE.
    
    Options:
    --delete          Delete existing entries in INFO-FILE;
                        don't insert any new entries.
     :
    --entry=TEXT      Insert TEXT as an Info directory entry.
     :
    --section=SEC     Put this file's entries in section SEC of the directory. :

Note: This program will not actually install info files; it merely inserts or deletes entries in the dir file.

Here's a seven-step procedure to convert ports to use install-info. editors/emacs will be used as an example.

Look at the texinfo sources and make a patch to insert @dircategory and @direntry statements to files that do not have them. This is part of my patch:
```
    --- ./man/vip.texi.org  Fri Jun 16 15:31:11 1995
    +++ ./man/vip.texi      Tue May 20 01:28:33 1997
    @@ -2,6 +2,10 @@
    
     @setfilename ../info/vip
     @settitle VIP
    +@dircategory The Emacs editor and associated tools
    +@direntry
    +* VIP: (vip).          A VI-emulation for Emacs.
    +@end direntry
    
     @iftex
     @finalout
     :
```
The format should be self-explanatory. Many authors leave a dir file in the source tree that contains all the entries you need, so look around before you try to write your own. Also, make sure you look into related ports and make the section names and entry indentations consistent (we recommend that all entry text start at the 4th tab stop).

Note: Note that you can put only one info entry per file because of a bug in install-info --delete that deletes only the first entry if you specify multiple entries in the <@direntry> section.

You can give the dir entries to install-info as arguments (--section and --entry) instead of patching the texinfo sources. This probably is not a good idea for ports because you need to duplicate the same information in three places (Makefile and @exec/@unexec of pkg-plist; see below). However, if you have Japanese (or other multibyte encoding) info files, you will have to use the extra arguments to install-info because makeinfo cannot handle those texinfo sources. (See Makefile and pkg-plist of japanese/skk for examples on how to do this).
Go back to the port directory and do a make clean; make and verify that the info files are regenerated from the texinfo sources. Since the texinfo sources are newer than the info files, they should be rebuilt when you type make; but many Makefiles do not include correct dependencies for info files. In Emacs' case, it was necessary to patch the main Makefile.in so it would descend into the man subdirectory to rebuild the info pages.
```
    --- ./Makefile.in.org   Mon Aug 19 21:12:19 1996
    +++ ./Makefile.in       Tue Apr 15 00:15:28 1997
    @@ -184,7 +184,7 @@
     # Subdirectories to make recursively.  `lisp' is not included
     # because the compiled lisp files are part of the distribution
     # and you cannot remake them without installing Emacs first.
    -SUBDIR = lib-src src
    +SUBDIR = lib-src src man
    
     # The makefiles of the directories in $SUBDIR.
     SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile
     lwlib/Makefile
    --- ./man/Makefile.in.org       Thu Jun 27 15:27:19 1996
    +++ ./man/Makefile.in   Tue Apr 15 00:29:52 1997
    @@ -66,6 +66,7 @@
     ${srcdir}/gnu1.texi \
     ${srcdir}/glossary.texi
    
    +all: info
     info: $(INFO_TARGETS)
    
     dvi: $(DVI_TARGETS)
```
The second hunk was necessary because the default target in the man subdir is called info, while the main Makefile wants to call all. The installation of the info info file was also removed because we already have one with the same name in /usr/share/info (that patch is not shown here).

If there is a place in the Makefile that is installing the dir file, delete it. Your port may not be doing it. Also, remove any commands that are otherwise mucking around with the dir file.

    --- ./Makefile.in.org   Mon Aug 19 21:12:19 1996
    +++ ./Makefile.in       Mon Apr 14 23:38:07 1997
    @@ -368,14 +368,8 @@
            if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
            then \
              (cd ${infodir};  \
    -          if [ -f dir ]; then \
    -            if [ ! -f dir.old ]; then mv -f dir dir.old; \
    -            else mv -f dir dir.bak; fi; \
    -          fi; \
               cd ${srcdir}/info ; \
    -          (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir);
    \
    -          (cd $${thisdir}; chmod a+r ${infodir}/dir); \
               for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
                 (cd $${thisdir}; \
                  ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
                  chmod a+r ${infodir}/$$f); \

(This step is only necessary if you are modifying an existing port.) Take a look at pkg-plist and delete anything that is trying to patch up info/dir. They may be in pkg-install or some other file, so search extensively.

    Index: pkg-plist
    ===================================================================
    RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
    retrieving revision 1.15
    diff -u -r1.15 pkg-plist
    --- pkg-plist       1997/03/04 08:04:00     1.15
    +++ pkg-plist       1997/04/15 06:32:12
    @@ -15,9 +15,6 @@
     man/man1/emacs.1.gz
     man/man1/etags.1.gz
     man/man1/ctags.1.gz
    -@unexec cp %D/info/dir %D/info/dir.bak
    -info/dir
    -@unexec cp %D/info/dir.bak %D/info/dir
     info/cl
     info/cl-1
     info/cl-2

Add a post-install target to the Makefile to call install-info with the installed info files. (It is no longer necessary to create the dir file yourself; install-info automatically creates this file if it does not exist.)

    Index: Makefile
    ===================================================================
    RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
    retrieving revision 1.26
    diff -u -r1.26 Makefile
    --- Makefile    1996/11/19 13:14:40     1.26
    +++ Makefile    1997/05/20 10:25:09     1.28
    @@ -20,5 +20,8 @@
     post-install:
     .for file in emacs-19.34 emacsclient etags ctags b2m
            strip ${PREFIX}/bin/${file}
     .endfor
    +.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
    +       install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
    +.endfor
    
     .include <bsd.port.mk>

Edit pkg-plist and add equivalent @exec statements and also @unexec for pkg_delete.

    Index: pkg-plist
    ===================================================================
    RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
    retrieving revision 1.15
    diff -u -r1.15 pkg-plist
    --- pkg-plist       1997/03/04 08:04:00     1.15
    +++ pkg-plist       1997/05/20 10:25:12     1.17
    @@ -16,7 +14,14 @@
     man/man1/etags.1.gz
     man/man1/ctags.1.gz
    +@unexec install-info --delete %D/info/emacs %D/info/dir
     :
    +@unexec install-info --delete %D/info/ccmode %D/info/dir
     info/cl
     info/cl-1
    @@ -87,6 +94,18 @@
     info/viper-3
     info/viper-4
    +@exec install-info %D/info/emacs %D/info/dir
     :
    +@exec install-info %D/info/ccmode %D/info/dir
     libexec/emacs/19.34/i386--freebsd/cvtmail
     libexec/emacs/19.34/i386--freebsd/digest-doc

Note: The @unexec install-info --delete commands have to be listed before the info files themselves so they can read the files. Also, the @exec install-info commands have to be after the info files and the @exec command that creates the the dir file.

Test and admire your work. :-). Check the dir file before and after each step.

Prev	Home	Next
X11 fonts		The `pkg-*` files