r1 - 14 Sep 2006 - 08:45:56 - TWikiGuestYou are here: TWiki >  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.

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. AttachContentPlugin
  10. BehaviourContrib
  11. BibtexPlugin
  12. BibtexSearchTemplate
  13. BibtexSelectTemplate
  14. BibtexSimpleSearchTemplate
  15. BookView
  16. BreadCrumbsPlugin
  17. BulkRegistration
  18. BulkResetPassword
  19. BumpyWord
  20. CalendarPlugin
  21. CaptchaPlugin
  22. CategoryCategory
  23. ChangeEmailAddress
  24. ChangePassword
  25. ClassMethod
  26. ClassicSkin
  27. ClassicSkinLogin
  28. CodeMikelPlugin
  29. CommentPlugin
  30. CommentPluginTemplate
  31. DeleteOrRenameATopic
  32. DeleteOrRenameAnAttachment
  33. DeveloperDocumentationCategory
  34. DontNotify
  35. EasyTimelinePlugin
  36. EditContrib
  37. EditDoesNotIncreaseTheRevision
  38. EditTablePlugin
  39. EmbedBibPlugin
  40. EmptyPlugin
  41. ExampleTopicTemplate
  42. ExplicitNumberingPlugin
  43. FileAttachment
  44. FileAttribute
  45. FilterPlugin
  46. FlexWebListExamples
  47. FlexWebListPlugin
  48. ForceNewRevision
  49. FormattedSearch
  50. GenPDFAddOn
  51. GenPDFExampleHeaderFooterTopic
  52. GenPDFExampleTitleTopic
  53. GenPDFLatexAddOn
  54. GenPDFLatexPlugin
  55. GluePlugin
  56. GnuGeneralPublicLicense
  57. GoBox
  58. GoodStyle
  59. GttsLogos
  60. GttsResources
  61. HiddenAttachment
  62. IfDefinedPlugin
  63. IfStatements
  64. IncludeTopicsAndWebPages
  65. InstalledPlugins
  66. InstantEnhancements
  67. InterWikis
  68. InterwikiPlugin
  69. JSCalendarContrib
  70. LanguageSelector
  71. LatexIntro
  72. LatexModePlugin
  73. LatexSymbols
  74. LatexSymbols2
  75. LatexSymbols3
  76. LatexSymbols4
  77. LatexSymbols5
  78. LoginName
  79. MailerContrib
  80. MainFeatures
  81. ManagingTopics
  82. ManagingUsers
  83. ManagingWebs
  84. MathModePlugin
  85. MoveTopic
  86. MySideBar
  87. MySideBarTemplate
  88. NatSearch
  89. NatSkin
  90. NatSkinConfiguration
  91. NatSkinCss
  92. NatSkinFAQ
  93. NatSkinPlugin
  94. NatSkinStyleBrowser
  95. NatSkinTemplates
  96. NewUserTemplate
  97. ObjectMethod
  98. OriginalColors
  99. PatternSkin
  100. PatternSkinCss
  101. PatternSkinCssCookbook
  102. PatternSkinCssCookbookCenterPage
  103. PatternSkinCssCookbookCenterPageBorder
  104. PatternSkinCssCookbookEditTableStyle
  105. PatternSkinCssCookbookFonts
  106. PatternSkinCssCookbookNoLeftBar
  107. PatternSkinCssCookbookNoTopBar
  108. PatternSkinCustomization
  109. PatternSkinHeaderArt
  110. PatternSkinJavascripts
  111. PeterThoeny
  112. PlainSkin
  113. PreferencesPlugin
  114. PreviewBackground
  115. PrintSkin
  116. PublishContrib
  117. PublishWeb
  118. QuietSave
  119. RedDotPlugin
  120. RegistrationApprovals
  121. RegularExpression
  122. RenameWeb
  123. RenderListPlugin
  124. ResetPassword
  125. SautrelaColors
  126. SautrelaResources
  127. SearchDoesNotWork
  128. SearchHelp
  129. SearchPatternCookbook
  130. SimultaneousEdits
  131. SiteChanges
  132. SiteMap
  133. SitePermissions
  134. SlideShowPlugin
  135. SmiliesPlugin
  136. SourceCode
  137. SpreadSheetPlugin
  138. StandardColors
  139. StartingPoints
  140. StaticMethod
  141. TWikiAccessControl
  142. TWikiAccessControlExceptionDotPm
  143. TWikiAccessDotPm
  144. TWikiAttachDotPm
  145. TWikiAttrsDotPm
  146. TWikiClientApacheLoginDotPm
  147. TWikiClientDotPm
  148. TWikiClientTemplateLoginDotPm
  149. TWikiCompatibilityDotPm
  150. TWikiContributor
  151. TWikiCss
  152. TWikiDocGraphics
  153. TWikiDocumentation
  154. TWikiDotPm
  155. TWikiDownload
  156. TWikiEditingShorthand
  157. TWikiEnhancementRequests
  158. TWikiFAQ
  159. TWikiFaqTemplate
  160. TWikiFormDotPm
  161. TWikiForms
  162. TWikiFuncDotPm
  163. TWikiGlossary
  164. TWikiHistory
  165. TWikiI18NDotPm
  166. TWikiI18NExtractDotPm
  167. TWikiIfDotPm
  168. TWikiInstallationGuide
  169. TWikiJavascripts
  170. TWikiLogos
  171. TWikiMergeDotPm
  172. TWikiMetaData
  173. TWikiMetaDotPm
  174. TWikiNetDotPm
  175. TWikiOopsExceptionDotPm
  176. TWikiPlannedFeatures
  177. TWikiPluginDotPm
  178. TWikiPlugins
  179. TWikiPluginsDotPm
  180. TWikiPluralsDotPm
  181. TWikiPreferences
  182. TWikiPreferencesForm
  183. TWikiPrefsDotPm
  184. TWikiPrefsParserDotPm
  185. TWikiPrefsPrefsCacheDotPm
  186. TWikiReferenceManual
  187. TWikiRegistration
  188. TWikiReleaseNotes04x00
  189. TWikiRenderDotPm
  190. TWikiSandboxDotPm
  191. TWikiScripts
  192. TWikiSearchDotPm
  193. TWikiShorthand
  194. TWikiSite
  195. TWikiSiteTools
  196. TWikiSkinBrowser
  197. TWikiSkins
  198. TWikiStoreDotPm
  199. TWikiStoreRcsFileDotPm
  200. TWikiStoreRcsLiteDotPm
  201. TWikiStoreRcsWrapDotPm
  202. TWikiSystemRequirements
  203. TWikiTemplates
  204. TWikiTemplatesDotPm
  205. TWikiTimeDotPm
  206. TWikiTip001
  207. TWikiTip002
  208. TWikiTip003
  209. TWikiTip004
  210. TWikiTip005
  211. TWikiTip006
  212. TWikiTip007
  213. TWikiTip008
  214. TWikiTip009
  215. TWikiTip010
  216. TWikiTip011
  217. TWikiTip012
  218. TWikiTip013
  219. TWikiTip014
  220. TWikiTip015
  221. TWikiTip016
  222. TWikiTip017
  223. TWikiTip018
  224. TWikiTip019
  225. TWikiTip020
  226. TWikiTip021
  227. TWikiTip022
  228. TWikiTip023
  229. TWikiTip024
  230. TWikiTip025
  231. TWikiTip026
  232. TWikiTip027
  233. TWikiTip028
  234. TWikiTip029
  235. TWikiTips
  236. TWikiTipsOfTheDay
  237. TWikiTipsOfTheDayAddNew
  238. TWikiTipsOfTheDayAdmin
  239. TWikiTipsOfTheDayInclude
  240. TWikiTipsOfTheDayTemplate
  241. TWikiTopics
  242. TWikiTutorial
  243. TWikiUIChangeFormDotPm
  244. TWikiUIDotPm
  245. TWikiUIEditDotPm
  246. TWikiUIManageDotPm
  247. TWikiUIOopsDotPm
  248. TWikiUIRDiffDotPm
  249. TWikiUIRegisterDotPm
  250. TWikiUIRestDotPm
  251. TWikiUISaveDotPm
  252. TWikiUISearchDotPm
  253. TWikiUIStatisticsDotPm
  254. TWikiUIUploadDotPm
  255. TWikiUIViewDotPm
  256. TWikiUpgradeGuide
  257. TWikiUserAuthentication
  258. TWikiUserDotPm
  259. TWikiUsersApacheHtpasswdUserDotPm
  260. TWikiUsersDotPm
  261. TWikiUsersGuide
  262. TWikiUsersPasswordDotPm
  263. TWikiUsersTWikiUserMappingDotPm
  264. TWikiVariables
  265. TWikiVariablesQuickStart
  266. TWikiWebButtons
  267. TWikiWebCss
  268. TWikiWebLinks
  269. TWikiWebLinksForAdmins
  270. TWikiWebRightBar
  271. TWikiWebSideBar
  272. TWikiWebTopicActions
  273. TWikiWebsTable
  274. TablePlugin
  275. TemplateWeb
  276. TextEditor
  277. TextFormattingFAQ
  278. TextFormattingRules
  279. ThreadedDiscussionPlugin
  280. TimBernersLee
  281. TimeInterval
  282. TipsContrib
  283. TwistyContrib
  284. TwistyPlugin
  285. UserDocumentationCategory
  286. UserToolsCategory
  287. UsingHTML
  288. VarACTIVATEDPLUGINS
  289. VarALLVARIABLES
  290. VarATTACHURL
  291. VarATTACHURLPATH
  292. VarAUTHREALM
  293. VarBASETOPIC
  294. VarBASEWEB
  295. VarDATE
  296. VarDISPLAYTIME
  297. VarDISPLAYTIME2
  298. VarENCODE
  299. VarENDSECTION
  300. VarFAILEDPLUGINS
  301. VarFORMFIELD
  302. VarGMTIME
  303. VarGMTIME2
  304. VarGROUPS
  305. VarHOMETOPIC
  306. VarHTTP
  307. VarHTTPHOST
  308. VarHTTPS
  309. VarICON
  310. VarICONURL
  311. VarICONURLPATH
  312. VarIF
  313. VarINCLUDE
  314. VarINCLUDINGTOPIC
  315. VarINCLUDINGWEB
  316. VarLANGUAGE
  317. VarLANGUAGES
  318. VarLOCALSITEPREFS
  319. VarLOGIN
  320. VarLOGOUT
  321. VarMAINWEB
  322. VarMAKETEXT
  323. VarMETA
  324. VarMETASEARCH
  325. VarNOP
  326. VarNOTIFYTOPIC
  327. VarPLUGINDESCRIPTIONS
  328. VarPLUGINVERSION
  329. VarPUBURL
  330. VarPUBURLPATH
  331. VarQUERYSTRING
  332. VarREMOTEADDR
  333. VarREMOTEPORT
  334. VarREMOTEUSER
  335. VarREVINFO
  336. VarREVINFO2
  337. VarSCRIPTNAME
  338. VarSCRIPTSUFFIX
  339. VarSCRIPTURL
  340. VarSCRIPTURL2
  341. VarSCRIPTURLPATH
  342. VarSCRIPTURLPATH2
  343. VarSEARCH
  344. VarSERVERTIME
  345. VarSERVERTIME2
  346. VarSESSIONID
  347. VarSESSIONVAR
  348. VarSESSIONVARIABLE
  349. VarSPACEDTOPIC
  350. VarSPACEOUT
  351. VarSTARTINCLUDE
  352. VarSTARTSECTION
  353. VarSTATISTICSTOPIC
  354. VarSTOPINCLUDE
  355. VarTOC
  356. VarTOC2
  357. VarTOPIC
  358. VarTOPICLIST
  359. VarTWIKIWEB
  360. VarURLPARAM
  361. VarUSERINFO
  362. VarUSERNAME
  363. VarVAR
  364. VarWEB
  365. VarWEBLIST
  366. VarWEBPREFSTOPIC
  367. VarWIKIHOMEURL
  368. VarWIKINAME
  369. VarWIKIPREFSTOPIC
  370. VarWIKITOOLNAME
  371. VarWIKIUSERNAME
  372. VarWIKIUSERSTOPIC
  373. VarWIKIVERSION
  374. WabiSabi
  375. WelcomeGuest
  376. WhatDoesTWikiStandFor
  377. WhatIsWikiWiki
  378. WikiCulture
  379. WikiName
  380. WikiNotation
  381. WikiReferences
  382. WikiSyntax
  383. WikiSyntaxSummary
  384. WikiTopic
  385. WikiWikiClones
  386. WikiWord
  387. WysiwygPlugin
  388. WysiwygPluginTopicLister
  389. 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

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r1 | More topic actions
 
Powered by TWiki
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 TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TocPluginHelp