[Pmwiki-users] notes on pmwiki documentation

[John Rankin]

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=
ed
some features like "PmWikiConfiguration" and "PmWikiPasswords", while =
other
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