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.

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

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

• 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

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

If a %SECTION0% tag 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% 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

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

1.3.2.1.A Table of contents for this web

1.3.2.2. Output from %CONTENTS% tag for this topic

1.3.2.2.A 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

%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

• 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

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
235. VarACTIVATEDPLUGINS
236. VarALLVARIABLES
237. VarATTACHURL
238. VarATTACHURLPATH
239. VarAUTHREALM
240. VarBASETOPIC
241. VarBASEWEB
242. VarDATE
243. VarDISPLAYTIME
244. VarDISPLAYTIME2
245. VarENCODE
246. VarENDSECTION
247. VarFAILEDPLUGINS
248. VarFORMFIELD
249. VarGMTIME
250. VarGMTIME2
251. VarGROUPS
252. VarHOMETOPIC
253. VarHTTP
254. VarHTTPHOST
255. VarHTTPS
256. VarICON
257. VarICONURL
258. VarICONURLPATH
259. VarIF
260. VarINCLUDE
261. VarINCLUDINGTOPIC
262. VarINCLUDINGWEB
263. VarLANGUAGE
264. VarLANGUAGES
265. VarLOCALSITEPREFS
266. VarLOGIN
267. VarLOGOUT
268. VarMAINWEB
269. VarMAKETEXT
270. VarMETA
271. VarMETASEARCH
272. VarNOP
273. VarNOTIFYTOPIC
274. VarPLUGINDESCRIPTIONS
275. VarPLUGINVERSION
276. VarPUBURL
277. VarPUBURLPATH
278. VarQUERYSTRING
279. VarREMOTEADDR
280. VarREMOTEPORT
281. VarREMOTEUSER
282. VarREVINFO
283. VarREVINFO2
284. VarSCRIPTNAME
285. VarSCRIPTSUFFIX
286. VarSCRIPTURL
287. VarSCRIPTURL2
288. VarSCRIPTURLPATH
289. VarSCRIPTURLPATH2
290. VarSEARCH
291. VarSERVERTIME
292. VarSERVERTIME2
293. VarSESSIONID
294. VarSESSIONVAR
295. VarSESSIONVARIABLE
296. VarSPACEDTOPIC
297. VarSPACEOUT
298. VarSTARTINCLUDE
299. VarSTARTSECTION
300. VarSTATISTICSTOPIC
301. VarSTOPINCLUDE
302. VarTOC
303. VarTOC2
304. VarTOPIC
305. VarTOPICLIST
306. VarTWIKIWEB
307. VarURLPARAM
308. VarUSERINFO
309. VarUSERNAME
310. VarVAR
311. VarWEB
312. VarWEBLIST
313. VarWEBPREFSTOPIC
314. VarWIKIHOMEURL
315. VarWIKINAME
316. VarWIKIPREFSTOPIC
317. VarWIKITOOLNAME
318. VarWIKIUSERNAME
319. VarWIKIUSERSTOPIC
320. VarWIKIVERSION
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

1.3.3.1.A 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.

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

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

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

generates

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:

%REFTABLE{type=Example}%

This will insert a table like this:

Example
1.1.1.A The Weborder topic
1.3.2.1.A Table of contents for this web
1.3.2.2.A Table of contents for this topic
1.3.3.1.A 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}%

and

%REFTABLE{type=Figure}%

will insert a table like this:

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

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

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