2. Using Texinfo Mode

You may edit a Texinfo file with any text editor you choose. A Texinfo file is no different from any other ASCII file. However, XEmacs comes with a special mode, called Texinfo mode, that provides XEmacs commands and tools to help ease your work.

This chapter describes features of XEmacs’ Texinfo mode but not any features of the Texinfo formatting language. So if you are reading this manual straight through from the beginning, you may want to skim through this chapter briefly and come back to it after reading succeeding chapters which describe the Texinfo formatting language in detail.

2.1 Texinfo Mode Overview

Texinfo mode provides special features for working with Texinfo files. You can:

• Insert frequently used @-commands.
• Automatically create @node lines.
• Show the structure of a Texinfo source file.
• Automatically create or update the ‘Next’, ‘Previous’, and ‘Up’ pointers of a node.
• Automatically create or update menus.
• Automatically create a master menu.
• Format a part or all of a file for Info.
• Typeset and print part or all of a file.

Perhaps the two most helpful features are those for inserting frequently used @-commands and for creating node pointers and menus.

2.2 The Usual XEmacs Editing Commands

In most cases, the usual Text mode commands work the same in Texinfo mode as they do in Text mode. Texinfo mode adds new editing commands and tools to XEmacs’ general purpose editing features. The major difference concerns filling. In Texinfo mode, the paragraph separation variable and syntax table are redefined so that Texinfo commands that should be on lines of their own are not inadvertently included in paragraphs. Thus, the M-q (fill-paragraph) command will refill a paragraph but not mix an indexing command on a line adjacent to it into the paragraph.

In addition, Texinfo mode sets the page-delimiter variable to the value of texinfo-chapter-level-regexp; by default, this is a regular expression matching the commands for chapters and their equivalents, such as appendices. With this value for the page delimiter, you can jump from chapter title to chapter title with the C-x ] (forward-page) and C-x [ (backward-page) commands and narrow to a chapter with the C-x n p (narrow-to-page) command. (See (xemacs)Pages section ‘Pages’ in XEmacs User’s Manual, for details about the page commands.)

You may name a Texinfo file however you wish, but the convention is to end a Texinfo file name with one of the extensions ‘.texinfo’, ‘.texi’, ‘.txi’, or ‘.tex’. A longer extension is preferred, since it is explicit, but a shorter extension may be necessary for operating systems that limit the length of file names. XEmacs automatically enters Texinfo mode when you visit a file with a ‘.texinfo’, ‘.texi’ or ‘.txi’ extension. Also, XEmacs switches to Texinfo mode when you visit a file that has ‘-*-texinfo-*-’ in its first line. If ever you are in another mode and wish to switch to Texinfo mode, type M-x texinfo-mode.

Like all other XEmacs features, you can customize or enhance Texinfo mode as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones.

2.3 Inserting Frequently Used Commands

Texinfo mode provides commands to insert various frequently used @-commands into the buffer. You can use these commands to save keystrokes.

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

C-c C-c c

M-x texinfo-insert-@code

Insert @code{} and put the cursor between the braces.

C-c C-c d

M-x texinfo-insert-@dfn

Insert @dfn{} and put the cursor between the braces.

C-c C-c e

M-x texinfo-insert-@end

Insert @end and attempt to insert the correct following word, such as ‘example’ or ‘table’. (This command does not handle nested lists correctly, but inserts the word appropriate to the immediately preceding list.)

C-c C-c i

M-x texinfo-insert-@item

Insert @item and put the cursor at the beginning of the next line.

C-c C-c k

M-x texinfo-insert-@kbd

Insert @kbd{} and put the cursor between the braces.

C-c C-c n

M-x texinfo-insert-@node

Insert @node and a comment line listing the sequence for the ‘Next’, ‘Previous’, and ‘Up’ nodes. Leave point after the @node.

C-c C-c o

M-x texinfo-insert-@noindent

Insert @noindent and put the cursor at the beginning of the next line.

C-c C-c s

M-x texinfo-insert-@samp

Insert @samp{} and put the cursor between the braces.

C-c C-c t

M-x texinfo-insert-@table

Insert @table followed by a <SPC> and leave the cursor after the <SPC>.

C-c C-c v

M-x texinfo-insert-@var

Insert @var{} and put the cursor between the braces.

C-c C-c x

M-x texinfo-insert-@example

Insert @example and put the cursor at the beginning of the next line.

C-c C-c {

M-x texinfo-insert-braces

Insert {} and put the cursor between the braces.

C-c }

C-c ]

