20 Creating and Installing Info Files
*************************************

This chapter describes how to create and install Info files.  See Info Files, for general information about the file format itself.

* Creating an Info File::       
* Installing an Info File::     


20.1 Creating an Info File
==========================

makeinfo is a program that converts a Texinfo file into an Info
file, HTML file, or plain text.  texinfo-format-region and
texinfo-format-buffer are GNU Emacs functions that convert
Texinfo to Info.

For information on installing the Info file in the Info system,
see Installing an Info File.

* makeinfo advantages::         makeinfo provides better error checking.
* Invoking makeinfo::           How to run makeinfo from a shell.
* makeinfo options::            Specify fill-column and other options.
* Pointer Validation::          How to check that pointers point somewhere.
* makeinfo in Emacs::           How to run makeinfo from Emacs.
* texinfo-format commands::     Two Info formatting commands written
                                  in Emacs Lisp are an alternative
                                  to makeinfo.
* Batch Formatting::            How to format for Info in Emacs Batch mode.
* Tag and Split Files::         How tagged and split files help Info
                                  to run better.
* makeinfo html::               Generating HTML output.


20.1.1 makeinfo Preferred
-------------------------

The makeinfo utility creates an Info file from a Texinfo source
file more quickly than either of the Emacs formatting commands and
provides better error messages.  We recommend it.  makeinfo is a
C program that is independent of Emacs.  You do not need to run Emacs to
use makeinfo, which means you can use makeinfo on machines
that are too small to run Emacs.  You can run makeinfo in any one
of three ways: from an operating system shell, from a shell inside
Emacs, or by typing the C-c C-m C-r or the C-c C-m C-b
command in Texinfo mode in Emacs.


The texinfo-format-region and the texinfo-format-buffer
commands are useful if you cannot run makeinfo.  Also, in some
circumstances, they format short regions or buffers more quickly than
makeinfo.

20.1.2 Running makeinfo from a Shell
------------------------------------

To create an Info file from a Texinfo file, type makeinfo
followed by the name of the Texinfo file.  Thus, to create the Info
file for Bison, type the following to the shell:

makeinfo bison.texinfo

(You can run a shell inside Emacs by typing M-x shell.)

Sometimes you will want to specify options.  For example, if you wish
to discover which version of makeinfo you are using,
type:

makeinfo --version

See makeinfo options, for more information.


20.1.3 Options for makeinfo
---------------------------

The makeinfo command takes a number of options.  Most often,
options are used to set the value of the fill column and specify the
footnote style.  Each command line option is a word preceded by
`--' or a letter preceded by `-'.  You can use abbreviations
for the long option names as long as they are unique.

For example, you could use the following shell command to create an Info
file for `bison.texinfo' in which each line is filled to only 68
columns:

makeinfo --fill-column=68 bison.texinfo

You can write two or more options in sequence, like this:

makeinfo --no-split --fill-column=70 ...

This would keep the Info file together as one possibly very long
file and would also set the fill column to 70.

The options are:

-D var
Cause the variable var to be defined.  This is equivalent to
@set var in the Texinfo file (see set clear value).

--commands-in-node-names
Allow @-commands in node names.  This is not recommended, as it
can probably never be implemented in TeX.  It also makes
makeinfo much slower.  Also, this option is ignored when
`--no-validate' is used.  See Pointer Validation, for more
details.

--docbook
Generate DocBook output rather than Info.  

--error-limit=limit
-e limit
Set the maximum number of errors that makeinfo will report
before exiting (on the assumption that continuing would be useless);
default 100.

--fill-column=width
-f width
Specify the maximum number of columns in a line; this is the right-hand
edge of a line.  Paragraphs that are filled will be filled to this
width.  (Filling is the process of breaking up and connecting lines so
that lines are the same length as or shorter than the number specified
as the fill column.  Lines are broken between words.) The default value
is 72.  Ignored with `--html'.

--footnote-style=style
-s style
Set the footnote style to style, either `end' for the end
node style (the default) or `separate' for the separate node style.
The value set by this option overrides the value set in a Texinfo file
by an @footnotestyle command (see Footnotes).  When the
footnote style is `separate', makeinfo makes a new node
containing the footnotes found in the current node.  When the footnote
style is `end', makeinfo places the footnote references at
the end of the current node.  Ignored with `--html'.

