Node:chap 2, Next:, Previous:chap 1, Up:Top



Sectioning, nodes and menus

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

Unnumbered sections and simple headings

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.