autoOutline

Sandcastle MAML

Sandcastle MAML Guide autoOutline

The autoOutline element is a special case used by Sandcastle to insert an auto-generated section outline within a topic's introduction or sub-sections.

Usage

Place the element within a topic's introduction element to produce an outline of the topic's section headings or within a section's content element to produce an outline of the section's sub-sections. In either case, the outline will be created at the location of the auto-outline element. As such, you can control the placement of the outline within the text.

Each section must have a title element as that is the text that will be used for the outline entry. In addition, an address attribute must be added to each section element to give it a unique ID that can be used as a link. You can also add an optional address attribute to the introduction element so that you can link back to it from a sub-section.

An optional lead attribute can be specified to define the lead-in text displayed before the list of links. If not specified, default lead-in text is used. If set to the value none, the lead-in text will be omitted.

An optional excludeRelatedTopics attribute can be specified. If set to True, the top-level auto-outline will exclude the Related Topics link. This can be useful if you simply want to list the main sections of the topic with some alternate lead-in text or no lead-in text at all.

If a numeric inner text value is specified, the section headings down to the indicated depth will be included in the outline. Zero (0), the default, specifies that only top-level section headings should be included in the outline.

Example
<?xml version="1.0" encoding="utf-8"?>
<topic id="1a817894-db7a-4c7f-bd67-cca896affa35" revisionNumber="1">
  <developerConceptualDocument
    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
    xmlns:xlink="http://www.w3.org/1999/xlink">

    <introduction address="Intro">
      <!-- No depth option so only show top-level sections here -->
      <autoOutline />
      <para>The introduction.  If <codeInline>&lt;autoOutline /&gt;</codeInline>
is included, this paragraph can be omitted.
      </para>
      <!-- Note that placing the autoOutline element here would place
           the section outline below the intro paragraph. -->
    </introduction>
    <section address="S1">
      <title>Section 1</title>
      <content>
        <para>This is section 1.</para>
        <!-- This will include sub-sections in the outline up to three
             levels down.  It also uses custom lead-in text. -->
        <autoOutline lead="Select a sub-section:">3</autoOutline>
      </content>
      <sections>
        <section address="SS1">
          <title>Sub-section 1</title>
          <content>
            <para>This is sub-section 1.</para>
          </content>
        </section>
        <section address="SS2">
          <title>Sub-section 2</title>
          <content>
            <!-- No <autoOutline /> in here so no outline -->
            <para>This is sub-section 2.</para>
          </content>
          <sections>
            <section address="SSS1">
              <title>Sub-sub-section 1</title>
              <content>
                <para>This is sub-sub-section 1.</para>
              </content>
            </section>
            <section address="SSS2">
              <title>Sub-sub-section 2</title>
              <content>
                <para>This is sub-sub-section 2.</para>
                <para>
                  <link xlink:href="#Intro">Back to the Top</link>
                </para>
              </content>
            </section>
          </sections>
        </section>
      </sections>
    </section>
    <section address="S2">
      <title>Section 2</title>
      <content>
        <para>This is section 2.</para>
      </content>
    </section>
    <relatedTopics>
      <link xlink:href="b9a1daac-a2d8-41b7-83b0-b7dc7b28b898" />
    </relatedTopics>
  </developerConceptualDocument>
</topic>
Example Output
See Also

Other Resources