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.

Requirements

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:

Kingdom
+-Plant
| +-Grass
+-Animal
  +-Canine
  | +-Terrier
  +-Feline
    +-Cat

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.

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:

• remark1
• remark2

Filesystem analogy

• 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

• The original proposal didn't consider relative links, that's why I substituted question marks. There should be a better syntax for that case.

Migration

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.

Contributors

• 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

Syntax Proposals

Proposals have been spwaned into seperate pages:

• By StirlingWestrup?.
• Start small? is a 'NoHierarchicalGroups?' proposal.