%SECTION0% Table of Contents and Cross-Reference Plugin This topic describes the facilities provided by the TOC TWiki Plugin 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.
%SECTION1{name=installation}% Installation and Configuration
Installation of the Plugin is straightforward. Simply unpack the tar file at the top level of your TWiki installation.
%SECTION2{name=WebOrder}% The WebOrder
special topic
The documentation extensions depend on the existance 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 Wiki Words]]
may be used to refer to topics.
NOTES
%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="SpidersOfTheWorld",name="The Funnel Web"}%
NOTES
%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
%SECTION3% The %SECTION0% tag If a %SECTION0% tag occurs in a topic, the heading of that section will replace the topic name in the table of contents.
NOTES
name
attribute cannot be used to refer to a %SECTION0% tag.
%SECTION2{name=TOC}% Building the table of contents; the %TOC%
tag
Supported attributes: depth topic
You can build a table of contents by inserting
%CONTENTS%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
.
topic
attribute may be used to generate a table of contents for just one topic.
depth
attribute may be used to set the maximum number of levels to generate.
%SECTION3% Output from %CONTENTS{depth=2}% tag for this web %CONTENTS{depth=2}% %ANCHOR{type="Example",name="TOC"}% Table of contents for this web
%SECTION3% Output from %CONTENTS% tag for this topic %CONTENTS{topic=TocPluginHelp}% %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.
NOTES
%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.
NOTES
%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 monsterswill 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 tablewill 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. 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 WebOrderwill 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.
NOTES
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]] * AnotherTopLevelTopicTopLevelTopic 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]] * AnotherTopLevelTopicTopLevelTopic 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.
%SECTION1{name=tips}% Hints and Tips
%SECTION1% Copyright The TOC Plugin is a development of the Architectures and Systems Platforms group of Motorola Inc. and is protected by the following copyrights:
%SECTION1% License As required for the publication of all extensions to TWiki, the software is published under the terms of the GNU General Public 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