M-x up-list

Move from between a pair of braces forward past the closing brace. Typing C-c ] is easier than typing C-c }, which is, however, more mnemonic; hence the two keybindings. (Also, you can move out from between braces by typing C-f.)

To put a command such as @code{…} around an existing word, position the cursor in front of the word and type C-u 1 C-c C-c c. This makes it easy to edit existing plain text. The value of the prefix argument tells XEmacs how many words following point to include between braces—‘1’ for one word, ‘2’ for two words, and so on. Use a negative argument to enclose the previous word or words. If you do not specify a prefix argument, XEmacs inserts the @-command string and positions the cursor between the braces. This feature works only for those @-commands that operate on a word or words within one line, such as @kbd and @var.

This set of insert commands was created after analyzing the frequency with which different @-commands are used in the XEmacs 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’.

C-c C-c C-d (texinfo-start-menu-description) is an insert command that works differently from the other insert commands. It inserts a node’s section or chapter title in the space for the description in a menu entry line. (A menu entry has three parts, the entry name, the node name, and the description. Only the node name is required, but a description helps explain what the node is about. See section The Parts of a Menu.)

To use texinfo-start-menu-description, position point in a menu entry line and type C-c C-c C-d. The command looks for and copies the title that goes with the node name, and inserts the title as a description; it positions point at beginning of the inserted text so you can edit it. The function does not insert the title if the menu entry line already contains a description.

This command is only an aid to writing descriptions; it does not do the whole job. You must edit the inserted text since a title tends to use the same words as a node name but a useful description uses different words.

2.4 Showing the Section Structure of a File

You can show the section structure of a Texinfo file by using the C-c C-s command (texinfo-show-structure). This command shows the section structure of a Texinfo file by listing the lines that begin with the @-commands for @chapter, @section, and the like. It constructs what amounts to a table of contents. These lines are displayed in another buffer called the ‘*Occur*’ buffer. In that buffer, 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.

C-c C-s

M-x texinfo-show-structure

Show the @chapter, @section, and such lines of a Texinfo file.

C-c C-c

M-x occur-mode-goto-occurrence

Go to the line in the Texinfo file corresponding to the line under the cursor in the ‘*Occur*’ buffer.

If you call texinfo-show-structure with a prefix argument by typing C-u C-c C-s, it will list not only those lines with the @-commands for @chapter, @section, and the like, but also the @node lines. You can use texinfo-show-structure with a prefix argument to check whether the ‘Next’, ‘Previous’, and ‘Up’ pointers of an @node line are correct.

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 by using the C-x n n (narrow-to-region) command and texinfo-show-structure will work on only that region. To see the whole buffer again, use C-x n w (widen). (See (xemacs)Narrowing section ‘Narrowing’ in XEmacs User’s Manual, for more information about the narrowing commands.)

