3.4 The First Node ¶

The first node of a Texinfo file is the Top node, except in an included file (see Include Files). The Top node should contain a short summary and a master menu. See The ‘Top’ Node and Master Menu for more information on the Top node contents and examples. Straight text before the Top node outside of any node should be avoided. Such text, if present, is not output for DocBook.

Here is a description of the node pointers to be used in the Top node:

• The Top node (which must be named ‘top’ or ‘Top’) should have as its ‘Up’ node the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses.

  Usually, all Info files are available through a single virtual Info tree, constructed from multiple directories. In this case, use ‘(dir)’ as the parent of the Top node; this specifies the top-level node in the dir file, which contains the main menu for the Info system as a whole. (Each directory with Info files is intended to contain a file named dir.)

  That’s fine for Info, but for HTML output, one might well want the Up link from the Top node to go to some specific place. For example, for GNU the natural place would be http://www.gnu.org/manual/ (a web page collecting links to most GNU manuals), better specified as just /manual/ if the manual will be installed on www.gnu.org. This can be specified with the TOP_NODE_UP_URL customization variable (see HTML Customization Variables), as in

  $ texi2any --html -c TOP_NODE_UP_URL=/manual/ ...
  

• The ‘Prev’ node of the Top node is usually omitted.
• The ‘Next’ node of the Top node should be the first chapter in your document.

See Installing an Info File, for more information about installing an Info file in the info directory.

It is usually best to leave the pointers off entirely and let the tools implicitly define them, with this simple result:

@node Top