TocPlugin

Sophisticated table of contents generation

Supports the generation of tables of contents, together with symbolic cross-references that operate within and between topics.

Adds a number of new macros:

• %SECTIONn% - inserts an anchored section header
• %CONTENTS% - generates a table of contents for a topic or an entire web, with full expansion depth control
• %REF% - inserts a symbolically named cross-reference URL
• %ANCHOR% - inserts a symbolically named jump target
• %TOCBUTTONS% - inserts "Prev", "Home" and "Next" buttons

Example:

The rest of this topic is written using the plugin, so you will see macros such as %SECTION0% if the plugin is not installed and enabled.

1.1. Books

The plugin depends on the existance of a topic called "WebOrder". This topic is referred to as the "book", and should contain a list of the topics that you want to generate section numbers for. Each topic in the book is allocated a SECTION0 section number i.e. the first topic is section 1, the second is section 2 etc.

The book topic is a simple list - either a bulleted list or a numbered list - and can be created interactively using the BookmakerPlugin.

Each entry in the book must be the name of a topic in the current web. This plugin ships with a simple WebOrder, which you can view (but are advised not to change).

e.g. 1.1.A An example Weborder topic

   * [[An Overview of Perl]]
      1 [[Getting Started]]
      2 [[Natural and Artificial Languages]]
      3 AGradeExample
   2 [[The Gory Details]]
      * LexicalTexture

1.2. The SECTION macro

Supported attributes: name

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

%SECTION1{name="SECTION"}% The =%SECTION= macro

NOTES

• See also 1.5. Getting clever for information about modifying section numbering from the book 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.2.1.1. The %SECTION0% macro

If a %SECTION0% macro occurs in a topic, the heading of that section will replace the topic name in the table of contents.

NOTES

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

1.2.2. Building the table of contents

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 1.5. Getting clever 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.

1.2.2.1. Output from %CONTENTS{depth=2}% macro for this web

1.2.2.1.A Table of contents for this web

1.2.2.2. Output from %CONTENTS% macro for this topic

1.2.2.2.A Table of contents for this topic

Note that the CONTENTS macro is quite slow. This is because it has to open and analyse all topics it refers to.

You can still use the standard %TOC% macro in topics that use TocPlugin. However only sections defined using the standard heading syntax will be visible.

1.2.3. The TOCCHECK macro

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

%TOCCHECK%

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

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. Anchors and References - the ANCHOR, REF and REFTABLE macros

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

1.3.1. The ANCHOR macro

Supported attributes: type name display

The ANCHOR macro 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.3.3. The REFTABLE macro 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 macro 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

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: 1.3.1.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.3.2. The REF macro

Supported attributes: type topic name

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

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

will generate:

See 1.1.A An example 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"}%

generates

Reference TocPlugin:Reference:NonExistantAnchor not satisfied

1.3.3. The REFTABLE macro

Supported attributes: type

The REFTABLE macro 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"}%

This will insert a table like this:

Example
1.1.A An example Weborder topic
1.2.2.1.A Table of contents for this web
1.2.2.2.A Table of contents for this topic
1.3.3.A REFTABLE{type="Table"} example
1.3.3.B REFTABLE{type="Figure"} example
1.3.3.C

and

%REFTABLE{type=Figure}%

will insert a table like this:

Figure
1.3.1.A Here be sea monsters

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

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

1.4. Adding navigation buttons

When using the WebOrder special topic to collect a list of topics into a somewhat "linearized" form (a "book"), it is often very convenient to be able to add navigation buttons to the previous and the next pages as well as to the home page (table of contents). This can be done by adding the %TOCBUTTONS% macro to your pages. For example, you can use it in a template which is included either at the top or the bottom of your pages. The included "view.tocbuttons.tmpl" template (intended to be used with NatSkin) adds the %TOCBUTTONS% macro to the content footer of all pages in the web. To activate it, use "* Set SKIN = tocbuttons, nat" in your WebPreferences.

Note that the "Prev", "Home" and "Next" links will be added only for such topics that are listed in the WebOrder special topic, and they will only be inserted when viewing a page, i. e. they will for example not show up when printing such a topic or the whole "book".

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

1.6. Hints and Tips

• Include a %TOCCHECK% macro 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.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Info

One Line Description:	Table of contents and cross-reference management
Author:	Foswiki:Main.CrawfordCurrie http://c-dot.co.uk
Release:	2.1.1
Version:	11472 (2011-04-15)
Change History:
2.1.1 (15 Apr 2011)	Minor correction on file permissions.
2.1.0 (23 Mar 2011)	Made compatible with BookmakerPlugin, which it now depends on. Now supports topics in different webs.
2.0.0 (22 Dec 2009)	Updated for Foswiki
1.0.3 (20 Apr 2006)	Minor doc update, headings no longer marked up as anchor text (Foswiki:Main.SteffenPoulsen)
1.0.2 (1 Oct 2001)	Corrected directory naming (no thanks to WindowsME!)
1.0.1 (23 Sep 2001)	Directories restructured according to Plugin requirements, and turned into a zip file
1.0.0 (15 Sep 2001)	Initial version. Originally developed for use by Motorola documentation teams.
Copyright:	© 2001-2002 Motorola. All Rights Reserved.
	© 2008-2011 Crawford Currie http://c-dot.co.uk.
License:	GPL (GNU General Public License)
Home:	http://foswiki.org/Extensions/TocPlugin
Support:	http://foswiki.org/Support/TocPlugin