PageTableOfContents

Note: The recipes here are for PmWiki versions 0.6 and 1.0 only. For PmWiki 2.0 recipes, see Cookbook.

Goal

Make long pages with several headings and FAQ pages easier to navigate with a list of links to anchors on the page. Give authors the option to generate a table of contents automatically or for selected paragraphs only.

Solution

New version: Attach:toc-0.2.3.tar.gz

This adds a number of capabilities required to make it "just work":

• generate anchors for designated headings with the !!!# and Q:# markups
• make anchors visible with the !!!## and [[##anchorname]] markups
• correctly deal with wiki markup in link text, which as a by-product means [[WikiWord text '''with''' @@markup@@ in it]] works
• sensibly deal with wiki words, free links and double brackets in link text
• render [[#anchor#]] as a link to [[#anchor]] and display the text following the anchor as the link text
• allow truncation of link text with the invisible stop character . (backtick-period)

To install:

1. move toc-scripts/ into local/
2. move css/toc.css into pub/css/
3. add the line include_once("local/toc-scripts/toc-config.php"); to your local/config.php file
4. you can test it by editing PmWiki.TextFormattingRules and adding [[tocauto]] to the start of the page, then pressing Preview

This recipe was tested and works correctly with a clean install of PmWiki 0.6.15 running on Mac OS X v10.3.

ChadLupkes: 'Alert!' The freesupport.php file is also included with the Calendar script. You can't load both at once. Here is the error I got:

Fatal error: Cannot redeclare wikify() (previously declared in /home/takeback/public_html/pmwiki-1.0.5/local/wikilog/freesupport.php:25) in /home/takeback/public_html/pmwiki-1.0.5/local/toc-scripts/freesupport.php on line 25

Got the same problem with extended-journal.php

The solution I used was to comment out those lines in the toc-config.php file.

Discussion

There are several variants:

1. [[tocauto anchors=visible title text]] generates a table of contents automatically, up to 2 levels of nesting
• [[tocauto]] no anchors, default title text
• [[tocauto anchors=visible]] shows the anchors, with a tool tip to give the ID
• [[toc]] no special formatting, default title text
• [[toc format=r]] toc floats right as an ordered list
• [[toc format=l*]] toc floats left as a bullet list
• [[toc format=:]] toc floats right as a definition list

The syntax is format=< r | l >< # | * | : > for right or left alignment and numbered, bulleted or definition list style. The default (format=) is a right-aligned numbered list.

It supports !, Q: and T: (manual toc only) start of line markup.

Includes and extends all the features provided in FootNotes and IncludePara. If you are using either of these scripts, you may want to upgrade them to the versions posted here.

Full documentation and examples are at: http://www.lyx.org/~chr/demo/pmwiki.php?pagename=TOC.TOC

History

22-Mar-2004 released following extensive testing at the above location

6-Apr-2004 enhanced to support {{Group/free links}} and several minor fixes

25-Apr-2004 enhanced to make visible anchors links by default (configurable); simpler installation

27-May-2004 fixes a problem encountered when using the extended include markup

The script has to decide what to do with markup in the text of title paragraphs when it uses this as link text in the corresponding toc entry. As far as possible, it tries to replicate the markup behaviour. It treats links as plain text. New markup may introduce unexpected or undesirable behaviour.

I usually markup my pages with 3 or more levels of headers (h1 for title, h2 for author, h3 for chapter title and h4 for paragraph title). Will this script support TOC-creation for such a setup in the future? At the moment, I only see my h1 and h2, which is rather useless.

Assuming that a page has only one title and author heading, put [[tocauto]] after your author line. The script will ignore any headings above it on the page, so you will see a toc that picks up the h3 and h4. Try this option first.

If that's not suitable, there are other things we can try. jr

The smartquote feature has a bug. While conversion, it does not consider the original backslashes in HTML tag attributes and they will be lost. E.g. If you have something like <a href="some/page?content=\">, after the smartquote processing, the backslash will disappear. A direct problem caused by this bug is the mimeTeX plugin, where backslashes are almost always used in URLs.

I am unable to reproduce this problem. I typed the address http://some/page?content=\ into a PmWiki edit window and it rendered correctly, including the \. The smartquote feature gets invoked after PmWiki has translated link markup and should pass over text inside < ... >. Can you provide more information and a link to an example? jr
I gave a wrong example. This only happens with BOTH smartquote and MimeTeX present. When they coexist, the MimeTeX code loses backslashes. E.g. http://pages.cpsc.ucalgary.ca/~gaoj/pmwiki109/pmwiki.php/Main/HomePage has two mimetex images: The first one gets "\"'s lost, and the second one uses double "\"'s and results in single "\".
Hmmm. I haven't used the MimeTeX recipe. The MimeTeX examples produce links to images in a cache like this:
  <img class='mimetex' src='/pmwiki/pub/cache/a132375055278e1c7b78b4a132c45ff3.gif'
alt='x^2 + y^2 = z^2' />

The MimeTeX code uses the pmwiki Keep function so smartquotes should neve see what it produces inside the img tag. Whereas your example page produces links like this:
  <img src="/~gaoj/mimeteximg.php?mathcode=5\begin{eqnarray}a%26amp;=%26amp;b\end{eqnarray}" align=absmiddle>  You appear not to be caching the images. Try changing the line:  return "<img src=\"MimetexCmd?tex\" align=absmiddle>";  to use the Keep function, like so:  return Keep("<img src=\"MimetexCmd?\$tex\" align=absmiddle>");
`
That may fix the problem. jr
Yes. Your suggestion is great. It solves the problem. Thank you very much!

I'd like a tag for limiting the toc... I've got nested tocs included from several files and right now each toc is including everything below. What I need is a way of limiting how far each toc should span. Something like this:

toc1
|
| toc2
| |
| toc2ends
|
| toc3
| |
| toc3ends
|
end of file
So toc1 indexes everything, toc2 indexes 'til the first end tag etc... All that is needed is a way to tell the toc to stop... Would this be possible? --rapid

One option would be to have a manual toc for toc 1 (a 1 level list) and auto tocs for toc2 and toc 3 (2 level lists). Then we could add a feature that stops the toc auto code from generating entries when it finds another toc auto directive. But I'll have to think about it. Probably, this would be part of the pmwiki 2 version. --jr
That sounds great... Any chance of this function being implemented before pmwiki 2 is released?

Contributors

• John Rankin designed and wrote the code
• Christian Ridderström tested, advised, challenged, documented and supported