texinfo: Updating Requirements

Updating Nodes and Menus

Other Updating Commands

Updating Commands

Back to Software Index

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.  (Note: 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.