Texinfo

The GNU Documentation Format

by Richard M. Stallman and Robert J. Chassell

Edition 1.1

May 1988

Copyright © 1988 Free Software Foundation, Inc.

This is version 1.1 of the Texinfo documentation, and is for
the Texinfo that is distributed as part of Version 18 of GNU Emacs.

Published by the Free Software Foundation
675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Printed copies are available for $10 each.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Indices, nodes containing large menus

A detailed node listing

Overview

Using Texinfo Mode

Beginning a Texinfo File.

Ending a Texinfo File

Node and Chapter Structuring

Making quotations and examples

Making lists and two column tables

Making Cross References

Formatting Paragraphs

Breaks, Blank Lines and Groups

Marking Text Within a Paragraph

Inserting Braces, ‘@’ and Periods

Emphasizing Text

Creating an Info File

Catching Mistakes

Finding badly referenced nodes

Appendices

Licensing Information

The programs currently being distributed that relate to Texinfo include two portions of GNU Emacs, plus two other separate programs (texindex and texinfo.tex). These programs are free; this means that everyone is free to use them and free to redistribute them on a free basis. The Texinfo related programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the programs that relate to Texinfo, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the Texinfo related programs, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to Texinfo. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public Licenses that accompany them. The programs that are part of GNU Emacs are covered by the GNU Emacs copying terms (see License in The GNU Emacs Manual), and other programs are covered by licenses that are contained in their source files.

1 Overview of Texinfo

Texinfo is a documentation system that uses a single source file for both on-line help and a printed manual. This means that instead of writing two different documents, one for the on-line help and the other for the printed manual, only one document needs to be written. When the system is revised, only one file has to be revised.

Using Texinfo, you can create a document with the normal features of a book such as chapters, sections, cross references and indices. The chapters and sections of the printed manual can be made to correspond to the nodes of the on-line help. The cross references and indices can be used in both the on-line help and in the printed document. Indices are generated semi-automatically. The GNU Emacs Manual is a good example of a Texinfo file.

To make the printed manual, the Texinfo source file is processed by the TeX typesetting program; the resulting DVI file can be typeset and printed as a book. To make the on-line help, the Texinfo source file is by processed the M-x texinfo-format-buffer command; the resulting Info file is installed in the ‘info’ directory.

Since the Texinfo source file is used for a dual task—to create both the on-line help and the printed manual—it must be written in a special format that uses @-commands (words preceded by an ‘@’) to indicate chapters, sections, nodes, examples, index entries and the like.

Before writing a Texinfo source file, you should be familiar with the on-line Info documentation reading program. (See (info)info, for more information.) If you are writing a document that will be both on-line and printed, you will need both Info and TeX.

To make an Info file, you use the M-x texinfo-format-buffer command in GNU Emacs.

To make a printed manual, you need to use TeX, a powerful, sophisticated typesetting program written by Donald Knuth. TeX is freely distributable. It is written in a dialect of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the TeX distribution) in C. (For information about getting TeX, see TeX Mode in The GNU Emacs Manual)

When TeX processes a Texinfo source file, TeX makes use of a macro definitions file called ‘texinfo.tex’ that comes with the GNU Emacs distribution in the ‘emacs/man’ sources directory. (The first line of every Texinfo file has a command that says \input texinfo; this tells TeX to use the ‘texinfo.tex’ file.)

If the ‘texinfo.tex’ file has not already been copied to the directory which contains the other TeX macro definition files when Emacs was installed, you will probably want to copy it to that directory. Usually, this is the ‘/usr/lib/tex/macros’ directory. For more information, see section TeX Input Initialization

Documentation for GNU utilities and libraries should be written in Texinfo format.

1.1 Characteristics of the Info file

A Texinfo file can be transformed into a printed manual and an on-line Info file.

An on-line Info file is a file formatted so that the Info documentation reading program can operate on it. Info files are divided into pieces called nodes, each of which contains the discussion of one topic. Each node has a name, and contains both text for the user to read and pointers to other nodes, which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to the other nodes to which the current node points.

Normally, most of the nodes are arranged in a tree which branches down. Each node may have any number of child nodes that describe subtopics of the node’s topic. The names of these child nodes, if any, are listed in a menu within the parent node; this allows certain Info commands to be used to move to one of the child nodes. Each child node records the parent node name, as its ‘Up’ pointer. Thus, if a node were at the logical level of a ‘chapter’, its child nodes would be ‘sections’; likewise, the child nodes of a section would be subsections.

The root of the tree is the top node of the file, through which users enter the file from the Info directory. By convention, this node is always called ‘Top’. This node normally contains just a brief summary of the file’s purpose, and a large menu through which the rest of the file is reached.

Generally you enter the Info file from the top; then you can either traverse the file systematically by going from node to node or you can search large menus that correspond to indices and go directly to the node that has the information you want.

If you want to read through an Info file in sequence, as if it were a printed manual, you can get the whole file with the advanced Info command g *. (See (info)info.)

All the children of any one parent are linked together in a bidirectional chain of ‘Next’ and ‘Previous’ pointers. This means that all the nodes that are logically parallel to sections within a chapter are all linked together. Normally the order in this chain is the same as the order of the children in the parent’s menu. The last child has no ‘Next’ pointer, and the first child normally has the parent as its ‘Previous’ pointer (as well as its ‘Up’ pointer, of course).

Structuring the nodes in a tree is a matter of convention, not a requirement. In fact, the ‘Up’, ‘Previous’ and ‘Next’ pointers of a node can point to any other nodes, and the menu can contain any other nodes. The structure of nodes can be any directed graph. But it is usually more comprehensible to make it a tree. Info provides another kind of pointer between nodes, called a reference, that can be sprinkled through the text of a node. This is usually the best way to represent links that do not fit the tree structure.

Most often the nodes fall into a strict tree structure that corresponds to the structure of chapters and sections in the printed manual. But there are times when this is not right for the material being discussed. Therefore, Texinfo uses separate commands to specify the node structure of the Info file and the section structure of the printed manual. Also, Texinfo requires that you specify menus explicitly, rather than generate them automatically based on an assumed tree structure.

1.2 Characteristics of the Printed Manual

A Texinfo file can be formatted and typeset as a printed manual. The printed manual will be the same as any other book; it will have a title page, copyright page, table of contents, and preface as you would expect, as well as chapters, numbered or unnumbered sections and subsections, not to mention page headers, cross references and indices.

Texinfo can be used for writing a book without ever having the intention of converting it into on-line help. Texinfo can be used for writing a novel; and it can even be used to write a memo, although this application is not recommended since electronic mail is so much easier.

