# Categories

authors (intermediate)

## Purpose of categories

Categories? (also known as "tags") are a way to organize and find related pages. Categories are implemented by default in PmWiki, and in most wikis they don't require any special code or markup, they're just a useful convention. The idea is that every page that falls into a particular subject area should have a link to a shared page containing links to other pages on that subject. These pages are created in the Category group, and thus these subject areas are called "categories".

## Using categories

Getting categories to work requires a single step: adding links to each category. A category named Subject is created by adding a link to Category.Subject on any page. When you add the link to a page, the page can be described as being in the category "Subject".

There is a special markup for creating these links which makes categories work more smoothly: [[!Subject]] will create a link to Category.Subject. So [[!Subject]] is a kind of shortcut to the page Subject in the category group.

A Category.GroupFooter file is included in the PmWiki release that contains the line (:pagelist link={*$FullName} list=normal:) so that whenever a category page is displayed, it will show a list of links to pages that reference that page in the category group. Like any other page in wikilib.d you can modify this page and it will not get overwritten by another release. It is worth noting that rather than using Category.GroupFooter, the pagelist directive can be added to Category.GroupHeader to similar effect; it just depends on whether you'd prefer to have the list of pages appear before or after any text that you add to the individual category pages (which can be edited just like normal pages). Because we use the normal PageList link= markup, you can use it not only in the category group. If you want to show all pages belonging to the category Subject you can use on any wiki page (:pagelist link=Category.Subject list=normal:). Similarly, there's no requirement that a "category page" has to be in the Category group -- any page can define a "category" of pages that link to it. An administrator can override the default category group name of "Category" by setting the $CategoryGroup variable in config.php to another group name. (Normally a change such as this should be done during initial setup on a new wiki; changing this on a wiki with existing content can cause problems with pagelists unless each page with a category is re-saved.)

SDV($CategoryGroup,'Category'); Markup('[[!','<links','/$$$!([^\|$] ?)$$\]/', "<span class='category'>[[$CategoryGroup/$1]]</span>");  ## Coming up with good category schemes The hard part about using categories is choosing a good vocabulary. Site content managers may wish to follow the Guidelines for the establishment and development of monolingual thesauri (ISO 2788-1986) and the Guidelines for the establishment and development of multilingual thesauri (ISO 5964-1985). Questions to think about include: • whether a scheme already exists and can be reused • number of levels in a multilevel scheme (not too shallow, not too deep -- e.g. 3) • number of categories per page (not too many, not too few -- e.g. 3) • consistent use of singular ([[Mercury]] is a [[!planet]]) or plural ([[Mercury]] is in the [[!planets]] category) • disambiguation and use of phrases ([[!musical instruments]] and [[!medical instruments]]) or Cookbook:Subgroup Markup ([[!Instruments*Musical]] and [[!Instruments*Medical]]) Or you can just let people use whatever category terms they find meaningful. A vocabulary (or "folksonomy") will emerge over time. ## Showing a list of categories To show a list of categories we can use a pagelist for the pages in the category group. For instance the following will list pages in the Category group, put it on page Category.Category? for convenience, or on any other page: (:pagelist group=Category list=normal fmt=#title:) But there is a problem: Just adding a category markup to a page will not create a corresponding category page, even though following the link will show the page with a list of pages linking to it! To have category pages automatically created in group 'Category' add the following to config.php: $AutoCreate['/^Category\./'] = array('ctime' => $Now, 'text' => 'List of pages linking to {$Title}'); (note the quotes)

Change 'Category' to the name of your category group. You can also add more definitions for more category groups, useful if you use a recipe like Cookbook:Tagger which allows multiple category groups.

Note that categorizing a page (using the [[!category markup]]) cannot be distinguished from referring or linking to a category (using the normal [[link markup]]), i.e. pages referring to a category become part of that category. This is the subject of a long outstanding feature request that seems to be hard to implement without breaking other functionality. You can link to a category without categorizing the page by using an external link, such as: [[{Category.MyCategory\$PageUrl}|MyCategory]]. Since the link is external, all pages (not just the category page) will ignore it when listing backlinks.