This page serves to collect proposals for establishing group hierarchies in PmWiki.

Intuition and analogies

This is an important aspect: PmWiki's philosophy mandates that its mechanisms should be intuitive, even to newcomers.

The most important consequence is that group and page names should mimick some well-known hierarchical structure, such as a filesystem hierarchy or the chapters and subchapter numbers of a book. The problem with chapter number syntax is that it doesn't differentiate between absolute and relative paths, i.e. writing "section 3.4.7" doesn't say whether it's chapter 3.4.7 as seen from the table of contents, or if it's subsection 3.4.7 of the current section - this must be established from the context. This leaves us with filesystem naming schemes as the primary analogy for a hierarchy.

Even the filesystem analogy isn't fully powerful enough. In a wiki, any hierarchical name should refer to both a page, as well as to the group of pages that are "below" that page. This is different from filesystems, where a name is either a directory or a file.

To make the problem explicit, let's assume that a name in a filesystem is both a file and a directory. Now if we assume it's a file, we intuitively assume that the current directory is the name's parent. If we assume it's a directory, we assume that itself is the current directory.

In other words, we have conflicting intuitions about what the current directory in such a file system would be. We need to decide for one of these intuitions, and give plenty of examples to counteract the wrong intuition. (It would be interesting to hear how the Reiser people handle the situation. Their file system is in exactly the same situation.)

There would be another way to avoid these conflicting intuitions: stick with filesystem semantics and mandate that a name can be either a directory (group) or a file (page), but not both. However, this is considered against Wiki principles: if something starts life as a page and has to be turned into a group later, this should be easy. In particular, if some other pages had a link to the page, and that page is turned into a group later, the link breaks - i.e. restructuring the wiki suddenly becomes a hard operation.


Relative links are invariant

Moving an entire group of pages from one place to another in the group hierarchy should leave any relative links within the group functional.

Links to sibling pages are the simplest case

The reasons for this are:

  • Standard use case. Even in a wiki that overdoes hierarchy, the majority of pages will be leaves, and we expect that most links will go to sibling pages if only for lack of child pages.
  • Compatibility. There are no child pages currently, and hence no child links.
  • Analogy with filesystem use. A bare name of "B" in file "A" is almost always understood to refer to a file named "B" in the same directory as "A".

Canonical example

This page assumes the following groups and pages:

| +-Grass
  | +-Terrier

Unless noted otherwise, Canine is the current page.

Concrete syntax proposals

Any proposals should use the following template.

In the path components section, fill in syntax for the components of a path name. Path names should be constructed by starting with one of the "start" components, followed by an arbitrary number of the other components. In the special rules section, write up any additional rules that may hold for forming a path name.

The examples section is just for establishing how the links would look like in practice. Assume you're on page Canine, and apply the rules from the first sections to get to the listed target pages.

Hint: Try this order when filling out the template:

  1. Fill in the syntax in the path components section, but leave the self, parent, top, up, over:X and down:X reminders in place now.
  2. Fill in the examples. This is a relatively mechanical process since you can reference the stuff in the path components section.
  3. Delete the self, parent, top, up, over:X and down:X reminders in the path components section.

Here's the template:

Path components
current page as starting group:self
parent page as starting group:parent
main group as starting group:top
go up:up
go to sibling X:over:X
go to child X:down:X
Special rules
Kingdom (grandparent):[[parent up]]
+-Plant (uncle):[[parent over:Plant]]
| +-Grass (cousin):[[parent over:Plant down:Grass]]
+-Animal (parent):[[parent]]
  +-Canine (self):[[self]]
  | +-Terrier (child):[[self down:Terrier]]
  +-Feline (sibling):[[self over:Feline]] or [[parent down:Feline]]
    +-Cat (nephew):[[self over:Feline down:Cat]] or [[parent down:Feline down:Cat]]
Absolute link (to Canine):[[top down:Kingdom down:Animal down:Canine]]
  • remark1
  • remark2

Filesystem analogy

