Table of Contents Macro

Description

The TocMacro generates a table of contents for the current page or a set of pages.

If no arguments are given, a table of contents is generated for the current page, with the top-level title stripped:

[[TOC]]

To generate a table of contents for a set of pages, simply pass them as comma separated arguments to the TOC macro. This is the macro call for the table of contents visible on the right side of this page:

[[TOC(TracGuide, TracInstall, TracUpgrade, TracIni, TracAdmin, TracBackup, TracLogging,
TracPermissions, TracWiki, WikiFormatting, TracBrowser, TracRoadmap, TracChangeset,
TracTickets, TracReports, TracQuery, TracTimeline, TracRss, TracNotification)]]

A wildcard '*' can be used to fetch a sorted list of all pages starting with the preceding pagename stub (Since [2801]):

[[TOC(Trac*, WikiFormatting, WikiMacros)]]

For 'titleindex' argument, an empty pagelist will evaluate to all pages (Since [2801]):

[[TOC(titleindex, notitle, heading=All pages)]]

'sectionindex' allows to generate a title index for all pages in a given section of the wiki. A section is defined by wiki page name, using '/' as a section level delimiter (like directories in a file system). Giving '/' or '*' as the page name produces the same result as 'titleindex' (title of all pages). If a page name ends with a '/', only children of this page will be processed. Else the page given in the argument is also included, if it exists. For 'sectionindex' argument, an empty pagelist will evaluate to all page below the same parent as the current page:

[[TOC(sectionindex, notitle, heading=This section pages)]]

The following control arguments change the default behaviour of the TOC macro (Since [22]):

Argument	Meaning
heading=<x>	Override the default heading of "Table of Contents" or "Page Index" for titleindex.
noheading	Suppress display of the heading.
depth=<n>	Display headings of subsequent pages to a maximum depth of <n>.
inline	Display TOC inline rather than as a side-bar.
sectionindex	Only display the page name and title of each page for all pages in a given section. (Since [3417]).
titleindex	Only display the page name and title of each page, similar to TitleIndex. (Since [37]).
notitle	Supress display of page title (Since [2801]).

Bugs/Feature Requests

Existing bugs and feature requests are here. If you have any issues, create a new ticket.

Installation

Both 0.10 and 0.11/0.12 entries at Python Package Index (pypi) are not up-to-date with latest versions and dependencies. To install the most recent versions, use direct installation from source:

easy_install http://trac-hacks.org/svn/tocmacro/0.10   # 0.10
easy_install http://trac-hacks.org/svn/tocmacro/0.11   # 0.11 and 0.12

...or download / check out the source from repository (see below) and install it in usual manner.

Do not forget to enable the macro in trac.ini:

[components]
tractoc.* = enabled

Download

Download the zipped source from here.

TocMacro requires that AnchorPatch be applied to 0.8 Trac. Trac 0.9 already includes this patch.

Source

You can check out TocMacro from here using Subversion, or browse the source with Trac.

Example

[[TOC(inline, heading=Trac Table of Contents, TracGuide, TracInstall, depth=2,
 TracLogging, depth=99, TracPermissions)]]

On the right you can see the TOC macro version of the default TracGuideToc macro.

Alternatives

Trac 0.12 (maybe earlier?) has the PageOutline macro built-in which can produce output identical to the simpler use cases for the TOC macro. For example, this is equivalent to the no-argument form of TOC:

[[PageOutline(2-5, Table of Contents, floated)]]

Change Log

[4366] by osimons on 10/02/08 00:47:15

TocMacro: Fixed a serious bug whereby the 0.11 version of the macro would keep a database connection open after execution.

This innocent-looking line...

self.formatter = formatter

... essentially attaches the transient formatter and its formatter.db connection to the instantiated plugin/component that lives for the lifetime of the environment (that in most setups gets cached for the duration of the process or until event like config change forces reload). Next time the macro executes it will free the old connection, and replace it with the new.

The problem continually ties up 1 connection of a process-wide default maximum number of 10. Many projects using the macro can get to the point where it locks the process due to no database connections being available - failing with TimeoutError. Particularly dangerous with embedded interpreter on Apache for Windows as it serves all requests using just a single process.

Code is changed to not persist the formatter, but instead pass it around as needed.

To all users of 0.11 version: Please upgrade!

[3418] by jouvin on 03/25/08 16:42:36

Add inline documentation for sectionindex

[3417] by jouvin on 03/25/08 15:35:22

Add support for keyword sectionindex in 11.0.0 (see http://trac-hacks.org/ticket/2790 and documentation); version incremented to 11.0.0.3

[3416] by coderanger on 03/25/08 07:39:08

Change my email to avoid Yahoo, which decided to brake my scraper script recently.

Author/Contributors

Authors: athomas, jouvin, coderanger, cboos, osimons
Maintainer: osimons
Contributors: