Revision [4443]

This is an old revision of TableofcontentsAction made by JavaWoman on 2005-01-11 12:21:55.

 

Table of contents Action


This is the development page for a proposed Table of contents action.
Last edited by JavaWoman:
small changes to WikiNi analysis
Tue, 11 Jan 2005 12:21 UTC
 

What

Many people wish for an easy way to build a table of contents for a page - preferably by simply including an action tag. Some of our "colleague" Wikis already have such a thing, and there has been some pressure to adopt their code (which should be somewhat easy if it's another WakkaWiki clone). A prime example of a good and user-friendly table of action can be see in Wikipedia (example), which has a nice feature of allowing the visitor to show or hide its contents with a single mouseclick (provided they have JavaScript enabled).

Why

When you look at long Wiki pages, the need for a table of contents becomes immediately apparent: when a lot of scrolling is needed to see all of the page's content, it also becomes hard to get an overview of what is on the page, and to find your way back to a section you've seen before. A table of contents block at the top of the page, linking to the page's sections using the headings as link text, fulfills both needs. It is even more helpful if such a table of contents can show the hierarchical structure of the page (as in the Wikipedia example).

Not surprisingly, a few proposals are already floating around in this site, such as:

Analysis

Before rushing to adopt one of these proposals (or something else yet again), let's see what a Table of contents action actually should do to fulfill all these needs.

To get an idea of how a table of contents may be produced, let's look in more detail at a few examples from other Wiki engines. None of the examples presented below requires the user to manually add link targets in the code; they are all automatically created in some way. The examples do differ in whether a table of contents (making use of these link targets) is created automatically, or whether the user has to "request" it by inserting an action code or some kind of tag; where a TOC is generated automatically, this may happen only under certain conditions, or may be suppressed by the user by means of a special tag (i.e., the opposite of requesting it). Another possible difference is whether link targets are produced even when no table of contents is generated.

Example 1: WikiNi

Description:
Proposal(s) only, apparently. The proposed solution has these properties:
Pros and cons:
pro:
(Can't really find any)
con:

Example 2: Wacko Wiki

Description:
Pros and cons:
pro:
con:

Example 3: Wikipedia

Description:
Pros and cons:
pro:
con:

Example 4: DokuWiki

Description:
Pros and cons:
pro:
con:

Example 5: CoMaWiki

Example page and an example of a variant (The same code is used in UniWakka - see notes on TableOfContentsPseudoAction.)
Description:
Pros and cons:
pro:
con:

Specifications

Now let's see what we need, and try derive some specifications based on our analysis. We'll have a few essentials, and a few would-be-nice items.

One unescapable essential is that a table of contents needs link targets - and these must come into existence somehow. Headings, forming the basic structural element of (HTML) pages, are the natural candidates for such link targets (a table of contents can then make use of the text of these headings as link descriptions). Other potential targets, useful in documentary type of content, are (data) tables and images (graphs, screen shots...).


Essentials


What else?


How



CategoryDevelopment
There are 6 comments on this page. [Show comments]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki