[Pmwiki-users] Automatic page table of contents with [[toc]]

John Rankin john.rankin
Sun Nov 30 15:35:28 CST 2003

Christian, I'll send you some files in the next day or so.

This has moved on a little in the last week:

- [[toc]] does a regular numbered contents list in the main body

- [[toc#]] [[toc*]] and [[toc:]] do small tocs, floated right

- works with ! Q: and T: markup

- doesn't do indented tocs, unlike the MoinMoin example below,
but yes, it probably should...

- checks for manual anchors first, then looks for # automatic ones

- doesn't do automatic contents generation from all ! markup

Maybe the markup should be

[[TableOfContents]] for the full inline version and

[[toc]] for a mini version??

John Rankin

On Monday, 1 December 2003 3:44 AM, Christian Ridderstr?m <chr at home.se> wrote:
On 24 Nov 2003, John Rankin wrote:

> Are there any volunteers who want to take this further??

I'm definitely interested in doing that.

> vanilla flavour
> ===============
> [[toc]], [[toc#]] or [[toc*]]
> produces a numbered or bulleted list of references to the 
> paragraph text following any ![[#anchors]] or :[[#anchors]]

I like this approach, but the keyword could be longer... it won't be used 
more than once on a page I suspect. How about something like:
or	[[toc-manual]]
Should the markup have to be first on a line?

> hokey-pokey flavour
> ===================
> It looks for markup like
> !!#A heading
> Q:#A question
> and turns the # into a [[#tocnn]] anchor
> [[toc]] then searches for !# or :#

I used MoinMoin before switching to PmWiki, and for the FAQ-pages it was 
very convenient with an automatically generated TOC, like on this page:


The anchors look like 'line5', meaning that the header was on the 5th line
of the source-file. This was a very convenient way of automatically
getting TOCs, but a drawback with this solution is that external links
to an anchor are easily broken. From that point of view, the 'vanilla 
flavour' is better...
On the other hand, even with anchors that you chose manually, you have no
guarantee that someone won't go and change the anchor.

A better keyword here might be, [[toc-auto]], so that both the 'vanilla' 
and the 'hokey-pokey' variants can be used.

> comment
> =======
> We thought of looking for !s and automatically inserting 
> anchors and toc entries, perhaps based on whatever ! comes 
> first. For example, if the first occurrence of ! markup is 
> !!, make a toc of any other !! occurrences, but not ! or !!!.
In my experience, you want the toc to contain all headers that appear 
after it..  if you really want something like this, how about using a 
markup like this: [[toc-auto:234]] where 234 indicates that levels 2, 3, 
and 4 should be included in the toc?

> The problem I see with this is what if an author inserts anchor
> markup manually. 
> Any thoughts on how a toc feature should work?

I'm afraid that in order to get something that's robust with respect to 
external links pointing to anchors within a page, you have to use 
manually inserted anchors. 

> I am happy to release this to the cookbook, but would like some
> volunteers to test it.

I'd like to try your code... I have quite a few pages that would really 
benefit from a toc. And my site has a lot of cookbook-extensions installed 
already (such as IncludePara), so I shouldn't have to add too much.
See http://wiki.lyx.org/pmwiki.php/Site/LocalConfiguration for details on 
what configuration I'm using.

> So I have to pull together a collection of stuff that works
> with a standard pmwiki distribution.

A collection is nice, but since I'll probably have to do some fiddling 
anyway, you could just as well send me the files separately. Later, we'll 
know exactly what files were needed.



Dr. Christian Ridderstr?m, +46-8-768 39 44       http://www.md.kth.se/~chr

Pmwiki-users mailing list
Pmwiki-users at pmichaud.com

More information about the pmwiki-users mailing list