--force
-F
Ordinarily, if the input file has errors, the output files are not
created.  With this option, they are preserved.

--help
-h
Print a usage message listing all available options, then exit successfully.

--html
Generate HTML output rather than Info.  See makeinfo html.  By
default, the HTML output is split into one output file per source node,
and the split output is written into a subdirectory with the name of the
top-level info file.

-I dir
Append dir to the directory search list for finding files that
are included using the @include command.  By default,
makeinfo searches only the current directory.  If dir is
not given, the current directory `.' is appended.  Note that
dir can actually be a list of several directories separated by the
usual path separator character (`:' on Unix, `;' on
MS-DOS/MS-Windows).

--macro-expand=file
-E file
Output the Texinfo source with all the macros expanded to the named
file.  Normally, the results of macro expansion are used internally by
makeinfo and then discarded.  This option is used by
texi2dvi if you are using an old version of `texinfo.tex'
that does not support @macro.

--no-headers
For Info output, do not include menus or node separator lines in the
output.  This results in a simple plain text file that you can (for
example) send in email without complications, or include in a
distribution (as in an `INSTALL' file).

For HTML output, likewise omit menus.  And if `--no-split' is also
specified, do not include a navigation links at the top of each node
(these are never included in the default case of split output).
See makeinfo html.

In both cases, write to standard output by default (can still be
overridden by `-o').

--no-split
Suppress the splitting stage of makeinfo.  By default, large
output files (where the size is greater than 70k bytes) are split into
smaller subfiles.  For Info output, each one is approximately 50k bytes.
For HTML output, each file contains one node (see makeinfo html).

--no-pointer-validate
--no-validate
Suppress the pointer-validation phase of makeinfo.  This can also
be done with the @novalidate command (see Use TeX).  Normally, after a Texinfo file is processed, some consistency
checks are made to ensure that cross references can be resolved, etc.
See Pointer Validation.

--no-warn
Suppress warning messages (but not error messages).  You might
want this if the file you are creating has examples of Texinfo cross
references within it, and the nodes that are referenced do not actually
exist.

--number-sections
Output chapter, section, and appendix numbers as in printed manuals.

--no-number-footnotes
Suppress automatic footnote numbering.  By default, makeinfo
numbers each footnote sequentially in a single node, resetting the
current footnote number to 1 at the start of each node.

--output=file
-o file
Specify that the output should be directed to file and not to the
file name specified in the @setfilename command found in the
Texinfo source (see setfilename).  If file is `-', output
goes to standard output and `--no-split' is implied.  For split
HTML output, file is the name for the directory into which all
HTML nodes are written (see makeinfo html).

-P dir
Prepend dir to the directory search list for @include.
If dir is not given, the current directory `.' is prepended.
See `-I' for more details.

--paragraph-indent=indent
-p indent
Set the paragraph indentation style to indent.  The value set by
this option overrides the value set in a Texinfo file by an
@paragraphindent command (see paragraphindent).  The value
of indent is interpreted as follows:

`asis'
Preserve any existing indentation at the starts of paragraphs.

`0' or `none'
Delete any existing indentation.

num
Indent each paragraph by num spaces.

--reference-limit=limit
-r limit
Set the value of the number of references to a node that
makeinfo will make without reporting a warning.  If a node has more
than this number of references in it, makeinfo will make the
references but also report a warning.  The default is 1000.

-U var
Cause var to be undefined.  This is equivalent to
@clear var in the Texinfo file (see set clear value).

--verbose
Cause makeinfo to display messages saying what it is doing.
Normally, makeinfo only outputs messages if there are errors or
warnings.

--version
-V
Print the version number, then exit successfully.

--xml
Generate XML output rather than Info.  



20.1.4 Pointer Validation
-------------------------

