Feature Proposal: Add control over TOC rendering

There is a number of control parameters I would like to add to TOC.

1. Currently we need to set ---+!! on every page because we always use a page title and often a table of contents. But the syntax is confusing to people that are just learning TML. I want to set the starting level of TOC to 2 so we don't have to think about it anymore.
   • Proposal: Add a global variable to set the starting level of TOC.
2. On almost every page I am adding the title parameter. I need a global setting for this as well.
   • Proposal: Add a global variable to set the TOC title.
3. TWiki.org docs have the table of contents above the page title. Very strange. It is done to prevent the TOC being included within the INCLUDE block.
   • Proposal: Add a parameter to TOC to not render if the topic is included (compare TOPIC to BASETOPIC).

Documentation:

• Generated Table of Contents (TOC) settings
  • The first header level to appear in the TOC:
    • Set TOC_MIN_DEPTH =
      • If not set: 1
      • Possible values: 1 to 6
  • The last header level to appear in the TOC:
    • Set TOC_MAX_DEPTH =
      • If not set: 6
      • Possible values: 1 to 6
      • Can be overridden by depth parameter of variable TOC
  • The default TOC title:
    • Set TOC_TITLE =
      • If not set: nothing
      • Possible values: any string, for example On this page:
      • Can be overridden by title parameter of variable TOC
  • Do not show a TOC if the topic it contains is included in another topic:
    • Set TOC_HIDE_IF_INCLUDED = on
      • If not set: included TOC is shown
      • Possible values: on or nothing

Show IRC discussion  Hide 

[11:13pm] ArthurClemens: we could use a parameter that prevents TOC when the topic is included
[11:13pm] PeterThoeny: so technically it is ok to spit out tml as long as there are no vars
[11:13pm] ArthurClemens: to create better documentation topics
[11:14pm] PeterThoeny: ah, the previous mentioned issue of toc before heading
[11:14pm] ArthurClemens: right
[11:14pm] PeterThoeny: yes, that could be solved with a new parameter to toc
[11:15pm] ArthurClemens: if a topic 'know's it is included
[11:15pm] ArthurClemens: I remember vaguely there was a problem in there
[11:16pm] ArthurClemens: IF gives a problem as well: %IF{"$ TOPIC='WebHome' then=''}% is not possible
[11:17pm] PeterThoeny: looking at example, http://twiki.org/cgi-bin/view/TWiki04x01/TWikiPlugins
[11:18pm] PeterThoeny: the topic starts like this:
[11:18pm] PeterThoeny: %TOC%
[11:18pm] PeterThoeny: %STARTINCLUDE%
[11:18pm] PeterThoeny: ---# TWiki Plugins
[11:18pm] HaraldJoerg: To avoid this I usually have TOC before STARTINCLUDE
[11:18pm] HaraldJoerg: Ah - duplicate ideas :-)
[11:19pm] PeterThoeny: what we leally want is this:
[11:19pm] PeterThoeny: %STARTINCLUDE%
[11:19pm] PeterThoeny: ---# TWiki Plugins
[11:19pm] PeterThoeny: %TOC{ ...switch to turn this off if included... }%
[11:19pm] PeterThoeny: and some control to exclude a higher level heading
[11:20pm] PeterThoeny: so, basically: "give me a toc staryting from level 2, but only if not included
[11:20pm] PeterThoeny: "
[11:20pm] ArthurClemens: yes, instead of the ---+!! syntax
[11:20pm] ArthurClemens: (which is incomprehensible to my colleagues)
[11:21pm] PeterThoeny: in the use case for the twiki manual, we can't use --+!! syntax since this is needed to build the proper top level toc
[11:21pm] PeterThoeny: that is the basic reason for the current qurky solution of toc, startinclude, and unescaped level 1 heading

-- ArthurClemens - 12 Mar 2007

Discussion

I think we need a clear spec of what this proposal really is before we can decide on it.

-- KennethLavrsen - 08 Apr 2007

I have added the proposals.

-- ArthurClemens - 22 Apr 2007

I take this as a committed driver and we now have a spec to decide on, so starting the 14-day ticking.

-- KennethLavrsen - 23 Apr 2007

Accepted by 14-day rule

-- KennethLavrsen - 07 May 2007

Very logical extension!

-- PeterThoeny - 08 May 2007

See Bugs:Item4153

-- ArthurClemens - 28 May 2007