Tclers Wiki Forum: Categories

The category system is one of the hidden gems of the Tclers Wiki.

Categories are simple and effective - a page just contains one or more links of the form "[Category name]", thus creating a backlink to the page from each category page, allowing all pages of a particular category to be accessed from the category's page.

This page is for discussion and documentation of the developers that use this category information and present it in a more sophisticated way - in particular, the Table of Contents.

Some of the activities involved in leveraging categories and the table of contents include:

Wikit support for the table of contents
Specifying the Table of Contents
Guidelines for categorisation

Wikit support for the table of contents

I added 2 tables of contents. One based on the headers used in the page (see Markup). It's the page-TOC. The other one is based on the contents of page 8. It's the wiki-TOC. Both can be seen here. The TOC's are based on the JavaScript dtree.js (see http://www.destroydrop.com/javascripts/tree). The TOC's are generated by calling accessing the URLs _pagetoc/N and _toc on the WubWiki server. Each call returns a JavaScript which must be evaluated in the browser. Each TOC has its own div region in a CSS layout.

Displaying the TOC's is optional. Based on the value found in the witoc cookie, the TOC's are displayed or not when loading a Wiki page. Once a page is displayed, the displaying of the TOC's can be toggled. This toggling will also change the value of the cookie to remember the TOC setting when loading another page. Displaying the TOC on load and toggling is implemented in JavaScript, based on the transclusion.js script which can be found at http://www.dynamicdrive.com .

The page-TOC can have 3 levels, derived from the headers used in the wiki page. The wiki-TOC is generated based on the contents of page 8. Currently it can have 2 levels. A top entry is specified as follows:

+++
A wiki-TOC top entry
+++

A top entry is placed on its own line, surrounded by the +++ lines. A top entry must start on the left-most charater.

Entries below a top entry are specified using the option/value syntax following the top-entry. The following example creates a top wiki-TOC entry Categories A with sub-entries for different category pages starting with an a:

+++
Categories A
+++
	Acronym		                   [Category Acronym]
	Actions		                   [Category Actions]
	Advanced Programming Fundamentals  [Category Advanced Programming Fundamentals]
	Advocacy		           [Category Advocacy]
	AI		                   [Category AI]
	Algorithm		           [Category Algorithm]
	Animation		           [Category Animation]
	Answered Questions		   [Category Answered Questions]
	Application		           [Category Application]
	Argument Processing		   [Category Argument Processing]
+++

The top entries and the option part of the sub-entries are show in the wiki-TOC. When clicking on the sub-entries, the page specified in the value part will be opened. Therefor, the value part must be written as a reference to an existing page.

It is also possible to include back references in the wiki-TOC. When specifying a top entry as a page ending with a * and no sub-entries are specified, the back references of the specified page will be added as sub-entries. The following example shows a wiki-TOC definition where the page with name test with backrefs in toc* (page name includes the *) is specified as top-entry without sub-entries. This top-entry is followed by another top entry.

+++
test with backrefs in toc*
+++
Categories
+++
	(L)GPL Licensed		[Category (L)GPL Licensed]
	3D Graphics		[Category 3D Graphics]
	?		        [Category ?]
	??		        [Category ??]
+++

This page shows a page with a name ending with a *. Note the back references at the end following Pages in this category. This same page was added to the wiki-TOC (see above). The corresponding menu can be seen in the same image.

jdc Made an extension to support categories in the TOC. When top entry in the TOC specification starts with 'Category ', it is inserted under a main TOC entry with name Categories without the 'Category ' prefix. The following TOC specification:

+++
Community
+++
	www.tcl.tk		[Long live tcl.tk]
	wiki.tcl.tk		[The Tcler's Wiki]
	comp.lang.tcl		[The comp.lang.tcl newsgroup]
	Tcler's chat		[Tcl Chatroom]
	Guru's
+++
Category AI
+++
	Place holder		[Category Place holder]
+++
Category Acronym
+++
	Place holder		[Category Place holder]
+++

will generate the this TOC:

Community
    www.tcl.tk
    wiki.tcl.tk
    comp.lang.tcl
    Tcler's chat
    Guru's
Categories
    AI
        Place holder
    Acronym
        Place holder

Specifying the Table of Contents

The table of contents will be specified on this forum - probably in a separate project (or two - one for production, one for development).

The reasons for this is that ProjectForum already has a number of features (including authentication, security and page versioning) that make possible the secure collaborative maintenance of such information, and to add these to Wikit for the management of just a few pages isn't worth the effort and duplication.

jdc 24-sep-2007 I implemented this differently. A file containing the TOC needs to be put on the webserver. A direct access method can be used to reload the TOC.

As currently implemented, the TOC has 2 parts: the wiki-TOC and the page-TOC. The wiki-TOC is based on the contents of page 8. The page-TOC is based on the use of headers in the page itself. Both TOCs can be combined to make the wiki more accessible. A general structure in the wiki-TOC, details in the page-TOC.

The TOCs can be used in combination with the page names ending with * to generate overview pages for a certain topic.

The TOCs are displayed left of the page. In the same area, other items may be included (e.g. the menu now displayed at the end of the page). This is an example with the menu added to the wiki-TOC.

The TOC is not meant to replace the current category system. It's meant to make navigation easier for first-time wiki visitors.

Some questions:

Is a 2-TOC setup as now implemented useful and sufficient? Is a wiki-TOC with 2 levels sufficient?
What would need to be included in the wiki-TOC? To test the current implementation, I added a main entry for each letter and a sub-entry for each know category page to the corresponding main.
Is adding the menu to the TOC-area useful? It can be a lot of scrolling to get to the menu when it's placed at the end of the page. Another option would be to at the menu below the title.
Is a tree-like menu the best style to use? Many web-pages have a different style menu.

jdc The first TOC I posted was extended by stevel. Take a look at the Table of Contents page to see the draft.

What needs to be done:

Check the list of main categories and add/remove/modify items
Add sub categories to each main category
Find corresponding wiki pages for each sub category
Find/write wiki pages for the non-category items in the TOC

Posted at May 15/2007 12:14AM by stevel:
Jos, did you deliberately leave out categories from your first draft? ;-)

Posted at May 15/2007 12:16AM by stevel:
I'm happy with 2 levels for the wiki-TOC .. if we limit each to a page, then you're between the extremes of too few and too many categories

Posted at May 15/2007 12:18AM by stevel:
My suggestion would be to have the above TOC entries followed by categories.

If the user is displaying the wiki home page then have them alll collapsed otherwise if displaying an ordinary page have the Contents category expanded and the current categories highlighted as per our previous discussion

This will have the twofold advantage of providing a gentle introduction for people coming to wiki.tcl.tk, plus showing the context of a particular page

jdc 20-sep-2007

Now Wub+Wikitcl are stable, I want to start the TOC work again. I started from 399 and Wikitcl 429 and added the TOC code to it. I used the TOC at the Table of Contents page as a start. I've put the modified Wikitcl code here: http://jos.decoster.googlepages.com/wikitcl%2Btoc . This page also has links to some screenshots. Feedback welcome!