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 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 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 wiki-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 TML or HTML formatting but it should be noted that all TML-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

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. AccessControl
2. AccessKeys
3. AdminDocumentationCategory
4. AdminSkillsAssumptions
5. AdminToolsCategory
6. AnApplicationWithWikiForm
7. AppendixEncodeURLsWithUTF8
8. ApprovalPlugin
9. BatchUploadPlugin
10. BeginnersStartHere
11. BehaviourContrib
12. BookView
13. BreadCrumbsPlugin
14. BulkRegistration
15. BulkResetPassword
16. BumpyWord
17. CalendarPlugin
18. CascadingStyleSheets
19. CategoryCategory
20. ChangeEmailAddress
21. ChangePassword
22. ClassMethod
23. CommandAndCGIScripts
24. CommentPlugin
25. CommentPluginExamples
26. CommentPluginTemplate
27. CompareRevisionsAddOn
28. CompareRevisionsAddonPlugin
29. CompleteDocumentation
30. Contribs
31. ContributedAddOns
32. DataForms
33. DatabasePlugin
34. DefaultMenu
35. DefaultPreferences
36. DefaultPreferencesForm
37. DefaultWebMenu
38. DefaultWidgets
39. DeleteOrRenameATopic
40. DeleteOrRenameAnAttachment
41. DeveloperDocumentationCategory
42. DevelopingPlugins
43. DocumentGraphics
44. DojoToolkitContrib
45. DontNotify
46. DownloadSources
47. EditDoesNotIncreaseTheRevision
48. EditTablePlugin
49. EditingShorthand
50. EmptyPlugin
51. EnhancementRequests
52. ExampleTopicTemplate
53. ExcelImportExportPlugin
54. FamFamFamContrib
55. FamFamFamFlagIcons
56. FamFamFamMiniIcons
57. FamFamFamMintIcons
58. FamFamFamSilkIcons
59. FaqTemplate
60. FileAttachment
61. FileAttribute
62. FilterPlugin
63. FlexWebListExamples
64. FlexWebListNavi
65. FlexWebListPlugin
66. FlexWebListTree
67. ForceNewRevision
68. FormatTokens
69. FormattedSearch
70. FrequentlyAskedQuestions
71. GenPDFAddOn
72. GenPDFAddOnDemo
73. GenPDFExampleHeaderFooterTopic
74. GenPDFExampleTitleTopic
75. GlossaryOfTerms
76. GluePlugin
77. GnuGeneralPublicLicense
78. GoBox
79. GoodStyle
80. HiddenAttachment
81. HierarchicalNavigation
82. HierarchicalNavigationChildExample
83. HistoryPlugin
84. IfDefinedPlugin
85. IfStatements
86. ImageGalleryPlugin
87. IncludeTopicsAndWebPages
88. InstallationGuide
89. InstalledPlugins
90. InstantEnhancements
91. InterWikis
92. InterwikiPlugin
93. JQueryAjaxHelper
94. JQueryAutocomplete
95. JQueryBgiframe
96. JQueryBlockUI
97. JQueryButton
98. JQueryChili
99. JQueryCodingStandards
100. JQueryCookie
101. JQueryCorner
102. JQueryCycle
103. JQueryDebug
104. JQueryEasing
105. JQueryEmpty
106. JQueryFarbtastic
107. JQueryFluidFont
108. JQueryFocus
109. JQueryForm
110. JQueryFoswiki
111. JQueryFullCalendar
112. JQueryGradient
113. JQueryGrid
114. JQueryHoverIntent
115. JQueryInnerFade
116. JQueryLocalScroll
117. JQueryMaskedInput
118. JQueryMasonry
119. JQueryMedia
120. JQueryMetadata
121. JQueryPlugin
122. JQueryRating
123. JQueryScrollTo
124. JQuerySerialScroll
125. JQueryShake
126. JQueryShrinkUrls
127. JQuerySimpleModal
128. JQuerySlimbox
129. JQuerySuperfish
130. JQuerySupersubs
131. JQueryTabpane
132. JQueryTextboxList
133. JQueryToggle
134. JQueryTooltip
135. JQueryTreeview
136. JQueryUI
137. JQueryValidate
138. JQueryWikiWord
139. JSCalendarContrib
140. JSCalendarContribInline
141. JavascriptFiles
142. LanguageSelector
143. LoginName
144. Macros
145. MacrosQuickStart
146. MailerContrib
147. MainFeatures
148. ManagingTopics
149. ManagingUsers
150. ManagingWebs
151. MenuListDefault
152. MenuListPlugin
153. MetaData
154. MoveTopic
155. MoveableTypeMantisDesign
156. MoveableTypeSample2Design
157. MoveableTypeSample3Design
158. MoveableTypeSampleDesign
159. MoveableTypeSkin
160. NewUserTemplate
161. NuLeftBar
162. NuMenuBar
163. NuMenuBarContents
164. NuMenuBarFunctions
165. NuMenuBarLocalNav
166. NuMenuBarUser
167. NuMenuBarWebs
168. NuParentTemplate
169. NuSkin
170. NuSkinNoJS
171. ObjectMethod
172. OfficeToolBar
173. OfficeToolBarOptions
174. PatternSkin
175. PatternSkinColorSettings
176. PatternSkinCss
177. PatternSkinCssCookbook
178. PatternSkinCssCookbookCenterPage
179. PatternSkinCssCookbookCenterPageBorder
180. PatternSkinCssCookbookEditTableStyle
181. PatternSkinCssCookbookFonts
182. PatternSkinCssCookbookNoLeftBar
183. PatternSkinCssCookbookNoTopBar
184. PatternSkinCustomization
185. PatternSkinElements
186. PatternSkinGraphics
187. PatternSkinHeaderArt
188. PatternSkinWebCreateNewTopicTemplate
189. PerlDoc
190. PlainSkin
191. Plugins
192. PreferenceSettings
193. PreferencesPlugin
194. PreviewBackground
195. PrintSkin
196. ProjectContributor
197. ProjectLogos
198. QuerySearch
199. QuickMenuBar
200. QuickMenuBarLanguage
201. QuickMenuBarLogin
202. QuickMenuBarUtilities
203. QuickMenuBarWebs
204. QuickMenuDisabled
205. QuickMenuSkin
206. QuietSave
207. RatingContrib
208. ReferenceManual
209. RegistrationApprovals
210. RegularExpression
211. ReleaseHistory
212. ReleaseNotes01x00
213. RenameWeb
214. RenderListPlugin
215. ResetPassword
216. SearchDoesNotWork
217. SearchHelp
218. SearchPatternCookbook
219. ShortHand
220. ShortcutMacros
221. SimultaneousEdits
222. SiteChanges
223. SiteMap
224. SiteMapViewTemplate
225. SitePermissions
226. SiteTools
227. SkinBrowser
228. SkinTemplates
229. Skins
230. SlideShowPlugin
231. SlionSkin
232. SlionSkinColorSettings
233. SlionSkinCss
234. SlionSkinCssCookbook
235. SlionSkinCssCookbookCenterPage
236. SlionSkinCssCookbookCenterPageBorder
237. SlionSkinCssCookbookEditTableStyle
238. SlionSkinCssCookbookFonts
239. SlionSkinCssCookbookNoLeftBar
240. SlionSkinCssCookbookNoTopBar
241. SlionSkinCustomization
242. SlionSkinElements
243. SlionSkinGraphics
244. SlionSkinHeaderArt
245. SlionSkinWebCreateNewTopicTemplate
246. SmiliesPlugin
247. SoftSkin
248. SpreadSheetPlugin
249. StandardColors
250. StartingPoints
251. StaticMethod
252. SubMenuBarExample
253. SubMenuContentsExample
254. SubscribePlugin
255. SystemRequirements
256. TWikiCompatibilityPlugin
257. TablePlugin
258. TagMeChangeRequests
259. TagMeCreateNewTag
260. TagMeDebugSearch
261. TagMeDebugViewTags
262. TagMeDeleteTag
263. TagMePlugin
264. TagMeRenameTag
265. TagMeSearch
266. TagMeViewAllTags
267. TagMeViewMyTags
268. TemplateTopics
269. TemplateWeb
270. TestUrls
271. TextEditor
272. TextFormattingRules
273. TimBernersLee
274. TimeSpecifications
275. TinyMCEFrequentlyAskedQuestions
276. TinyMCEPlugin
277. TinyMCEQuickHelp
278. TipTopic001
279. TipTopic002
280. TipTopic003
281. TipTopic004
282. TipTopic005
283. TipTopic006
284. TipTopic007
285. TipTopic008
286. TipTopic009
287. TipTopic010
288. TipTopic011
289. TipTopic012
290. TipTopic013
291. TipTopic014
292. TipTopic015
293. TipTopic016
294. TipTopic017
295. TipTopic018
296. TipTopic019
297. TipTopic020
298. TipTopic021
299. TipTopic022
300. TipTopic023
301. TipTopic024
302. TipTopic025
303. TipTopic026
304. TipTopic027
305. TipTopic028
306. TipTopic029
307. TipsContrib
308. TipsOfTheDay
309. TipsOfTheDayAddNew
310. TipsOfTheDayAdmin
311. TipsOfTheDayInclude
312. TipsOfTheDayTemplate
313. TipsTopics
314. TopicDoesNotExistViewTemplate
315. TopicUserMappingContrib
316. TopicsAndWebs
317. TreeBrowserPlugin
318. TreePlugin
319. TreePluginBookviewOutlineSample
320. TreePluginHeadingOutlineSample
321. TreePluginSamples
322. TwentyMinuteTutorial
323. TwistyPlugin
324. UpgradeGuide
325. UploadPlugin
326. UserAuthentication
327. UserDocumentationCategory
328. UserForm
329. UserRegistration
330. UserSetting
331. UserToolsCategory
332. UsersGuide
333. UsersTemplate
334. UsingHTML
335. VarACTIVATEDPLUGINS
336. VarADDTOHEAD
337. VarALLVARIABLES
338. VarAQUA
339. VarATTACHURL
340. VarATTACHURLPATH
341. VarAUTHREALM
342. VarBASETOPIC
343. VarBASEWEB
344. VarBB
345. VarBB2
346. VarBB3
347. VarBB4
348. VarBLACK
349. VarBLUE
350. VarBR
351. VarBROWN
352. VarBULLET
353. VarCALC
354. VarCARET
355. VarCOMMENT
356. VarDATE
357. VarDISPLAYTIME
358. VarEDITACTION
359. VarEDITTABLE
360. VarENCODE
361. VarENDCOLOR
362. VarENDSECTION
363. VarENV
364. VarFAILEDPLUGINS
365. VarFORMFIELD
366. VarGMTIME
367. VarGRAY
368. VarGREEN
369. VarGROUPS
370. VarH
371. VarHOMETOPIC
372. VarHTTP
373. VarHTTPHOST
374. VarHTTPS
375. VarI
376. VarICON
377. VarICONURL
378. VarICONURLPATH
379. VarIF
380. VarIMAGEGALLERY
381. VarINCLUDE
382. VarINCLUDINGTOPIC
383. VarINCLUDINGWEB
384. VarLANGUAGE
385. VarLANGUAGES
386. VarLIME
387. VarLOCALSITEPREFS
388. VarLOGIN
389. VarLOGOUT
390. VarM
391. VarMAINWEB
392. VarMAKETEXT
393. VarMAROON
394. VarMETA
395. VarMETASEARCH
396. VarN
397. VarNAVY
398. VarNOP
399. VarNOTIFYTOPIC
400. VarNRIMAGES
401. VarOLIVE
402. VarORANGE
403. VarP
404. VarPINK
405. VarPLUGINDESCRIPTIONS
406. VarPLUGINVERSION
407. VarPUBURL
408. VarPUBURLPATH
409. VarPURPLE
410. VarQ
411. VarQUERYPARAMS
412. VarQUERYSTRING
413. VarRED
414. VarREMOTEADDR
415. VarREMOTEPORT
416. VarREMOTEUSER
417. VarRENDERLIST
418. VarREVINFO
419. VarS
420. VarSCRIPTNAME
421. VarSCRIPTSUFFIX
422. VarSCRIPTURL
423. VarSCRIPTURLPATH
424. VarSEARCH
425. VarSERVERTIME
426. VarSESSIONID
427. VarSESSIONVAR
428. VarSESSIONVARIABLE
429. VarSILVER
430. VarSLIDESHOWEND
431. VarSLIDESHOWSTART
432. VarSPACEDTOPIC
433. VarSPACEOUT
434. VarSTARTINCLUDE
435. VarSTARTSECTION
436. VarSTATISTICSTOPIC
437. VarSTOPINCLUDE
438. VarSUBSCRIBE
439. VarSYSTEMWEB
440. VarT
441. VarTABLE
442. VarTEAL
443. VarTOC
444. VarTOPIC
445. VarTOPICLIST
446. VarTOPICURL
447. VarTWIKIWEB
448. VarU
449. VarURLPARAM
450. VarUSERINFO
451. VarUSERNAME
452. VarUSERSWEB
453. VarVAR
454. VarVBAR
455. VarVOTE
456. VarWEB
457. VarWEBLIST
458. VarWEBPREFSTOPIC
459. VarWHITE
460. VarWIKIHOMEURL
461. VarWIKINAME
462. VarWIKIPREFSTOPIC
463. VarWIKITOOLNAME
464. VarWIKIUSERNAME
465. VarWIKIUSERSTOPIC
466. VarWIKIVERSION
467. VarX
468. VarY
469. VarYELLOW
470. VotePlugin
471. WabiSabi
472. WelcomeGuest
473. WhatIsWikiWiki
474. WidgetsMantisDesign
475. WidgetsSample2Design
476. WidgetsSample3Design
477. WidgetsSampleDesign
478. WidgetsSkin
479. WikiCulture
480. WikiName
481. WikiNotation
482. WikiReferences
483. WikiSyntax
484. WikiSyntaxSummary
485. WikiWikiClones
486. WikiWord
487. WysiwygPlugin
488. WysiwygPluginSettings
489. WysiwygPluginTopicLister
490. YahooUserInterfaceContrib
491. YouAreHere
492. YuiMenuContrib

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

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