create new tag
, view all tags


I know that I can use %TOC{levels="n"}% to control the amount of detail that appears in a table of contents. However, I'd like to be able to create a table of contents that shows only those headings beneath one I specify.

Consider a topic with 25 headings. The main TOC might show only 5, the top level headings. However, within some substantial subsection of that topic, after some introductory text, I'd like to be able to insert a TOC for just that subsection.

The workaround, of course, is to create a separate topic linked from the first, but that is less desirable for two reasons. First, that creates another topic in the Web that will show up in searches, etc. Second, the link to the new topic will not appear in the TOC of the first. Even putting a link immediately after the %TOC% won't look or act the same.

So, assuming there isn't functionality for what I want, I'm asking to be able to specify a parent heading somehow. Here's one way: %TOC{parent="Question"}%.


TWiki version: TWikiRelease04x00x00
TWiki plugins: DefaultPlugin, EmptyPlugin, InterwikiPlugin
Server OS: Suse Linux SLES 9
Web server:  
Perl version:  
Client OS:  
Web Browser:  
Categories: Missing functionality

-- RobStewart - 09 Mar 2007


ALERT! If you answer a question - or someone answered one of your questions - please remember to edit the page and set the status to answered. The status selector is below the edit box.

> within some substantial subsection of that topic, after some introductory text, I'd like to be able to insert a TOC for just that subsection.

I want this too. I came looking for an answer and found someone else with the same need.

-- VickiBrown - 27 Mar 2007

enhancement request filed at develop.twiki.org: Item 3814

-- VickiBrown - 27 Mar 2007

Another workaround is to write the substantial subsection into a separate topic and then not linking to it, but including it with %INCLUDE{"SubstantialSubsection"}%. In the main topic, use %TOC{depth="1"}%. Within SubstantialSubsection, write %TOC{"%TOPIC%"}% to restrict the "local" table of contents to SubstantialSubsection even if it is included (technical background: %TOPIC% is processed before including, %TOC% afterwards).

Of course this workaround has the drawback of one additional topic to maintain. And it has a "complicated" user interface if you want to edit the SubstantialSubsection, because when editing the main topic all you see is the %INCLUDE%.

I don't think it is possible (or even desirable) to have something like %TOC{parent="Question"}%, though. There is no unique identifier which could be safely used to specify the parent attribute. I'd rather go for something like a scope="local" attribute (difficult to implement), or more explicit something like scope="---++" or even height="2" (height as opposed to depth wink ) which would stop before hitting the next heading of the specified level.

-- HaraldJoerg - 28 Mar 2007

The %INCLUDE% solution is better than just using a link, but it has the drawbacks I mentioned with having an additional topic. Furthermore, if a user does a search and finds the included topic, how does one find the topic that includes it to get the proper context?

You said you didn't think it desirable "to have something like %TOC{parent="Question"}%," yet I claim it is (unless you're speaking technically rather than semantically). You said you didn't think it was possible, though I wouldn't think it impossible to locate a heading by matching the exact text. That may be less than desirable because of its brittleness; is that what you meant?

Your scope="local" idea has merit since it is up to the engine to note the current heading level and to recognize only those headings at a lower level than the current until the next heading at the current level.

-- RobStewart - 09 Apr 2007

About hitting a topic in a search and then finding the topic which includes it: The most natural way would be to define the including topic as a parent topic, so that it shows up in the breadcrumbs. If that is not sufficient, you can add %STARTINCLUDE% and %STOPINCLUDE% in the included topic to delimit what actually gets included, and write some introductory lines before %STARTINCLUDE%. Again, that's at the price of adding more overhead frown .

About having %TOC{parent="Question"}%: You are correct, I would avoid such a solution because of its brittleness, but not only speaking technically. Matching the exact text is fragile if you, for example, decide to add another subsection in another section with the same heading (%TOC%= has problems there anyway), or if you decide to rename the heading from "Question" to "Questions". Such problems are easily overlooked while proofreading a long document for the umpteenth time.

I should mention another property of having separate smaller topics instead of a single big one: If the topic is "alive" in the sense that it is still being changed, then with one topic per subsection it is easy to spot which subsections have changed. On the other hand, the "main" topic may look unchanged if you look at its TWiki revision, though, if looked at its expansion, it is different because some of its included files have changed.

About scope="local": Yes, the automatism has its charm. However, it can not be used for e.g. the following situation:

Part Two


Table of Contents

For the heading of the TOC itself one could use the title attribute (you'd have to explicitly write <h2> instead of ---++), and perhaps one could live with the fact that headings before the toc of a subsection are not possible. If not, some attribute to define the level where the TOC has to stop must be given explicitly.

Sooner or later this discussion needs to be carried over to Codev, since it needs changes to the documented user interface...

-- HaraldJoerg - 10 Apr 2007

I'm sorry I haven't replied before now, but I don't think I got a notification of your response and I haven't looked in a while!

I reviewed your earlier response and the last one. I understand your concerns about the brittleness of a parent attribute for TOC. I think there's value in separate subsections being tracked separately in the web changes, though it seems as though breaking a single topic into multiple subtopics is an implementation detail. (I defend against editing long topics by moving the code to a better editor, but not all do, so shorter topics are definitely superior in that regard.)

I didn't know about %STARTINCLUDE% or %STOPINCLUDE%. Those will certainly permit creating a nicer subsection topic. Thank you.

I'm not sure I understand your counter example for scope="local" is valid. If a subsection of a topic were to include a table of contents, it would be for content to follow. Why would or should previous headings be included?

I very much like the automatic discovery of the level; using a "height" attribute would be brittle, though not nearly as brittle as matching text, since heading levels can be adjusted without corresponding changes to the "height" attributes.

If you feel the scope="level" idea has merit, then it should be moved to Codev, though I don't know what that entails.

-- RobStewart - 15 Jun 2007

Another note regarding using INCLUDES, I did this and got exactly what I was looking for visually. I.e. Each sub-section or included topic had it's own TOC with a higher level TOC at the top of the parent topic. The drawback when trying to navigate a single parent topic, is that the sub-section TOCs link to the included topic, not the corresponding section in the parent.

-- MichelleAlbertin - 29 Nov 2007

Change status to:
Edit | Attach | Watch | Print version | History: r7 < r6 < r5 < r4 < r3 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r7 - 2007-11-29 - MichelleAlbertin
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.