To write good documentation with Texinfo, it is required to have control on nodes and menus. With Sgmltexi, nodes and menus can be forgotten, but the Info result may suffer for this choice. Anyway, with Sgmltexi it is possible to choose different levels of manual/automatic node handling.
Headings elements can incorporate some more attributes:
node
and menu
. The first one define the node
name, overriding any automatic determination; the second define the node
description on the menu (the automatical choice is otherwise the
title).
<h1 id="ip history" node="history" menu="History of IP protocol"> IP protocol history</h1>
This will generate on the Info menu, the following line:
* history:: History of IP protocol
The node
and menu
attribute may be
used independently: the attribute that is not used, will be
determined automatically.
Having access to nodes, it is possible to use them for cross
reference, without the need for the id
attribute.
Sgmltexi creates automatically the Top node menu. As already explained before (see top node menu), the menu can be explicitly defined. In this way, all nodes and descriptions must be made manually.
Inserting the menu
element at the bottom
of a chapter, or at a lower section, will ask an insertion of
a lower Info menu. See the example:
<h1>IP protocol history</h1> <p>Bla bla bla...</p> <p>Bla bla bla...</p> <menu> <h2>ISO/OSI model</h2> <p>Bla bla bla...</p> <p>Bla bla bla...</p> <h2>More information</h2> <p>Bla bla bla...</p> <p>...</p>
The example shows the insertion of an automatic Info menu before
h2
sections. This menu may otherwise be described
completely, like this:
<menu> * IP layer:: IP ISO/OSI layer model * more on IP:: More details on IP </menu>
When the menu is described this way, node names must be the same as the one used with the heading elements. That is: when writing the menu, also nodes must be exactly declared, like this:
<h1>IP protocol history</h1> <p>Bla bla bla...</p> <p>Bla bla bla...</p> <menu> * IP layer:: IP ISO/OSI layer model * more on IP:: More details on IP </menu> <h2 node="IP layer">ISO/OSI model</h2> <p>Bla bla bla...</p> <p>Bla bla bla...</p> <h2 node="more on IP">More information</h2> <p>Bla bla bla...</p> <p>...</p>
It is evident that a menu
attribute (like <h2
menu="Much more information">
) has no effect in this case.
Element | Attribute | Content | Description or Texinfo equivalence
|
tomeheading | in-line | title of a tome
| |
partheading | title of a part
| ||
h1 | in-line | title of a chapter, introduction or appendix
| |
h2 | in-line | title of a section
| |
h3 | in-line | title of a subsection
| |
h4 | in-line | title of a sub-subsection
| |
indexheading | in-line | title of an analytic index
| |
node | Info node name
| ||
menu | Info node description
| ||
next | Next node name
| ||
prev | Previous node name
| ||
up | Up node name
| ||
type | numbered, unnumbered, heading | type of section, for h1 to h4 elements
|
Elements h1
, h2
, h3
and
h4
may have an additional attribute: type
. The
keywords numbered
, unnumbered
and
heading
may be assigned. numbered
is the default
value; it means that the title will be numbered (with numbers if inside
body
, with letters if inside appendix
).
Assigning unnumbered
, the titles are not numbered.
Assigning heading
, the titles are not numbered and not
annotated inside the table of context.
<h1 type="unnumbered">Acknowledgements</h1> ...
Inside the intro
elements, titles cannot be numbered:
it is explicitly excluded.