You are here: CFCL Wiki>System Web>TocPluginHelp (16 Apr 2010, WolfgangDenk)Edit Attach
If you see tags such as %SECTION0% on the next line, read TocPlugin

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.

Installation of the Plugin is straightforward. Simply unpack the tar file at the top level of your installation.

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.

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.

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 Bad REF: Current topic not in WebOrder 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.

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.

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 Bad REF: Current topic not in WebOrder 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.

Bad topic TocPluginHelp

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.

The following topics were not found in the WebOrder:
  1. ACRONYM
  2. AccessControl
  3. AdminDocumentationCategory
  4. AdminSkillsAssumptions
  5. AdminToggle
  6. AdminToolsCategory
  7. AppendixCascadingStyleSheets
  8. AutoViewTemplatePlugin
  9. BeautifierPlugin
  10. BeginnersStartHere
  11. BehaviourContrib
  12. BookView
  13. BookmakerPlugin
  14. BreadCrumbsPlugin
  15. BulkRegistration
  16. BulkResetPassword
  17. CalendarPlugin
  18. Category
  19. ChangeEmailAddress
  20. ChangePassword
  21. ChecklistPlugin
  22. ChecklistPluginChecklistItemState
  23. ClassMethod
  24. CommandAndCGIScripts
  25. CommentPlugin
  26. CommentPluginTemplate
  27. CompareRevisionsAddOn
  28. CompareRevisionsAddonPlugin
  29. CompleteDocumentation
  30. ConfigurePlugin
  31. Contribs
  32. ContributedAddOns
  33. CountryList
  34. DBCacheContrib
  35. DBCachePlugin
  36. DataForms
  37. DefaultPreferences
  38. DefaultPreferencesForm
  39. DefaultUserRegistration
  40. DefaultWebStatistics
  41. DeveloperDocumentationCategory
  42. DevelopingPlugins
  43. DocumentGraphics
  44. EditRowPlugin
  45. EditRowPluginExamples
  46. EditTablePlugin
  47. EditingShorthand
  48. EmptyPlugin
  49. EnhancementRequests
  50. ExampleTopicTemplate
  51. ExplicitNumberingPlugin
  52. FAQAnApplicationWithWikiForm
  53. FAQDeleteOrRenameATopic
  54. FAQDeleteOrRenameAnAttachment
  55. FAQDownloadSources
  56. FAQEditDoesNotIncreaseTheRevision
  57. FAQEditTemplate
  58. FAQForm
  59. FAQGnuGeneralPublicLicense
  60. FAQHiddenUsersAndGroups
  61. FAQRebuildingWikiUsersTopic
  62. FAQSearchDoesNotWork
  63. FAQSimultaneousEdits
  64. FAQTemplate
  65. FAQTroubleshootingExtensions
  66. FAQViewTemplate
  67. FAQWhatIsWikiWiki
  68. FAQWhyYouAreAskedToConfirm
  69. FamFamFamContrib
  70. FamFamFamFlagIcons
  71. FamFamFamFoswikiExtras
  72. FamFamFamMiniIcons
  73. FamFamFamMintIcons
  74. FamFamFamSilkCompanion1Icons
  75. FamFamFamSilkCompanion2Icons
  76. FamFamFamSilkGeoSilkIcons
  77. FamFamFamSilkIcons
  78. FastCGIEngineContrib
  79. FileAttachment
  80. FileAttribute
  81. FilterPlugin
  82. FlexFormPlugin
  83. FlexWebListExamples
  84. FlexWebListPlugin
  85. FlexWebListTree
  86. ForEachPlugin
  87. FormPlugin
  88. FormatTokens
  89. FormattedSearch
  90. FoswikiServerInformation
  91. FrequentlyAskedQuestion
  92. FrequentlyAskedQuestions
  93. GlossaryOfTerms
  94. GluePlugin
  95. GoBox
  96. GoUptoTocPlugin
  97. GoodStyle
  98. HierarchicalNavigation
  99. HierarchicalNavigationChildExample
  100. HistoryPlugin
  101. HomePagePlugin
  102. IconService
  103. IfDefinedPlugin
  104. IfStatements
  105. ImagePlugin
  106. IncludeTopicsAndWebPages
  107. InstallationGuide
  108. InstallationGuidePart2
  109. InstalledPlugins
  110. InstantEnhancements
  111. InterWikis
  112. InterwikiPlugin
  113. JEditableContrib
  114. JQSelect2Contrib
  115. JQueryAjaxHelper
  116. JQueryAnimate
  117. JQueryAutocomplete
  118. JQueryBgiframe
  119. JQueryBlockUI
  120. JQueryButton
  121. JQueryChili
  122. JQueryCodingStandards
  123. JQueryCookie
  124. JQueryCorner
  125. JQueryCycle
  126. JQueryDebug
  127. JQueryEasing
  128. JQueryEmpty
  129. JQueryFarbtastic
  130. JQueryFluidFont
  131. JQueryFocus
  132. JQueryFontAwesome
  133. JQueryForm
  134. JQueryFoswiki
  135. JQueryGradient
  136. JQueryHoverIntent
  137. JQueryI18N
  138. JQueryInnerFade
  139. JQueryLiveQuery
  140. JQueryLoader
  141. JQueryLocalScroll
  142. JQueryMaskedInput
  143. JQueryMasonry
  144. JQueryMedia
  145. JQueryMetadata
  146. JQueryMigrate
  147. JQueryPNotify
  148. JQueryPlaceholder
  149. JQueryPlugin
  150. JQueryPopUpWindow
  151. JQueryQueryObject
  152. JQueryRating
  153. JQueryRender
  154. JQueryScrollTo
  155. JQuerySerialScroll
  156. JQueryShake
  157. JQueryShrinkUrls
  158. JQuerySimpleModal
  159. JQuerySlimbox
  160. JQueryStars
  161. JQuerySuperfish
  162. JQuerySupersubs
  163. JQueryTabpane
  164. JQueryTextboxList
  165. JQueryTmpl
  166. JQueryTooltip
  167. JQueryTreeview
  168. JQueryUI
  169. JQueryUIAutocomplete
  170. JQueryUIDialog
  171. JQueryUITooltip
  172. JQueryValidate
  173. JQueryView
  174. JQueryWikiWord
  175. JSCalendarContrib
  176. JSCalendarContribInline
  177. JSTreeContrib
  178. JavascriptFiles
  179. JsonRpcContrib
  180. LanguageSelector
  181. LexiconForm
  182. Macros
  183. MacrosQuickReference
  184. MailerContrib
  185. MailerContribPlugin
  186. MainFeatures
  187. ManagingTopics
  188. ManagingUsers
  189. ManagingWebs
  190. MarkdownPlugin
  191. MetaData
  192. MetaDataPlugin
  193. MimeIconPlugin
  194. ModPerlEngineContrib
  195. MoreFormfieldsAjaxHelper
  196. MoreFormfieldsPlugin
  197. MultiLingualPlugin
  198. NatEditHelpText
  199. NatEditPlugin
  200. NatEditWordHelpText
  201. NewUserTemplate
  202. ObjectMethod
  203. OriginalDocumentGraphics
  204. PackageForm
  205. PageCaching
  206. ParentList
  207. PatternSkin
  208. PatternSkinCss
  209. PatternSkinCssCookbook
  210. PatternSkinCssCookbookCenterPage
  211. PatternSkinCssCookbookCenterPageBorder
  212. PatternSkinCssCookbookEditTableStyle
  213. PatternSkinCssCookbookFonts
  214. PatternSkinCssCookbookHideActions
  215. PatternSkinCssCookbookNoLeftBar
  216. PatternSkinCssCookbookNoTopBar
  217. PatternSkinCssCookbookSidebarBackground
  218. PatternSkinCssCookbookSidebarToggle
  219. PatternSkinCustomization
  220. PatternSkinElements
  221. PatternSkinGraphics
  222. PatternSkinHorizontalNavigationExample
  223. PatternSkinNavigation
  224. PatternSkinTheme
  225. PatternSkinTheme115
  226. PatternSkinTheme2009
  227. PatternSkinThemeFatWilly
  228. PatternSkinThemeFatWillyNavigation
  229. PendingRegistrations
  230. PendingRegistrationsTemplate
  231. PerlDependencyReport
  232. PerlDoc
  233. PhotoGalleryPlugin
  234. PlainFileStoreContrib
  235. PlainSkin
  236. Plugins
  237. PreferenceSettings
  238. PreferencesPlugin
  239. PreviewBackground
  240. PrintSkin
  241. ProjectContributor
  242. ProjectLogos
  243. PubLinkFixupPlugin
  244. PublishedAPI
  245. QuerySearch
  246. QuerySearchPatternCookbook
  247. RCSStoreContrib
  248. RedirectPlugin
  249. ReferenceManual
  250. RegularExpression
  251. ReleaseHistory
  252. ReleaseNotes01x00
  253. ReleaseNotes01x01
  254. ReleaseNotes02x00
  255. ReleaseNotes02x01
  256. RemoveUser
  257. RenameWeb
  258. RenderListPlugin
  259. RenderPlugin
  260. ResetPassword
  261. SearchHelp
  262. SearchPatternCookbook
  263. SendEmailPlugin
  264. SendEmailPluginTemplate
  265. SetVariablePlugin
  266. SiteChanges
  267. SiteMap
  268. SitePermissions
  269. SiteToolStatistics
  270. SiteTools
  271. SkinBrowser
  272. SkinTemplateTokens
  273. SkinTemplateViewTemplate
  274. SkinTemplates
  275. Skins
  276. SlideShowPlugin
  277. SmiliesPlugin
  278. SpreadSheetPlugin
  279. StandardColors
  280. StaticMethod
  281. SubscribePlugin
  282. SyntaxHighlightingPlugin
  283. SystemRequirements
  284. TWikiCompatibilityPlugin
  285. TablePlugin
  286. TagCloudPlugin
  287. TalkContrib
  288. TemplateTopics
  289. TemplateWeb
  290. TextEditor
  291. TimBernersLee
  292. TimeSpecifications
  293. TinyMCEFrequentlyAskedQuestions
  294. TinyMCEPlugin
  295. TinyMCEQuickHelp
  296. TipTopic001
  297. TipTopic002
  298. TipTopic003
  299. TipTopic004
  300. TipTopic005
  301. TipTopic006
  302. TipTopic007
  303. TipTopic008
  304. TipTopic009
  305. TipTopic010
  306. TipTopic011
  307. TipTopic012
  308. TipTopic013
  309. TipTopic014
  310. TipTopic015
  311. TipTopic016
  312. TipTopic017
  313. TipTopic018
  314. TipTopic019
  315. TipTopic020
  316. TipTopic021
  317. TipTopic022
  318. TipTopic023
  319. TipTopic024
  320. TipTopic025
  321. TipTopic026
  322. TipTopic027
  323. TipTopic028
  324. TipTopic029
  325. TipsContrib
  326. TipsOfTheDay
  327. TipsOfTheDayAddNew
  328. TipsOfTheDayAdmin
  329. TipsOfTheDayInclude
  330. TipsOfTheDayTemplate
  331. TipsTopics
  332. TocPluginHelp
  333. ToolTipPlugin
  334. TopicClassification
  335. TopicDoesNotExistViewTemplate
  336. TopicInteractionPlugin
  337. TopicMarkupLanguage
  338. TopicTitlePlugin
  339. TopicUserMappingContrib
  340. TopicsAndWebs
  341. TreeBrowserPlugin
  342. TreePlugin
  343. TreePluginBookviewOutlineSample
  344. TreePluginHeadingOutlineSample
  345. TreePluginSamples
  346. TwentyMinuteTutorial
  347. TwistyPlugin
  348. UpdatesPlugin
  349. UpgradeGuide
  350. UserAuthentication
  351. UserDocumentationCategory
  352. UserForm
  353. UserFormHelp
  354. UserName
  355. UserRegistration
  356. UserRegistrationParts
  357. UserSetting
  358. UserToolsCategory
  359. UsersGuide
  360. UsersTemplate
  361. UsingHTML
  362. VarACTIVATEDPLUGINS
  363. VarADDTOHEAD
  364. VarADDTOZONE
  365. VarALLVARIABLES
  366. VarATTACHURL
  367. VarATTACHURLPATH
  368. VarAUTHREALM
  369. VarBASETOPIC
  370. VarBASEWEB
  371. VarBUTTON
  372. VarCALC
  373. VarCALCULATE
  374. VarCHECKLIST
  375. VarCHECKLISTEND
  376. VarCHECKLISTSTART
  377. VarCLI
  378. VarCODE
  379. VarCOMMENT
  380. VarCOVER
  381. VarCachePlugin
  382. VarCachePluginTest
  383. VarDATE
  384. VarDISPLAYTIME
  385. VarEDITTABLE
  386. VarENCODE
  387. VarENDCODE
  388. VarENDCOLOR
  389. VarENDINCLUDE
  390. VarENDSECTION
  391. VarENDTAB
  392. VarENDTABPANE
  393. VarENDTWISTY
  394. VarENDTWISTYTOGGLE
  395. VarENV
  396. VarEXAMPLETAG
  397. VarEXPAND
  398. VarFAILEDPLUGINS
  399. VarFORMAT
  400. VarFORMFIELD
  401. VarGMTIME
  402. VarGROUPINFO
  403. VarGROUPS
  404. VarHISTORY
  405. VarHOMETOPIC
  406. VarHTTP
  407. VarHTTPHOST
  408. VarHTTPS
  409. VarICON
  410. VarICONURL
  411. VarICONURLPATH
  412. VarIF
  413. VarINCLUDE
  414. VarINCLUDINGTOPIC
  415. VarINCLUDINGWEB
  416. VarJQICON
  417. VarJQICONPATH
  418. VarJQPLUGINS
  419. VarJQREQUIRE
  420. VarJQTHEME
  421. VarLANG
  422. VarLANGUAGE
  423. VarLANGUAGES
  424. VarLOCALSITEPREFS
  425. VarLOGIN
  426. VarLOGOUT
  427. VarMAINWEB
  428. VarMAKETEXT
  429. VarMETA
  430. VarMETASEARCH
  431. VarMIMEICON
  432. VarNONCE
  433. VarNOP
  434. VarNOTIFYTOPIC
  435. VarPERLDEPENDENCYREPORT
  436. VarPHOTOGALLERY
  437. VarPLUGINDESCRIPTIONS
  438. VarPLUGINVERSION
  439. VarPOPUPWINDOW
  440. VarPUBURL
  441. VarPUBURLPATH
  442. VarQUERY
  443. VarQUERYPARAMS
  444. VarQUERYSTRING
  445. VarREMOTEADDR
  446. VarREMOTEPORT
  447. VarREMOTEUSER
  448. VarRENDERLIST
  449. VarRENDERZONE
  450. VarREVARG
  451. VarREVINFO
  452. VarREVTITLE
  453. VarSCRIPTNAME
  454. VarSCRIPTSUFFIX
  455. VarSCRIPTURL
  456. VarSCRIPTURLPATH
  457. VarSEARCH
  458. VarSERVERINFORMATION
  459. VarSERVERTIME
  460. VarSESSIONID
  461. VarSESSIONVAR
  462. VarSESSIONVARIABLE
  463. VarSET
  464. VarSHOWPREFERENCE
  465. VarSKIN
  466. VarSLIDESHOWEND
  467. VarSLIDESHOWSTART
  468. VarSPACEDTOPIC
  469. VarSPACEOUT
  470. VarSTARTINCLUDE
  471. VarSTARTSECTION
  472. VarSTATISTICSTOPIC
  473. VarSTOPINCLUDE
  474. VarSTOPSECTION
  475. VarSUBSCRIBE
  476. VarSYSTEMWEB
  477. VarTAB
  478. VarTABLE
  479. VarTABPANE
  480. VarTOC
  481. VarTOPIC
  482. VarTOPICLIST
  483. VarTREEBROWSER
  484. VarTREEVIEW
  485. VarTWIKIWEB
  486. VarTWISTY
  487. VarTWISTYBUTTON
  488. VarTWISTYHIDE
  489. VarTWISTYSHOW
  490. VarTWISTYTOGGLE
  491. VarURLPARAM
  492. VarUSERINFO
  493. VarUSERNAME
  494. VarUSERSWEB
  495. VarVAR
  496. VarVARCACHE
  497. VarWEB
  498. VarWEBLIST
  499. VarWEBPREFSTOPIC
  500. VarWIKIAGENTEMAIL
  501. VarWIKIAGENTNAME
  502. VarWIKIHOMEURL
  503. VarWIKINAME
  504. VarWIKIPREFSTOPIC
  505. VarWIKITOOLNAME
  506. VarWIKIUSERNAME
  507. VarWIKIUSERSTOPIC
  508. VarWIKIVERSION
  509. VarWIKIWEBMASTER
  510. VarWIKIWEBMASTERNAME
  511. WYSIWYG
  512. WelcomeGuest
  513. WikiCulture
  514. WikiName
  515. WikiSyntaxSummary
  516. WikiWord
  517. WysiwygPlugin
  518. WysiwygPluginSettings
  519. WysiwygPluginTopicLister

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.

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 Bad REF: Current topic not in WebOrder 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:

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.

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 Bad REF: Current topic not in WebOrder 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

Bad REF: Current topic not in WebOrder

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

and
%REFTABLE{type=Figure}%
will insert a table like this:
Figure

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

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% tag 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% tag 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".

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.

  • 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.
Topic revision: r1 - 16 Apr 2010, WolfgangDenk

This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback