texinfo: Top Node Naming

Cross References

@ref

@xref

Back to Software Index

8.5 Naming a 'Top' Node
=======================

Ordinarily, you must always name a node in a cross reference.  However,
it's not unusual to want to refer to another manual as a whole, rather
than a particular section within it.  In this case, giving any section
name is an unnecessary distraction.

  So, with cross references to other manuals (Note: Four and Five
Arguments), if the first argument is either 'Top' (capitalized just
that way) or omitted entirely, and the third argument is omitted, the
printed output includes no node or section name.  (The Info output
includes 'Top' if it was given.)  For example,

     @xref{Top,,, make, The GNU Make Manual}.

produces

     Note: (make)Top.

and

     See 'The GNU Make Manual'.

Info readers will go to the Top node of the manual whether or not the
'Top' node is explicitly specified.

  It's also possible (and is historical practice) to refer to a whole
manual by specifying the 'Top' node and an appropriate entry for the
third argument to the '@xref' command.  Using this idiom, to make a
cross reference to 'The GNU Make Manual', you would write:

     @xref{Top,, Overview, make, The GNU Make Manual}.

which produces

     Note: Overview.

in Info and

     See section "Overview" in 'The GNU Make Manual'.

in a printed manual.

  In this example, 'Top' is the name of the first node, and 'Overview'
is the name of the first section of the manual.  There is no widely-used
convention for naming the first section in a printed manual, this is
just what the Make manual happens to use.  This arbitrariness of the
first name is a principal reason why omitting the third argument in
whole-manual cross references is preferable.