NRAO Home  >  Green Bank  |  Wiki Topic:    GB > TWiki > TocPluginHelp

Welcome | Register | Changes | Topics | Index | Search | Go

1. Table of Contents and Cross-Reference Plugin

1.1. Installation and Configuration

Installation of the Plugin is straightforward. Simply unpack the tar file at the top level of your TWiki installation.

1.1.1. The WebOrder special topic

   * PageOne
   * [[Page two]]

NOTES

• The WebOrder can contain any other TWiki or HTML formatting but it should be noted that all TWiki-format list bullets in the topic are taken as part of the ordering list.

1.2. Attributes on documentation tags

%REF{type=Figure,topic="SpidersOfTheWorld",name="The Funnel Web"}%

NOTES

• Attribute values that contain only no spaces or punctuation need not be quoted, but values containing punctuation or white space must be protected by double quotes. You are highly recommended to stick to values that don't require quoting! All attribute names and values are case sensitive.

1.3. Sections and Tables of Contents

1.3.1. Creating sections using the SECTION tag

Subsections may be inserted in any topic using the SECTIONn tag, where n is the required subsection level. The heading of the section is taken as all text after the tag up to the end of line. For example, the heading at the top of this section is marked with

%SECTION1{name=SECTION}% Creating sections using the =SECTION= tag

NOTES

• See also 1.5. Getting clever for information about modifying section numbering from the WebOrder topic.
• Sections do not have to be named, but if they are not then they can only be referred to by knowing the exact section number. Section names must be unique within the topic.
• The only way to close a section is to start a new section with a different level, or to end the topic.
• You can still use standard HTML heading tags such as <H1>, but sections marked this way will not be included in the table of contents.

1.3.1.1. The %SECTION0% tag

NOTES

• The name attribute cannot be used to refer to a %SECTION0% tag.

1.3.2. Building the table of contents; the %TOC% tag

You can build a table of contents by inserting

%CONTENTS%

• The topic attribute may be used to generate a table of contents for just one topic.
• The depth attribute may be used to set the maximum number of levels to generate.

1.3.2.1. Output from %CONTENTS{depth=2}% tag for this web

1.3.2.2. Output from %CONTENTS% tag for this topic

1.3.3. The TOCCHECK tag

Any topic (but most usually the WebOrder topic) may include the

%TOCCHECK%

NOTES

• Any topics that begin with the characters "Web" are special topics and are excluded from the list, though they can still be listed in the WebOrder and will appear in the table of contents.

1.3.3.1. Output from the %TOCCHECK% tag for this web

1.4. Anchors and References - the ANCHOR, REF and REFTABLE tags

NOTES

• Anchors and references only work within the current web; they cannot be used to create references between webs.

1.4.1. The ANCHOR tag

The ANCHOR tag creates a jump target suitable for jumping to from somewhere else. The type adds the anchor to a "group"; this group is required when generating a reference to the anchor, and may be used to generate tables of same-type anchors (see 1.4.3. The REFTABLE tag below). The type can be any name, though convention suggests the use of types such as Figure and Table. The special group Section is used internally to refer to sections and subsections. Avoid using it for an ANCHOR or you may see strange results.

The ANCHOR tag is normally visible in the output, though it may be made invisible by setting the display attribute to no . For example:

%ANCHOR{type=Figure,name=A,display=no}% Here be sea
monsters

<A name="#Figure_A"> </A>

%ANCHOR{type=Table,name=A}% A wooden table

All the text between the anchor and the next end-of-line will be used to create the anchor. If the anchor is invisible, this text will be invisible too.

1.4.2. The REF tag

The REF tag may be used to refer to an anchor. Anchors are automatically inserted by SECTION tags or may be added using the ANCHOR tag. For a REF tag to work, the type of the target must be known. For example:

See %REF{type=Example,name=WebOrder}% for more information about WebOrder

See 1.1.1.A The Weborder topic for more information about WebOrder

To refer to anchors in a different topic, use the topic attribute. You can refer to sections by name by using the special type Section e.g. %REF{type=Section,name=TOCCHECK}%.

If you refer to a non-existant anchor you are warned: for example,

%REF{type=Reference,name=NonExistantAnchor}%

Reference TocPluginHelp:Reference:NonExistantAnchor not satisfied

1.4.3. The REFTABLE tag

The REFTABLE tag can be used to build tables of references based on the type assigned to anchors. For example, if you have a lot of anchors of type Example you can build a table of all these anchors thus:

%REFTABLE{type=Example}%

and

%REFTABLE{type=Figure}%

All topics listed in the WebOrder are scanned, but only anchors of the requested type will be listed.

NOTES

• If you use REFTABLE with the type Section the table will contain a list of all named sections. For example

1.5. Getting clever

   * [[Top level topic]]
   * AnotherTopLevelTopic

   * [[Top level topic]]
      * [[Second level topic]]
   * AnotherTopLevelTopic

1.6. Hints and Tips

• The standard TWiki variable HTTP_EQUIV_ON_VIEW can be set in WebPreferences to define a style-sheet for the web, for example to apply corporate style quidelines to your documents.
• Include a %TOCCHECK% tag at the end of the table of contents topic.
• Name all sections. This makes it easier to refer to them by symbolic names rather than trying to REF numbered sections.

1.7. Copyright

• Copyright (C) 2001 Motorola. All Rights Reserved.

1.8. License

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, published at http://www.gnu.org/copyleft/gpl.html