Wiki source for TableofcontentsAction


Show raw source

=====Table of contents Action=====

>>==See also:==
Documentation: TableofcontentsActionInfo.
Development: AdvancedFormatter>>This is the development page for a proposed Table of contents action.{{lastedit show="2"}}::c::
====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//
~1)A clear page //structure// with sections labeled with headings
~1)A means of quickly //going to a section// of interest
~1)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 [[http://en.wikipedia.org/wiki/Wiki_software | 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:
~-AndreaRossato's TableOfContentsPseudoAction (note: code removed! license issue; but see CoMaWiki example below...)
~-[[DotMG]]'s AnchorAction
~-[[FatherNitwit]]'s SimpleTableOfContents
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""===
~[[http://www.wikini.net/wakka.php?wiki=ActionSommaire | Development page]]
==Description:==
Proposal(s) only, apparently. The proposed solution has these properties:
~-Link targets are formed by an anchor with the heading text as its content and a **name** (note there's a comment about **name** being deprecated in XHTML)
~-The anchor **name** is a just a number, derived by consecutively numbering all headings in a page (there is also a proposal of using the heading texts instead)
~-A Table of contents is produced by including an action in the page (while the targets are produced by the Formatter)
~-Since the table of contents is produced by an action, it appears in the page at the location where the action is included
~-Table of contents consists of a flat list containing links with as link description the actual headings of the page (i.e., complete hn elements)
==Pros and cons:==
pro:
~(Can't really find any)
con:
~-Anchor names are deprecated (but just numbers cannot be used as IDs!)
~-Using actual headings in the table of contents makes for a confusing (and not very accessible) //page// structure by effectively creating the same structure twice, once without content and once with; it seems headings in the TOC are used mostly for appearance, disregarding their role as major structural elements
~-Using consecutive numbering makes the link targets very susceptable to changes in a page's structure and effectively prevents reliable linking //into// a page from another (or from an external site)

===Example 2: Wacko Wiki===
~[[WackoWiki:WackoDocumentation/WackoFormatting?v=na | Example page]] | [[http://wackowiki.com/WackoDocumentation/WackoFormatting?v=na#h7705-11 | reference]]
==Description:==
~-Link targets are formed by a an (empty) anchor with a **name** in front of of a heading
~-Anchor **name**s are derived by consecutively numbering all headings in a page, preceded by a letter and (apparently) the page ID
~-A Table of contents is produced by including an action in the page
~-Since the table of contents is produced by an action, it appears in the page at the location where the action is included
~-Table of contents consists of a flat list (actually a series of divs)
~-The table of contents (itself in a div) is enclosed in a fieldset which provides a legend "on" the box
==Pros and cons:==
pro:
~-Using a fieldset with legend is a nice idea to mark up the TOC
con:
~-Anchor names are deprecated
~-Using consecutive numbering makes the link targets very susceptable to changes in a page's structure and effectively prevents reliable linking //into// a page from another page (or from an external site)
unclear:
~-While the fieldset markup creates a nice presentation (and syntactically is no problem), its status with respect to semantics and accessibility is not clear: the fieldset element is intended (as its name suggests) to group form controls - not a menu of links.

===Example 3: Wikipedia===
~[[Wikipedia:Wiki_software | Example page]] | [[http://en.wikipedia.org/wiki/Wikipedia:Wiki_markup#Placement_of_the_Table_of_Contents_.28TOC.29 | reference]]
==Description:==
~-Link targets are formed by a paragraph containing an (empty) anchor with both **name** and **id** in front of a heading
~-Anchor **name** //and// **id** (identical, as they must be) derived from the text of the heading
~-Having at least four headers on a page triggers the TOC to appear in front of the first header (or after introductory sections).
~-It can be put somewhere else with a special tag, or suppressed with a special tag
~-Headings can be kept out of the toc by using HTML markup instead if Wiki markup
~-When a TOC is suppressed, you can make one manually (which implies targets are generated independently)
~-Table of contents consists of a single-cell layout table where the hierarchical display is accomplished by nesting divs; items are dynamically and hierarchically numbered; link descriptions are formed by the texts of the actual headings
~-Initial state of the TOC is fully shown, this state can be toggled to (and from) "hidden" by means of a JavaScript function
==Pros and cons:==
pro:
~-Anchor names are deprecated but ids are included as well - this is apparently done to ensure compatibility with a wide range of browsers
~-The ability to hide the TOC (provided JavaScript is enabled) is very nice
con:
~-Anchor names are deprecated

===Example 4: ""DokuWiki""===
~[[http://wiki.splitbrain.org/wiki:syntax | Example page]]
==Description:==
~-Link targets are formed by a an (empty) anchor with a **name** in front of of a heading
~-Anchor **name** is derived from the text of the heading
~-If there are more than 3 headings in a page, a table of contents is [[http://wiki.splitbrain.org/wiki:syntax#sectioning | automatically generated]]; this can be //suppressed// by ading a special code in a page
~-It appears as a side bar at the top of the page (it's a div at the start of the page content)
~-Table of contents consists of a hierarchical (unordered) list; link descriptions are formed by the texts of the actual headings

==Pros and cons:==
pro:
con:
~-Anchor names are deprecated

===Example 5: ""CoMaWiki""===
~[[http://comawiki.org/CoMa.php?CoMa=TocPlugin | Example page]] and an [[http://comawiki.org/CoMa.php?CoMa=TocNrPlugin | example of a variant]] (The same code is used in ""UniWakka"" - see notes on TableOfContentsPseudoAction.)
==Description:==
~-Link targets are formed by an (empty) anchor with an **name** in front of a heading
~-Anchor **name**s are derived by consecutively numbering all headings in a page, preceded by a fixed string
~-The table of contents is generated by inclusion of an action in the page
~-Since the table of contents is produced by an action, it appears in the page at the location where the action is included; regardless, **all** headings are included, even the ones appearing before the location of the action code
~-Both table of contents links //and// headings may be hierarchically numbered by using a variant of the action
~-While it visually seems like a hierarchical list, it is actually a flat list, with styled indents to create the appearance of a hierarchy
~-The table of contents (itself in a div) is enclosed in a fieldset which provides a legend "on" the box
==Pros and cons:==
pro:
~-Using a fieldset with legend is a nice idea to mark up the TOC
con:
~-Anchor names are deprecated
~-Using consecutive numbering makes the link targets very susceptable to changes in a page's structure and effectively prevents reliable linking //into// a page from another page (or from an external site)
~-TOC is only visually a hierarchical but not structurally - this presents an accessibility problem
~-TOC numbering (optional) is nice but no option to number only the link texts but not the headings themselves; also the numbers don't appear in Preview mode when editing - only when the page is stored
unclear:
~-While the fieldset markup creates a nice presentation (and syntactically is no problem), its status with respect to semantics and accessibility is not clear: the fieldset element is intended (as its name suggests) to group form controls - not a menu of links.

====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
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki