Next: Outline Motion, Up: Outline Mode [Contents][Index]

#### 25.9.1 Format of Outlines

Outline mode assumes that the lines in the buffer are of two types: heading lines and body lines. A heading line represents a topic in the outline. Heading lines start with one or more asterisk (‘`*`’) characters; the number of asterisks determines the depth of the heading in the outline structure. Thus, a heading line with one ‘`*`’ is a major topic; all the heading lines with two ‘`*`’s between it and the next one-‘`*`’ heading are its subtopics; and so on. Any line that is not a heading line is a body line. Body lines belong with the preceding heading line. Here is an example:

    * Food
    This is the body,
    which says something about the topic of food.

    ** Delicious Food
    This is the body of the second-level header.

    ** Distasteful Food
    This could have
    a body too, with
    several lines.

    *** Dormitory Food

    * Shelter
    Another first-level topic with its header line.

A heading line together with all following body lines is called collectively an entry. A heading line together with all following deeper heading lines and their body lines is called a subtree.

You can customize the criterion for distinguishing heading lines by setting the variable `outline-regexp`. (The recommended ways to do this are in a major mode function or with a file local variable.) Any line whose beginning has a match for this regexp is considered a heading line. Matches that start within a line (not at the left margin) do not count.

The length of the matching text determines the level of the heading; longer matches make a more deeply nested level. Thus, for example, if a text formatter has commands ‘`@chapter`’, ‘`@section`’ and ‘`@subsection`’ to divide the document into chapters and sections, you could make those lines count as heading lines by setting `outline-regexp` to ‘`"@chap\\|@\\(sub\\)*section"`’. Note the trick: the two words ‘`chapter`’ and ‘`section`’ are equally long, but by defining the regexp to match only ‘`chap`’ we ensure that the length of the text matched on a chapter heading is shorter, so that Outline mode will know that sections are contained in chapters. This works as long as no other command starts with ‘`@chap`’.

You can explicitly specify a rule for calculating the level of a heading line by setting the variable `outline-level`. The value of `outline-level` should be a function that takes no arguments and returns the level of the current heading. The recommended ways to set this variable are in a major mode command or with a file local variable.

Next: Outline Motion, Up: Outline Mode [Contents][Index]