In addition to providing the texinfo-show-structure command, Texinfo mode sets the value of the page delimiter variable to match the chapter-level @-commands. This enables you to use the C-x ] (forward-page) and C-x [ (backward-page) commands to move forward and backward by chapter, and to use the C-x n p (narrow-to-page) command to narrow to a chapter. See (xemacs)Pages section ‘Pages’ in XEmacs User’s Manual, for more information about the page commands.

2.5 Updating Nodes and Menus

Texinfo mode provides commands for automatically creating or updating menus and node pointers. The commands are called “update” commands because their most frequent use is for updating a Texinfo file after you have worked on it; but you can use them to insert the ‘Next’, ‘Previous’, and ‘Up’ pointers into an @node line that has none and to create menus in a file that has none.

If you do not use the updating commands, you need to write menus and node pointers by hand, which is a tedious task.

2.5.1 The Updating Commands

You can use the updating commands to:

• insert or update the ‘Next’, ‘Previous’, and ‘Up’ pointers of a node,
• insert or update the menu for a section, and
• create a master menu for a Texinfo source file.

You can also use the commands to update all the nodes and menus in a region or in a whole Texinfo file.

The updating commands work only with conventional Texinfo files, which are structured hierarchically like books. In such files, a structuring command line must follow closely after each @node line, except for the ‘Top’ @node line. (A structuring command line is a line beginning with @chapter, @section, or other similar command.)

You can write the structuring command line on the line that follows immediately after an @node line or else on the line that follows after a single @comment line or a single @ifinfo line. You cannot interpose more than one line between the @node line and the structuring command line; and you may interpose only an @comment line or an @ifinfo line.

Commands which work on a whole buffer require that the ‘Top’ node be followed by a node with an @chapter or equivalent-level command. The menu updating commands will not create a main or master menu for a Texinfo file that has only @chapter-level nodes! The menu updating commands only create menus within nodes for lower level nodes. To create a menu of chapters, you must provide a ‘Top’ node.

The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. This is a deficiency. Rather than use menu entries, you can use cross references to refer to other Info files. None of the updating commands affect cross references.

Texinfo mode has five updating commands that are used most often: two are for updating the node pointers or menu of a single node (or a region); two are for updating every node pointer and menu in a file; and one, the texinfo-master-menu command, is for creating a master menu for a complete file, and optionally, for updating every node and menu in the whole Texinfo file.

The texinfo-master-menu command is the primary command:

C-c C-u m

M-x texinfo-master-menu

Create or update a master menu that includes all the other menus (incorporating the descriptions from pre-existing menus, if any).

With an argument (prefix argument, C-u, if interactive), first create or update all the nodes and all the regular menus in the buffer before constructing the master menu. (See section The Top Node and Master Menu, for more about a master menu.)

For texinfo-master-menu to work, the Texinfo file must have a ‘Top’ node and at least one subsequent node.

After extensively editing a Texinfo file, you can type the following:

C-u M-x texinfo-master-menu or C-u C-c C-u m

This updates all the nodes and menus completely and all at once.

The other major updating commands do smaller jobs and are designed for the person who updates nodes and menus as he or she writes a Texinfo file.

The commands are:

C-c C-u C-n

M-x texinfo-update-node

Insert the ‘Next’, ‘Previous’, and ‘Up’ pointers for the node that point is within (i.e., for the @node line preceding point). If the @node line has pre-existing ‘Next’, ‘Previous’, or ‘Up’ pointers in it, the old pointers are removed and new ones inserted. With an argument (prefix argument, C-u, if interactive), this command updates all @node lines in the region (which is the text between point and mark).

C-c C-u C-m

M-x texinfo-make-menu

Create or update the menu in the node that point is within. With an argument (C-u as prefix argument, if interactive), the command makes or updates menus for the nodes which are either within or a part of the region.

Whenever texinfo-make-menu updates an existing menu, the descriptions from that menu are incorporated into the new menu. This is done by copying descriptions from the existing menu to the entries in the new menu that have the same node names. If the node names are different, the descriptions are not copied to the new menu.

C-c C-u C-e

M-x texinfo-every-node-update

Insert or update the ‘Next’, ‘Previous’, and ‘Up’ pointers for every node in the buffer.

C-c C-u C-a

M-x texinfo-all-menus-update

Create or update all the menus in the buffer. With an argument (C-u as prefix argument, if interactive), first insert or update all the node pointers before working on the menus.

If a master menu exists, the texinfo-all-menus-update command updates it; but the command does not create a new master menu if none already exists. (Use the texinfo-master-menu command for that.)

When working on a document that does not merit a master menu, you can type the following:

C-u C-c C-u C-a or C-u M-x texinfo-all-menus-update

This updates all the nodes and menus.

The texinfo-column-for-description variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it can be useful to reduce it to as low as 24. You can set the variable via customization (see (xemacs)Changing an Option section ‘Changing an Option’ in XEmacs User’s Manual) or with the M-x set-variable command (see (xemacs)Examining section ‘Examining and Setting Variables’ in XEmacs User’s Manual).

Also, the texinfo-indent-menu-description command may be used to indent existing menu descriptions to a specified column. Finally, if you wish, you can use the texinfo-insert-node-lines command to insert missing @node lines into a file. (See section Other Updating Commands, for more information.)

2.5.2 Updating Requirements

To use the updating commands, you must organize the Texinfo file hierarchically with chapters, sections, subsections, and the like. When you construct the hierarchy of the manual, do not ‘jump down’ more than one level at a time: you can follow the ‘Top’ node with a chapter, but not with a section; you can follow a chapter with a section, but not with a subsection. However, you may ‘jump up’ any number of levels at one time—for example, from a subsection to a chapter.

Each @node line, with the exception of the line for the ‘Top’ node, must be followed by a line with a structuring command such as @chapter, @section, or @unnumberedsubsec.

Each @node line/structuring-command line combination must look either like this:

@node     Comments,  Minimum, Conventions, Overview
@comment  node-name, next,    previous,    up
@section Comments

or like this (without the @comment line):

@node Comments, Minimum, Conventions, Overview
@section Comments

or like this (without the explicit node pointers):

@node Comments
@section Comments

In this example, ‘Comments’ is the name of both the node and the section. The next node is called ‘Minimum’ and the previous node is called ‘Conventions’. The ‘Comments’ section is within the ‘Overview’ node, which is specified by the ‘Up’ pointer. (Instead of an @comment line, you may also write an @ifinfo line.)

If a file has a ‘Top’ node, it must be called ‘top’ or ‘Top’ and be the first node in the file.

The menu updating commands create a menu of sections within a chapter, a menu of subsections within a section, and so on. This means that you must have a ‘Top’ node if you want a menu of chapters.

Incidentally, the makeinfo command will create an Info file for a hierarchically organized Texinfo file that lacks ‘Next’, ‘Previous’ and ‘Up’ pointers. Thus, if you can be sure that your Texinfo file will be formatted with makeinfo, you have no need for the update node commands. (See section Creating an Info File, for more information about makeinfo.) However, both makeinfo and the texinfo-format-… commands require that you insert menus in the file.

2.5.3 Other Updating Commands

In addition to the five major updating commands, Texinfo mode possesses several less frequently used updating commands:

M-x texinfo-insert-node-lines

Insert @node lines before the @chapter, @section, and other sectioning commands wherever they are missing throughout a region in a Texinfo file.

With an argument (C-u as prefix argument, if interactive), the texinfo-insert-node-lines command not only inserts @node lines but also inserts the chapter or section titles as the names of the corresponding nodes. In addition, it inserts the titles as node names in pre-existing @node lines that lack names. Since node names should be more concise than section or chapter titles, you must manually edit node names so inserted.

For example, the following marks a whole buffer as a region and inserts @node lines and titles throughout:

C-x h C-u M-x texinfo-insert-node-lines

This command inserts titles as node names in @node lines; the texinfo-start-menu-description command (see section Inserting Frequently Used Commands) inserts titles as descriptions in menu entries, a different action. However, in both cases, you need to edit the inserted text.

M-x texinfo-multiple-files-update

Update nodes and menus in a document built from several separate files. With C-u as a prefix argument, create and insert a master menu in the outer file. With a numeric prefix argument, such as C-u 2, first update all the menus and all the ‘Next’, ‘Previous’, and ‘Up’ pointers of all the included files before creating and inserting a master menu in the outer file. The texinfo-multiple-files-update command is described in the appendix on @include files. See section texinfo-multiple-files-update.

M-x texinfo-indent-menu-description

Indent every description in the menu following point to the specified column. You can use this command to give yourself more space for descriptions. With an argument (C-u as prefix argument, if interactive), the texinfo-indent-menu-description command indents every description in every menu in the region. However, this command does not indent the second and subsequent lines of a multi-line description.

M-x texinfo-sequential-node-update

Insert the names of the nodes immediately following and preceding the current node as the ‘Next’ or ‘Previous’ pointers regardless of those nodes’ hierarchical level. This means that the ‘Next’ node of a subsection may well be the next chapter. Sequentially ordered nodes are useful for novels and other documents that you read through sequentially. (However, in Info, the g * command lets you look through the file sequentially, so sequentially ordered nodes are not strictly necessary.) With an argument (prefix argument, if interactive), the texinfo-sequential-node-update command sequentially updates all the nodes in the region.

2.6 Formatting for Info

Texinfo mode provides several commands for formatting part or all of a Texinfo file for Info. Often, when you are writing a document, you want to format only part of a file—that is, a region.

You can use either the texinfo-format-region or the makeinfo-region command to format a region:

C-c C-e C-r

M-x texinfo-format-region

C-c C-m C-r

M-x makeinfo-region

Format the current region for Info.

You can use either the texinfo-format-buffer or the makeinfo-buffer command to format a whole buffer:

C-c C-e C-b

M-x texinfo-format-buffer

C-c C-m C-b

M-x makeinfo-buffer

Format the current buffer for Info.

For example, after writing a Texinfo file, you can type the following:

C-u C-c C-u m
or
C-u M-x texinfo-master-menu

This updates all the nodes and menus. Then type the following to create an Info file:

C-c C-m C-b
or
M-x makeinfo-buffer

For TeX or the Info formatting commands to work, the file must include a line that has @setfilename in its header.

See section Creating an Info File, for details about Info formatting.

2.7 Printing

Typesetting and printing a Texinfo file is a multi-step process in which you first create a file for printing (called a DVI file), and then print the file. Optionally, you may also create indices. To do this, you must run the texindex command after first running the tex typesetting command; and then you must run the tex command again. Or else run the texi2dvi command which automatically creates indices as needed (see section Format with texi2dvi).

Often, when you are writing a document, you want to typeset and print only part of a file to see what it will look like. You can use the texinfo-tex-region and related commands for this purpose. Use the texinfo-tex-buffer command to format all of a buffer.

C-c C-t C-b

M-x texinfo-tex-buffer

Run texi2dvi on the buffer. In addition to running TeX on the buffer, this command automatically creates or updates indices as needed.

C-c C-t C-r

M-x texinfo-tex-region

Run TeX on the region.

C-c C-t C-i

M-x texinfo-texindex

Run texindex to sort the indices of a Texinfo file formatted with texinfo-tex-region. The texinfo-tex-region command does not run texindex automatically; it only runs the tex typesetting command. You must run the texinfo-tex-region command a second time after sorting the raw index files with the texindex command. (Usually, you do not format an index when you format a region, only when you format a buffer. Now that the texi2dvi command exists, there is little or no need for this command.)

C-c C-t C-p

M-x texinfo-tex-print

Print the file (or the part of the file) previously formatted with texinfo-tex-buffer or texinfo-tex-region.

For texinfo-tex-region or texinfo-tex-buffer to work, the file must start with a ‘\input texinfo’ line and must include an @settitle line. The file must end with @bye on a line by itself. (When you use texinfo-tex-region, you must surround the @settitle line with start-of-header and end-of-header lines.)

See section Formatting and Printing Hardcopy, for a description of the other TeX related commands, such as tex-show-print-queue.

2.8 Texinfo Mode Summary

In Texinfo mode, each set of commands has default keybindings that begin with the same keys. All the commands that are custom-created for Texinfo mode begin with C-c. The keys are somewhat mnemonic.

Insert Commands

The insert commands are invoked by typing C-c twice and then the first letter of the @-command to be inserted. (It might make more sense mnemonically to use C-c C-i, for ‘custom insert’, but C-c C-c is quick to type.)

C-c C-c c       Insert ‘@code’.
C-c C-c d       Insert ‘@dfn’.
C-c C-c e       Insert ‘@end’.
C-c C-c i       Insert ‘@item’.
C-c C-c n       Insert ‘@node’.
C-c C-c s       Insert ‘@samp’.
C-c C-c v       Insert ‘@var’.
C-c {       Insert braces.
C-c ]
C-c }       Move out of enclosing braces.

