Changes [Sep 25, 2007]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:
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
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.
What needs to be done:
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
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!