If you do not suppress pointer validation with the `--no-validate'
option or the @novalidate command in the source file (see Use TeX), makeinfo will check the validity of the final
Info file.  Mostly, this means ensuring that nodes you have referenced
really exist.  Here is a complete list of what is checked:

1. If a `Next', `Previous', or `Up' node reference is a reference to a
node in the current file and is not an external reference such as to
`(dir)', then the referenced node must exist.

2. In every node, if the `Previous' node is different from the `Up' node,
then the node pointed to by the `Previous' field must have a `Next'
field which points back to this node.

3. Every node except the `Top' node must have an `Up' pointer.

4. The node referenced by an `Up' pointer must itself reference the current
node through a menu item, unless the node referenced by `Up'
has the form `(file)'.

5. If the `Next' reference of a node is not the same as the `Next' reference
of the `Up' reference, then the node referenced by the `Next' pointer
must have a `Previous' pointer that points back to the current node.
This rule allows the last node in a section to point to the first node
of the next chapter.

6. Every node except `Top' should be referenced by at least one other node,
either via the `Previous' or `Next' links, or via a menu or a
cross-reference.

Some Texinfo documents might fail during the validation phase because
they use commands like @value and @definfoenclose in
node definitions and cross-references inconsistently.  Consider the
following example:

@set nodename Node 1

@node @value{nodename}, Node 2, Top, Top

This is node 1.

@node Node 2, , Node 1, Top

This is node 2.

Here, the node "Node 1" was referenced both verbatim and through
@value.

By default, makeinfo fails such cases, because node names are not
fully expanded until they are written to the output file.  You should
always try to reference nodes consistently; e.g., in the above example,
the second @node line should have also used @value.
However, if, for some reason, you must reference node names
inconsistently, and makeinfo fails to validate the file, you can
use the `--commands-in-node-names' option to force makeinfo
to perform the expensive expansion of all node names it finds in the
document.  This might considerably slow down the program, though;
twofold increase in conversion time was measured for large documents
such as the Jargon file.

The support for @-commands in @node directives is not
general enough to be freely used.  For example, if the example above
redefined nodename somewhere in the document, makeinfo
will fail to convert it, even if invoked with the
`--commands-in-node-names' option.

`--commands-in-node-names' has no effect if the `--no-validate'
option is given.


20.1.5 Running makeinfo inside Emacs
------------------------------------

You can run makeinfo in GNU Emacs Texinfo mode by using either the
makeinfo-region or the makeinfo-buffer commands.  In
Texinfo mode, the commands are bound to C-c C-m C-r and C-c
C-m C-b by default.

C-c C-m C-r
M-x makeinfo-region
Format the current region for Info.

C-c C-m C-b
M-x makeinfo-buffer
Format the current buffer for Info.

When you invoke either makeinfo-region or
makeinfo-buffer, Emacs prompts for a file name, offering the
name of the visited file as the default.  You can edit the default
file name in the minibuffer if you wish, before pressing <RET> to
start the makeinfo process.

The Emacs makeinfo-region and makeinfo-buffer commands
run the makeinfo program in a temporary shell buffer.  If
makeinfo finds any errors, Emacs displays the error messages in
the temporary buffer.

You can parse the error messages by typing C-x `
(next-error).  This causes Emacs to go to and position the
cursor on the line in the Texinfo source that makeinfo thinks
caused the error.  See Running make or Compilers Generally in The GNU Emacs Manual, for more
information about using the next-error command.

In addition, you can kill the shell in which the makeinfo
command is running or make the shell buffer display its most recent
output.

C-c C-m C-k
M-x makeinfo-kill-job
Kill the current running makeinfo job
(from makeinfo-region or makeinfo-buffer).

C-c C-m C-l
M-x makeinfo-recenter-output-buffer
Redisplay the makeinfo shell buffer to display its most recent
output.

(Note that the parallel commands for killing and recentering a TeX
job are C-c C-t C-k and C-c C-t C-l.  See Texinfo Mode Printing.)

You can specify options for makeinfo by setting the
makeinfo-options variable with either the M-x
edit-options or the M-x set-variable command, or by setting the
variable in your `.emacs' initialization file.

