• 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 Subgroup 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.

• Latest version: subpages-55.phpΔ, compatible with php 5.5 and above, including php 7
• Earlier version: subpages.phpΔ

Configuration

Place the subpages.php file in the cookbook/ directory, or place subpages-55.php there and rename it.

Add the following line to local/config.php

Two configuration variables are defined:

• $EnableDisambiguation = 2; default 2 - see explanation below
• $EnableSubpageHeader = 1; default 1 - set to zero to disable creation of "Subpage of" message in group header

Usage

Put [[,Child]] on the current page to create a reference to the page called SubpageMarkup,Child.
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.

It adds on subpages the page variables

• {$SubpageTitle containing the spaced subpage name, excluding the page page name, beginning with the comma, e.g. , Child
• {$SubpageParent containing the spaced subpage's parent name, e.g. Subpage Markup

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. In addition, some Cookbook recipes call the MakePageName function (either directly or indirectly) and this will set PmWiki's $MakePageNamePatterns before the subpages script has a chance to influence $PageNameChars. So if you use many recipes and the subpages recipe doesn't seem to be working, try moving its include statement to the top of local/config.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]
  • it should be possible to do something with a $SearchPatterns array entry
• page links, eg [[,day1|First day details]] show as ",First day details" ^[2]
  • arguably a feature not a problem, but changed in version 2.1.10
• Using brackets in links does not work, [[(,)day2|Sunday]], it is interpreted as Group/,Day2
  • arguably, this is consistent with PmWik1's treatment of ! and ~ markup characters for category and profile links
• there is one feature the recipe should have, but I can't figure out how to add it -- if Group.PageX has an edit password set, then Group.PageX,SubpageA should inherit the password, in the same way that pages in Group inherit any Group password settings; unfortunately, a page-level password applies only to the page and not its subpages (it must be possible to fix this, but I can't see how)

Suggest priorities for enhancements

In order, highest first

• make links to sub pages work again in the latest beta version, (Cookbook.SubgroupMarkup,example?)
  • this is a configuration issue: the subpages recipe has to load before any recipes that invoke the MakePageName function
• stop deleted pages showing in pagelists when recipe installed
• stop deleted pages showing in search results when recipe installed
  • these are now fixed, using a less permissive $NamePattern to look for a comma followed by an uppercase or digit, thus excluding ,del-... pages
• provide a way to exclude subpages from pagelist
  • try adding $SearchPatterns['normal']['subpages'] = '!,[[:upper:]\\d].*$!'; to local/config.php and include list=normal in the pagelist directive
• inherited passwords
  • to do (written, but not tested)

List of subpages of this recipe:

Release history

• 6 August 2010 -- fixed problem with slashes in front of quotation marks, and the (:title:) of a child page overwrite that of the parent page. Anke
• 18 August 2008 -- fix for problem with deleted pages in pagelists
• 1 August 2008 -- version 2.1.10 changes the display of [[,day1|First day details]] to omit the comma
• 17 July 2008 -- version 2.1.9 uploaded to replace corrupted version with added show/hide option
• 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