D. Include Files

When TeX or an Info formatting command sees an @include command in a Texinfo file, it processes the contents of the file named by the command and incorporates them into the DVI or Info file being created. Index entries from the included file are incorporated into the indices of the output file.

Include files let you keep a single large document as a collection of conveniently small parts.

D.1 How to Use Include Files

To include another file within a Texinfo file, write the @include command at the beginning of a line and follow it on the same line by the name of a file to be included. For example:

@include buffers.texi

The name of the file is taken literally, with a single exception: @value{var} references are expanded. This makes it possible to reliably include files in other directories in a distribution. See section @verbatiminclude, for an example.

An included file should simply be a segment of text that you expect to be included as is into the overall or outer Texinfo file; it should not contain the standard beginning and end parts of a Texinfo file. In particular, you should not start an included file with a line saying ‘\input texinfo’; if you do, that phrase is inserted into the output file as is. Likewise, you should not end an included file with an @bye command; nothing after @bye is formatted.

In the past, you were required to write an @setfilename line at the beginning of an included file, but no longer. Now, it does not matter whether you write such a line. If an @setfilename line exists in an included file, it is ignored.

Conventionally, an included file begins with an @node line that is followed by an @chapter line. Each included file is one chapter. This makes it easy to use the regular node and menu creating and updating commands to create the node pointers and menus within the included file. However, the simple XEmacs node and menu creating and updating commands do not work with multiple Texinfo files. Thus you cannot use these commands to fill in the ‘Next’, ‘Previous’, and ‘Up’ pointers of the @node line that begins the included file. Also, you cannot use the regular commands to create a master menu for the whole file. Either you must insert the menus and the ‘Next’, ‘Previous’, and ‘Up’ pointers by hand, or you must use the XEmacs Texinfo mode command, texinfo-multiple-files-update, that is designed for @include files.

When an included file does not have any node lines in it, the multiple files update command does not try to create a menu entry for it. Consequently, you can include any file, such as a version or an update file without node lines, not just files that are chapters. Small includable files like this are created by Automake (see section GNU Sample Texts).

D.2 texinfo-multiple-files-update

XEmacs Texinfo mode provides the texinfo-multiple-files-update command. This command creates or updates ‘Next’, ‘Previous’, and ‘Up’ pointers of included files as well as those in the outer or overall Texinfo file, and it creates or updates a main menu in the outer file. Depending whether you call it with optional arguments, the command updates only the pointers in the first @node line of the included files or all of them:

M-x texinfo-multiple-files-update

Called without any arguments:

• - Create or update the ‘Next’, ‘Previous’, and ‘Up’ pointers of the first @node line in each file included in an outer or overall Texinfo file.
• - Create or update the ‘Top’ level node pointers of the outer or overall file.
• - Create or update a main menu in the outer file.

C-u M-x texinfo-multiple-files-update

Called with C-u as a prefix argument:

• - Create or update pointers in the first @node line in each included file.
• - Create or update the ‘Top’ level node pointers of the outer file.
• - Create and insert a master menu in the outer file. The master menu is made from all the menus in all the included files.

C-u 8 M-x texinfo-multiple-files-update

Called with a numeric prefix argument, such as C-u 8:

• - Create or update all the ‘Next’, ‘Previous’, and ‘Up’ pointers of all the included files.
• - Create or update all the menus of all the included files.
• - Create or update the ‘Top’ level node pointers of the outer or overall file.
• - And then create a master menu in the outer file. This is similar to invoking texinfo-master-menu with an argument when you are working with just one file.

Note the use of the prefix argument in interactive use: with a regular prefix argument, just C-u, the texinfo-multiple-files-update command inserts a master menu; with a numeric prefix argument, such as C-u 8, the command updates every pointer and menu in all the files and then inserts a master menu.

D.3 Include Files Requirements

If you plan to use the texinfo-multiple-files-update command, the outer Texinfo file that lists included files within it should contain nothing but the beginning and end parts of a Texinfo file, and a number of @include commands listing the included files. It should not even include indices, which should be listed in an included file of their own.

Moreover, each of the included files must contain exactly one highest level node (conventionally, @chapter or equivalent), and this node must be the first node in the included file. Furthermore, each of these highest level nodes in each included file must be at the same hierarchical level in the file structure. Usually, each is an @chapter, an @appendix, or an @unnumbered node. Thus, normally, each included file contains one, and only one, chapter or equivalent-level node.

The outer file should contain only one node, the ‘Top’ node. It should not contain any nodes besides the single ‘Top’ node. The texinfo-multiple-files-update command will not process them.

D.4 Sample File with @include

Here is an example of an outer Texinfo file with @include files within it before running texinfo-multiple-files-update, which would insert a main or master menu:

\input texinfo @c -*-texinfo-*-
@setfilename include-example.info
@settitle Include Example

... See section Sample Texinfo Files, for
examples of the rest of the frontmatter ...

@ifnottex
@node Top
@top Include Example
@end ifnottex

@include foo.texinfo
@include bar.texinfo
@include concept-index.texinfo
@bye

An included file, such as ‘foo.texinfo’, might look like this:

@node First
@chapter First Chapter

Contents of first chapter …

The full contents of ‘concept-index.texinfo’ might be as simple as this:

@node Concept Index
@unnumbered Concept Index

@printindex cp

The outer Texinfo source file for The XEmacs Lisp Reference Manual is named ‘elisp.texi’. This outer file contains a master menu with 417 entries and a list of 41 @include files.

D.5 Evolution of Include Files

When Info was first created, it was customary to create many small Info files on one subject. Each Info file was formatted from its own Texinfo source file. This custom meant that XEmacs did not need to make a large buffer to hold the whole of a large Info file when someone wanted information; instead, XEmacs allocated just enough memory for the small Info file that contained the particular information sought. This way, XEmacs could avoid wasting memory.

References from one file to another were made by referring to the file name as well as the node name. (See section Referring to Other Info Files. Also, see @xref with Four and Five Arguments.)

Include files were designed primarily as a way to create a single, large printed manual out of several smaller Info files. In a printed manual, all the references were within the same document, so TeX could automatically determine the references’ page numbers. The Info formatting commands used include files only for creating joint indices; each of the individual Texinfo files had to be formatted for Info individually. (Each, therefore, required its own @setfilename line.)

However, because large Info files are now split automatically, it is no longer necessary to keep them small.

Nowadays, multiple Texinfo files are used mostly for large documents, such as The XEmacs Lisp Reference Manual, and for projects in which several different people write different sections of a document simultaneously.

In addition, the Info formatting commands have been extended to work with the @include command so as to create a single large Info file that is split into smaller files if necessary. This means that you can write menus and cross references without naming the different Texinfo files.

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