%TOC% is one of the most useful features in TWiki - it instantly adds useful structure and unlike some TWiki tags is intuitive for most users.

The implementation however leaves something to be desired - essentially it makes a large number of assumptions and comes a cropper on a regular occasion - also more bugs for TOC are being reported faster than they are being fixed. (not over a period of days/weeks, but years )

BugReport Summary of bugs on http://twiki.org/

None of these lists here are likely to be exhaustive.

Bugs that exist in TOC (date is date of report)

• UserDefinedAnchorNamesTruncated- 14 Aug 2003
• TOCDoesntRender - 10 May 2003
• TocFailsForIdenticalHeadingNames - 16 Jun 2001
  • FullHierarchyPathInTOCAnchors - 29 Oct 2002 (dup)
• LinksDontDifferentiateIdenticalHeadings- 27 Aug 2003 (dup)
• TocNotClosedProperly - 28 Aug 2003
• TocShowsCommentedOutHeadings - 24 Jul 2002
• TocWithParameterIgnoresStopinclude - 05 Feb 2002
• IncorrectWhitespaceParsingInTOC - 04 Jul 2002

Bugs that might still be broken

• OneLinePreTagsBreakTOC

*Bugs with fixes not in a production release*

Still broken in production release, but fix available (dates are date of fix):

• UppercaseHeaderTagsRenderedInTOC - 11 Feb 2003

Bugs Resolved

Previous bugs - fixed (?) in production release (anyone checked recently?) (dates are date of fix):

• TocFailsWithFormattings - 20 Dec 2001
• ViewAuthHandlingForTOC - 24 Nov 2001
• FixedWithSharpFailsInHeading (marked as dup, but comment implying it works) - fixed by accident AFAICT - no statement as to when. (No one checked in all likelyhood)
• MultipleAngleBracketsDoNotGetEscaped - 17 Jul 2002

Clearly bugs are being fixed, but more are being found faster than the fix rate, and the above list of bugs is inexaustive - not all bugs with TWiki get reported on TWiki.org.

For example, if you allow a Wiki Word into a heading, then that will not be rendered correctly in the heading if TOC gets anywhere near it. If you include an URL in the heading, the heading & TOC entry link to website, the TOC heading does not correctly link to the anchor since the generated anchor includes an extra a_ on the end which does not exist in the TOC links. These two bugs have existed for about 2 years. (I've had people whinge at me since my time at Inktomi about this - but the bug report never seems to have been made). See FooBarTopic for an example of the problem.

The marking of lots of these bugs as duplicates (when in fact they're just different symptoms of the same problem) and then ignoring them doesn't strike me as a sensible practice.

Suggested Way Forward - Rearchitect, or Enhance TocPlugin to subsume TOC handling

TOC handling needs revamping - there's already a TOC plugin - why not move the TOC handling out into a plugin and re-architect it from scratch? It's a useful, simple feature that would benefit well from this IMO. If the "completely rendered" text was passed to it, decorating it with extra anchors, detecting headers, and so on would be significantly simpler.

-- TWikiGuest - 28 Aug 2003