r1 - 14 Sep 2006 - 08:45:56 - TWikiGuestYou are here: Astrophysics Wiki >  TWiki Web  > TocPluginHelp
If you see tags such as %SECTION0% on the next line, read TocPlugin

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

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

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.
   * PageOne
   * [[Page two]]
Both WikiWords and [[Odd Wiki Words]] may be used to refer to topics.


  • 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

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


  • 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

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


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


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

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

Supported attributes: depth topic

You can build a table of contents by inserting

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. Output from %CONTENTS{depth=2}% tag for this web Table of contents for this web Output from %CONTENTS% tag for this topic Table of contents for this topic

1.3.3. The TOCCHECK tag

Supported attributes: none

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

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.


  • 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. Output from the %TOCCHECK% tag for this web

The following topics were not found in the WebOrder:
  1. ATasteOfTWiki
  2. ATasteOfTWikiTemplate
  3. AccessKeys
  4. AdminDocumentationCategory
  5. AdminSkillsAssumptions
  6. AdminToolsCategory
  7. AnApplicationWithWikiForm
  8. AppendixEncodeURLsWithUTF8
  9. BackupRestoreConsole
  10. BackupRestorePlugin
  11. BookView
  12. BreadCrumbsPlugin
  13. BulkRegistration
  14. BulkResetPassword
  15. BumpyWord
  16. CategoryCategory
  17. ChangeEmailAddress
  18. ChangePassword
  19. ClassMethod
  20. ClassicSkin
  21. ClassicSkinLogin
  22. CommentPlugin
  23. CommentPluginTemplate
  24. DeleteOrRenameATopic
  25. DeleteOrRenameAnAttachment
  26. DeveloperDocumentationCategory
  27. DontNotify
  28. EditDoesNotIncreaseTheRevision
  29. EditTablePlugin
  30. EmptyPlugin
  31. ExampleTopicTemplate
  32. FileAttachment
  33. FileAttribute
  34. ForceNewRevision
  35. FormattedSearch
  36. GetAWebAddOn
  37. GnuGeneralPublicLicense
  38. GoBox
  39. GoodStyle
  40. HiddenAttachment
  41. IfStatements
  42. IncludeTopicsAndWebPages
  43. InstalledPlugins
  44. InstantEnhancements
  45. InterWikis
  46. InterwikiPlugin
  47. JSCalendarContrib
  48. LanguageSelector
  49. LoginName
  50. MailerContrib
  51. MainFeatures
  52. ManagingTopics
  53. ManagingUsers
  54. ManagingWebs
  55. MoveTopic
  56. NewUserTemplate
  57. ObjectMethod
  58. PatternSkin
  59. PatternSkinCss
  60. PatternSkinCssCookbook
  61. PatternSkinCssCookbookCenterPage
  62. PatternSkinCssCookbookCenterPageBorder
  63. PatternSkinCssCookbookEditTableStyle
  64. PatternSkinCssCookbookFonts
  65. PatternSkinCssCookbookNoLeftBar
  66. PatternSkinCssCookbookNoTopBar
  67. PatternSkinCustomization
  68. PatternSkinHeaderArt
  69. PatternSkinJavascripts
  70. PeterThoeny
  71. PlainSkin
  72. PreferencesPlugin
  73. PreviewBackground
  74. PrintSkin
  75. QuietSave
  76. RegistrationApprovals
  77. RegularExpression
  78. RenameWeb
  79. RenderListPlugin
  80. ResetPassword
  81. SearchDoesNotWork
  82. SearchHelp
  83. SearchPatternCookbook
  84. SimultaneousEdits
  85. SiteChanges
  86. SiteMap
  87. SitePermissions
  88. SlideShowPlugin
  89. SmiliesPlugin
  90. SourceCode
  91. SpreadSheetPlugin
  92. StandardColors
  93. StartingPoints
  94. StaticMethod
  95. TWikiAccessControl
  96. TWikiAccessControlExceptionDotPm
  97. TWikiAccessDotPm
  98. TWikiAttachDotPm
  99. TWikiAttrsDotPm
  100. TWikiClientApacheLoginDotPm
  101. TWikiClientDotPm
  102. TWikiClientTemplateLoginDotPm
  103. TWikiCompatibilityDotPm
  104. TWikiContributor
  105. TWikiCss
  106. TWikiDocGraphics
  107. TWikiDocumentation
  108. TWikiDotPm
  109. TWikiDownload
  110. TWikiEditingShorthand
  111. TWikiEnhancementRequests
  112. TWikiFAQ
  113. TWikiFaqTemplate
  114. TWikiFormDotPm
  115. TWikiForms
  116. TWikiFuncDotPm
  117. TWikiGlossary
  118. TWikiHistory
  119. TWikiI18NDotPm
  120. TWikiI18NExtractDotPm
  121. TWikiIfDotPm
  122. TWikiInstallationGuide
  123. TWikiJavascripts
  124. TWikiLogos
  125. TWikiMergeDotPm
  126. TWikiMetaData
  127. TWikiMetaDotPm
  128. TWikiNetDotPm
  129. TWikiOopsExceptionDotPm
  130. TWikiPlannedFeatures
  131. TWikiPluginDotPm
  132. TWikiPlugins
  133. TWikiPluginsDotPm
  134. TWikiPluralsDotPm
  135. TWikiPreferences
  136. TWikiPreferencesForm
  137. TWikiPrefsDotPm
  138. TWikiPrefsParserDotPm
  139. TWikiPrefsPrefsCacheDotPm
  140. TWikiReferenceManual
  141. TWikiRegistration
  142. TWikiReleaseNotes04x00
  143. TWikiRenderDotPm
  144. TWikiSandboxDotPm
  145. TWikiScripts
  146. TWikiSearchDotPm
  147. TWikiShorthand
  148. TWikiSite
  149. TWikiSiteTools
  150. TWikiSkinBrowser
  151. TWikiSkins
  152. TWikiStoreDotPm
  153. TWikiStoreRcsFileDotPm
  154. TWikiStoreRcsLiteDotPm
  155. TWikiStoreRcsWrapDotPm
  156. TWikiSystemRequirements
  157. TWikiTemplates
  158. TWikiTemplatesDotPm
  159. TWikiTimeDotPm
  160. TWikiTip001
  161. TWikiTip002
  162. TWikiTip003
  163. TWikiTip004
  164. TWikiTip005
  165. TWikiTip006
  166. TWikiTip007
  167. TWikiTip008
  168. TWikiTip009
  169. TWikiTip010
  170. TWikiTip011
  171. TWikiTip012
  172. TWikiTip013
  173. TWikiTip014
  174. TWikiTip015
  175. TWikiTip016
  176. TWikiTip017
  177. TWikiTip018
  178. TWikiTip019
  179. TWikiTip020
  180. TWikiTip021
  181. TWikiTip022
  182. TWikiTip023
  183. TWikiTip024
  184. TWikiTip025
  185. TWikiTip026
  186. TWikiTip027
  187. TWikiTip028
  188. TWikiTip029
  189. TWikiTips
  190. TWikiTipsOfTheDay
  191. TWikiTipsOfTheDayAddNew
  192. TWikiTipsOfTheDayAdmin
  193. TWikiTipsOfTheDayInclude
  194. TWikiTipsOfTheDayTemplate
  195. TWikiTopics
  196. TWikiTutorial
  197. TWikiUIChangeFormDotPm
  198. TWikiUIDotPm
  199. TWikiUIEditDotPm
  200. TWikiUIManageDotPm
  201. TWikiUIOopsDotPm
  202. TWikiUIRDiffDotPm
  203. TWikiUIRegisterDotPm
  204. TWikiUIRestDotPm
  205. TWikiUISaveDotPm
  206. TWikiUISearchDotPm
  207. TWikiUIStatisticsDotPm
  208. TWikiUIUploadDotPm
  209. TWikiUIViewDotPm
  210. TWikiUpgradeGuide
  211. TWikiUserAuthentication
  212. TWikiUserDotPm
  213. TWikiUsersApacheHtpasswdUserDotPm
  214. TWikiUsersDotPm
  215. TWikiUsersGuide
  216. TWikiUsersPasswordDotPm
  217. TWikiUsersTWikiUserMappingDotPm
  218. TWikiVariables
  219. TWikiVariablesQuickStart
  220. TWikiWebsTable
  221. TablePlugin
  222. TemplateWeb
  223. TextEditor
  224. TextFormattingFAQ
  225. TextFormattingRules
  226. TimBernersLee
  227. TimeInterval
  228. TipsContrib
  229. TopicReferencePlugin
  230. TreePlugin
  231. TwistyContrib
  232. UserDocumentationCategory
  233. UserToolsCategory
  234. UsingHTML
  241. VarBASEWEB
  242. VarDATE
  245. VarENCODE
  249. VarGMTIME
  250. VarGMTIME2
  251. VarGROUPS
  253. VarHTTP
  254. VarHTTPHOST
  255. VarHTTPS
  256. VarICON
  257. VarICONURL
  259. VarIF
  260. VarINCLUDE
  263. VarLANGUAGE
  266. VarLOGIN
  267. VarLOGOUT
  268. VarMAINWEB
  269. VarMAKETEXT
  270. VarMETA
  272. VarNOP
  276. VarPUBURL
  282. VarREVINFO
  283. VarREVINFO2
  287. VarSCRIPTURL2
  290. VarSEARCH
  297. VarSPACEOUT
  302. VarTOC
  303. VarTOC2
  304. VarTOPIC
  306. VarTWIKIWEB
  307. VarURLPARAM
  308. VarUSERINFO
  309. VarUSERNAME
  310. VarVAR
  311. VarWEB
  312. VarWEBLIST
  315. VarWIKINAME
  321. WabiSabi
  322. WelcomeGuest
  323. WhatDoesTWikiStandFor
  324. WhatIsWikiWiki
  325. WikiCulture
  326. WikiName
  327. WikiNotation
  328. WikiReferences
  329. WikiSyntax
  330. WikiSyntaxSummary
  331. WikiTopic
  332. WikiWikiClones
  333. WikiWord
  334. WysiwygPlugin
  335. WysiwygPluginTopicLister
  336. YouAreHere Output of the %TOCCHECK% tag

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


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

1.4.1. 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 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
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.4.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.4.2. 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 WebOrder
will generate:

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,


Reference TocPluginHelp:Reference:NonExistantAnchor not satisfied

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

This will insert a table like this:
1.1.1.A The Weborder topic Table of contents for this web Table of contents for this topic Output of the %TOCCHECK% tag
1.4.3.A REFTABLE{type=Table} example
1.4.3.B REFTABLE{type=Figure} example
1.4.3.C REFTABLE{type=Section} example %REFTABLE{type=Section}%


will insert a table like this:
1.4.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. For example

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

  • 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

The TOC Plugin is a development of the Architectures and Systems Platforms group of Motorola Inc. and is protected by the following copyrights:
  • Copyright (C) 2001 Motorola. All Rights Reserved.

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

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r1 | More topic actions

key Log In or Register

Main Web Users Groups Index Search Changes Notifications Statistics Preferences

Webs Main Sandbox TWiki Zen Information

Main Web Users Groups Index Search Changes Notifications Statistics Preferences

Webs Main Sandbox TWiki Zen

Astrophysics Wiki

Edit Wysiwyg Attach Printable
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Astrophysics Wiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TocPluginHelp