Texinfo uses the formatting language called TeX for typesetting. A file called ‘texinfo.tex’ contains information (definitions or macros) that TeX uses when it typesets a Texinfo file. (The macros tell TeX how to convert the Texinfo @-commands to TeX commands which TeX can then process to create the typeset document.) ‘texinfo.tex’ contains the specifications for printing a document, either with 7 inch by 9.25 inch pages or with 8.5 inch by 11 inch pages. (This is 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the parameters in ‘texinfo.tex’ you can easily change the size of the printed document. In addition, you can readily change the style in which the printed document is formatted; for example, you can change the sizes and fonts used, the amount of indentation for each paragraph, the degree to which words are hyphenated, and the like. By changing the specifications, you can make a book look dignified, old and serious, or light-hearted, young and cheery.

TeX is very powerful and has a great many features. Because a Texinfo file must be able to present information both on a character-only terminal in Info form and in a typeset book, the commands that Texinfo supports are necessarily limited.

1.3 General Syntactic Conventions

Texinfo files contain a strictly limited set of constructs. The strict limits make it possible for Texinfo files to be understood both by TeX and by the code which converts them into Info files.

All ASCII printing characters except ‘@’, ‘{’ and ‘}’ can appear in body text in a Texinfo file and stand for themselves. ‘@’ is the escape character which introduces commands. ‘{’ and ‘}’ should be used only to surround arguments to certain commands. ‘{’ and ‘}’ appearing anywhere else will be treated by TeX as a grouping but treated by the code that produces an Info file as themselves; this inconsistency is undesirable, so don’t let it occur. To put one of these special characters into the document, put an ‘@’ character in front of it. For example, you would insert ‘@@’, ‘@{’, and ‘@}’.

It is customary in TeX to use doubled single-quote characters to begin and end quotations, ‘``’ like these ‘''’. This convention should be followed in Texinfo files. Also, three hyphens in a row, ‘---’, are used for a dash—like this. In TeX, a single or even a double hyphen produces a dash that is shorter than you want.

TeX ignores the line-breaks in the input text, except for blank lines, which separate paragraphs. Info generally preserves the line breaks that are present in the input file. Therefore, break the lines in the Texinfo file the way you want them to appear in the output Info file, and let TeX take care of itself.

Since Info does not normally refill paragraphs when it processes them, a line with @-commands in it will sometimes look bad after Info has run on it. To cause Info to refill the paragraph after finishing with the other processing, you need to put the command @refill at the end of the paragraph. (See section Refilling paragraphs and Preventing indentation.)

To prevent a paragraph from being indented in the printed manual, put the command @noindent on a line by itself before the start of the text that should not be indented.

If you mark off a region of the Texinfo file with the @iftex and @end iftex commands so that the region will appear only in the printed copy, you can use TeX commands that cannot be used in the Info file.

In order to be made into a printed manual, a Texinfo file must begin with lines that looks like

\input texinfo   @c -*-texinfo-*-
@setfilename info-file-name
@settitle Name of Manual

The ‘\input texinfo’ line tells TeX to use the ‘texinfo.tex’ file. This line is usually followed by a start-of-header line (not shown here) and then by the ‘@setfilename info-file-name’ and ‘@settitle Name of Manual’ lines. These two lines are needed to provide a name for the Info file and to specify the name used on the left-hand page headers of the printed manual.

The two lines that contain the @setfilename and @settitle commands usually are sandwiched between the start-of-header line and the end-of-header line. (See section ‘start-of-header’, for more information.) The start-of-header and end-of-header lines are needed if you are going to run TeX or Info on just part of a file.

1.4 A Short Sample Texinfo File

A Texinfo file looks like the following, which is a complete but very short Texinfo file. The @comment command introduces comments that will not appear in either the Info file or the printed manual; they are for the person who reads the Texinfo file.

The first part of the file, from ‘\input texinfo’ through to ‘@end titlepage’, looks more intimidating than it is. Most of the material is standard boilerplate; when you write a manual, you just put in the name of your own manual in this section.

All the commands that tell TeX how to typeset the printed manual and tell texinfo-format-buffer how to create an Info file are preceded by ‘@’; thus, @node indicates a node and @chapter indicates the start of a chapter.

\input texinfo   @c -*-texinfo-*-
@setfilename name-of-texinfo-file
@settitle Name of Manual
@setchapternewpage odd

@ifinfo
@comment The following line inserts the copyright notice 
@comment into the Info file.
Copyright @copyright{} 1988 Free Software Foundation, Inc.
@end ifinfo

@comment The titlepage section does not appear in the Info file.
@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@comment  The following two commands start the copyright page
@comment  for the printed manual.  This will not appear in the Info file.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner
@end titlepage

@comment The Top node contains the master menu for the Info file.
@comment This appears only in the Info file, not the printed manual.

@node    Top,       First Chapter, (dir),    (dir)
@comment node-name, next,          previous, up

@menu
* First Chapter::    The first chapter is the 
                     only chapter in this sample.
@end menu

@node     First Chapter,     , Top,      Top
@comment  node-name,     next, previous, up
@chapter First Chapter
@cindex Reference to First Chapter

This is the contents of the first chapter. 

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file
like this into an Info file; and @TeX{} typesets it for a printed
manual.

@node    Concept Index,    ,  Previous Node, Top
@comment node-name,    next,  previous,      up
@unnumbered Concept Index

@printindex cp

@contents
@bye

Here is what the contents of the first chapter of the sample look like:

This is the contents of the first chapter.

Here is a numbered list.

1. This is the first item.
2. This is the second item.

The M-x texinfo-format-buffer command transforms a Texinfo file like this into an Info file; and TeX typesets it for a printed manual.

2 Using Texinfo Mode

In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files. This means that Emacs has commands and features especially designed for working with Texinfo files. Like all other Emacs features, you can customize or enhance these as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones.

The major features of Texinfo mode are:

• Paragraph filling control.
• A command to show the structure of the file.
• Pre-defined keystroke commands to insert commonly used strings of text.
• Formatting a part of a file for Info, rather than the whole file.

In general, in Texinfo mode, the GNU Emacs editing commands are like those in text-mode. The major difference is that the paragraph separation variable and syntax table are set up so expression commands skip Texinfo bracket groups. This means, for example, that the M-q (fill-paragraph) command will refill a paragraph but not the @-command on a line adjacent to it.

By convention, the Texinfo file name shall end with the extension ‘.texinfo’ so that Emacs knows to use Texinfo mode for editing it.

2.1 Formatting a Region for Info

To see what part of a Texinfo file will look like after it has been transformed into an Info file, use the command C-c C-f (texinfo-format-region). This command formats the current region of the Texinfo file for Info and writes it to a temporary buffer called ‘*Info Region*’.

For texinfo-format-region to work, the file must include a line that has @setfilename in its header.

The command is:

C-c C-f

texinfo-format-region

2.2 Showing the Structure of a File

You can show the structure of a Texinfo file by using the C-c C-s command (texinfo-show-structure). This command shows the structure of a Texinfo file by listing the lines with the @-commands for @node, @chapter, @section and the like. These lines are displayed in another window called the ‘*Occur*’ window. In that window, you can position the cursor over one of the lines and use the C-c C-c command (occur-mode-goto-occurrence), to jump to the corresponding spot in the Texinfo file.

The two commands are:

C-c C-s

texinfo-show-structure

C-c C-c

occur-mode-goto-occurrence

Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark off the region of the buffer that you are interested in with the C-x n (narrow-to-region) command and texinfo-show-structure will work on only that region. (To see the whole buffer again, use C-x w (widen).)

2.3 Inserting Frequently Used Commands

Texinfo mode provides commands that insert various frequently used @-commands into the buffer. You can use these commands to save keystrokes. And you can insert balanced curly braces with the M-{ command, (texinfo-insert-braces) and later use the M-} command (up-list) to move forward past the closing brace.

The special commands are invoked by typing C-c twice and then the first letter of the @-command.

C-c C-c c

texinfo-insert-@code

C-c C-c d

texinfo-insert-@dfn

C-c C-c e

texinfo-insert-@end

C-c C-c i

texinfo-insert-@item

C-c C-c n

texinfo-insert-@node

C-c C-c s

texinfo-insert-@samp

C-c C-c v

texinfo-insert-@var

M-{

texinfo-insert-braces

M-}

up-list

This list was generated by analyzing the frequency with which commands were used in the GNU Emacs Manual and the GDB Manual. If you wish to add your own insert commands, you can bind a keyboard macro to a key, use abbreviations or extend the code in ‘texinfo.el’.

3 Beginning a Texinfo File

Various pieces of information have to be provided to Texinfo at the beginning of a Texinfo file, such as the name of the file, the title of the document and the like. Generally, the beginning of a Texinfo file has four parts:

1. The header, marked by start-of-header and end-of-header lines, that includes the commands for naming the Texinfo file and telling TeX what definitions’ file to use when processing the file.
2. A section, marked by the @ifinfo and @end ifinfo commands, that contains a short statement of what the file is about, the copyright notice and copying permissions. This section appears only in the Info file.
3. A section, marked by the @titlepage and @end titlepage commands, that contains the title page, the copyright page and copying permissions. This section appears only in the printed manual.
4. The ‘Top’ node that contains an extensive menu for the whole Info file. The contents of this node only appear in the Info file.

If the Texinfo file has a section containing licensing information and a warranty disclaimer, that section usually follows the ‘Top’ node. The licensing section will be followed by a preface or else by the first chapter of the manual.

Since the copyright notice and the copying permissions are in sections that appear only in the Info file or only in the printed manual, this information has to be repeated twice.

The following sample shows what is needed.

\input texinfo   @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename name-of-texinfo-file
@settitle Name of Manual
@setchapternewpage odd
@comment %**end of header (This is for running Texinfo on a region.)

@ifinfo
This file documents …

Copyright @copyright{} year  copyright-owner

Permission is granted to …
@end ifinfo

@titlepage
@sp 10
@center @titlefont{Name of Manual When Printed}
@sp 2
@center Subtitle, If Any
@sp 2
@center Author

@comment  The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner

Published by …

Permission is granted to …
@end titlepage


@node Top, Overview, (dir), (dir)

@menu
* First Chapter::		The first chapter is usually an overview.
* Second Chapter::		…
  <many more menu items here>
@end menu

@node    First Chapter, Second Chapter, top,      top
@comment node-name,     next,           previous, up
@chapter First Chapter
@cindex Reference to First Chapter

3.1 The Texinfo File Header

Texinfo files start with at least three lines that provide Info and TeX with necessary information. If you want to run TeX on just a part of the Texinfo File, you also have to mark these heading lines with start-of-header and end-of-header lines.

3.1.1 The First Line of a Texinfo File

Every Texinfo file that is to be the top-level input to TeX must begin with a line that looks like this:

\input texinfo   @c -*-texinfo-*-

The line serves two functions:

1. When the file is processed by TeX, it loads the macros needed for processing a Texinfo file. These are in a file called ‘texinfo.tex’ which is usually located in the ‘/usr/lib/tex/macros’ directory.
2. When the file is edited in GNU Emacs, it causes Texinfo mode to be used.

The ‘\input texinfo’ line should be followed by the start-of-header line. This makes it possible for the command for running TeX on a part of the Texinfo file (texinfo-hardcopy-region) to operate. The reason for this is that the texinfo-hardcopy-region command will look on the line preceding the start-of-header line for the ‘\input texinfo’ line.

3.1.2 ‘start-of-header’

The start-of-header line should immediately follow the first line of the Texinfo file.

Usually, the start-of-header line looks like this:

@comment %**start of header (This is for running Texinfo on a region.)

The reason for the odd string of characters (‘%**’) is so that the texinfo-hardcopy-region command does not accidently find something that it shouldn’t when it is looking for the header.

In the default configuration, the phrase ‘(This is for running Texinfo on a region.)’ is not needed and is just included to make it easier for someone reading the Texinfo file.

The start-of-header line and the end-of-header line are Texinfo mode variables that you can change.

3.1.3 @setfilename

In order to be made into an Info file, a Texinfo file must contain a line that looks like this:

@setfilename info-file-name

This line specifies the name of the Info file to be generated. In fact, there can be other things in the file before this line, but they are ignored in the generation of an Info file. The @setfilename line is ignored when a printed manual is generated.

3.1.4 @settitle

In order to be made into a printed manual file, a Texinfo file must contain a line that specifies the title of the manual. Texinfo uses this information during printing to put the title on every other page as a heading; Texinfo puts the current chapter title on the other pages. Texinfo can find the name of the chapter title from the information provided by the @chapter command, but you must tell it the manual title with @settitle:

@settitle Title

This command, on a line by itself, causes title to be used for the headings. Usually, you will use the same words for the title on the title page and for the title specified by this command for the headings, but the two could be different. For example, the title on the title page may be longer than the title specified by the settitle command.

The @settitle command should precede everything that generates actual output.

3.1.5 @setchapternewpage

Conventionally, chapters start on the page on the right hand side of a book; and the right hand page has an odd number. To make sure that Texinfo does this, you can use the command @setchapternewpage. For example, to cause each chapter to start on a fresh odd-numbered page:

@setchapternewpage odd

Page numbering is turned on by the @end titlepage command, so the @setchapternewpage should come before it. Although it can occur anywhere in the beginning of the file, it is most convenient to put it in this location.

3.1.6 ‘end-of-header’

The end-of-header line should follow the line containing the @setchapternewpage command.

Usually, the end-of-header line looks like this:

@comment %**end of header (This is for running Texinfo on a region.)

3.2 Copying Permissions for Info

Since the title page and the copyright page appear only in the printed copy of the manual, the same information has to inserted in a section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice and copying permissions.

The copyright notice should read:

Copyright year copyright-owner

and be put on a line by itself.

Standard text for the copyright permissions is contained in the appendix. See section Ifinfo Copying Permissions, for the complete text.

3.3 The Title and Copyright Pages

The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use a couple of slightly obscure TeX typesetting commands that could not be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual.

3.3.1 @titlepage

Start the material for the title page and following copyright page with @titlepage on a line by itself and end it with @end titlepage on a line by itself. The title page and copyright page material appears only in the printed manual, not in the Info file.

Also, the @end titlepage command starts a new page and turns on page numbering (generation of headings). Therefore, all the material that you want to appear on unnumbered pages should be put between the @titlepage and @end titlepage commands. By using the @page command you can force a page break within the region delineated by the @titlepage and @end titlepage commands and create more than one unnumbered page. This is how the copyright page is produced.

To select a large font suitable for the title itself, you can use the command @titlefont. For example:

@center @titlefont{Texinfo}

Also, you can use @sp commands to adjust vertical spacing. For example:

@sp 2

In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch manual.

3.3.2 @center

A line containing @center text produces a line of output containing text, centered between the margins.

3.3.3 The Copyright Page and Printed Permissions

By international treaty, the copyright notice for a book should either be on the title page or on the back of the title page. Other locations in a book are not official and do not provide copyright protection. The copyright notice should include the year followed by the name of the person or organization who has the copyright.

When the copyright notice is on the back of the title page, the page is not numbered. Therefore, in Texinfo, the information on the copyright page should be within the region delineated by the @titlepage and @end titlepage commands.

To cause a page break, the @page command is used. In the sample, the @page command is followed by the somewhat mysterious line that reads: ‘@vskip 0pt plus 1filll’. This is a line that uses TeX commands to push the copyright notice and the other text on the copyright page towards the bottom of the page. The @vskip command means to skip lines and put in white space. The ‘0pt plus 1filll’ means to put in zero points of mandatory white space, and as much optional white space as needed. Note the use of three ‘l’s in the word ‘filll’; this is the correct use in TeX.

The @copyright{} command generates a ‘c’ inside a circle. The copyright notice itself has the following legally defined sequence:

Copyright © year copyright-owner

It is customary to put information on how to get a manual after the copyright notice (the address of the Free Software Foundation, for example) and the permissions.

Note that the permissions have to be repeated here as well as in the ‘ifinfo’ section that immediately follows the header since this section appears only in the printed manual and the ‘ifinfo’ section appears only in the Info file.

Standard text for the permissions appears in the appendix. See section Standard text for Copying Permissions.

3.4 The Top Node and Master Menu

The ‘Top’ node contains an extensive, master menu for the whole Info file. The contents of this node appear only in the Info file. Nothing in this node should appear in the printed file. Since a node line by itself and a menu by itself are not printed, the contents of this node do not have to be within a region delineated by @ifinfo and @end ifinfo commands. However, any text within the node should be marked off in that manner. You may want to put a short summary before the master menu inside a region delineated by @ifinfo and @end ifinfo commands. Usually, the ‘Previous’ and ‘Up’ nodes refer to the top level directory of the whole Info system, with pointers to ‘(dir)’.

Generally, the top menu is divided into parts.

• The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections and the major appendices.
• The second part contains entries for the indices. In an Info file, it is very useful to have indices here at the beginning of the file in the top node rather than at the end, as in a printed book.
• The third and subsequent parts contain a listing of the other, lower level nodes, often ordered by chapter. This way, an inquirer can go directly to a particular node if he or she is searching for specific information. (These nodes are not required; use them if you think they are a convenience.)

Each section in the menu can be introduced a descriptive line. So long as the line does not begin with an asterisk, it will not be treated as a menu item. (See section Making Menus, for more information.)

For example, the Top node of this manual looks like this (but with many more entries):

@node Top, Overview, (dir), (dir)

@menu
* Overview::                    What is Texinfo?
* Texinfo Mode::                Special features in GNU Emacs.
…

Indices, nodes containing large menus

* Command Index::               An item for each @-command.
* Concept Index::               An item for each concept.

A detailed node listing

Overview
* Info File::                   Characteristics of the Info file.
* Printed Manual::              Characteristics of the printed manual.

Using Texinfo Mode
* Info on a Region::            Formatting a region for Info.
* Showing the Structure::       Showing the structure of a file.
…
…

3.5 Licensing and Distribution Information

If the Texinfo file has a section containing the “General Public License” and the distribution information and a warranty disclaimer, this section usually follows the ‘Top’ node. The licensing and distribution information and the disclaimer are followed by a preface or else by the first chapter of the manual.

The licensing agreement is very important to Project GNU documentation and software. Without it, you may find that you can no longer get the software or its documentation. This sounds paradoxical, but the state of the world is such that documentation and software that does not have a “restrictive” license to make them freely distributable may be lost to the public. This has happened.

For a good example of the text that could be used for the Distribution, General Public License and NO WARRANTY sections of your document, see the latest version of the GNU Emacs Manual.

Although a preface is not a required part of a Texinfo file, it is very helpful. Ideally, it should state clearly and concisely what the file is about and who would be interested in reading it. In general, the preface would follow the licensing and distribution information, although sometimes people put it earlier in the document. Usually, a preface is put in an @unnumbered section. (See section @unnumbered, @appendix.)

4 Ending a Texinfo File

The end of a Texinfo file should include the indices, the commands to generate detailed and summary tables of contents and the @-command that tells TeX that it has reached the end of the file.

For example, a Texinfo file might be ended as follows:

@node    Concept Index,     , Previous Node, Top
@comment node-name,     next, previous,      up
@unnumbered Concept Index

@printindex cp

@contents
@bye

The @bye command should be on a line by itself and every Texinfo file must end with such a line. This command terminates TeX processing and forces out unfinished pages.

4.1 Generating a Table of Contents

The commands @chapter, @section, etc., supply the information to make up a table of contents, but they do not cause an actual table to be generated. To do this, you must use the commands @contents and @summarycontents.

@contents

The table of contents command outputs (into a printed manual) a complete table of contents, based on the @chapter, @unnumbered and other sectioning commands. This command should be used on a line by itself.

@summarycontents

The summary contents command generates a summary table of contents that lists only the chapters (and appendices and unnumbered chapters); sections, subsections and subsubsections are omitted. This command should be used on a line by itself. Only large manuals need a summary table of contents.

You can use either one of these commands, or both. Each command automatically generates a chapter-like heading at the top of the page. Tables of contents should be generated at the very end of the manual, just before the @bye command; the tables of contents commands should follow any indices that are output, so that the indices will appear in the contents.

indices…
@summarycontents
@contents
@bye

The commands @contents and @summarycontents are ignored when an Info file is being generated.

4.2 Creating Indices

Using Texinfo, you can generate printed indices and Info file menus without having to sort and collate entries manually. Texinfo will do this for you automatically. Each index covers a certain kind of entry (functions, or variables, or concepts, etc.) and lists all of those entries in alphabetical order, together with information on how to find the discussion of each entry. In a printed manual, this information consists of page numbers. In an Info file, it consists of a menu item leading to the first node referenced.

When you are making index entries, it is good practice to think of the different categories under which people may look for something. Different people do not think of the same words when they look something up. They think of different words. A helpful index will have items indexed under all the different words that people may use. For example, someone might think it obvious that the two letter names for indices should be listed under “Indices, two letter names”, since the word “Index” is the general concept. But another reader may remember the specific concept of two letter names and search for the entry listed as “Two letter names for indices”. A good index will have both entries and will help both kinds of user.

Like typesetting, the construction of an index is a highly skilled, professional art, the subtleties of which are not appreciated until you have to do it yourself.

Normally, six indices are provided for:

• A program index listing names of programs and leading to the places where those programs are documented.
• A function index listing functions (such as, entry points of libraries).
• A variables index listing variables (such as, external variables of libraries).
• A data type index listing data types (such as, structures defined in header files).
• A keystroke index listing keyboard commands.
• A concept index listing concepts that are discussed.

Not every manual needs all of these. This manual has two indices: a concept index and an @-command index (that uses the function index but is called a command index in the chapter heading). Two or more indices can be combined into one using the @synindex command. See section Combining Indices.

4.2.1 Defining the Entries of an Index

The data to make an index comes from many individual commands scattered throughout the Texinfo source file. Each command says to add one entry to a particular index; after processing, it will give the current page number or node name as the reference.

@cindex concept

Make an entry in the concept index for concept, referring to the current page or node.

@findex function

Make an entry in the function index for function, referring to the current page or node.

@vindex variable

Make an entry in the variable index for variable, referring to the current page or node.

@pindex program

Make an entry in the program index for program, referring to the current page or node.

@kindex key

Make an entry in the key index for key, referring to the current page or node.

@tindex data type

Make an entry in the data type index for data type, referring to the current page or node.

If the same name is indexed on several pages, all the pages are listed in the printed manual’s index. However, only the first node referenced will appear in the index of an Info file. This means that it is best to write indices in which each entry will refer to only one place in the Texinfo file. Fortunately, this constraint is a feature rather than loss since it means that the index will be easy to use. Otherwise, it can be easy to create an index which has many pages listed for an entry and you don’t know which one you need.

You are not actually required to use indices for their canonical purposes. For example, you might wish to index some C preprocessor macros. You could put them in the function index along with actual functions, just by writing @findex commands for them; then, when you print the “function index”, you could give it the title ‘Function and Macro Index’ and all will be consistent for the reader. Or you could put the macros in with the data types by writing @tindex commands for them, and give that index a suitable title so the reader will understand.

4.2.2 Combining Indices

Sometimes you will want to combine two disparate indices such as functions and variables, perhaps because you have few enough of one of them that a separate index for them would look silly.

You could put variables into the function index by writing @findex commands for them instead of @vindex commands, and produce a consistent manual by printing the function index with the title ‘Function and Variable Index’ and not printing the ‘Variable Index’ at all; but this is not a robust procedure. It works only as long as your document is never included in part of or together with another document that is designed to have a separate variable index; if you did that, the variables from your document and those from the other would not end up together.

What you should do instead when you want functions and variables in one index is to index the variables with @vindex as they should be, but use the @synindex command to redirect these @vindex commands to the function index. @synindex takes two arguments: the name of an index to redirect, and the name of an index to redirect it to. For this purpose, the indices are given two-letter names:

‘cp’

the concept index

‘vr’

the variable index

‘fn’

the function index

‘ky’

the key index

‘pg’

the program index

‘tp’

the data type index

Thus, @synindex vr fn at the front of a Texinfo file will cause all entries designated for the variable index to go to the function index instead.

4.2.3 Printing an Index and Generating Menus

To print an index means to include it as part of a manual or Info file. This does not happen automatically just because you use @cindex or other index-entry generating commands in the Texinfo file; those just cause the raw data for the index to be accumulated. To print an index, you must include the @printindex command at the place in the document where you want the index to appear. Also, for the case of the printed manual, you must run a program called texindex to sort the raw data to produce a sorted index file, which is what will actually be used to print the index.

The Texinfo command that is used to print indices is @printindex. It takes the two-letter index name (see section Combining Indices) as an argument without braces, and reads the corresponding sorted index file and formats it appropriately into an index.

@printindex does not generate a chapter heading for the index. Consequently, you should precede the command with a suitable section or chapter command (usually @unnumbered) to supply the chapter heading and put the index into the table of contents. And before that, you will probably put a @node command. For example,

@node Variables Index, Concept Index, Function Index, Top
@comment    node-name,          next,       previous,  up
@unnumbered Variable Index

@printindex vr

@node     Concept Index,     , Variables Index, Top
@comment      node-name, next,        previous,  up
@unnumbered Concept Index

@printindex cp

@summarycontents
@contents
@bye

In TeX, @printindex needs a sorted index file to work from. TeX does not know how to do sorting; this is one of the main deficiencies of TeX. You must invoke the program texindex to do so, giving it the names of the raw index files to be sorted as arguments. You do not have to run texindex on all of them; only the ones you are going to print. (See section Printing Hardcopy, for more information.)

5 Node and Chapter Structuring

The chapter structuring commands divide a document into a hierarchy of chapters, sections, subsections and subsubsections. These commands generate large headings.

In a printed manual, the table of contents is based on the information specified by the chapter structuring commands.

Although the chapter structuring commands used for creating a printed document are entirely different from the node commands for structuring an Info file, you are likely to use the two kinds of command together since the single Texinfo file is usually designed to be read both as an Info file and as a printed manual. The only time you are likely to use the chapter structuring commands without using the node structuring commands is if you are writing a document that will never be put into Info format, for example, a novel, a letter, an article or a memorandum.

It is unlikely that you will ever write a Texinfo file that is only intended as an on-line Info file and not as a printable document. However, Texinfo is flexible enough so that you can do this if you wish.

Although a Texinfo file can be structured in a variety of ways, it is usually structured like a book with chapters, sections, subsections and the like. This structure can also be visualized as a tree (or rather as an upside down tree) with the root at the top and each level corresponding to chapters or sections or whatnot. In Info format, you reach the nodes on each level by using the the ‘Next’ and ‘Previous’ pointers in the node line. For example, you go from one chapter to the next or previous chapter by using the the pointers to the next and previous chapters. In Info, you go the level above by using an ‘Up’ pointer and you go to the level below through a ‘Menu’. In the printed manual, cross references are indicated by page and section numbers; in the on-line file, cross references are specified by inline menu items.

Here is a diagram that shows a Texinfo file with three chapters; each chapter has two sections.

                                 top
                                  |
                                  |
            ---------------------------------------------
           |                      |                      |
           |                      |                      |
       Chapter 1              Chapter 2               Chapter 3
           |                      |                      |
           |                      |                      |
      ----------             ----------              ----------          
     |          |           |          |            |          |         
 Sect. 1.1   Sect. 1.2   Sect. 2.1  Sect. 2.2    Sect. 3.1  Sect. 3.2     
			   				   

In this structure, the node for Chapter 2 looks like this:

@node     Chapter 2,  Chapter 3, Chapter 1, top
@comment  node-name,  next,      previous,  up

To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2 that says:

    @menu
    * Sect. 2.1::    Description of this section.
    * Sect. 2.2::  
    @end menu

This menu is located inside Chapter 2, after the beginning of the chapter, just before Section 2.1.

Note that a menu entry has three parts: the menu item name, the name of the node and, optionally, a description of the item (in that order). If the menu item name and the name of the node are the same, you can put two colons after the item name, as is shown in the example. (If the second part is different from the first, the first part is terminated by a colon and the second part terminated by a tab, newline, comma or period.) (See section @menu.)

The node for Sect. 2.1 will look like this:

    @node     Sect. 2.1, Sect. 2.2,         ,  Chapter 2
    @comment  node-name, next,      previous,  up

This node does not have a ‘Previous’ node.

Usually, an @node command and a chapter structuring command are used in sequence, along with indexing commands. For example, the node for the chapter on ending a file looks like this:

@node    Ending a File, Structuring, Beginning a File, Top
@comment node-name,     next,        previous,         up
@chapter Ending a Texinfo File
@cindex  Ending a Texinfo file
@cindex  Texinfo file ending
@cindex  File ending

The chapter structuring commands fall into four groups that have the characteristics of chapters, sections, subsections and subsubsections. The groups are:

@chapter

@unnumbered

@appendix

For chapters and chapter-like parts of a document.

@section

@unnumberedsec

@appendixsec

For sections and section-like parts of a document.

@subsection

@unnumberedsubsec

@appendixsubsec

For subsections and subsection-like parts of a document.

@subsubsection

@unnumberedsubsubsec

@appendixsubsubsec

For subsubsections and subsubsection-like parts of a document.

In the sections that follow, the chapter structuring commands are described first and then the @node and @menu commands.

5.1 @chapter

@chapter identifies a chapter in the document. It is followed by a single argument which is the rest of the line, as in

@chapter Node and Chapter Structuring

In TeX, it creates a chapter in the document, specifying the chapter title.

In the Info file, @chapter causes its argument to appear on a line by itself, with a line of asterisks inserted underneath. Thus, the above example produces the following output:

Node and Chapter Structuring
****************************

5.2 @unnumbered, @appendix

These commands are equivalent to @chapter for Info file output. (See section @chapter.) In a printed manual, they generate chapters that are numbered differently in the table of contents. @unnumbered chapters appear without chapter numbers of any kind, and @appendix chapters are given a letter instead of a number.

5.3 @section

@section is like @chapter except that in TeX it makes a section rather than a chapter. (See section @chapter.) Sections go within chapters. In the Info file, @chapter and @section differ only in that @section underlines with ‘=’. For example,

This is a section
=================

5.4 @unnumberedsec, @appendixsec

Use these constructs for sections within chapters made by @unnumbered or @appendix. (See section @section.)

5.5 @subsection

Subsections are to sections as sections are to chapters. (See section @section.) They are underlined with ‘-’. For example,

This is a subsection
--------------------

5.6 @unnumberedsubsec, @appendixsubsec

Use these constructs for subsections within sections within chapters made by @unnumberedsec or @appendixsec. (See section @subsection.)

5.7 @subsubsection And Other Subsection Commands

Subsubsections are to subsections as subsections are to sections. (See section @subsection.) They are underlined with periods. The equivalent commands for @unnumberedsubsec and @appendixsubsec are @unnumberedsubsubsec and @appendixsubsubsec. For example,

This is a subsubsection
.......................

5.8 @node

@node defines the beginning of a new node in the Info output file (See (info)info.). It is followed by four arguments, separated by commas, that make up the rest of the line. Since it is often hard to remember the order in which are arguments are listed, texinfo-mode provides the C-c C-c n command (texinfo-insert-@node) which automatically inserts a comment line listing the arguments. For example,

@node    Texinfo Mode, Beginning a File,  Overview, Top    
@comment node-name,    next,              previous, up

defines a node named ‘Texinfo Mode’, whose ‘Next’ pointer is to node ‘Beginning a File’, whose ‘Previous’ pointer is to node ‘Overview’, and whose ‘Up’ pointer is to node ‘Top’. What this means is that Texinfo changes @node args into the special text string necessary to separate Info nodes and to identify the node that is starting and say what nodes it points to.

The pointer names should be the names of nodes defined elsewhere. For this example, nodes named ‘Beginning a File’, ‘Overview’ and ‘Top’ should be defined elsewhere in the file with other @node commands. It does not matter whether they are before or after the node that refers to them.

Normally, a node’s ‘Up’ pointer should point at the node whose menu mentions that node. The node’s ‘Next’ pointer should point at the node that follows that node and its ‘Previous’ pointer should point at the node that precedes it in that menu.

In TeX, @node is nearly ignored. It generates no text. Its only function is to identify the name to use for cross-references to the chapter or section which follows the @node command and which which makes up the body of the node. (Cross references are made with @xref. See section Making Cross References.)

@node should be followed immediately by a chapter-structuring command such as @chapter, @section, @subsection or @subsubsection.

The easiest way to write a node is to use the Texinfo mode keyboard command C-c C-c n to insert ‘@node’ and a comment line listing the names of each of the pointers in their proper order. This way you won’t lose track of which arguments are for which pointers. The template is especially useful if you are not familiar with Texinfo. It is important to pick a suitable node name. Generally, these begin with an uppercase letter as if the node name were a heading for a chapter or section. Do not use any of the Texinfo @-commands in the name; these commands confuse Info. The node name should be informative. Unfortunately, long names will not fit onto the line, which can be awkward. Sometimes it is better to use long but informative names rather than short ones.

Some people insert the names of the ‘Next’, ‘Previous’ and ‘Up’ pointers at the same time they insert the node’s own name. This is because it is easier to keep track of the node structure as you create a document than it is to sort it out after you have dozens of nodes. Others wait to insert the ‘Next’, ‘Previous’ and ‘Up’ pointers until they have a nearly final version of the document. This is because they expect to change the organization of the document while they write it and insert or delete sections and move them around. The command texinfo-show-structure can be used to find the ‘Next’, ‘Previous’ and ‘Up’ pointers of a node. (See See section Using texinfo-show-structure.)

However you do it, it is best to name the node whenever you write the section so you can easily make cross references to the section. A large number of cross references are an especially important feature of a good Info file.

After you have inserted the node-line, you should immediately write an @-command for the chapter or section and insert its name. Next, (and this is important!), put in several index entries. Usually, you will find at least two and often as many as four or five ways of referring to the node in the index. Use them all. This will make it much easier for people to find the node.

The top node of the file, named ‘Top’, should have as its parent the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses. If the file is to be installed directly in the Info directory file, use ‘(dir)’ as the parent of the top node; this is short for ‘(dir)top’, the node ‘top’ in the file ‘dir’, which is the main menu of Info. For example,

@node    Top,       Overview, (dir),    (dir)
@comment node-name, next,     previous, up

For more information about installing an Info file in the ‘info’ directory, see section Installing an Info file

5.9 @menu

Info file nodes can contain menus which point to other nodes. You must type the menus in by hand, and surround them with lines containing @menu and @end menu. In Info, the @menu line changes into ‘* Menu:’, which indicates the beginning of a menu to the Info program. Otherwise, the contents are unchanged by Texinfo, except for the processing of any other @-commands within. The entire menu construct has no effect in the printed manual and will not appear there.

By convention, a menu is put at the end of a node. This way, it is easy for someone using Info to find the menu, using the M-> (end-of-buffer) command.

In a menu, every line that begins with a ‘*’ lists a single topic. A line that does not start with a ‘*’ will also appear in the menu and can be used as a comment.

A menu item has three parts:

1. The menu item name.
2. The name of the node.
3. A description of the item.

Only the first part is required. This part is the name of the topic—the name of the menu item that the user must give to the m command to select this topic when using Info. The first part comes right after the asterisk and a space, and is followed by a colon, spaces and tabs, and then the name of the node which discusses that topic. The name of the node is terminated by a tab, comma, newline or period. If the node name and topic name are the same, rather than give the name twice, put two colons after the name instead. For example, ‘* Name::’. (You should do this whenever possible, since it reduces visual clutter in the menu).

If the second part is present, it may be terminated with a tab, comma, or newline; or with a period.

For example,

@menu
A Section on Foo and Switches
* Foo::           The node named Foo tells you how to go fooing.
* Sw: Switches.   Type @code{m Sw} to see node @code{Switches}
                  which describes the switches available here.
@end menu

produces

* menu:

A Section on Foo and Switches
* Foo::         The node named foo tells you how to go fooing.
* Sw: Switches. Type `m Sw' to see node `Switches'
                which describes the switches available here.

In this example, the menu has two items. ‘Foo’ is both a menu item name and the name of the node referred to by that item. ‘Sw’ is the other menu item name, and it refers to the node named ‘Switches’. Since no file name is specified with ‘Foo’ or ‘Switches’, they must be the names of other nodes in the same Info file.

Nodes in other Info files can be referred to by putting the file name in parentheses at the beginning of the node name. For example,

@menu
* Outlining: (emacs) Outline Mode.  The major mode for editing outlines.
* Rebinding: (emacs) Rebinding.     How to redefine the meaning of a key.
@end menu

When this is done, the item has to have at least two parts: the first part is the menu item name and the second part is the name of the node.

6 Making Quotations and Examples

Quotations and examples are blocks of text, consisting of one or more whole paragraphs that are set off from the bulk of the text and treated differently. They are usually indented.

In Texinfo, an insertion is always begun by writing an @-command on a line by itself, and ended by writing an @end command that is also on a line by itself. For instance, an example is a kind of insertion that is begun with @example and ended with @end example.

There are three commands for quotations and examples:

@quotation

Used to indicated text that is quoted.

@example

Used to illustrate code, commands and the like in a fixed width font without filling.

@display

Used for illustrative text.

6.1 @quotation

@quotation is used to indicate text that is excerpted from another (real or hypothetical) printed work. The inside of a quotation is processed normally except that

1. The margins are narrower.
2. Paragraphs are not indented.
3. Interline spacing and interparagraph spacing are reduced.

Thus, the input

@quotation
This is
a foo.
@end quotation

produces in the printed manual

This is a foo.

and in the Info file

This is
a foo.

6.2 @example

@example is used to indicate an example that is not part of the running text. In the printed manual, this is done by switching to a fixed width font, turning off filling, and making extra spaces and blank lines significant. In the Info file, an analogous result is obtained by indenting each line with five extra spaces.

@example should appear on a line by itself; this line will disappear from the output. Mark the end of the example with a line containing @end example, which will likewise disappear. For example:

@example
mv foo bar
@end example

produces

mv foo bar

Since the lines containing @example and @end example will disappear, you will want to put a blank line before the @example and another blank line after the @end example. (Remember that blank lines between the beginning @example and the ending @end example will appear in the output.)

Don’t use tabs in lines of an example! TeX has trouble with tabs: it treats them like single spaces, and that is not what they look like.

6.3 @display

@display is just like @example except that, in the printed manual, @display does not select the fixed-width font. In fact, it does not specify the font at all, so that the text appears in the same font it would have appeared in without the @display.

7 Making Lists and Tables

Texinfo has several ways of making lists and two-column tables. Lists can be bulleted or numbered while two-column tables can highlight the items in the first column.

For example, this is an enumerated list:

1. This is a numbered item.
2. This is the second item in this list.
3. This is the third item on this list.

Texinfo will automatically indent the text in lists or tables and number an enumerated list. This last feature is useful if you are reordering the list, since you do not have to renumber it yourself.

Lists or tables are always begun by an @-command on a line by itself and ended with an @end command on a line by itself. For example, an enumerated list begins with the command @enumerate and ends with the command @end enumerate; and an itemized list begins with the command @itemize and ends with the command @end itemize.

The elements of a list are begun with the @item command.

Here is an itemized list of the different kinds of table and lists:

• Itemized lists with or without bullets.
• Numbered lists.
• two-column tables with highlighting.

7.1 @itemize

@itemize is used to produce sequences of indented paragraphs, with a mark inside the left margin at the beginning of each paragraph. The rest of the line that starts with @itemize should contain the character or Texinfo commands to generate such a mark. Usually, it is the @-command @bullet. Whatever mark you choose, ultimately, it should result in a single character in the Texinfo file, or the indentation will come out wrong. When you write the command, omit the ‘{}’ after the command if you use just one command and nothing else.

The text of the indented paragraphs themselves come after the @itemize, up to another line that says @end itemize.

Before each paragraph for which a mark in the margin is desired, place a line that says just @item. Don’t put any other text on this line.

Info indents the lines in an itemized list by five columns, but it does not fill them. This can produce lines in the Info file that are too wide. You can either write shorter lines in the Texinfo file by setting the fill column to five columns less than it is normally, or else you can tell Info to refill the paragraphs by adding the @-command @refill to the end of the paragraph. (See section @refill, for more information about the use of the @refill command.)

Usually, you should put a blank line before an @item. This puts a blank like in the Info file. Except when the entries are very brief, a blank line looks better.

Here is an example of the use of @itemize, followed by the output it produces. Note that @bullet produces a ‘*’ in Texinfo and a round dot in TeX.

@itemize @bullet
@item
Some text for foo.

@item
Some text
for bar.
@end itemize

produces

• Some text for foo.
• Some text for bar.

7.2 @enumerate

@enumerate is like @itemize except that the marks in the left margin contain successive integers starting with 1. (See section @itemize.) Do not put any argument on the same line as @enumerate.

@enumerate
@item
Some text for foo.
@item
Some text
for bar.
@end enumerate

produces

1. Some text for foo.
2. Some text for bar.

If you want, you can put a blank line between the entries in the list. This often makes it easier to read the Info file. For example,

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

7.3 @table

@table is similar to @itemize, but allows you to specify a name or heading line for each item. (See section @itemize.) The command is used to produce two-column tables, and is especially useful for glossaries and explanatory exhibits.

You must follow each use of @item inside of @table with text to serve as the heading line for that item. This text is put on the same line as the @item command. Each heading line is put into the first column of the table and the supporting text, which you put on the line following the line beginning with @item, goes into the second column.

Also, @table itself must be followed by an argument that is a Texinfo command such as @code, @var, @kbd or @asis. Although these commands are usually followed by arguments in braces, in this case you use the command name without an argument. (@item supplies the argument.) This command will be applied to the text that goes into the first column of each item and determines how it will be highlighted. For example, @samp will cause the text in the first column to be highlighted as if it were acted on by an @samp command.

@asis is a command that does nothing; in that case, each item will come out without highlighting, unless that particular piece of text contains @-commands for highlighting.

(Various other command names might work with @table. However, only commands that normally take arguments in braces may be used.)

The following table, for example, highlights the text in the first column as if each item were acted on by an @samp command:

@table @samp
@item foo
This is the text for
@samp{foo}.

@item bar
Text for @samp{bar}.
@end table

produces

‘foo’

This is the text for ‘foo’.

‘bar’

Text for ‘bar’.

Info indents the lines of text in the second column, but does not fill them. As a result, the lines in the Info file may be too wide. To prevent this, cause Info to refill the paragraphs after processing by adding the @-command @refill to the end of the paragraph. (See section @refill, for more information about the use of the @refill command.)

If you want to list two or more named items with a single block of text, use the @itemx command.

7.3.1 @itemx

@itemx is used inside a @table when you have two or more named items for the same block of text. Use @itemx for all but the first of the items. It works exactly like @item except that it does not generate extra vertical space above the item text. For example,

@table @code
@item upcase
@itemx downcase
These two functions accept a character or a string as argument,
and return the corresponding upper case (lower case) character
or string. @refill
@end table

produces

upcase

downcase

These two functions accept a character or a string as argument, and return the corresponding upper case (lower case) character or string.

A more complicated example of the use of @itemx comes from the chapter on structuring commands. Here is how the list showing how the chapter structuring commands fall into four groups was constructed. (See section Chapter Structuring Commands.)

@table @code
@item  @@chapter
@itemx @@unnumbered
@itemx @@appendix
For chapters and chapter-like parts of a document.

@item  @@section
@itemx @@unnumberedsec
@itemx @@appendixsec
For sections and section-like parts of a document.

@item  @@subsection
@itemx @@unnumberedsubsec
@itemx @@appendixsubsec
For subsections and subsection-like parts of a document.

@item  @@subsubsection
@itemx @@unnumberedsubsubsec
@itemx @@appendixsubsubsec
For subsubsections and similar parts of a document.
@end table

and this is what the resulting table looks like:

@chapter

@unnumbered

@appendix

For chapters and chapter-like parts of a document.

@section

@unnumberedsec

@appendixsec

For sections and section-like parts of a document.

@subsection

@unnumberedsubsec

@appendixsubsec

For subsections and subsection-like parts of a document.

@subsubsection

@unnumberedsubsubsec

@appendixsubsubsec

For subsubsections and similar parts of a document.

Also, either column of a table can be empty.

8 Making Cross References

Cross references are used to refer the reader to other parts of the same or different Texinfo files. In Texinfo, nodes are the points to which cross-references can refer.

In general, a document should be designed so that it can be read sequentially. People soon tire of flipping back and forth to find information that should be presented to them as they need it. However, there will be information (often too detailed for whatever the current context may be) that is related to whatever is presented and to which reference should be made. More important, in an on-line help system or in a reference manual, readers do not read everything in sequence from beginning to end. Instead, they look up what they need. For this reason, such creations should contain many cross references to help the reader find other information that he or she may not have read.

Although nodes are not a fundamental concept in a printed manual, they still serve to define a cross-reference point and the variants of @xref still serve to make references. Thus, if you are writing a manual that will only be printed, and will not be used on-line, you continue to use the @node command for when you make cross references.

There are several kinds of cross reference command.

@xref

Used to start a sentence in the printed manual saying, ‘See …’
or an entry in the Info file saying ‘*note …’.

@pxref

Used to make a reference that starts with a lowercase ‘see’
and is usually contained within parentheses.

@inforef

Used to make a reference to an Info file for which there is no printed manual.

8.1 @xref

@xref generates a cross-reference. In Texinfo, it turns into an Info cross-reference which the Info ‘f’ command can use to go directly to another node. In TeX, it turns into a sentence of the form

See section section [topic], page page

but does not generate a period to end it.

@xref must refer to an Info node created by @node, by the node’s name.

@xref is followed by an argument inside braces; but actually the text inside the braces is treated as several arguments, separated by commas. Whitespace after these commas is ignored. A period or comma must follow the closing brace of an @xref. It is required to terminate the cross reference. This period or comma will appear in the output, both in the Info file and in the printed manual.

The simplest form of @xref takes one argument, the name of another node in the same Info file. Here we show the input text, followed by a blank line and then the output text for Info files and the output text for printed manuals.

@xref{node-name}, for more info.

*note node-name::, for more info.

See section nnn [node-name], page ppp, for more info.

With two arguments, the second one is used as the name of the Info cross-reference, while the first argument is still the node that the cross-reference points to:

@xref{node-name, name-for-note}, for more info.

*note name-for-note: node-name, for more info.

See section nnn [node-name], page ppp, for more info.

A third argument replaces the node name when it actually appears in the TeX output. It should state the topic discussed by the section being referenced. Often, you will want to use initial uppercase letters so it will be easier to read when the reference is printed. Use a third argument when the node name is unsuitable because of syntax, grammar or diction.

@xref{node-name, name-for-note, Topic Description}, for more info.

*note name-for-note: node-name, for more info.

See section nnn [Topic Description], page ppp, for more info.

If a third argument is given and the second one is empty, then the third argument serves both purposes:

@xref{node-name, , Topic Description}, for more info.

*note Topic Description: node-name, for more info.

See section nnn [Topic Description], page ppp, for more info.

A fourth argument specifies the name of the Info file in which the referenced node is located, assuming it is not the one in which the reference appears. @xref with only four arguments is used when the reference is not within one Info file, but is within a single printed manual—when multiple Texinfo files are incorporated into the same TeX run but make separate Info files. (This is seldom the case and usually you will use five arguments if you are making a reference that is outside the current Info file.)

@xref{node-name, name-for-note, Topic, info-file-name}, 
for more info.

*note name-for-note: (info-file-name) node-name, for more info.

See section nnn [Topic], page ppp, for more info.

A fifth argument is used when you are making a reference to another Info file which is also part of another printed manual. Write the title of the manual in this slot. Since a different manual is made during a different TeX run, the printed reference will not have a page number.

Whenever you refer to another manual, use this version of @xref with five arguments.

@xref{node-name, name-for-note, Topic, info-file-name, A Printed Manual},
for more info.

*note name-for-note: (info-file-name) node-name, for more info.

See section Topic of A Printed Manual, for more info.

The name of the printed manual will be typeset in italics.

Often, you will leave out the second argument when you use the long version of @xref. In this case, the third argument, the topic description, will replace the node name:

@xref{node-name, , Topic Description, info-file-name, A Printed Manual},
for more info.

*note Topic Description: (info-file-name) node-name, for more info.

See section Topic Description of A Printed Manual, for more info.

8.2 @pxref

@pxref is nearly the same as @xref; it differs in only two ways:

1. The output starts with lower case ‘see’ rather than ‘See’.
2. A period is generated automatically in the Info file output to end the Info cross-reference, but no period is generated for the printed manual.

The purpose of @pxref is to be used inside parentheses as part of another sentence. In the printed manual, no period is needed after the cross reference text itself (within the parentheses), but a period is needed after the cross reference text in the Info file because only thus can Info recognize the end of the cross-reference. @pxref spares you the need to use complicated methods to put a period into one form of the output and not the other.

@pxref can be used with up to five arguments just like @xref. (See section @xref.)

8.3 @inforef

@inforef is used for cross-references to Info files for which there are no printed manuals. Even in a printed manual, @inforef generates a reference directing the user to look in an Info file. @inforef takes exactly three arguments. The syntax is @inforef{node, name, file}.

@inforef{node-name, name-for-note, info-file-name}, for more information.

*note name-for-note: (info-file-name) node-name, for more information.

See Info file ‘info-file-name’, node ‘node-name’, for more information.

9 Formatting Paragraphs

Usually, a Texinfo file will be processed both by TeX and by the M-x texinfo-format-buffer command. Consequently, you must make sure that text will come out looking right both in the printed manual and in the on-line help.

For example, unless told otherwise, M-x texinfo-format-buffer will not refill a paragraph after processing it although TeX will. This means that a paragraph with numerous or large @-commands may not look properly filled after processing by Info. The @-commands are removed from the text but the lines are not refilled so some are much shorter than they were. To cause the M-x texinfo-format-buffer command to refill such a paragraph, put @refill at the end of the paragraph.

TeX may also format a document improperly. For example, page breaks may occur in the “wrong place”; to control this, text can be held together by a group command that keeps the text within the group from being split across two pages.

9.1 Refilling Paragraphs and Preventing Indentation

The @refill and @noindent commands are used just after or just before paragraphs which, after processing by either Info or TeX, might look bad. The @refill command refills a paragraph in the Info file after all the other processing has been done. In the printed manual, the @noindent command prevents a piece of text that is a continuation of the preceding paragraph from being indented as if it were a new paragraph.

9.1.1 @refill

If a paragraph contains sizable @-constructs, it may look badly filled after texinfo-format-buffer is through with it.

Put @refill at the end of the paragraph to tell texinfo-format-buffer to refill the paragraph after finishing all other processing on it. @refill has no effect on TeX, which always fills everything that ought to be filled. For example,

To use @code{foo}, pass @samp{xx%$} and @var{flag} and type @kbd{x}
after running @code{make-foo}.@refill

produces (in the Info file)

To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.

whereas without the @refill it would produce

To use `foo', pass `xx%$' and FLAG and type `x'
after running `make-foo'.

with the line broken at the same place as in the Texinfo input file.

Do not put a space before @refill; otherwise the command might be put at the beginning of the line when you refill the paragraph in the Texinfo file with M-q (fill-paragraph). If this were to happen, the @refill command might fail to work

9.1.2 @noindent

If you have text following an @example or other similar “special paragraph” that reads as a continuation of the text before the @example, it is good to prevent this text from being indented as a new paragraph. To accomplish this, put @noindent on a line by itself before the start of the text that should not be indented. For example,

@example
This is an example
@end example

@noindent
This line will not be indented.

produces

This is an example

This line will not be indented.

To adjust the number of blank lines properly in the Info file output, remember that the line containing @noindent does not generate a blank line, and neither does the @end example line.

In the Texinfo source file for this documentation, each of the lines that says ‘produces’ is preceded by a line containing @noindent.

9.2 Breaks, Blank Lines and Groups

Texinfo has several commands for making blank lines, for forcing paragraph and page breaks in the printed manual and for preventing text from running from one page to the next.

@*

Force a line break in the printed manual. This command has no effect on the Info file.

@sp

Generate blank lines in both the printed manual and in the Info file.

@br

Force a paragraph break in the printed manual. This command has no effect on the Info file.

@w

Prevent text from being split across two lines in the printed manual. This command has no effect on the Info file.

@page

Start a new page in the printed manual. This command has no effect on the Info file.

@group

Hold text together that must appear on one printed page. This command has no effect on the Info file.

@need

Start a new printed page if required space not on this one. This command has no effect on the Info file.

9.2.1 @*

@* forces a line break in the printed manual. It has no effect on the Info file output, where line breaks follow those in the source file. If you want a line break at a certain spot in both forms of output, break the line there in the source file and put @* at the end of the line.

9.2.2 @sp

A line containing @sp n generates n blank lines of space in either the printed manual or the Info file. For example,

@sp 2

generates two blank lines.

9.2.3 @br

In a printed manual, a line containing @br forces a paragraph break; in the Info file output, it does nothing (not even a blank line results from it).

9.2.4 @w

In a printed manual, @w{text} outputs text and prohibits line breaks within text. @w has no effect on the Info file output; it is the same as would result from just text.

9.2.5 @page

A line containing @page starts a new page in a printed manual. The line has no effect on Info files since they are not paginated.

9.2.6 @group

A line containing @group begins an unsplittable vertical group, which must appear entirely on one page. The group is terminated by a line containing @end group. These two lines produce no output of their own, and in the Info file output they have no effect at all.

If you forget to end a group, you may get strange and unfathomable error messages when you run TeX. This is because TeX keeps trying to put the rest of the Texinfo file into the group and error messages do not start to get generated until TeX has gone a long way. It’s a good rule of thumb to look for a missing @end group if you get incomprehensible error messages in TeX.

9.2.7 @need

A line containing @need n starts a new page in a printed manual if fewer than n mils (thousandths of an inch) remain on the current page. The line has no effect on Info files since they are not paginated.

10 Marking Text Within a Paragraph

In Texinfo, text within a paragraph can be marked in a variety of ways. The most important way is to specify whether a word or phrase is a definition, a metasyntactic variable, a literal example of a program or what not.

In addition, there are special commands for inserting single characters that have special meaning in Texinfo, such as braces, and for inserting symbols with special handling, such as dots and bullets. Finally, there are ways to emphasize words.

10.1 Specifying Definitions, Files, Commands etc.

Texinfo has a variety of commands for specifying just what kind of object a piece of text refers to. Metasyntactic variables, for example, are marked by one @-command and code by another. Texinfo uses this information to determine how to highlight the text. Since the pieces of text are labelled by commands that tell what kind of object they are, it is easy to change the way Texinfo formats and typesets such text. For example, code is usually illustrated in a typewriter font, but it would be easy to change the way Texinfo highlights code to use another font. This change would not effect how metasyntatic variables are highlighted. If straight typesetting commands were used in the body of the file, you would have to check every single occurrence to make sure that you were changing code and not something else that should not be changed.

In addition, the commands can be used to generate useful information from the file, such as lists of functions or file names. It is possible, for example, to write code in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains the text labelled by a specified command. You could do this to construct an index of functions if you had not already made the entries.

The commands serve a variety of purposes:

@code

Indicates text that is a literal example of a piece of a program.

@samp

Indicates text that is a literal example of a sequence of characters.

@file

Indicates the name of a file.

@kbd

Indicates the names of keys on the keyboard or characters you type.

@key

Used for the conventional name for a key on a keyboard.

@ctrl

Indicates an ASCII control character.

@var

Indicates a metasyntactic variable.

@dfn

Indicates the introductory or defining use of a term.

@cite

Indicates the name of a book.

10.1.1 @code

@code is used to indicate text that is a piece of a program which consists of entire syntactic tokens. The text follows, enclosed in braces.

For example, @code is used for an expression in a program, the name of a variable or function used in a program, or a keyword. @code is not used for a piece of a token, such as when speaking about the characters used in a token; for example, when you are explaining what letters or printable symbols can be used in the names of functions. It is also not used for input to programs unless the input is written in a language that is like a programming language. For example, it is not used for the single character commands of GNU Emacs although it is used for the names of Emacs Lisp functions that the keyboard commands invoke.

You should also @code for command names in command languages that resemble programming languages, such as Texinfo or the shell. Note, however, that @code is not used for options such as ‘-c’ when such options stand alone. There is some argument as to whether an entire shell command incorporating an option should be written using @code or @samp.

It is an error to alter the case of a word inside an @code command. This is a particularly insidious error if the language being documented is case sensitive. If the command is printf, then Printf is a misspelling. If you do not like having such a command with lower case at the beginning of a sentence, you may wish to rearrange the sentence.

In the printed manual, @code puts the argument in bold face. In the Info file, it uses ‘…’ quotation. For example:

To compare two files, showing text inserted or removed, use @code{diff}.

produces

To compare two files, showing text inserted or removed, use diff.

10.1.2 @samp

@samp is used to indicate text that is a literal example of a sequence of characters in a file, string, pattern, etc. The text follows, enclosed in braces. The argument appears within ‘…’ quotation in both the Info file and the printed manual; in addition, it is printed in a fixed-width font.

To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.

produces

To match ‘foo’ at the end of the line, use the regexp ‘foo$’.

Any time you are referring to single characters, you should use @samp unless @kbd is more appropriate. Basically, @samp is a catchall for whatever is not covered by @code, @file, @kbd.

Punctuation marks that are part of the English text that surrounds the strings you are specifying are never included within the braces. In the following sentence, for example, the commas and period are outside of the braces:

A symbol name ends in @samp{a}, @samp{b}, or @samp{c}.

10.1.3 @file

@file is used to indicate text that is the name of a file or directory. Currently, it is equivalent to @samp in its effects on the output. For example,

The @file{.el} files are in 
the @file{/gnu/emacs/lisp} directory.

produces

The ‘.el’ files are in the ‘/gnu/emacs/lisp’ directory.

10.1.4 @kbd

@kbd is used much like @code. The difference is that @kbd is for names of keys on the keyboard, or of characters you can type. For example, to refer to the command M-a, you would use

@kbd{M-a}

and to refer to M-x shell, you would use

@kbd{M-x shell}

The @kbd command has the same effect as @code in Info, but may produce a different font in a printed manual.

You can embed another @-command inside the braces of a @kbd command. This is the way to describe a command that would be described more verbosely as “press an ‘r’ and then press the <RET> key”:

@kbd{r @key{RET}}  

This produces: r <RET>

You also use the @kbd command if you are spelling out the letters you type; for example:

To give the @code{logout} command, 
type the characters @kbd{l o g o u t @key{RET}}.

This produces

To give the logout command, type the characters l o g o u t <RET>.

10.1.5 @key

@key is used for the conventional name for a key on a keyboard, as in

@key{RET}

Often, @key is used within the argument of a @kbd command, whenever the sequence of characters to be typed includes one or more keys that are described by name.

For example, to produce C-x <ESC> you would use

@kbd{C-x @key{ESC}}

The recommended names to use for keys are in upper case and are

SPC

Space.

RET

Return.

LFD

Linefeed.

TAB

Tab.

BS

Backspace.

ESC

Escape.

DEL

Delete.

SFT

Shift.

CTL

Control.

META

Meta.

There are subtleties to handling words like ‘meta’ or ‘ctrl’ which are names of shift keys. When mentioning a character in which the shift key is used, such as Meta-a, use the @kbd command alone without the @key command, but when you are referring to shift key in isolation, use the @key command. For example, you would use ‘@kbd{Meta-a}’ to produce Meta-a and ‘@key{META}’ to produce <META>.

10.1.6 @ctrl

@ctrl is used to describe an ASCII control character. The pattern of usage is @ctrl{ch}, where ch is an ASCII character whose control-equivalent is wanted. Thus, you put in an ‘f’ when you want to indicate a ‘control-f’

Thus, to specify ‘control-f’, you would enter

@ctrl{f}

which produces

f

In the Info file, this generates the specified control character, output literally into the file. This is done so a user can copy the specified control character (along with whatever else he or she wants) into another Emacs buffer and use it. Since the ‘control-h’,‘control-i’, and ‘control-j’ characters are formatting characters, they should not be indicated this way.

In a printed manual, this generates text to describe or identify that control character: an uparrow followed by the character ch.

10.1.7 @var

@var is used to indicate metasyntactic variables. A metasyntactic variable is something that stands for another piece of text. You would use a metasyntactic variable in the documentation of a function to describe the arguments that are passed to that function.

@var is not used for names of particular variables in programming languages. For example, the Texinfo variable texinfo-tex-command is not a metasyntactic variable.

Its effect in the Info file is to upcase the argument; in the printed manual, to italicize it. Example:

To delete file @var{filename}, type @code{rm @var{filename}}.

produces

To delete file filename, type rm filename.

In some documentation styles, metasyntactic variables are shown with angle brackets, for example:

…, type rm <filename>

10.1.8 @dfn

@dfn is used to identify the introductory or defining use of a technical term. The command should be used only in a passage whose purpose is to introduce a term which will be used again or which the reader ought to know. Mere passing mention of a term for the first time doesn’t deserve @dfn. It generates italics in the printed manual, and double quotation marks in the Info file. Example:

Getting rid of a file is called @dfn{deleting} it.

produces

Getting rid of a file is called deleting it.

10.1.9 @cite

@cite is used for the name of a book. It produces italics in the printed manual, and quotation marks in the Info file.

10.2 Inserting Braces, ‘@’ and Periods

‘@’ and curly braces are special characters in Texinfo. This means that you have to put an ‘@’ in front of these characters in order to insert them into text.

Periods are also special. Depending on whether the period is inside of or at the end of a sentence, less or more space is inserted after a period in a typeset manual. Since it is not always possible for Texinfo to determine when a period ends a sentence and when it is used in an abbreviation, special commands are needed. (Usually, Texinfo figures out how to handle periods, so you don’t have to use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the period that ends a sentence and after a colon.)

10.2.1 @@

@@ stands for a single @ in either printed or Info output.

10.2.2 @{

@{ stands for a single { in either printed or Info output.

10.2.3 @}

@} stands for a single } in either printed or Info output.

10.2.4 @:

@: is used after a character such as period or colon which normally causes TeX to increase the width of the following whitespace, to suppress that effect. For example, it can be used after periods that end abbreviations and do not end sentences. @: has no effect on the Info file output.

It displays @code{Foo:}@: at that time.

produces

It displays Foo: at that time.

The meanings of @: and @. in Texinfo are designed to work well with the Emacs sentence motion commands. This means they are different from their meanings in some other formatting systems that use @-commands.

10.2.5 @.

@. stands for a period that really does end a sentence, useful when TeX would otherwise assume by its heuristics that that is not so. This happens when there is a single-capital-letter word at the end of a sentence: TeX normally guesses that it is an abbreviation.

In the Info file output, @. is equivalent to a simple ‘.’. The Texinfo program preserves the amount of space that you use, so put two spaces after a period if you intend it to be the end of a sentence (as well as using @., if necessary, for the printed manual’s sake).

Give it to X. Give it to X@.  Give it to X@.

produces

Give it to X. Give it to X. Give it to X.

10.3 Inserting Dots, Bullets and TeX

An ellipsis, a line of dots, is typeset differently than a string of periods; more whitespace is put between the dots in the ellipsis than is put between the periods. Because of this, a special command is used in Texinfo for inserting dots. Also, the trademark, TeX, is typeset in a special fashion and it needs an @-command, as does the command for inserting the copyright symbol. The @bullet command is special, too. Each of these commands is followed by a pair of braces, ‘{}’, without any whitespace between the name of the command and the braces.

10.3.1 @dots{}

@dots{} generates an ellipsis which is three dots in a row, appropriately spaced, like this: ‘…’. Do not simply write three periods in the input file; that would work for the Info file output, but would produce the wrong amount of space between the periods in the printed manual.

10.3.2 @bullet{}

@bullet{} generates a large round dot, or the closest possible thing to one.

Here is a bullet: •

10.3.3 @TeX{}

@TeX{} generates ‘TeX’. In a printed manual, this is a special logo that is different from three ordinary letters.

10.4 Emphasizing Text

Usually, Texinfo changes the font automatically to mark words in the text according to what category the words belong to. The @code command, for example, does this. Most often, this is the best way to mark specified words. However, sometimes you will want to emphasize text directly. Texinfo has two ways to do this: commands that tell Texinfo to emphasize the text but leave the method to the program, and commands that specify the font to use. The first method is generally the best and it makes it possible to change the style of a document without have to re-edit it line by line.

10.4.1 @emph and @strong

@emph and @strong are two forms of emphasis. @strong is stronger.

In printed output, @emph produces italics and @strong produces bold.

In the Info file, both of these commands put asterisks around the argument.

10.4.2 @i, @b and @t

These three commands specify font changes in the printed manual and have no effect in the Info file. @i requests italic font (in some versions of TeX, a slanted font is used), @b requests bold face, and @t requests the fixed-width font used by @kbd. All three commands apply to an argument that follows, surrounded by braces.

If possible, you should avoid using these three commands. If you find a need to use one, it probably indicates a lack in the Texinfo language.

11 Conditionals

You may not always be able to use the same text for both the printed manual and the on-line Info file. In this case, you can use the conditional commands to specify which text is for the printed manual and which is for the Info file.

@ifinfo begins text that should be ignored by TeX when it typesets the printed manual. The text appears only in the Info file. The @ifinfo command should appear on a line by itself. End the info-only text with a line containing @end ifinfo by itself. At the beginning of a Texinfo file, the Info permissions are contained within a region marked by @ifinfo and @end ifinfo.

Likewise, @iftex and @end iftex lines delimit text that will not appear in the Info file but will appear in the printed manual.

For example,

@iftex
This text will appear only in the printed manual.
@end iftex


@ifinfo
However, this text will appear only in the info manual.
@end ifinfo

The preceding example produces the following. Note how you only see one of the two lines, depending on whether you are reading the on-line Info version or the printed version of this manual.

The @titlepage command is a special variant of @iftex that is used for making the title and copyright pages of the printed manual.

11.1 Using TeX Commands

Inside a region delineated by @iftex and @end iftex, you can embed ordinary TeX commands. Info will ignore these commands since they are only in that part of the file that is seen by TeX. The TeX commands are the same as any TeX commands except that an ‘@’ replaces the ‘\’ used by TeX. For example, in the @titlepage section of a Texinfo file, the TeX command @vskip is used to format the copyright page.

You can enter TeX completely, and use ‘\’ in the TeX commands by delineating a region with the @tex and @end tex commands. (These commands automatically put the region inside of @iftex and @end iftex commands.) For example,

@tex
Here you would put text with TeX commands;
such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
that will appear only  in the printed manual.
@end tex

In the Info file, nothing between @tex and @end tex will appear.

12 Printing Hardcopy

There are three shell commands for printing a hardcopy of a Texinfo file. One is for formatting the file, the second is for sorting the index and the third is for printing the formatted document. When you use the shell commands, you can either work directly in the operating system shell or work within a shell inside of GNU Emacs.

The typesetting program TeX is used for formatting a Texinfo file. TeX is a very powerful typesetting program and, if used right, does an exceptionally good job. The @-commands in a Texinfo file are translated by a file called ‘texinfo.tex’ into commands that TeX understands. (That is why the beginning of every Texinfo file starts with the line that says ‘\input texinfo’; this command tells TeX to use the ‘texinfo.tex’ file in processing the Texinfo file. Customarily, ‘texinfo.tex’ is in a directory called ‘/usr/lib/tex/macros’.) texinfo-format-buffer reads the very same @-commands in the Texinfo file and processes them differently from TeX to make an Info file.

Usually, the TeX formatting command is the shell command tex followed by the name of the Texinfo file. The TeX command produces a formatted DVI file as well as several auxiliary files containing indices, cross references, etc. The DVI file (for DeVice Independent file) can be printed on a wide variety of printers.

The TeX formatting command itself does not sort the indices. This is a misfeature of TeX. Hence, to generate a printed index, you first need a sorted index to work from.

TeX outputs raw, unsorted index files under names that obey a standard convention. These names are the name of your main input file to TeX, with everything after the first period thrown away, and the two letter names of indices added at the end. For example, the raw index output files for the input file ‘foo.texinfo’ would be ‘foo.cp’, ‘foo.vr’, ‘foo.fn’, ‘foo.tp’, ‘foo.pg’ and ‘foo.ky’. Those are exactly the arguments to give to texindex. Or else, you can use ‘??’ as “wild-cards” and give the command in this form:

texindex foo.??

For each file specified, texindex generates a sorted index file whose name is made by appending ‘s’ to the input file name. The @printindex command knows to look for a file of that name. texindex does not alter the raw index output file. After you have sorted the indices, you need to rerun the TeX command on the Texinfo file. This regenerates a formatted DVI file with the index entries in the correct order.

To summarize, this is a three step process:

1. Run the TeX command on the Texinfo file. This generates the formatted DVI file as well as the raw index files with two letter extensions.
2. Run the shell command texindex on the raw index files to sort them. The arguments to texindex are the names of the raw index files. texindex creates sorted index files whose names are the names of the raw index files with an ‘s’ appended. To cause texindex to sort all the raw index files, append ‘??’ to the Texinfo file name in place of the ‘.texinfo’ extension.
3. Rerun the TeX command on the Texinfo file. This regenerates a formatted DVI file with the index entries in the correct order. This second run also makes all the cross references correct as well. (The tables of contents are always correct.)

You need not run texindex after each TeX run. If you don’t, the next TeX run will use whatever sorted index files happen to exist from the previous use of texindex. This is usually ok while you are debugging.

Finally, the document can be printed out with the DVI print command (a shell command). Depending on the system used, the DVI print command will be a command such as lpr -d. The DVI print command may require a file name without any extension or with a ‘.dvi’ extension.

The following commands, for example, sort the indices, format and print the Bison Manual (where ‘%’ is the shell prompt):

% tex bison.texinfo
% texindex bison.??
% tex bison.texinfo
% lpr -d bison.dvi

(Remember that the words for the shell commands may be different at your site; but these are commonly used versions.)

It is often most convenient to give formatting and printing commands from a shell within GNU Emacs. This way, you can easily keep track of errors. To create a shell within Emacs, type M-x shell. In this shell, you can format and print the document. You can switch to and from this shell while it is running and do other things. If you are formatting a very long document on a slow machine, this can be very convenient; on a VAX 750, for example, formatting often takes 8 seconds or more per page depending on how loaded the computer is. Faster machines take correspondingly less time.

12.1 Formatting Requirements

Every Texinfo file that is to be input to TeX must begin with a line that looks like

\input texinfo   @c -*-texinfo-*-

This serves two functions.

1. When the file is processed by TeX, it loads the macros needed for processing a Texinfo file.
2. When the file is edited in Emacs, it causes Texinfo mode to be used.

Every Texinfo file must end with a line saying

@bye

which terminates TeX processing and forces out unfinished pages.

You also have to include two lines that specify the Info file name and the title of the printed manual:

@setfilename name-of-texinfo-file
@settitle Name of Manual

You might also want to include a line saying

@setchapternewpage odd

to cause each chapter to start on a fresh odd-numbered page.

By default, TeX typesets pages for printing in an 8.5 by 11 inch format. However, you can direct TeX to typeset a document in a 7 by 9.25 inch format that is suitable for bound books by inserting the following command on a line by itself at the beginning of the Texinfo file, before the @setchapternewpage command:

@smallbook

The Free Software Foundation distributes printed copies of the GNU Emacs Manual in this size.

Finally, TeX sometimes is unable to typeset a line without extending it into the right margin. This can occur when TeX comes upon what it interprets as a long word that it cannot hyphenate, like a net address, or a very long title. When this happens, TeX prints an error message like this:

Overfull \hbox (20.76302pt too wide)

and gives the line number along with the text of the offending line marked at all the places that TeX knows to hyphenate words. (In TeX lines are in ‘horizontal boxes’, hence the term, ‘hbox’.)

If the Texinfo file has an overfull hbox, you can rewrite the sentence so the overfull hbox does not occur or you can decide to leave it. A small excursion into the right margin often does not matter and may not even be noticable. However, unless told otherwise, TeX will print a large, ugly, black rectangle beside every line that is overfull. This is so you will notice the location of the problem if you are correcting a draft. To prevent such monstrosities from marring your final printout, put the following in the beginning of the Texinfo file on lines of their own, before the @setchapternewpage command:

@iftex
@finalout
@end iftex

See section @titlepage, for information about creating a title page. See section Generating a Table of Contents, for information about creating a table of contents.

12.2 Using Local Variables and the Compile Command

Another way to give the TeX formatting command to Texinfo is to put that command in a local variables list at the end of the Texinfo file. You can then specify the TeX formatting command as a compile-command and have Emacs run the TeX formatting command by giving the command M-x compile. This creates a special shell called the ‘*compilation buffer*’. For example, at the end of the ‘gdb.texinfo’ file, after the @bye, you would put the following:

@c Local Variables:
@c compile-command: "tex gdb.texinfo"
@c End:

This technique is most often used by programmers who compile programs this way.

13 Creating an On-line Info file

In GNU Emacs, using Texinfo mode, you can see what part or all of a Texinfo file will look like in Info by using the keyboard command C-c C-f (texinfo-format-region). This formats a region and displays in a temporary buffer called ‘*Info Region*’; however, this command does not turn on Info reading program—it just displays what the region will look like. The texinfo-format-region command is described more extensively in the chapter on using Texinfo mode. See section Formatting a Region for Info.

In GNU Emacs, the way to create a working Info file is to visit the file and invoke

M-x texinfo-format-buffer

A new buffer is created and the Info file text is generated there. C-x C-s will save it under the name specified in the @setfilename command.

If the Texinfo file has more than 30,000 bytes, texinfo-format-buffer will automatically create a tag table for it. With a tag table, Info can jump to new nodes more quickly than it can otherwise. In addition, if the file has more than 100,000 bytes in it, texinfo-format-buffer will split the file into shorter Indirect subfiles of about 50,000 bytes each. Files are split so that Info does not have to make a large buffer to hold the whole of a large Info file; instead, Info 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 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.)

When the file is split, Info itself works through a shortened version of the original file that contains 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 names 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 ‘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:’.

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 section Running Info-validate on a Large File.

13.1 Installing an Info file

An Info file is usually installed in the GNU Emacs directory called ‘info’. For Info to work, this directory must contain all the Info files, including the split off files. In addition, the ‘info’ directory must have a file that serves as a top level directory for the Info system. This file is called ‘dir’.

For example, in the ‘info’ directory, the file called ‘dir’ has the top level menu for all the Info files in the system. This file has a master menu that 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 using
                        Texinfo.

To add a new Info file, just add it to this menu. For example, if you were adding documentation for GDB, you would make the following entry:

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

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

The top node of the file, named ‘top’, should have as its parent the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses. If the file is to be installed directly in the Info directory file, use ‘(dir)’ as the parent of the top node; this is short for ‘(dir)top’, the node ‘top’ in the file ‘dir’, which is the main menu of Info.

14 Catching Mistakes

Besides mistakes with the content of what ever you are describing, there are two kinds of mistake you can make with Texinfo: you can make mistakes with @-commands, and you can make mistakes with the structure of the nodes and chapters.

There are two tools for catching the first kind of mistake and two for catching the second.

For finding problems with @-commands, your best action is to run M-x texinfo-format-region on regions of your file as you write it. In Texinfo mode, the texinfo-format-region command is bound to C-c C-f. In addition, you can run TeX on the whole file.

For finding problems with the structure of nodes and chapters, you can use C-c C-s (texinfo-show-structure) (and the related occur command) and you can use the M-x Info-validate command.

14.1 Catching Errors with Info Formatting

After you have written part of a Texinfo file, you can use the M-x texinfo-format-region command to see whether the region formats properly. In Texinfo mode, this command is bound to the keyboard command C-c C-f.

If you have made a mistake with an @-command, M-x texinfo-format-region will stop processing at or after the error and give an error message. To see where in the file the error occurred, switch to the ‘*Info Region*’ buffer; the cursor will be in a position that is after the location of the error. Also, the text will not be formatted after the place the error occurred.

For example, if you accidently end a menu with the command @end menus with an ‘s’ on the end, instead of with @end menu, you will get an error message that says:

@end menus is not handled by texinfo.

The cursor will stop at the point in the file where the error occurs, or not long after it. It will look like this:

@menu
* Using texinfo-show-structure::    Using texinfo-show-structure
                                    to catch mistakes.
* Running Info-Validate::           Checking for unreferenced nodes.
@end menus

The texinfo-format-region command does not always recognize errors. For example, no errors were reported when texinfo-format-region was run on the whole itemized list of which the following is a part:

name of the Texinfo file as an extension.  The @samp{??} are `wildcards'
that cause the shell to substitute all the raw index files.  (@xref{sorting
indices), for more information about sorting indices.) @refill
@cindex Sorting indices
@cindex Indices, sorting

@item 
@emph{Third}, rerun the @TeX{} command on the Texinfo file.  This
regenerates a formatted DVI file with the index entries in the correct
order.  This second run also makes all the cross references and table of
contents correct as well.

Instead, texinfo-format-region ran without reporting the error, but it produced output with very long lines, containing some of the original @cindex commands mixed in. (It is not practical to display these over long lines here.

However, when texinfo-format-region was run on part of the list that is shown, it did give an error message, ‘Search failed: "[{,}"’. (This error message is explained in the section on using the Emacs Lisp Debugger, see section Using the Emacs Lisp Debugger)

Sometimes texinfo-format-region will stop long after the original error; this is because it does not discover the problem until then. In this case, you will have to backtrack.

14.1.1 Using the Emacs Lisp Debugger

If an error is especially elusive, you can turn on the Emacs Lisp debugger and look at the backtrace; this tells you where in the texinfo-format-region function the problem occurred. You can turn on the debugger with the command:

M-x set-variable <RET> debug-on-error <RET> t

and turn it off with

M-x set-variable <RET> debug-on-error <RET> nil

Often, when you are using the debugger, it is easier to follow what is going on if you use the Emacs Lisp files that are not byte-compiled. The byte-compiled sources send octal numbers to the debugger that may look mysterious. To use the uncompiled source files, load ‘texinfmt.el’ and ‘texinfo.el’ with the M-x load-file command.

The debugger will not catch an error if texinfo-format-region does not detect one. In the example shown above, texinfo-format-region did not find the error when the whole list was formatted, but only when part of the list was formatted. When texinfo-format-region did not find an error, the debugger did not find one either.

However, when texinfo-format-region did report an error, it invoked the debugger. This is the backtrace it produced:

Signalling: (search-failed "[},]")
  re-search-forward("[},]")
  (while ...)
  (let ...)
  texinfo-format-parse-args()
  (let ...)
  texinfo-format-xref()
  funcall(texinfo-format-xref)
  (if ...)
  (let ...)
  (if ...)
  (while ...)
  texinfo-format-scan()
  (save-excursion ...)
  (let ...)
  texinfo-format-region(103370 103631)
* call-interactively(texinfo-format-region)

The backtrace is read from the bottom up. texinfo-format-region was called interactively; and it, in turn, called various functions, including texinfo-format-scan, texinfo-format-xref and texinfo-format-parse-args. Inside the function texinfo-format-parse-args, the function re-search-forward was called; it was this function that could not find the missing right hand brace.

See Debugging Emacs Lisp in The GNU Emacs Manual, for more information.

14.2 Catching Errors with TeX Formatting

You can also catch mistakes when you format a file with TeX.

Usually, you will want to do this after you have run texinfo-format-buffer on the same file. texinfo-format-buffer is usually faster and sometimes gives error messages that make more sense. See section Catching Errors with Info Formatting, for more information.

For example, TeX was run on the same itemized list discussed in the section on the use of texinfo-format-region (see section Catching Errors with Info Formatting); the fragment with the error looked like this:

name of the texinfo file as an extension.  The @samp{??} are `wildcards'
that cause the shell to substitute all the raw index files.  (@xref{sorting
indices, for more information about sorting indices.) @refill

This produced the following output, after which TeX stopped:

Runaway argument?
{sorting indices, for more information about sorting indices.) @refill @ETC.
! Paragraph ended before \xref was complete.
<to be read again> 
                   \par 
l.27 
     
? 

In this case, TeX produced an accurate and understandable error message: ‘Paragraph ended before \xref was complete.’ (Note, however, that TeX translated the ‘@’ into a ‘\’.) Also, ‘\par’ is an internal TeX command of no relevance to Texinfo.)

Unfortunately, TeX is not always so helpful, and sometimes you have to be truly a Sherlock Holmes to discover what went wrong.

In any case, if you run into a problem like this, you can do one of two things.

1. You can tell TeX to continue running and to ignore errors as best it can by typing r <RET> at the ‘?’ prompt.

   This is often the best thing to do. However, beware: the one error may produce a cascade of additional error messages as it consequences are felt through the rest of the file.

2. You can tell TeX to stop this run by typing x <RET> at the ‘?’ prompt.

Sometimes TeX will format a file without producing error messages even though there is a problem. This usually occurs if a command is not ended but TeX is able to continue processing anyhow. For example, if you fail to end an itemized list with the @end itemize command, TeX will write a DVI file that you can print out. The only error message that TeX will give you is the somewhat mysterious comment that

(\end occurred inside a group at level 1)

However, if you print the DVI file, you will find that the text of the file that follows the itemized list is entirely indented as if it were part of the last item in the itemized list. The error message is the way TeX says that it expected to find an @end command somewhere in the file; but that it could not locate where it was needed.

Another source of notoriously hard to find errors is a missing @end group command. If you ever are stumped by incomprehensible errors, look for a missing @end group command first.

If you do not have the header lines in the file, TeX may stop in the beginning of its run and display output that looks like the following. The ‘*’ indicates that TeX is waiting for input.

This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm 
87.10.25) (#tz-bar-a02987.tex [1])
*

In this case, simply type \end <RET> after the asterisk. Then put the header lines into the Texinfo file and run the TeX command again.

14.3 Using texinfo-show-structure

It is not always easy to keep track of the nodes, chapters, sections and subsections of a Texinfo file. This is especially true if you are revising or adding to a Texinfo file that someone else has written.

In GNU Emacs, in Texinfo mode, there is a command that will list all the lines that begin with the @-commands that specify the structure: @node, @chapter, @section, @appendix and so on. This is the texinfo-show-structure command. It is bound to the keyboard command C-c C-s. texinfo-show-structure displays the lines that begin with the node and chapter structuring @-commands in another window called the ‘*Occur*’ buffer. For example, when texinfo-show-structure is run on the first part of this chapter, it produces the following:

Lines matching
"^@\\(chapter\\|unnum\\|appendix\\|sect\\|sub\\|heading\\|major
\\|node\\)" in buffer new-texinfo-manual.texinfo.
  2:@node     catching mistakes, @-Command Syntax, running info, top
  4:@chapter Catching Mistakes
 41:@node debugging with info, debugging with tex, , catching mistakes
 43:@section Catching errors with Info Formatting

This means that lines 2, 4, 41 and 43 began with @node, @chapter, @node, and @section respectively. If you move your cursor into the ‘*Occur*’ window, you can position the cursor over one of the lines and use the C-c C-c command (occur-mode-goto-occurrence), to jump to the corresponding spot in the Texinfo file. See Using Occur in The GNU Emacs Manual, for more information about occur-mode-goto-occurrence.

The first line in the ‘*Occur*’ window describes the regular expression specified by texinfo-heading-pattern. This regular expression is the pattern that texinfo-show-structure looks for. See Using Regular Expressions in The GNU Emacs Manual, for more information.

When you give the texinfo-show-structure command, it will show the structure of the whole buffer. If you want to see the structure of just a part of the buffer, of one chapter, for example, use the C-x n (narrow-to-region) command to mark the region. (See Narrowing in The GNU Emacs Manual.) This is how the example used above was generated. (To see the whole buffer again, use C-x w (widen).)

You can remind yourself of the structure of a Texinfo file by looking at the list in the ‘*Occur*’ window; and if you have mis-named a node or left out a section, you can correct the mistake.

14.3.1 Using occur

Sometimes the texinfo-show-structure command produces too much information. Perhaps you want to remind yourself of the overall structure of a Texinfo file, and are overwhelmed by the detailed list produced by texinfo-show-structure. In this case, you can use the occur command itself. To do this, type

M-x occur

and then, when prompted, type a regexp, a regular expression for the pattern you want to match. (See Regular Expressions in The GNU Emacs Manual.) occur works from the current location of the cursor in the buffer to the end of the buffer. If you want to run occur on the whole buffer, place the cursor at the beginning of the buffer. For example, to see all the lines that contain the word ‘@chapter’ in them, just type ‘@chapter’. This will produce a list of the chapters. It will also list all the sentences with ‘@chapter’ in the middle of the line. If you want to see only those lines that start with the word ‘@chapter’, type ‘^@chapter’ when prompted by occur. If you want to see all the lines that end with a word or phrase, end the last word with a ‘$’; for example, ‘catching mistakes$’. This can be helpful when you want to see all the nodes that are part of the same chapter or section and therefore have the same ‘Up’ pointer.

See Using Occur in The GNU Emacs Manual, for more information.

14.4 Finding Badly Referenced Nodes

You can check whether any of the ‘Next’, ‘Previous’, ‘Up’ or other node pointers fail to point to a node with the Info-validate command. This command checks that every node pointer points to an existing node.

To use this command, you first need to load the info library and then do M-x Info-validate.

M-x load-library <RET> info <RET> 
M-x Info-validate

(Note that all the Info commands require an uppercase ‘I’.)

If your file is ok, you will receive a message that says “File appears valid”. However, if you have a pointer that does not point to a node, error messages will be displayed in a buffer called ‘*problems in info file*’.

For example, Info-validate was run on a test file that contained only the first node of this manual. One of the messages said:

In node "Overview", invalid Next: Texinfo Mode

This meant that the node called ‘Overview’ had a ‘Next’ pointer that did not point to anything (which was true in this case, since the test file had only one node in it).

Now suppose we add a node named ‘Texinfo Mode’ to our test case but we don’t specify a ‘Previous’ for this node. Then we will get the following error message:

In node "Texinfo Mode", should have Previous: Overview

This is because every ‘Next’ pointer should be matched by a ‘Previous’ (in the node where the ‘Next’ points) which points back.

Info-validate also checks that all menu items and cross-references point to actual nodes.

Significantly, Info-validate does not work with large files that have been split. (Info thinks of a large file as being over 100,000 bytes, approximately.) In order to use Info-validate on a large file, you must run texinfo-format-buffer with an argument so that it does not split the Info file, and then create a tag table.

14.4.1 Running Info-validate on a Large File.

You can run Info-validate only on a single Info file. The command will not work on indirect subfiles that are generated when the master file is split. If you have a large file (longer than 100,000 bytes), you need to run the texinfo-format-buffer command in such a way that it does not create indirect subfiles. You will also need to create a tag table. When you have done this, you can run Info-validate and look for badly referenced nodes.

After you have validated the node structure, you can rerun texinfo-format-buffer in the normal way so it will construct the tag table and split the file automatically or, you can make the tag table and split the file manually.

To prevent the texinfo-format-buffer command from splitting a Texinfo file into smaller Info files, give a prefix to the M-x texinfo-format-buffer command:

C-u  M-x texinfo-format-buffer

When you do this, Texinfo will not split the file and will not create a tag table for it.

Before you can run M-x Info-validate on the Info file, you need to create a tag table for it. In order to do this, you first need to load the info library into Emacs with the following command:

M-x load-library <RET> info <RET>

Then you can give the command:

M-x Info-tagify

This creates a file which you can validate.

M-x Info-validate

After you have checked the validity of the nodes, you can either run M-x texinfo-format-buffer as you would normally, or else tagify and split the file manually with the two commands Info-tagify and Info-split.

14.4.2 Splitting a File Manually

If the file has more than 100,000 or so bytes in it, you should split it or else let the texinfo-format-buffer command do it for you automatically. (Generally you will let texinfo-format-buffer do this job for you. See section Creating an On-line Info file.)

The split off files are called the indirect subfiles.

Info files are split to save memory. With smaller files, Emacs does not have make such a large buffer to hold the information. This way, Emacs can save memory.

If the Info file has more than 30 nodes, you should also make a tag table for it. See section Running Info-validate on a Large File., for information about creating a tag table.

Before running Info-split, you need to load the info library into Emacs by giving the command M-x load-library <RET> info <RET>. After you have done this, you can give the two commands:

M-x Info-tagify
M-x Info-split

(Note that the ‘I’ in ‘Info’ is uppercase.)

When you use the Info-split command, the buffer is modified into a (small) Info file which lists the indirect subfiles. This file should be saved in place of the original visited file. The indirect subfiles are written in the same directory the original file is in, with names generated by appending ‘-’ and a number to the original file name.

The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles.

Appendix A @-Command Syntax

The character ‘@’ is used to start special Texinfo commands. (It has the same meaning that ‘\’ has in plain TeX.) Syntactically, there are three classes of @-commands:

1. Non-alphabetic commands: @ followed by a punctuation character.

These commands are always part of the text within a paragraph, and never take any argument. The two characters (@ and the other one) are complete in themselves. For example, @., @:, @{ and @}.

2. Alphabetic commands used within a paragraph.

These commands have @ followed by a letter or a word, followed by an argument within braces. For example, the command @dfn indicates the introductory or defining use of a term; it is used as follows: ‘In Texinfo, @-commands are @dfn{mark-up} commands.’

3. Alphabetic commands used outside of paragraphs.

Each such command occupies an entire line. The line starts with @, followed by the name of the command (a word) such as @center or @cindex. If no argument is needed, the word is followed by the end of the line. If there is an argument, it is separated from the command name by a space.

Thus, the alphabetic commands fall into two classes that have different argument syntax. You cannot tell which class a command falls in by the appearance of its name, but you can tell by the command’s meaning: if it makes sense to use the command together with other words as part of a paragraph, the command is in class 2 and must be followed by an argument in braces; otherwise, it is in class 3 and uses the rest of the line as its argument.

The purpose of having different syntax for commands of classes 2 and 3 is to make the Texinfo file easier to read, and also to help the GNU Emacs paragraph and filling commands work properly. There is only one exception to this rule: the command @refill, which is always used at the end of a paragraph immediately following the final period or other punctuation character. @refill takes no argument. @refill never confuses the Emacs paragraph commands because it cannot start at the beginning of a line.

Appendix B Include Files

When Info was first created, it was customary to create many small Info files on one subject. By doing this, Emacs did not have to make a large buffer to hold the whole of a large Info file; instead, Emacs allocated just enough memory for the small Info file that was needed at the time. This way, Emacs could avoid wasting memory. Include files were designed as a way to create a single, large printed manual out of several smaller Info files.

However, because large Info files can now be split, include files are no longer strictly necessary and they are used infrequently. Most often, they are now used in projects where several different people are writing different sections of a document simultaneously.

B.1 How Include Files Work

In a Texinfo file, a line of the form @include ‘filename’ is ignored when the Info file is generated, but in a printed manual it causes the contents of the file ‘filename’ to be processed and included in the manual. The contents of the file ‘filename’ can be ignored by Info because the first file can refer to ‘filename’ with menus as well as cross references. In the Info system, all the information is, as it were, ‘in one place’. However, when two printed manuals are made from two separate Texinfo files, the two manuals are separate, and even if they give each other as references, the references are to separate documents. Consequently, you will sometimes want to create a comprehensive, printed manual that contains all the necessary information together in one place.

@include files are special Texinfo files that are used only for making such a comprehensive manual. They are listed inside an outer file that contains nothing but the beginning and end matter of a Texinfo file and a number of @include commands listing the included files.

An @include file–a file that will be listed inside an outer file and processed with the @include command–should not start with ‘\input texinfo’, as that has already been done by the outer file, and the character ‘\’ has already been redefined to generate a backslash in the output. Instead, an @include file usually begins with a node; it lacks the beginning and ending of a Texinfo file that are described in the chapters on beginning and ending a file. See section Beginning a Texinfo File, and see section Ending a Texinfo File

Likewise, an @include file should not end with @bye, since that would terminate TeX processing immediately.

Here is an example of a outer Texinfo file with @include files within it:

\input texinfo @c -*-texinfo-*-
@setfilename  include 
@settitle Include Manual

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

@page
Copyright @copyright{} 1988 Free Software Foundation, Inc.
@end titlepage

@include foo.texinfo
@include bar.texinfo

@unnumbered Concept Index
@printindex cp

@summarycontents
@contents

@bye

Appendix C TeX Input Initialization

You must put an input command on the first line of every Texinfo file to tell TeX to use the ‘texinfo.tex’ file when it is processing the Texinfo source file. Otherwise TeX will not know what to do with the @-commands. (The TeX input command is written as ‘\input texinfo’. See section The First Line of a Texinfo File.)

TeX needs to be told where to find the ‘texinfo.tex’ file that you have told it to input. The preferred way to do this is to put ‘texinfo.tex’ in the default inputs directory, which is the ‘/usr/lib/tex/macros’ directory. If this is done (as it usually is when GNU Emacs is installed), TeX will find the file and you don’t have to do anything. Alternatively, you can put ‘texinfo.tex’ in the directory in which the Texinfo source file is located.

However, you may want to specify the location of the \input file yourself. One way to do this is to write the complete path for the file after the \input command. Another way is to set the ‘TEXINPUTS’ environment variable in your ‘.cshrc’ or ‘.profile’ file. The ‘TEXINPUTS’ environment variable will tell TeX where to find the ‘texinfo.tex’ file and any other file that you might want TeX to use.

Whether you use a ‘.cshrc’ or ‘.profile’ file depends on whether you use ‘csh’ or ‘sh’ for your shell command interpreter. When you use ‘csh’, it looks to the ‘.cshrc’ file for initialization information, and when you use ‘sh’, it looks to the ‘.profile’ file.

In a ‘.cshrc’ file, you could use the following csh command sequence:

setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros

In a ‘.profile’ file, you could use the following sh command sequence:

TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
export TEXINPUTS

This would cause TeX to look for ‘\input’ file first in the current directory, indicated by the ‘.’, then in a hypothetical user’s ‘me/mylib’ directory, and finally in the system library.

Appendix D Standard text for Copying Permissions

Texinfo files should contain sections that tell the readers that they have the right to copy and distribute the Info file, the printed manual and any accompanying software. This appendix contains the standard text of the Free Software Foundation copying permission notice. For an example of the text that could be used for the Distribution, General Public License and NO WARRANTY sections of a document, see the latest version of the GNU Emacs Manual.

The texts of the Free Software Foundation copying permission notice in the @ifinfo section and in the @titlepage section are slightly different.

The @ifinfo section usually begins with a line that says what the file documents. This is what a person looking at the file will first read if he or she reads the unprocessed Texinfo file or if he or she uses the advanced Info command g *. See (info)info, for more information. (If the reader uses the regular Info commands, he or she will usually start reading at the first node and skip this first section, which is not in a node.)

In the @ifinfo section, the summary sentence should be followed by a copyright notice and then by the copying permission notice. One of the copying permission paragraphs is enclosed in @ignore and @end ignore commands. This paragraph states that the Texinfo file can be processed through TeX and printed, provided the printed manual carries the proper copying permission notice. This paragraph is not made part of the Info file since it is not relevant to the Info file; but it is a mandatory part of the Texinfo file since it permits people to process the Texinfo file in TeX.

In the printed manual, the Free Software Foundation copying permission notice follows the copyright notice and publishing information and is located within the region delineated by the @titlepage and @end titlepage commands. The copying permission notice is exactly the same as the notice in the @ifinfo section except that the paragraph enclosed in @ignore and @end ignore commands is not part of the notice.

To make it simpler to copy the permission notice into each section of the Texinfo file, the complete permission notices for each section are reproduced in full below even though most of the information is redundant.

Note that you my have to specify the correct name of a section mentioned in the permission notice. For example, in the GDB Manual, the name of the section referring to the General Public License is called the “GDB General Public License”, but in the sample shown below, that section is referred to generically as the “General Public License”.

D.1 Ifinfo Copying Permissions

In the @ifinfo section of the Texinfo file, the standard Free Software Foundation permission notices reads as follows:

This file documents …

Copyright 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Distribution'' and ``General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``Distribution'' and ``General Public
License'' may be included in a translation approved by the author instead
of in the original English.

D.2 Titlepage Copying Permissions

In the @titlepage section of the Texinfo file, the standard Free Software Foundation copying permission notices follows the copyright notice and publishing information. The standard phrasing is:

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Distribution'' and ``General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``Distribution'' and ``General Public
License'' may be included in a translation approved by the author instead
of in the original English.

Command Index

(When used in a Texinfo file, @-commands are preceded by an ‘@’.)

Concept Index