nxml-mode: Outlining
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 as‘C-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.
Info Catalog
nxml-mode: Paragraphs
nxml-mode: Top
nxml-mode: Locating a schema