For example, you could write the following in your `.emacs' file:

(setq makeinfo-options
      "--paragraph-indent=0 --no-split
       --fill-column=70 --verbose")

For more information, see

Editing Variable Values in The GNU Emacs Manual,

Examining and Setting Variables in The GNU Emacs Manual,

Init File in The GNU Emacs Manual, and

Options for makeinfo.

20.1.6 The texinfo-format... Commands
-------------------------------------

In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
file with the texinfo-format-region command.  This formats the
current region and displays the formatted text in a temporary buffer
called `*Info Region*'.

Similarly, you can format a buffer with the
texinfo-format-buffer command.  This command creates a new
buffer and generates the Info file in it.  Typing C-x C-s will
save the Info file under the name specified by the
@setfilename line which must be near the beginning of the
Texinfo file.

C-c C-e C-r
texinfo-format-region
Format the current region for Info.

C-c C-e C-b
texinfo-format-buffer
Format the current buffer for Info.

The texinfo-format-region and texinfo-format-buffer
commands provide you with some error checking, and other functions can
provide you with further help in finding formatting errors.  These
procedures are described in an appendix; see Catching Mistakes.
However, the makeinfo program is often faster and
provides better error checking (see makeinfo in Emacs).

20.1.7 Batch Formatting
-----------------------

You can format Texinfo files for Info using batch-texinfo-format
and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
including a shell inside of Emacs.  (See Command Line Switches and Arguments in The GNU Emacs Manual.)

Here is a shell command to format all the files that end in
`.texinfo' in the current directory:

emacs -batch -funcall batch-texinfo-format *.texinfo

Emacs processes all the files listed on the command line, even if an
error occurs while attempting to format some of them.

Run batch-texinfo-format only with Emacs in Batch mode as shown;
it is not interactive.  It kills the Batch mode Emacs on completion.

batch-texinfo-format is convenient if you lack makeinfo
and want to format several Texinfo files at once.  When you use Batch
mode, you create a new Emacs process.  This frees your current Emacs, so
you can continue working in it.  (When you run
texinfo-format-region or texinfo-format-buffer, you cannot
use that Emacs for anything else until the command finishes.)

20.1.8 Tag Files and Split Files
--------------------------------

If a Texinfo file has more than 30,000 bytes,
texinfo-format-buffer automatically creates a tag table
for its Info file;  makeinfo always creates a tag table.  With
a tag table, Info can jump to new nodes more quickly than it can
otherwise.

In addition, if the Texinfo file contains more than about 70,000
bytes, texinfo-format-buffer and makeinfo split the
large Info file into shorter indirect subfiles of about 50,000
bytes each.  Big files are split into smaller files so that Emacs does
not need to make a large buffer to hold the whole of a large Info
file; instead, Emacs allocates just enough memory for the small, split-off
file that is needed at the time.  This way, Emacs avoids wasting
memory when you run Info.  (Before splitting was implemented, Info
files were always kept short and include files were designed as
a way to create a single, large printed manual out of the smaller Info
files.  See Include Files, for more information.  Include files are
still used for very large documents, such as The Emacs Lisp
Reference Manual, in which each chapter is a separate file.)

When a file is split, Info itself makes use of a shortened version of
the original file that contains just the tag table and references to
the files that were split off.  The split-off files are called
indirect files.

The split-off files have names that are created by appending `-1',
`-2', `-3' and so on to the file name specified by the
@setfilename command.  The shortened version of the original file
continues to have the name specified by @setfilename.

At one stage in writing this document, for example, the Info file was saved
as the file `test-texinfo' and that file looked like this:

Info file: test-texinfo,    -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo

^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...

(But `test-texinfo' had far more nodes than are shown here.)  Each of
the split-off, indirect files, `test-texinfo-1',
`test-texinfo-2', and `test-texinfo-3', is listed in this file
after the line that says `Indirect:'.  The tag table is listed after
the line that says `Tag table:'. 

In the list of indirect files, the number following the file name
records the cumulative number of bytes in the preceding indirect files,
not counting the file list itself, the tag table, or the permissions
text in each file.  In the tag table, the number following the node name
records the location of the beginning of the node, in bytes from the
beginning of the (unsplit) output.

If you are using texinfo-format-buffer to create Info files,
you may want to run the Info-validate command.  (The
makeinfo command does such a good job on its own, you do not
need Info-validate.)  However, you cannot run the M-x
Info-validate node-checking command on indirect files.  For
information on how to prevent files from being split and how to
validate the structure of the nodes, see Using Info-validate.


20.1.9 Generating HTML
----------------------

Besides generating output in the Info format, you can use the
`--html' option to generate output in HTML format, for installation
on a web site (for example).  By default, the HTML output is split at
node level.

When splitting, the HTML output files are written into a subdirectory.
The subdirectory is named according to the name from
@setfilename with any extension removed; for example, HTML
output for @setfilename emacs.info would be written into a
subdirectory named `emacs'.  If that directory cannot be created
for any reason, then `.html' is appended to the directory name, as
in `emacs.html' (this is necessary because sometimes the info file
is named without an extension, e.g., `texinfo').  If the
`name.html' directory can't be created either,
makeinfo gives up.  In any case, the top-level output file within
the directory is always named `index.html'.

Monolithic output (--no-split) is named according to
@setfilename or --outfile.  Cross-document node
references are not supported in monolithic HTML.

Texinfo input marked up with the @ifhtml command will produce
output only with the `--html' option supplied.  Input marked up
with the @html is passed literally to the output (suppressing
the normal escaping of input `<', `>' and `&' characters
which have special significance in HTML).

The `--footnote-style' option is currently ignored for HTML output;
footnotes are linked to the end of the output file.

The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866).  The
exception is that HTML 3.2 tables are generated from the
@multitable command, but tagged to degrade as well as possible
in browsers without table support.  The HTML 4 `lang' attribute on
the `<html>' attribute is also used.  Please report output from an
error-free run of makeinfo which has browser portability problems
as a bug.

Navigation bars are inserted at the start of nodes, similarly to Info
output.  The `--no-headers' option will suppress this if used with
`--no-split'.  Header <link> elements in split output can
support info-like navigation with browsers like Lynx and Emacs W3
which implement this HTML 1.0 feature.  `@xref' commands to
other documents are generated assuming the other document is available
in split HTML form, and installed in the same HTML documentation tree,
at `../<info-document>/'.


20.2 Installing an Info File
============================

Info files are usually kept in the `info' directory.  You can read
Info files using the standalone Info program or the Info reader built
into Emacs.  (See (info)info, for an introduction to Info.)

* Directory File::              The top level menu for all Info files.
* New Info File::               Listing a new Info file.
* Other Info Directories::      How to specify Info files that are
                                  located in other directories.
* Installing Dir Entries::      How to specify what menu entry to add
                                  to the Info directory.
* Invoking install-info::       install-info options.


20.2.1 The Directory File `dir'
-------------------------------

For Info to work, the `info' directory must contain a file that
serves as a top level directory for the Info system.  By convention,
this file is called `dir'.  (You can find the location of this file
within Emacs by typing C-h i to enter Info and then typing
C-x C-f to see the pathname to the `info' directory.)

The `dir' file is itself an Info file.  It contains the top level
menu for all the Info files in the system.  The menu looks like
this:

* Menu:
* Info:    (info).     Documentation browsing system.
* Emacs:   (emacs).    The extensible, self-documenting
                       text editor.
* Texinfo: (texinfo).  With one source file, make
                       either a printed manual using
                       @TeX{} or an Info file.
...

Each of these menu entries points to the `Top' node of the Info file
that is named in parentheses.  (The menu entry does not need to
specify the `Top' node, since Info goes to the `Top' node if no node
name is mentioned.  See Nodes in Other Info Files.)

Thus, the `Info' entry points to the `Top' node of the
`info' file and the `Emacs' entry points to the `Top' node
of the `emacs' file.

In each of the Info files, the `Up' pointer of the `Top' node refers
back to the dir file.  For example, the line for the `Top'
node of the Emacs manual looks like this in Info:

File: emacs  Node: Top, Up: (DIR), Next: Distrib

In this case, the `dir' file name is written in upper case
letters--it can be written in either upper or lower case.  This is not
true in general, it is a special case for `dir'.


20.2.2 Listing a New Info File
------------------------------

To add a new Info file to your system, you must write a menu entry to
add to the menu in the `dir' file in the `info' directory.
For example, if you were adding documentation for GDB, you would write
the following new entry:

* GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a
colon.  The second part is the name of the Info file, in parentheses,
followed by a period.  The third part is the description.

The name of an Info file often has a `.info' extension.  Thus, the
Info file for GDB might be called either `gdb' or `gdb.info'.
The Info reader programs automatically try the file name both with and
without `.info'(11); so it is better to avoid
clutter and not to write `.info' explicitly in the menu entry.  For
example, the GDB menu entry should use just `gdb' for the file
name, not `gdb.info'.


20.2.3 Info Files in Other Directories
--------------------------------------

If an Info file is not in the `info' directory, there are three
ways to specify its location:

1. Write the pathname in the `dir' file as the second part of the menu.

2. If you are using Emacs, list the name of the file in a second `dir'
file, in its directory; and then add the name of that directory to the
Info-directory-list variable in your personal or site
initialization file.

This variable tells Emacs where to look for `dir' files (the files
must be named `dir').  Emacs merges the files named `dir' from
each of the listed directories.  (In Emacs version 18, you can set the
Info-directory variable to the name of only one
directory.)

3. Specify the Info directory name in the INFOPATH environment
variable in your `.profile' or `.cshrc' initialization file.
(Only you and others who set this environment variable will be able to
find Info files whose location is specified this way.)

For example, to reach a test file in the `/home/bob/info'
directory, you could add an entry like this to the menu in the
standard `dir' file:

* Test: (/home/bob/info/info-test).  Bob's own test file.

In this case, the absolute file name of the `info-test' file is
written as the second part of the menu entry.

Alternatively, you could write the following in your `.emacs' file:

