• View
• Edit
• History
• Attach
• Print

PageTableOfContents

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
   • [[tocauto title text]] replaces the default table of contents heading
2. [[toc format=... title text]] generates a table of contents for designated headings, with no nesting
   • [[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.

See Also

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

Comments & Bugs

Currently prefers "classic" free links (Group.{{free link}}; but should handle links of the form {{Group/free link}} correctly. Regular wiki words and free links in headings are handled correctly in the page's table of contents. The scripts will break if PmWiki adds support for group name.free links?.

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.

An administrator can change the markup so that [[toc]] produces an automatic table of contents and [[tocmanual]] produces the manual version.

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.

-- Jeroen Coumans

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.

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.

  <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

Contributors

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

Copyright

If necessary, put your copyright information for the script here. pmwiki-2.3.38 -- Last modified by {{Restore}}?

from IP: 85.171.160.186 ip should be disabled by default for security reasons