• View
• Edit
• History
• Attach
• Print
• Backlinks

SubgroupMarkup

Goal

Provide a simple way to solve certain problems that would otherwise require use of a hierarchical page naming scheme.

Solution

The subpages recipe adds one level of subgroup to PmWiki's Group.Page structure, by introducing a [[,subpage]] markup. It extends the AsSpaced function so that Page,Subpage is spaced as Page, Subpage.

Place the subpages.php file in the local/ directory.

Add the following line to local/config.php

    include_once("$FarmD/local/subpages.php");

Subpages do not nest: a reference to [[,Sibling]] on the SubpageMarkup,Child page links to SubpageMarkup,Sibling.

It adds a modified trail markup, through the (:subpage:) directive. Suppose the parent page contains a list of subpages and a subpage directive:

  (:subpage:)
  * [[,page 1]]
  * [[,page 2]]

On display, the subpage directive generates a button allowing a reader to toggle between showing and hiding the contents of the subpages as part of the parent page. If the author adds (:subpage action=print:) it adds an option of generating a print view of the page and its subpages.

Because of the way pmwiki.php is structured, this recipe doesn't work as a per group customisation. There is a work-around, discussed below.

Discussion

This recipe is designed as a simple solution to the page disambiguation problem -- when you want to give different pages in the same group the same name. There are 2 distinct cases: ambiguous parents and ambiguous children.

The following examples are to illustrate the idea of subpages. There is always more than one way to do it; subpages may not be the best. It's up to the administrator to decide the most appropriate strategy in any given case. Subpages are functionally equivalent to adding one level of subgroup to PmWiki -- the subpages of a given page form a subgroup.

Ambiguous parents

Consider the movie The Italian Job. Is this a reference to the ultra-cool '60s original or the leaden 2004 remake?

We would create 3 pages: TheItalianJob might give a plot synopsis. It would also include links to [[,1968]] and [[,2004]]. On the page TheItalianJob,1968 there might be a disparaging reference to the [[,2004]] remake.

Another example: is [[Mercury]] a reference to the god, the planet, the element or the telephone company? Set up a [[Mercury]] page and on it make links to [[,god]], [[,planet]], [[,element]], and [[,company]].

The script includes an $EnableDisambiguation parameter. If ($EnableDisambiguation = 1), a reference to [[Mercury,planet]] displays as Mercury? and links to Mercury,Planet. The context of the reference will tell the reader the intended meaning and the subpage qualifier is not needed in the link text. It just works and does the right thing.

Ambiguous children

Consider the Profiles group. People may wish to describe their [[,hobbies]], [[,work experience]] and [[,qualifications]]. We may also want a Hobbies? page that does a (hypothetical) (:pagelist ,hobbies:) to generate a list of all pages with ',hobbies' in the name (ie excluding pages that just refer to 'hobbies').

An example from the PmWiki mailing list was a group that consists of TeamA, TeamB and so on. Each team has a [[,schedule]], and other properties.

If you set $EnableDisambiguation = 2, the script displays a reference to [[TeamA,schedule]] as "schedule (TeamA)"; that is, separate links to the schedule and TeamA pages.

Subpages form a subgroup

Another way of thinking about subpage markup is that it adds one level of subgroup to PmWiki's standard Group.Page structure. Taken together, the subpages of a particular page form a subgroup within the current group. The recipe supports subgroup customisations. It extends the standard pgcust capability to apply a local page customisation (local/Group.Page.php) to a page and all its subpages.

Limitations

The script redefines the $NamePattern and $PageNameChars variables. If you want to restrict subpages to a specific group, ie put the include statement in a Group.php file, you must put the 2 pattern variables in config.php. That's because pmwiki.php uses them after it loads config.php but before it loads Group.php.

A case can be made that subpages introduce unnecessary complexity and confusion. Remembering the PmWiki philosophy to avoid gratuitous features, a prudent approach would be to use them only after you have considered the alternatives and are really sure you need them. On the other hand, if you think that you need hierarchical groups, consider whether subpages (which add subgroups) are all you really need.

Since the purpose of SubpageMarkup is to solve the page disambiguation problem, subpages do not nest. The contributor has not been able to think of a problem that nested subpages would solve, and sees several problems that nested subpages would create. In particular, the markup does not readily scale to multiple levels of hierarchy.

Notes related to problems with beta 19 and later

• page lists may show sub pages, there does not seem to be a way of omitting these from your pagelist
• pagelists may show deleted pages, a solution may be to add $SearchPatterns['normal'][] = '!,del-\d+$!'; to your config.sys to prevent deleted pages showing
• search results may also show deleted pages, solution yet to be determined or provided ^[1]
• page links, eg [[,day1|First day details]] show as ",First day details" ^[2]
• Using brackets in links does not work, [[(,)day2|Sunday]], it is interpreted as Group/,Day2
• summaries do not display, {Trips.2006-12-StewartIsland,Day1$:Summary}, perhaps because of the comma ^[3]

Release history

04 July 2006 -- version 2.1.5 handles show/hide of subpage list items that start or end a page 19 June 2006 -- version 2.1.4 adds subpage list show/hide feature

Contributor

jr