texinfo: Raise/lower sections

Chapter Structuring

@part

Back to Software Index

5.12 Raise/lower Sections: '@raisesections' and '@lowersections'
================================================================

The '@raisesections' and '@lowersections' commands implicitly raise and
lower the hierarchical level of following chapters, sections and the
other sectioning commands (excluding parts).

  That is, the '@raisesections' command changes sections to chapters,
subsections to sections, and so on.  Conversely, the '@lowersections'
command changes chapters to sections, sections to subsections, and so
on.  Thus, an '@lowersections' command cancels an '@raisesections'
command, and vice versa.

  You can use '@lowersections' to include text written as an outer or
standalone Texinfo file in another Texinfo file as an inner, included
file (Note: Include Files).  Typical usage looks like this:

     @lowersections
     @include somefile.texi
     @raisesections

(Without the '@raisesections', all the subsequent sections in the main
file would also be lowered.)

  If the included file being lowered has an '@top' node, you'll need to
conditionalize its inclusion with a flag (Note: @set @value).

  Another difficulty can arise with documents that use the (recommended)
feature of 'makeinfo' for implicitly determining node pointers.  Since
'makeinfo' must assume a hierarchically organized document to determine
the pointers, you cannot just arbitrarily sprinkle '@raisesections' and
'@lowersections' commands throughout the document.  The final result has
to have menus that take the raising and lowering into account.  So, as a
practical matter, you generally only want to raise or lower large
chunks, usually in external files as shown above.

  Repeated use of the commands continues to raise or lower the
hierarchical level a step at a time.  An attempt to raise above
'chapter' reproduces chapter commands; an attempt to lower below
'subsubsection' reproduces subsubsection commands.  Also, lowered
subsubsections and raised chapters will not work with 'makeinfo''s
feature of implicitly determining node pointers, since the menu
structure cannot be represented correctly.

  Write each '@raisesections' and '@lowersections' command on a line of
its own.