Table of contents Action


This is the development page for a proposed Table of contents action.
Last edited by BrianKoontz:
Replaces old-style internal links with new pipe-split links.
Fri, 20 May 2016 07:38 UTC
 

Navigating a page

A long Wiki page can be hard to navigate. For the reader to navigate a page easily, a number of things are needed:
  1. A quick way to determine what a page is about
  2. A clear page structure with sections labeled with headings
  3. A means of quickly going to a section of interest
  4. A way of finding your way back to a section you've seen before

Some of this simply depends on how the page is written: the writer should keep the reader in mind who sees the page for the first time! A good page title, supplemented with a short introductory text helps with point 1. A clear hierarchical page structure (created by sectioning and preceding the sections with headlines) will make the page easily scannable when scrolling through it - that takes care of point 2.

But even on a page that is clearly labeled and sectioned, just getting an overview by scrolling and scanning can be hard work, and the longer the page is, the harder it becomes to find your way back to a particular section you'd noticed or just want to read again.

Navigation help

While our first two points, showing what a page is about and giving the page a clear stucture, obviously depend on writing, navigating a page can be greatly helped when it has an in-page Table of contents (TOC). In general, a TOC appears near the top of the page and contains a list of section headings that serve as links to those sections. It is even more helpful if such a table of contents can show the hierarchical structure of the page and in that way gives a clear overview without even needing to scroll through it.

In order to accomplish this, some of our "colleague" Wiki engines provide a way to (semi-)automatically create a table of contents. In some of them, this happens completely automatically, in others the page author must include a code or tag in the page to trigger this process. A prime example of a good and user-friendly table of contents can be seen in Wikipedia (example); it has a nice feature of allowing the visitor to show or hide its contents with a single mouseclick (provided they have JavaScript enabled).

WikkaWiki does not have such a feature. Apart from not being able to construct a TOC automatically, even doing it manually is not (yet) possible since that requires a method of section linking which we don't have either: you need link targets, as well as a linking syntax to allow this.

The need to be able to construct a TOC in WikkaWiki clearly exists though, since a few proposals for WikkaWiki are already floating around in this site, such as: Also there has been some pressure to adopt the code from another engine (which should be somewhat easy if it's another WakkaWiki clone).

Analysis

Before rushing to adopt one of these proposals (or something else yet again), let's see what a Table of contents action actually can (or should) provide to serve as a good page navigation tool. To get an idea of how a table of contents may be produced, and how they work, let's look in some 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 (which would enable section linking within a page and from other pages, whether or not there is a TOC).

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: unclear:

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: unclear:

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...); code blocks are yet another candidate for targets.


Essentials


What else?


How



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