21. Creating and Installing Info Files

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

21.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 XEmacs functions that convert Texinfo to Info.

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

21.1.1 makeinfo Preferred

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

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.

21.1.2 Running makeinfo from a Shell

To create an Info file from a Texinfo file, invoke 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 XEmacs by typing M-x shell.)

makeinfo has many options to control its actions and output; see the next section.

You can give makeinfo more than one input file name; each is processed in turn. If an input file name is ‘-’, or no input file names are given at all, standard input is read.

21.1.3 Options for makeinfo

The makeinfo program accepts many options. Perhaps the most commonly needed are those that change the output format. By default, makeinfo outputs Info files.

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 section @set, @clear, and @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 section Pointer Validation, for more details.

--css-include=file

Include the contents of file, which should contain cascading style sheets specifications, in the ‘<style>’ block of the HTML output. See section HTML CSS. If file is ‘-’, read standard input.

--css-ref=url

In HTML mode, add a ‘<link>’ tag to the HTML output which references a cascading style sheet at url. This allows using standalone style sheets.

--disable-encoding

--enable-encoding

By default, or with ‘--enable-encoding’, output accented and special characters in Info or plain text output based on ‘@documentencoding’. With ‘--disable-encoding’, 7-bit ASCII transliterations are output. See section documentencoding, and Inserting Accents.

--docbook

Generate Docbook output rather than Info.

--document-language=lang

Use lang to translate Texinfo keywords which end up in the output document. The default is the locale specified by the @documentlanguage command if there is one (see section @documentlanguage ll[_cc]: Set the Document Language).

--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 section 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 section Generating HTML. By default, the HTML output is split into one output file per Texinfo 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).

--ifdocbook

--ifhtml

--ifinfo

--ifplaintext

--iftex

--ifxml

For the specified format, process ‘@ifformat’ and ‘@format’ commands even if not generating the given output format. For instance, if ‘--iftex’ is specified, then ‘@iftex’ and ‘@tex’ blocks will be read.

--internal-links=file

In HTML mode, output a tab separated file containing three columns: the internal link to an indexed item or item in the table of contents, the name of the index (or "toc") in which it occurs, and the term which was indexed or entered.

--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.

--no-headers

--plaintext

Do not include menus or node separator lines in the output, and implicitly ‘--enable-encoding’ (see above). 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 section Generating HTML.

In both cases, ignore @setfilename and write to standard output by default—can be overridden with ‘-o’.

--no-ifdocbook

--no-ifhtml

--no-ifinfo

--no-ifplaintext

--no-iftex

--no-ifxml

Do not process ‘@ifformat’ and ‘@format’ commands, and do process ‘@ifnotformat’, even if generating the given format. For instance, if ‘--no-ifhtml’ is specified, then ‘@ifhtml’ and ‘@html’ blocks will not be read, and ‘@ifnothtml’ blocks will be.

--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.

--no-number-sections

Do not output chapter, section, and appendix numbers. You need to specify this if your manual is not hierarchically-structured.

--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 section Generating HTML).

--no-pointer-validate

--no-validate

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

--no-warn

Suppress warning messages (but not error messages).

--number-sections

Output chapter, section, and appendix numbers as in printed manuals. This is the default. It works only with hierarchically-structured manuals.

--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 section @setfilename: Set the output file name). 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 section Generating 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 section @paragraphindent: Paragraph Indenting). 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.

--split-size=num

Keep Info files to at most num characters; default is 300,000.

--transliterate-file-names

Enable transliteration of 8-bit characters in node names for the purpose of file name creation. See section HTML Cross-reference 8-bit Character Expansion.

-U var

Cause var to be undefined. This is equivalent to @clear var in the Texinfo file (see section @set, @clear, and @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.

makeinfo also reads the environment variable TEXINFO_OUTPUT_FORMAT to determine the output format, if not overridden by a command line option. The possible values are:

docbook  html  info  plaintext  xml

If not set, Info output is the default.

21.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 section 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. (Your best bet is to avoid using @-commands in node names.) 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.

21.1.5 Running makeinfo Within XEmacs

You can run makeinfo in XEmacs 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 makeinfo-region the output goes to a temporary buffer. When you invoke makeinfo-buffer output goes to the file set with @setfilename (see section @setfilename: Set the output file name).

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

You can parse the error messages by typing C-x ` (next-error). This causes XEmacs to go to and position the cursor on the line in the Texinfo source that makeinfo thinks caused the error. See (xemacs)Compilation section ‘Running make or Compilers Generally’ in XEmacs User’s 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 section Formatting and Printing in Texinfo Mode.)

You can specify options for makeinfo by setting the makeinfo-options variable with either the M-x customize or the M-x set-variable command, or by setting the variable in your ‘init.el’ initialization file.

For example, you could write the following in your ‘init.el’ file:

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

For more information, see
(xemacs)Easy Customization section ‘Easy Customization Interface’ in XEmacs User’s Manual,
(xemacs)Examining section ‘Examining and Setting Variables’ in XEmacs User’s Manual,
(xemacs)Init File section ‘Init File’ in XEmacs User’s Manual, and
Options for makeinfo.

21.1.6 The texinfo-format… Commands

In XEmacs 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 Formatting Mistakes. However, the makeinfo program is often faster and provides better error checking (see section Running makeinfo Within XEmacs).

21.1.7 Batch Formatting

You can format Texinfo files for Info using batch-texinfo-format and XEmacs Batch mode. You can run XEmacs in Batch mode from any shell, including a shell inside of XEmacs. (See (xemacs)Command Arguments section ‘Command Arguments’ in XEmacs User’s Manual.)

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

xemacs -batch -funcall batch-texinfo-format *.texinfo

XEmacs 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 XEmacs in Batch mode as shown; it is not interactive. It kills the Batch mode XEmacs 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 XEmacs process. This frees your current XEmacs, so you can continue working in it. (When you run texinfo-format-region or texinfo-format-buffer, you cannot use that XEmacs for anything else until the command finishes.)

21.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 300,000 bytes, texinfo-format-buffer and makeinfo split the large Info file into shorter indirect subfiles of about 300,000 bytes each. Big files are split into smaller files so that XEmacs does not need to make a large buffer to hold the whole of a large Info file; instead, XEmacs allocates just enough memory for the small, split-off file that is needed at the time. This way, XEmacs 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 section Include Files, for more information. Include files are still used for very large documents, such as The XEmacs 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 Running Info-validate.

21.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 XEmacs. (See info: (info)Top, for an introduction to Info.)

21.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 XEmacs 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.
* XEmacs:  (xemacs).   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 section Nodes in Other Info Files.)

Thus, the ‘Info’ entry points to the ‘Top’ node of the ‘info’ file and the ‘XEmacs’ entry points to the ‘Top’ node of the ‘xemacs’ 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 XEmacs manual looks like this in Info:

File: xemacs  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’.

21.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’(10); 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’.

21.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 XEmacs, 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 XEmacs where to look for ‘dir’ files (the files must be named ‘dir’). XEmacs merges the files named ‘dir’ from each of the listed directories. (In XEmacs 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 ‘init.el’ file:

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

This tells XEmacs 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. XEmacs does the merging only when M-x info is first run, so if you want to set Info-directory-list in an XEmacs session where you’ve already run info, you must (setq Info-dir-contents nil) to force XEmacs 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/xemacs/info

• In a ‘.profile’ file, you would achieve the same effect by writing:

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

• In a ‘autoexec.bat’ file, you write this command(11):

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

The ‘.’ indicates the current directory as usual. XEmacs uses the INFOPATH environment variable to initialize the value of XEmacs’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(12), 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.

21.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.

install-info will automatically reformat the description of the menu entries it is adding. As a matter of convention, the description of the main entry (above, ‘The GNU documentation format’) should start at column 32, starting at zero (as in what-cursor-position in XEmacs). This will make it align with most others. Description for individual utilities best start in column 48, where possible. For more information about formatting see the ‘--calign’, ‘--align’, and ‘--max-width’ options in Invoking install-info.

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.

When choosing a category name for the @dircategory command, we recommend consulting the Free Software Directory. If your program is not listed there, or listed incorrectly or incompletely, please report the situation to the directory maintainers (bug-directory@gnu.org) so that the category names can be kept in sync.

Here are a few examples (see the ‘util/dir-example’ file in the Texinfo distribution for large sample dir file):

XEmacs
Localization
Printing
Software development
Software libraries
Text creation and manipulation

Each ‘Invoking’ node for every program installed should have a corresponding @direntry. This lets users easily find the documentation for the different programs they can run, as with the traditional man system.

21.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). install-info also removes menu entries from the ‘dir’ file. 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 (gzip)Top section ‘Top’ 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’, ‘dir-file.bz2’, and ‘dir-file.lzma’, in that order.

Options:

--add-once

Specifies that the entry or entries will only be put into a single section.

--align=column

Specifies the column that the second and subsequent lines of menu entry’s description will be formatted to begin at. The default for this option is ‘35’. It is used in conjunction with the ‘--max-width’ option. column starts counting at 1.

--append-new-sections

Instead of alphabetizing new sections, place them at the end of the DIR file.

--calign=column

Specifies the column that the first line of menu entry’s description will be formatted to begin at. The default for this option is ‘33’. It is used in conjunction with the ‘--max-width’ option. When the name of the menu entry exceeds this column, entry’s description will start on the following line. column starts counting at 1.

--debug

Report what is being done.

--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. Any empty sections that result from the removal are also removed.

--description=text

Specify the explanatory portion of the menu entry. If you don’t specify a description (either via ‘--entry’, ‘--item’ or this option), the description is taken from the Info file itself.

--dir-file=name

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

--dry-run

Same as ‘--test’.

--entry=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

Display a usage message with basic usage and all available options, then exit successfully.

--info-file=file

Specify Info file to install in the directory. This is equivalent to using the info-file argument.

--info-dir=dir

Specify the directory where the directory file ‘dir’ resides. Equivalent to ‘--dir-file=dir/dir’.

--infodir=dir

Same as ‘--info-dir’.

--item=text

Same as ‘--entry=text’. An Info directory entry is actually a menu item.

--keep-old

Do not replace pre-existing menu entries. When ‘--remove’ is specified, this option means that empty sections are not removed.

--max-width=column

Specifies the column that the menu entry’s description will be word-wrapped at. column starts counting at 1.

--maxwidth=column

Same as ‘--max-width’.

--menuentry=text

Same as ‘--name’.

--name=text

Specify the name portion of the menu entry. If the text does not start with an asterisk ‘*’, it is presumed to be the text after the ‘*’ and before the parentheses that specify the Info file. Otherwise text is taken verbatim, and is taken as defining the text up to and including the first period (a space is appended if necessary). If you don’t specify the name (either via ‘--entry’, ‘--item’ or this option), it is taken from the Info file itself. If the Info does not contain the name, the basename of the Info file is used.

--no-indent

Suppress formatting of new entries into the ‘dir’ file.

--quiet

--silent

Suppress warnings, etc., for silent operation.

--remove

Same as ‘--delete’.

--remove-exactly

Also like ‘--delete’, but only entries if the Info file name matches exactly; .info and/or .gz suffixes are not ignored.

--section=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. If the Info file doesn’t specify a section, the menu entries are put into the Miscellaneous section.

--section regex sec

Same as ‘--regex=regex --section=sec --add-once’.

install-info tries to detect when this alternate syntax is used, but does not always guess correctly. Here is the heuristic that install-info uses:

1. If the second argument to --section starts with a hyphen, the original syntax is presumed.
2. If the second argument to --section is a file that can be opened, the original syntax is presumed.
3. Otherwise the alternate syntax is used.

When heuristic fails because your section title starts with a hyphen, or it happens to be a filename that can be opened, the syntax should be changed to ‘--regex=regex --section=sec --add-once’.

--regex=regex

Put this file’s entries into any section that matches regex. If more than one section matches, all of the entries are added in each of the sections. Specify regex using basic regular expression syntax, more or less as used with grep, for example.

--test

Suppress updating of the directory file.

--version

Display version information and exit successfully.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.