A new syntax would be useful to exclude heading from being listed in the TOC. What would be good? ---+ is the usual heading, ---# is reserved for numbered headings. How about ---! for a heading excluded from TOC?

-- PeterThoeny - 06 Apr 2002

Sounds good to me!

-- RandyKramer - 06 Apr 2002

Is there any need for excluding headings apart from creating a special Contents heading that doesn't appear in the TOC? In which case, why not extend the TOC syntax to be something like %TOC{top="Contents"}?

-- RichardDonkin - 07 Apr 2002

Sometimes I want to have heading-like text, a paragraph or two of normal text (intro), and TOC after intro. RichardDonkin's proposal will not allow that, but PeterThoeny's will. I vote for Peter's way. We will have ---!++ as h2 header not listed at TOC, right?

Since we opened TOC, I have another "feature proposal": I created ---++ headers, which contained also link to the top (by creating variable =PAGETOP = Top) and placing it right into header. It looked OK in expanded text, but it was pain in expanded TOC: link with Top was on every line.

So I was thinking, can we have some string (like !!! or so), which will put left-side text to TOC, but not rest of the line? So I can write ---++Heading !!! with something, and TOC will get only ---++Heading, but actual heading will be ---++Heading with something.

Did I wrote it clear enough? You can see example of TOC with links from headers at http://130.132.79.29/twiki/bin/view/Sandbox/TestTOC. I did not liked result of TOC, so I created nicer TOC manually - it is commented out.

-- PeterMasiar - 08 Apr 2002

I also prefer Peter's suggestion. I'm not sure if he meant headings not in the TOC would be like ---!, ---!!, ---!!!, ... or ---!+, ---!++, ---!+++, ... -- either is acceptable to me but the first seems a little simpler. (For a little while I thought I'd also want to keep selected numbered headings out of the TOC (like ---!#, ---!##, ..., but I think I decided I would not likely use such a feature -- I might limit the number of levels in the TOC, but don't think I'd exclude arbitrary headings at arbitrary levels.)

I also like the other feature that PeterMasiar suggests, something to exclude part of a heading from the TOC, and !!! seems as good a markup as anything else.

-- RandyKramer - 08 Apr 2002

Is it fair to say that the only place where you need to exclude headings from the TOC is just before the TOC as Richard said? Example:

    ---+ Brewing Coffee
    ---++ Table of Contents
    %TOC%
    ---++ Types of machines
    ---++ Water temperature
    ---++ etc...

Here you would expect a TOC like:

       * Types of machines
       * Water temperature
       * etc...

This could be achieved with a new switch in TOC, for example %TOC{top="Contents"}% or %TOC{exclude="above"}%. The exclude switch could list names of headings to exclude as well.

But then, which is more intuitive: To specify what to exclude in the TOC or in the headings themselves?

-- PeterThoeny - 09 Apr 2002

Until now I needed only to exclude headers abowe TOC, but if more flexible exclusion is not too much hassle...

Which is easier to implement? Or, can we merge both ideas, and use !!! as heading exclusion sign, and excluded headers will be like ---!!!++ header, meaning: exclude text after !!!, and if result is empty, do not display it in TOC? String !!! might be a TOC parameter, with !!! as default. Thinking again probably better notation to exclude whole h2 header will be ---++!!! header.

-- PeterMasiar - 10 Apr 2002

Any solution should also take into account the behaviour(s) reported in TocWithParameterIgnoresStopinclude. It would be nice if a few problems could be solved at the same time.

-- JohnAltstadt - 10 Apr 2002

I kind of like the ---++!!! header syntax. Possibly make it shorter like ---++! header? To support PeterMasiar's idea of cutting arbitrary content we would write ---++ header! excluded part. So the algorithm is: For the TOC cut ! and any of the following chars if there are any, but leave ! if it is at the end of the header (to support headings with exclamation points).

-- PeterThoeny - 11 Apr 2002

This is now implemented and in TWikiAlphaRelease. There are two ways of specifying excluded text for TOC: Two or more exclamation points (!!) and %NOTOC% variable. Examples:

• ---+!! Heading L1 (not shown in TOC)
• ---+ !! Heading L1 (same)
• ---+ %NOTOC% Heading L1 (same)
• ---+ Heading L1 !! this part is not shown in TOC
• ---++ Heading L2 %NOTOC% this part is not shown in TOC
• ---++ Heading %BACKTOTOP%
• (the last example assumes that there is a BACKTOTOP prefs variable that defines a linked "back to top" icon)

Requiring two exclamation points instead of one has less unwanted side-effects. Both, !! and %NOTOC% work, but only one should get documented. Which one is more intuitive?

-- PeterThoeny - 26 Apr 2002

Well, %NOTOC% might be more intuitive in some sense, but !! is more wiki like, IMHO, i.e., quicker and easier to type. I vote for !!.

Aside: If people see usefulness to both, shouldn't they both be documented (at some level) -- my newly developed fear of undocumented features is that they will disappear in a future release (without warning or due consideration). Is the intent of not documenting both of them to specifically allow for the future removal of one? (If so, let's remove it before it goes into a beta or official release.)

One further point -- isn't having both of these a little bit like allowing wiki "markup" and HTML tags? Nothing wrong with that in the TWiki philosophy, is there?

(I wouldn't care if the %NOTOC% went away, because I don't expect to use it. I would be disappointed if the !! went away, because that is what I expect to use consistently.)

BTW, thanks for implementing this!

-- RandyKramer - 26 Apr 2002

So lets document the !! rule and leave %NOTOC% as an undocumented feature. The exact regular expression is (\!\!+|%NOTOC%), so two or more exclamation points can be used.

-- PeterThoeny - 24 May 2002

If it isn't going to be documented, I vote get rid of NOTOC.

-- MartinCleaver - 25 May 2002

Somebody has documented the !! rule. Updating BeijingRelease...

-- MartinCleaver - 21 Dec 2002

I'm not clear, is there more documentation to do on this item or not?

-- GrantBow - 14 Jan 2003

It is documented in TWikiVariables , scroll down to %TOC{"SomeTopic" ...}%

-- MattWilkie - 14 Jan 2003

It should probably be noted in the entry for %TOC% that it is equivalent to:

%TOC{topic="_current topic_" web="_current web_" depth="3"}%

Not sure about the default depth though.

-- JohnRouillard - 14 Jan 2003