Building a TOC with more information

Problem

Then and now I have any kind of ToDo/Bug Lists to maintain, which are not under control of any action- or bug-tracker. E.g. after a meeting with a customer I document the discussed issues in T/Foswiki. But if it becomes a longer topic it becomes hard to get an overview about current state of all issues.

Context

This tip presents a technique to generate a table of contents with more information then just the headings. It uses the FilterPlugin to build such a table.

Solution

Here is how it looks like (simulated):

Detailed explanation follows below.

Writing content

Each level-2 heading in the document is followed by some extra information right after the heading. This looks as follows in TML:

---++ Analog Input Performance
#AnalogInputPerformance
| Bob Peace | %WIP% |

The first line is the normal level-2 heading. The second line is an anchor as described in TextFormattingRules (Just a # with a unique WikiWord). Finally the third line is a small table of two columns where the first one is the person responsible and the second column is the state. I prefer to use icons from DocumentGraphics for the state.

In this case I created a shortcut for the %ICON{}% syntax by adding the following line to Main.TWikiPreferences:

   * Set WIP = %ICON{"wip"}%

Building the table of contents

FilterPlugin is now utilized to search the document for all level-2 headings and build a table of them.

The whole thing looks like this:

%EXTRACT{topic="%TOPIC%" expand="off" 
pattern="^---\+\+ (.+?)[\r\n]+#([a-zA-Z0-9_]*?)[\r\n]+\| (.+?) \| (.+?) \|" 
format="| [[#$2][$1]] | $3   | $4   |$n"
header="| *Topic*  | *Responsible*  | *State* |$n"
}%

The option expand="off" forces FilterPlugin to process %TOPIC% before any TML processing. Therefore it sees the raw TML markup. If you don't use this, then FilterPlugin sees the expanded HTML syntax, which is harder to process.

The pattern utilizes Perls non-greedy (or minimal-matching) quantifiers. The slice ^---\+\+ (.+?)[\r\n]+ is interpreted as follows: Match ---++ at the beginning of a line followed by characters as long as one or more \r or \n characters appears. Literally meant plus signs ( +) and vertical bars ( |) have to be quoted in the pattern as they have special meaning.

Everything in the pattern that is enclosed in brackets ( (...)) is saved for later use.

The format parameter of %EXTRACT% specifies the output to be produced for any pattern match. In this case it just builds a table row with the previously match data:

• $1: The level-2 heading text
• $2: The anchor (so we can jump to the heading by clicking)
• $3: The responsible person
• $4: The state

Known Uses

Known Limitations

See Also