[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

E.1 How to Use Include Files  How to use the @include command.
E.2 texinfo-multiple-files-update  How to create and update nodes and menus when using included files.
E.3 Include File Requirements  What texinfo-multiple-files-update expects.
E.4 Sample File with @include  A sample outer file with included files within it; and a sample included file.
E.5 Evolution of Include Files  How use of the @include command has changed over time.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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 Emacs 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 GNU Emacs Texinfo mode command, texinfo-multiple-files-update, that is designed for @include files.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

E.2 texinfo-multiple-files-update

GNU Emacs 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:

C-u M-x texinfo-multiple-files-update
Called with C-u as a prefix argument:

C-u 8 M-x texinfo-multiple-files-update
Called with a numeric prefix argument, such as C-u 8:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

E.3 Include File 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

E.4 Sample File with @include

Here is an example of a complete 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

@setchapternewpage odd
@titlepage
@sp 12
@center @titlefont{Include Example}
@sp 2
@center by Whom Ever

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998 Free Software Foundation, Inc.
@end titlepage

@ifinfo
@node Top, First, , (dir)
@top Master Menu
@end ifinfo

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

@summarycontents
@contents

@bye

An included file, such as `foo.texinfo', might look like this:

 
@node First, Second, , Top
@chapter First Chapter

Contents of first chapter ...

The full contents of `concept-index.texinfo' might be as simple as this:

 
@node Concept Index, , Second, Top
@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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

E.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 Emacs did not need to make a large buffer to hold the whole of a large Info file when someone wanted information; instead, Emacs allocated just enough memory for the small Info file that contained the particular information sought. This way, Emacs 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.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs Webmaster on July, 12 2002 using texi2html