Path components
current page as starting group:self ./
parent page as starting group:parent
main group as starting group:top /
go up:up ../
go to sibling X:over:X X
go to child X:down:X /X
Special rules
Kingdom (grandparent):parent up
+-Plant (uncle):parent over:Plant
| +-Grass (cousin):parent over:Plant down:Grass
+-Animal (parent):parent
  +-Canine (self):self
  | +-Terrier (child):self down:Terrier
  +-Feline (sibling):self over:Feline or parent down:Feline
    +-Cat (nephew):self over:Feline down:Cat or parent down:Feline down:Cat
Absolute link (to Canine):top down:Kingdom down:Animal down:Canine
  • The main counterintuitive case here is that links to pages in a sibling hierarchy start with ../.
  • A minor counterintuitive case is the self link. If we were sticking with filesystem semantics, both .. and . would refer to the parent group.

Chapter numbering analogy

Path components
current page as starting group:self ?.
parent page as starting group:parent ??.
main group as starting group: (nothing)
go up:up ??.
go to sibling X:over:X ??.X.
go to child X:down:X X.
Special rules
A final dot on the path name is dropped.
Kingdom (grandparent):??.??
+-Plant (uncle):??.??.Plant
| +-Grass (cousin):??.??.Plant.Grass
+-Animal (parent):??.
  +-Canine (self):?.
  | +-Terrier (child):?.Terrier
  +-Feline (sibling):??.Feline
    +-Cat (nephew):??.Feline.Cat
Absolute link (to Canine):Kingdom.Animal.Canine
  • The original proposal didn't consider relative links, that's why I substituted question marks. There should be a better syntax for that case.


It's quite likely that syntax for a group hierarchy will be incompatible with PmWiki's current internal link syntax. However, since it's unclear what the incompatibilities will be and whether there's still a way around them, the current stance is to ignore this problem and concentrate on a syntax that's intuitive for the time being.


  • JoachimDurchholz May 25, 2006, at 03:41 PM (initial structure)
  • JoachimDurchholz June 16, 2006, at 05:37 AM (Added the template and three proposals)
  • mrcs June 21, 2006, at 04:10 PM (reiser4 analogy: page and group are *the same thing*)

General Comments

Quote: The most important consequence is that group and page names should mimick filesystem directory and file names.

I would agree with the analogy so long as you also carry forward the metaphor with hard and soft symlinks, virtual directories and inhertience.
John McGinnis
The filesystem analogy serves to give non-geeks a chance to understand hierarchy as such. Properties of objects inside the hierarchy can be handled orthogonally to the way that hierarchy is established, so I don't think that we need to carry the analogy that far on this page. (I don't think that non-geeks even know what a hardlink is, and if they knew, the concrete effects would keep surprising them.)
Actually I think that symlinks already exist (in the form of redirects), that hardlinks are problematic, and that virtual directories and inheritance aren't standard filesystem concepts at all (I don't know a single Linux filesystem that has them).
JoachimDurchholz June 16, 2006, at 03:18 AM
I keep feeling I've missed something. So shoot this comment to dust if I'm covering old ground. I would tackle this as Object Oriented. Files and directories are things. So a thing can be (a) directory and/or (b) file. Unless I misunderstand this is what I'm currently about to download. Now a thing can note it has a nominal parent of an arbitrary other thing including itself. Such self relationships in ERDs have around my way come to be called a "who's ya daddy?" link which simply expresses at it's simplest that the thing needs to know it's parent but does not exclude a "daddy" having an index of it's children.
In this context your group (type A+B thing) is represented by the group home page (the B part) which leaves the A (folder) free to decide if it is root or if it inherits from another group, page or third party thing (yet to be created type C).
At the logic layer now I would have the data layer make an index (like for back links) of known children which can be contextually linked to from the group home (optionally). Further more the path back to root including "UP" to each parent level can be obtained by asking the current thing "who is your daddy" all the way until the answer is "I am". This gives you the "trail" in reverse.
Functionally very little need change and for the user the feel of groups in groups exists. In that way it is like people. Each person has a National Insurance Number in the UK and in the US a similar number is issued to everyone. In the system this "number" is $group.$page now this may be joined to a family, live in a flat (with other families) in a town, under a stack of councils under a government in a country on a planet but it is still $group.$page and it is down to presentational logic as to when you would like things that are not their own parents to be shown. A couple of settings should do it.
In this way groups are a loose coupling (good design pattern) ad do not break easily. Or did I miss something over the course of several pages?
- "Lord" Matt ([(approve links) edit diff])
IMHO, I think that maybe one way to deal with this is to always link to pages and never link to groups, so links inside one page will always refer to other pages within the same group/path, just the way it already is with PmWiki.

