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

• its start-tag must occur at the beginning of a line (possibly indented);
• its local name must match nxml-section-element-name-regexp;
• either its first child element or a descendant of that first child element must have a local name that matches nxml-heading-element-name-regexp; the first such element is treated as the section’s heading.

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

There are three possible outline states for a section:

• normal, showing everything, including its heading, text content and subsections; each subsection is displayed according to the state of that subsection;
• showing just its heading, with both its text content and its subsections hidden; all subsections are hidden regardless of their state;
• showing its heading and its subsections, with its text content hidden; each subsection is displayed according to the state of that subsection.

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.

• C-c C-o C-a shows all sections in the buffer normally.
• C-c C-o C-t hides the text content of all sections in the buffer.
• C-c C-o C-c hides the text content of the current section.
• C-c C-o C-e shows the text content of the current section.
• C-c C-o C-d hides the text content and subsections of the current section.
• C-c C-o C-s shows the current section and all its direct and indirect subsections normally.
• C-c C-o C-k shows the headings of the direct and indirect subsections of the current section.
• C-c C-o C-l hides the text content of the current section and of its direct and indirect subsections.
• C-c C-o C-i shows the headings of the direct subsections of the current section.
• C-c C-o C-o hides as much as possible without hiding the current section’s text content; the headings of ancestor sections of the current section and their child section sections will not be hidden.

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.