[Pmwiki-users] notes on pmwiki documentation

John Rankin john.rankin at affinity.co.nz
Fri Feb 28 14:48:22 CST 2003

Maybe this implies a dual-page distinction, e.g.,
"WikiStyles" for authors and "WikiStylesAdmin" or "WikiStylesCustomization"=

for administrators.
In the encyclopedia we are working on, we have a similar structure, which =
may be useful to consider for the PmWiki documentation.

There are 2 main groups: Rules which is the rule book (written by lawyers) =
and Grid which is the plain language guide to the rule book. Each group =
has a GroupHeader of the form:
- in Rules -- [[Grid/[[$title]] Grid]] [[title:Grid/[[$title]]]] <|Rules/=
Rules|> ^|Rules/Rules|^
- in Grid -- [[Rules/[[$title]] Rules]] [[title:Rules[[$title]]]] <|Grid/=
Grid|> ^|Grid/Grid|^

So there is the same set of page names in each group and [[title:... pulls =
in the first paragraph of the corresponding page in the other group. Each =
group carries a different colour scheme to distinguish them, but the =
physical layouts is identical.

The contents page is a deeply nested hierarchy (like the one Dawn Green =
has set up for PmWiki only it goes to level 6 I think) and ^|Group/Group|^ =
give a vertical navigation bread crumb.

Although most pagenames are {{free link}}s, Group/[[$Title]] works =
everywhere because we have redefined the $PageNamePattern. We have *not* =
changed $WikiWordPattern.

>From time to time I feel that there should be a "Reference" or "Dictionary"=

group to hold common (Pm)Wiki definitions like WikiWord, WikiWikiWeb,=20
WikiGroup, WikiTrail, etc.  But the problem with sticking these pages=20
into another group as opposed to Main is that an author has to understand=20
WikiGroups in order to be able to access those pages effectively. =20
Perhaps that's not a real problem--I'd like to hear from others.
The rule book has many pages of definitions. We set up a page for each, =
plus a trail page that lists them all. Again, most of the definitions are {=
{free link}}s. (We also found some terms that were tagged in a lawyerly =
fashion as being defined terms, but that had no definitions.)

Also, it might be useful to come up with some consistent naming choices
about when to include "PmWiki" in the document.  For example, I've document=
some features like "PmWikiConfiguration" and "PmWikiPasswords", while =
features do not contain PmWiki in the title, as in WikiStyles, WikiTrails,
InterMap, etc.
Why do terms need PmWiki in the title? What is wrong with just {{=
configuration}} and {{password}}s? And is there a convention for favouring =
singular or plural page names?

John Rankin

More information about the pmwiki-users mailing list