5 Outlining

nXML mode allows you to display all or part of a buffer as an outline, in a similar way to Emacs’s outline mode. An outline in nXML mode is based on recognizing two kinds of element: sections and headings. There is one heading for every section and one section for every heading. A section contains its heading as or within its first child element. A section also contains its subordinate sections (its subsections). The text content of a section consists of anything in a section that is neither a subsection nor a heading.

Note that this is a different model from that used by XHTML. nXML mode’s outline support will not be useful for XHTML unless you adopt a convention of adding a div to enclose each section, rather than having sections implicitly delimited by different hn elements. This limitation may be removed in a future version.

The variable nxml-section-element-name-regexp gives a regexp for the local names (i.e., the part of the name following any prefix) of section elements. The variable nxml-heading-element-name-regexp gives a regexp for the local names of heading elements. For an element to be recognized as a section

You can customize these variables using M-x customize-variable.

There are three possible outline states for a section:

In the last two states, where the text content is hidden, the heading is displayed specially, in an abbreviated form. An element like this:

<section>
<title>Food</title>
<para>There are many kinds of food.</para>
</section>

would be displayed on a single line like this:

<-section>Food...</>

If there are hidden subsections, then a + will be used instead of a - like this:

<+section>Food...</>

If there are non-hidden subsections, then the section will instead be displayed like this:

<-section>Food...
  <-section>Delicious Food...</>
  <-section>Distasteful Food...</>
</-section>

The heading is always displayed with an indent that corresponds to its depth in the outline, even it is not actually indented in the buffer. The variable nxml-outline-child-indent controls how much a subheading is indented with respect to its parent heading when the heading is being displayed specially.

Commands to change the outline state of sections are bound to key sequences that start with C-c C-o (o is mnemonic for outline). The third and final key has been chosen to be consistent with outline mode. In the following descriptions current section means the section containing point, or, more precisely, the innermost section containing the character immediately following point.

When a heading is displayed specially, you can use RET in that heading to show the text content of the section in the same way as C-c C-o C-e.

You can also use the mouse to change the outline state: S-mouse-2 hides the text content of a section in the same way asC-c C-o C-c; mouse-2 on a specially displayed heading shows the text content of the section in the same way as C-c C-o C-e; mouse-1 on a specially displayed start-tag toggles the display of subheadings on and off.

The outline state for each section is stored with the first character of the section (as a text property). Every command that changes the outline state of any section updates the display of the buffer so that each section is displayed correctly according to its outline state. If the section structure is subsequently changed, then it is possible for the display to no longer correctly reflect the stored outline state. C-c C-o C-r can be used to refresh the display so it is correct again.