C-c C-c C-d     Insert a node's section title
               in the space for the description
               in a menu entry line.

Show Structure

The texinfo-show-structure command is often used within a narrowed region.

C-c C-s         List all the headings.

The Master Update Command

The texinfo-master-menu command creates a master menu; and can be used to update every node and menu in a file as well.

C-c C-u m
M-x texinfo-master-menu
               Create or update a master menu.

C-u C-c C-u m   With C-u as a prefix argument, first
               create or update all nodes and regular
               menus, and then create a master menu.

Update Pointers

The update pointer commands are invoked by typing C-c C-u and then either C-n for texinfo-update-node or C-e for texinfo-every-node-update.

C-c C-u C-n     Update a node.
C-c C-u C-e     Update every node in the buffer.

Update Menus

Invoke the update menu commands by typing C-c C-u and then either C-m for texinfo-make-menu or C-a for texinfo-all-menus-update. To update both nodes and menus at the same time, precede C-c C-u C-a with C-u.

C-c C-u C-m     Make or update a menu.

C-c C-u C-a     Make or update all
               menus in a buffer.

C-u C-c C-u C-a With C-u as a prefix argument,
               first create or update all nodes and
               then create or update all menus.

Format for Info

The Info formatting commands that are written in XEmacs Lisp are invoked by typing C-c C-e and then either C-r for a region or C-b for the whole buffer.

