7. Menus

Menus contain pointers to subordinate nodes. In online output, you use menus to go to such nodes. Menus have no effect in printed manuals and do not appear in them.

A node with a menu should not contain much text. If you find yourself writing a lot of text before a menu, we generally recommend moving most of the text into a new subnode—all but a paragraph or two. Otherwise, a reader with a terminal that displays only a few lines may miss the menu and its associated text. As a practical matter, it is best to locate a menu within 20 or so lines of the beginning of the node.

7.1 Menu Location

A menu must be located at the end of a node, without any regular text or additional commands between the @end menu and the beginning of the next node. (As a consequence, there may be at most one menu in a node.)

This is actually a useful restriction, since a reader who uses the menu could easily miss any such text. Technically, it is necessary because in Info format, there is no marker for the end of a menu, so Info-reading programs would have no way to know when the menu ends and normal text resumes.

Technically, menus can carry you to any node, regardless of the structure of the document; even to nodes in a different Info file. However, we do not recommend ever making use of this, because the makeinfo implicit pointer creation feature (see section Creating Pointers with makeinfo) and XEmacs Texinfo mode updating commands work only to create menus of subordinate nodes in a hierarchically structured document. Instead, use cross references to refer to arbitrary nodes.

In the past, we recommended using a ‘@heading’ command within an @ifinfo conditional instead of the normal sectioning commands after a very short node with a menu. This had the advantage of making the printed output look better, because there was no very short text between two headings on the page. But this also does not work with makeinfo’s implicit pointer creation, and it also makes the XML output incorrect, since it does not reflect the true document structure. So, regrettably, we can no longer recommend this.

7.2 Writing a Menu

A menu consists of an @menu command on a line by itself followed by menu entry lines or menu comment lines and then by an @end menu command on a line by itself.

A menu looks like this:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                 several files at once.
@end menu

In a menu, every line that begins with an ‘* ’ is a menu entry. (Note the space after the asterisk.) A line that does not start with an ‘* ’ may also appear in a menu. Such a line is not a menu entry but is a menu comment line that appears in the Info file. In the example above, the line ‘Larger Units of Text’ is a menu comment line; the two lines starting with ‘* ’ are menu entries. Space characters in a menu are preserved as-is; this allows you to format the menu as you wish.

In the HTML output from makeinfo, the accesskey attribute is used with the values ‘1’…‘9’ for the first nine entries. This allows people using web browsers to follow the first menu entries using (typically) M-digit, e.g., M-1 for the first entry.

7.3 The Parts of a Menu

A menu entry has three parts, only the second of which is required:

1. The menu entry name (optional).
2. The name of the node (required).
3. A description of the item (optional).

The template for a generic menu entry looks like this (but see the next section for one more possibility):

* menu-entry-name: node-name.   description

Follow the menu entry name with a single colon and follow the node name with tab, comma, newline, or the two characters period and space (‘. ’).

In Info, a user selects a node with the m (Info-menu) command. The menu entry name is what the user types after the m command.

The third part of a menu entry is a descriptive phrase or sentence. Menu entry names and node names are often short; the description explains to the reader what the node is about. A useful description complements the node name rather than repeats it. The description, which is optional, can spread over two or more lines; if it does, some authors prefer to indent the second line while others prefer to align it with the first (and all others). It’s up to you.

7.4 Less Cluttered Menu Entry

When the menu entry name and node name are the same, you can write the name immediately after the asterisk and space at the beginning of the line and follow the name with two colons.

For example, write

* Name::                        description

instead of

* Name: Name.                   description

You should indeed use the node name for the menu entry name whenever possible, since it reduces visual clutter in the menu.

7.5 A Menu Example

A menu looks like this in Texinfo:

@menu
* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.
@end menu

This produces:

* menu:

* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.

Here is an example as you might see it in a Texinfo file:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                 several files at once.
@end menu

This produces:

* menu:
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                 several files at once.

In this example, the menu has two entries. ‘Files’ is both a menu entry name and the name of the node referred to by that name. ‘Multiples’ is the menu entry name; it refers to the node named ‘Buffers’. The line ‘Larger Units of Text’ is a comment; it appears in the menu, but is not an entry.

Since no file name is specified with either ‘Files’ or ‘Buffers’, they must be the names of nodes in the same Info file (see section Referring to Other Info Files).

7.6 Referring to Other Info Files

You can create a menu entry that enables a reader in Info to go to a node in another Info file by writing the file name in parentheses just before the node name. In this case, you should use the three-part menu entry format, which saves the reader from having to type the file name.

The format looks like this:

@menu
* first-entry-name:(filename)nodename.     description
* second-entry-name:(filename)second-node. description
@end menu

For example, to refer directly to the ‘Outlining’ and ‘Rebinding’ nodes in the XEmacs User’s Manual, you would write a menu like this:

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

If you do not list the node name, but only name the file, then Info presumes that you are referring to the ‘Top’ node.

The ‘dir’ file that contains the main menu for Info has menu entries that list only file names. These take you directly to the ‘Top’ nodes of each Info document. (See section Installing an Info File.)

For example:

* Info: (info).         Documentation browsing system.
* XEmacs: (xemacs).     The extensible, self-documenting
                        text editor.

(The ‘dir’ top level directory for the Info system is an Info file, not a Texinfo file, but a menu entry looks the same in both types of file.)

The XEmacs Texinfo mode menu updating commands only work with nodes within the current buffer, so you cannot use them to create menus that refer to other files. You must write such menus by hand.

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