i.e. a page named "Animals.Canine.Terrier" with a link to "[[bulldog]]" inside it, will always link to "Animals.Canine.Bulldog" where bulldog is a page, it will never link to a group named bulldog inside the current path "Animals.Canine".

So the last argument within a pagename "Animals.Canine.Terrier" is the page itself and the rest is the group/path name "Animals.Canine". If there isn't a page named "Animals.Canine.Terrier" you will see a page saying that that page doesn't exist and inviting you to create one.

You can keep links the way they are now, normally refering to pages in the actual group and if you wanna link to other pages with diferent path/group, just give the fullname (path+pagename) of that page as a link. CarlosAB June 16, 2006, at 01:57 PM
"Always link to pages, never link to groups" seems the right PmWiki thing to do. However, as currently presented, this may cause problems if one restructures the pages or uses an include statement. On Animals.Canine, a link to "[[bulldog]]" refers to Animals.Bulldog whereas on Animals.Canine.Terrier, a link to "[[bulldog]]" refers to Animals.Canine.Bulldog. Furthermore, on Animals.Canine.Terrier, one might want to refer to Animals.Feline. Presumably, one can now no longer write "[[feline]]".
I see two angles of attack on this one, both relying on PmWiki rewriting the links as needed.
For inclusion, the current group that the include directive starts from should always be the location of the include page itself. (If you use the location of the including page, it's very difficult to use inclusion from include files.)
For page restructuring, I think PmWiki can rewrite the links inside the page. This is desirable even in the nonhierarchical case, though less important.
JoachimDurchholz August 19, 2006, at 03:11 AM
In trying to solve this for one level of subgroup, one way that seemed to make sense was to have a subgroup markup character (see Cookbook.SubgroupMarkup).
I don't like that idea. It doesn't scale to sub-sub-groups. What if a former subgroup is turned into a group - you may want to add code that changes the links, but that code would have to handle a lot of borderline cases.
JoachimDurchholz August 19, 2006, at 03:44 AM
This leads to: on Animals.Canine and Animals.Canine.Terrier, a link to "[[,bulldog]]" (note the addition of a comma) refers to Animals.Canine.Bulldog. On the other hand, a link to "[[feline]]" on those pages refers to Animals.Feline. A link on Animals.Feline to "[[canine,bulldog]]" is a reference to Animals.Canine.Bulldog -- a page in the Animals.Canine group; an Animals.Canine page may or may not exist. This could be generalised to any level of hierarchy.
I feel uneasy about leading commas that carry meaning. It's far too easily overlooked, or confused with a full stop.
JoachimDurchholz August 19, 2006, at 03:11 AM
I think this is way over-complicated. Personally, after playing and using PMWiki for about 3 weeks now, the one thing I would love to be able to do is just keep adding the "/"'s. As many as I want.
If I want to do Main/Animals/Mammals/Canines/Dogs/Rottweiler, why not? Main can be a page, as well as Main/Animals, or even Main/Animals/Mammals/Canines/Dogs/Rottweiler. If there's no page for it, the admin can either lock it, or leave it open for creation. No worries.
Take from the UNIX-think of file systems: Everything is an inode to the kernel(PMWiki): Files, Directories, Softlinks, hardlink, devs. It's up to the shell(Admin glue) to decide what to do with different types of inodes.
If I want to move the hierarchy around, so be it. If I want to reference something inside a different "directory" than I'm in, I need to be explicit, or give a bunch of ".." until I get there. And, with Intermaps, we can even do hardlinks. But, to follow KISS, just need to allow as many "/" as the end-user wants. JMO. CoreyReichle -> mailto:coreyreichle [snail] verizon [period] net

Syntax Proposals

Proposals have been spwaned into seperate pages:

This page may have a more recent version on pmwiki.org: PmWiki:HierarchicalGroups-Proposals, and a talk page: PmWiki:HierarchicalGroups-Proposals-Talk?.