(require 'info)
(setq Info-directory-list
  (cons (expand-file-name "/home/bob/info")
        Info-directory-list))

This tells Emacs to merge the system `dir' file with the `dir'
file in `/home/bob/info'.  Thus, Info will list the
`/home/bob/info/info-test' file as a menu entry in the
`/home/bob/info/dir' file.  Emacs does the merging only when
M-x info is first run, so if you want to set
Info-directory-list in an Emacs session where you've already run
info, you must (setq Info-dir-contents nil) to force Emacs
to recompose the `dir' file.

Finally, you can tell Info where to look by setting the INFOPATH
environment variable in your shell startup file, such as `.cshrc',
`.profile' or `autoexec.bat'.  If you use a Bourne-compatible
shell such as sh or bash for your shell command
interpreter, you set the INFOPATH environment variable in the
`.profile' initialization file; but if you use csh or
tcsh, you set the variable in the `.cshrc' initialization
file.  On MS-DOS/MS-Windows systems, you must set INFOPATH in
your `autoexec.bat' file or in the Registry.  Each type of shell
uses a different syntax.

* In a `.cshrc' file, you could set the INFOPATH
variable as follows:

setenv INFOPATH .:~/info:/usr/local/emacs/info

* In a `.profile' file, you would achieve the same effect by
writing:

INFOPATH=.:$HOME/info:/usr/local/emacs/info
export INFOPATH

* In a `autoexec.bat' file, you write this command(12):

set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info

The `.' indicates the current directory as usual.  Emacs uses the
INFOPATH environment variable to initialize the value of Emacs's
own Info-directory-list variable.  The stand-alone Info reader
merges any files named `dir' in any directory listed in the
INFOPATH variable into a single menu presented to you in the node
called `(dir)Top'.

However you set INFOPATH, if its last character is a
colon(13), this
is replaced by the default (compiled-in) path.  This gives you a way to
augment the default path with new directories without having to list all
the standard places.  For example (using sh syntax):

INFOPATH=/local/info:
export INFOPATH

will search `/local/info' first, then the standard directories.
Leading or doubled colons are not treated specially.

When you create your own `dir' file for use with
Info-directory-list or INFOPATH, it's easiest to start by
copying an existing `dir' file and replace all the text after the
`* Menu:' with your desired entries.  That way, the punctuation and
special CTRL-_ characters that Info needs will be present.


20.2.4 Installing Info Directory Files
--------------------------------------

When you install an Info file onto your system, you can use the program
install-info to update the Info directory file `dir'.
Normally the makefile for the package runs install-info, just
after copying the Info file into its proper installed location.

In order for the Info file to work with install-info, you include
the commands @dircategory and
@direntry...@end direntry in the Texinfo source
file.  Use @direntry to specify the menu entries to add to the
Info directory file, and use @dircategory to specify which part
of the Info directory to put it in.  Here is how these commands are used
in this manual:

@dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
@end direntry

Here's what this produces in the Info file:

INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
END-INFO-DIR-ENTRY

The install-info program sees these lines in the Info file, and
that is how it knows what to do.

Always use the @direntry and @dircategory commands near
the beginning of the Texinfo input, before the first @node
command.  If you use them later on in the input, install-info
will not notice them.

If you use @dircategory more than once in the Texinfo source,
each usage specifies the `current' category; any subsequent
@direntry commands will add to that category.  

Here are some recommended @dircategory categories:

GNU packages
GNU programming tools
GNU programming documentation
GNU Emacs Lisp
GNU libraries
TeX
Individual utilities

The idea is to include the `Invoking' node for every program installed
by a package under `Individual utilities', and an entry for the manual
as a whole in the appropriate other category.


20.2.5 Invoking install-info
----------------------------


install-info inserts menu entries from an Info file into the
top-level `dir' file in the Info system (see the previous sections
for an explanation of how the `dir' file works).  It's most often
run as part of software installation, or when constructing a `dir' file
for all manuals on a system.  Synopsis:

install-info [option]... [info-file [dir-file]]

If info-file or dir-file are not specified, the options
(described below) that define them must be.  There are no compile-time
defaults, and standard input is never used.  install-info can
read only one Info file and write only one `dir' file per invocation.

If dir-file (however specified) does not exist,
install-info creates it if possible (with no entries).

If any input file is compressed with gzip (see Invoking gzip in Gzip), install-info automatically uncompresses it
for reading.  And if dir-file is compressed, install-info
also automatically leaves it compressed after writing any changes.
If dir-file itself does not exist, install-info tries to
open `dir-file.gz'.

Options:

--delete
Delete the entries in info-file from dir-file.  The file
name in the entry in dir-file must be info-file (except for
an optional `.info' in either one).  Don't insert any new entries.

--dir-file=name
-d name
Specify file name of the Info directory file.  This is equivalent to
using the dir-file argument.

--entry=text
-e text
Insert text as an Info directory entry; text should have the
form of an Info menu item line plus zero or more extra lines starting
with whitespace.  If you specify more than one entry, they are all
added.  If you don't specify any entries, they are determined from
information in the Info file itself.

--help
-h
Display a usage message listing basic usage and all available options,
then exit successfully.

--info-file=file
-i file
Specify Info file to install in the directory.
Equivalent to using the info-file argument.

--info-dir=dir
-D dir
Specify the directory where `dir' resides.
Equivalent to `--dir-file=dir/dir'.

--item=text
Same as `--entry=text'.  An Info directory entry is actually
a menu item.

--quiet
Suppress warnings.

--remove
-r
Same as `--delete'.

--section=sec
-s sec
Put this file's entries in section sec of the directory.  If you
specify more than one section, all the entries are added in each of the
sections.  If you don't specify any sections, they are determined from
information in the Info file itself.

--version
-V
Display version information and exit successfully.



