pWiki/bootstrap/Doc/Path.md

pWiki Path

XXX a Wiki is a set of pages, mostly top level pages, mostly titled in WikiWord style, pWiki follows this culture but does not restrict either page nesting or title formatting, though following this style is recommended.

XXX write a set of recommendations...

Basic terminology

Path
One or more strings (or parts) separated by "/" that identifies a view.

We call the last part in a path sequence a title.

We call the sub-path without the title a basedir or simply dir.

In pWiki, there is no distinction between a page and a directory, thus we do not use the later term, instead, we may use the term sub-page.

Paths are case sensitive.

Page
A set of data associated with a path.

A page is identified by it's path, but this does not require every sub-path of that path to exist -- the full path is the identifier.

Some pages are bootstrapped, i.e. are predefined in pWiki, these pages can be overridden but can not be removed. This is done to make it simple to revert to the default state if something goes wrong.

View
A path that resolves to a page that may or may not be at that specific path.

A view's path may match that of a specific page or may not match any page directly, but any view will resolve to a page via the acquisition process

Any page is a view, every view resolves to a page, but not every view is a page.

(see: Page acquisiton below)

WikiWord
A WikiWork is a specially formated string that is treated as a link

In pWiki a simple WikiWord is any string starting with a capital letter, must contain at least and one more capital letter and can consist of letters, numbers, underscores (WikiWord itself is a good example)

A Path WikiWord is a set of path parts separated by '/' the first part must start with a capital letter and the rest can contain letters, numbers and/or underscores (example: Path/to/somepage).

Special path characters User page titles must not contain the leading underscore _ character, such paths are used internally.

Page acquisition

pWiki path system differs from how traditional file system paths are handled. In pWiki if a path does not reference a page directly (i.e. it's a view), a search is conducted to find an alternative page. This search is called page acquisition.

Acquisition process:
A set of rules defining how a page is retrieved via a path.

This is used as a simple and uniform mechanism to:

• Get default pages for specific situations
  Like [Templates/EmptyPage] to handle the page not found condition.
• define generic templates/pages accessible by multiple pages in path
  A good example would be the viewer used to show this page [Templates/_view] and all of it's chrome like the path in the header and links in the footer (seen: when viewing through pWiki)
• Overload default templates/pages

The acquisition order/rules:

1. if path matches a specific page, target page is found
2. if path does not match a page:
3. if title matches a page in the parent path, page is found
4. repeat until we either have a match or reach root (empty basedir)
5. if no match is found, check if title exists in [Templates] in basedir
6. if no match is found, check if title exists in [/System]
7. if no match is found, repeat process for EmptyPage instead of title

Example:

For path Path/To/Page the following paths are checked in order and the first matching page is returned:

• Check path as-is then go up:
  • Path/To/Page
  • Path/Page
  • Page
• Check in Templates, in path and up:
  • Path/To/Templates/Page
  • Path/Templates/Page
  • Templates/Page
• Check root System:
  • System/Page
• Check EmptyPage in path, then in templates:
  • Path/To/EmptyPage
  • Path/EmptyPage
  • EmptyPage
  • Path/To/Templates/EmptyPage
  • Path/Templates/EmptyPage
  • Templates/EmptyPage (This is guaranteed to exist)

Exceptions:

• System/settings is global and can not be overloaded for use as system configuration. This is done for security reasons.

Default pages

XXX

• EmptyPage
• EmptyToDo
• EmptyOutline
• NoMatch

Relative and absolute paths (".", "..", ">>" and "/")

pWiki follows the traditional path semantics with one addition, the ">>" that is similar to ".." but works in the opposite direction, removing the next, i.e. child, path element.

To illustrate the relative and absolute mechanics:

Source Page	Path	Resolves to
\Example/Page	\./Target/Page	\Example/Page/Target/Page
\Example/Page	\../Target/Page	\Example/Target/Page
\Example/Page	>>/Target/Page	\Example/Page/Page
\Example/Page	/Target/Page	/Target/Page

Path patterns ("*" and "**")

XXX

Path actions

XXX path elements that perform actions on pages but do not actually correspond to actual pages.

Path variables

$NOW

XXX

Also see the \@now() macro: [Doc/Macros].

WikiWord

XXX not actualy part of the path spec but a way (culture) to define paths in pages + automatic link creation.