See: TocPlugin

Motorola extensions to the TWiki

This topic describes the facilities added in the Motorola TWiki for the support of documentation generation. The extensions support definition of an order among the topics in the web for the generation of tables of contents, together with cross-references that operate within, as well as between, topics.

%TOC{topic=Plugins.MotorolaExtensionsToTWiki}%

%SECTION1% Enabling the extensions

The documentation extensions are enabled on a per-web basis by setting the variable ENABLE_TOC to on in the WebPreferences, as follows:

      * Set  ENABLE_TOC = on

Other extensions are enabled by default.

%SECTION2% The WebOrder special topic

The documentation extensions depend on the existence of a special topic called WebOrder, which is is analagous to a Framemaker "book". This topic should contain a list of the topics you want included. This list must be formatted as a TWiki-format bulleted list e.g. %ANCHOR{type=Example,name=WebOrder,display=no}% The Weborder topic

  * PageOne
  * [[Page two]]

Both WikiWords and [[Odd WikiWords]] may be used to refer to topics.

NOTE: The WebOrder can contain any other TWiki or HTML formatting but it should be noted that all list bullets in are taken as part of the ordering list - irrespective of where they occur.

%SECTION1{name=Attributes}% Attributes on documentation tags

Following the TWiki standard, attributes are used to pass values to tags to control their behaviour. Attributes are given as a list of name = value pairs enclosed in curly braces {} after the tag name. For example:

%REF{type=Figure,topic="[[Spiders of the world]]",name="The Funnel Web"}%

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.

%SECTION1% Sections and Tables of Contents

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

Supported attributes: name

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 %REF{type=Section,name=IndentedWebOrder}% 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.

%SECTION2{name=TOC}% Building the table of contents; the %TOC% tag

Supported attributes: depth topic

You can build a table of contents by inserting

%TOC%

in a topic. The first level of the table of contents is normally the topics in the order of the list in WebOrder, though see %REF{type=Section,name=IndentedWebOrder}% for information about modifying section numbering from the WebOrder topic. Subsections listed in the table are automatically linked to the target SECTION.

• 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.

%SECTION3% Output from %TOC{depth=2}% tag for this web

%TOC{depth=2}%

%ANCHOR{type="Example",name="TOC"}% Table of contents for this web

%SECTION3% Output from %TOC{depth=2}% tag for this topic

%TOC{topic=WebHelp,depth=2}%

%ANCHOR{type="Example",name="TopicTOC"}% Table of contents for this topic

%SECTION2{name=TOCCHECK}% The TOCCHECK tag

Supported attributes: none

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

%TOCCHECK%

tag. This causes the entries in the WebOrder topic to be cross-referenced against the files actually stored in the web (see WebIndex). Any topics which exist as files in the web but are missing from the WebOrder will be listed.

NOTE: 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.

%SECTION3% Output from the %TOCCHECK% tag for this web

%TOCCHECK%

%ANCHOR{type=Example,name=TOCCHECK}% Output of the %TOCCHECK% tag

%SECTION1% Anchors and References - the ANCHOR, REF and REFTABLE tags

Bookmarks and references can be inserted into text using the ANCHOR and REF tags. These can be used for references, for example, to tables or figures.

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

%SECTION2{name=ANCHOR}% The ANCHOR tag

Supported attributes: type name display

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 %REF{type=Section,name=REFTABLE}% 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

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

will generate an invisible anchor on the text (there's one one the line above, honest!) and

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

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

will generate: %ANCHOR{type=Table,name=A,display=yes}% 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.

%SECTION2{name=REF}% The REF tag

Supported attributes: type topic name

The REF tag may be used to refer to an anchor. The type of the target must be known. For example:

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

will generate:

See %REF{type=Example,name=WebOrder}% 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}%

generates

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

%SECTION2{name=REFTABLE}% The REFTABLE tag

Supported attributes: type

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}%

%ANCHOR{type=Example,name=example1,display=no}% REFTABLE{type=Table} example

This will insert a table like this:

%REFTABLE{type="Example"}%

and

%REFTABLE{type=Figure}%

will insert a table like this:

%ANCHOR{type=Example,name=example2,display=no}% REFTABLE{type=Figure} example

%REFTABLE{type=Figure}%

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

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

%ANCHOR{type=Example,name=example2,display=no}% REFTABLE{type=Section} example

%REFTABLE{type=Section}%

%SECTION1{name=IndentedWebOrder}% Getting clever

It is possible to change the way the table of contents for the web is ordered by using extra levels of indent in the WebOrder. If you indent a topic below another topic, then that topic will be treated as a section of the parent topic. Section numbers within the subtopic are adjusted accordingly. For example, say the WebOrder contains

   * [[Top level topic]]
   * AnotherTopLevelTopic

TopLevelTopic will be numbered 1., and the first SECTION1 within TopLevelTopic will be 1.1. AnotherTopLevelTopic will be numbered 2. If, instead, WebOrder contains

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

TopLevelTopic will still be numbered 1., but now SecondLevelTopic will be numbered 1.1., and the first SECTION1 within SecondLevelTopic will be 1.1.1. The first SECTION1 within TopLevelTopic will now be numbered 1.2. AnotherTopLevelTopic will still be numbered 2.

-- CrawfordCurrie - 31 May 2001

Thanks Crawford for sharing this with the TWiki community! I reformatted your text to show TOC and SECTION commands in fixed bold type face since your code is not running on this server.

See Crawford's actual code at TWikiForBookAuthoring.

Related topics: TWikiForBookAuthoring, SectionTitles

-- PeterThoeny - 16 Jun 2001