5.12 @raisesections and @lowersections

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

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. Typical usage looks like this:

     @lowersections
     @include somefile.texi
     @raisesections

(Without the @raisesections, all the subsequent sections in the document would be lowered.)

If the included file being lowered has a @top node, you'll need to conditionalize its inclusion with a flag (see 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 in the document. The final result has to have menus that take the raising and lowering into account. Therefore, 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 continue 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 won't be correct.

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