The Info formatting commands that are written in C and based on the makeinfo program are invoked by typing C-c C-m and then either C-r for a region or C-b for the whole buffer.

Use the texinfo-format… commands:

C-c C-e C-r     Format the region.
C-c C-e C-b     Format the buffer.

Use makeinfo:

C-c C-m C-r     Format the region.
C-c C-m C-b     Format the buffer.
C-c C-m C-l     Recenter the makeinfo output buffer.
C-c C-m C-k     Kill the makeinfo formatting job.

Typeset and Print

The TeX typesetting and printing commands are invoked by typing C-c C-t and then another control command: C-r for texinfo-tex-region, C-b for texinfo-tex-buffer, and so on.

C-c C-t C-r     Run TeX on the region.
C-c C-t C-b     Run texi2dvi on the buffer.
C-c C-t C-i     Run texindex.
C-c C-t C-p     Print the DVI file.
C-c C-t C-q     Show the print queue.
C-c C-t C-d     Delete a job from the print queue.
C-c C-t C-k     Kill the current TeX formatting job.
C-c C-t C-x     Quit a currently stopped TeX formatting job.
C-c C-t C-l     Recenter the output buffer.

Other Updating Commands

The remaining updating commands do not have standard keybindings because they are rarely used.

M-x texinfo-insert-node-lines
               Insert missing @node lines in region.
               With C-u as a prefix argument,
               use section titles as node names.

M-x texinfo-multiple-files-update
               Update a multi-file document.
               With C-u 2 as a prefix argument,
               create or update all nodes and menus
               in all included files first.

M-x texinfo-indent-menu-description
               Indent descriptions.

M-x texinfo-sequential-node-update
               Insert node pointers in strict sequence.

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