[pmwiki-users] Fixing the documentation

Hans design5 at softflow.co.uk
Sun Jul 12 14:09:12 CDT 2009


Sunday, July 12, 2009, 7:12:51 PM, Ed W wrote:

> Basically *because* you have the flexibility to override
> $MakePageNamePatterns, it's then important to be consistent between
> "PmWiki" and "Pm Wiki" since both may point to different pages if
> people make use of this flexibility

No. It is possible for an admin to redefine $MakePageNamePatterns
in all kinds of ways, which may be by design totally incompatible
with the page names used in the documentation included in the
distribution. The flexibility I mentioned lies in the default
page name patterns used for links, in that we can use
for instance [[PageListTemplates]], [[page list templates]] or
[[PageList templates]] etc. synonymously.

> Additionally arguing not to define the correct answer is just
> arguing in favour of ambiguity for the sake of it.  Defining
> "PmWiki" to be correct and "Pm Wiki" to be inconsistent should hurt no-one?

My point was that there is no correct way to write a link, even though
there is just one page name per page (leaving out the possiblities of
Intermap link definitions here).

If you look at the documentation index page
http://pmwiki.org/wiki/PmWiki/DocumentationIndex
you find a very consistent use of wording in the links, namely that
they are all worded for easy readability, and not as CamelCase wiki
words, using spaces and dropping the CamelCase capitals in general.

But if you read through the documentation pages you often find that
CamelCase words are use for links, possibly to emphasise the exact
page the link points to. This is done by no means consistently, and
often natural word links are employed as well, to improve readability
by constructuing natural sentences.

I do find one page named badly (inconsistent), which is
PagelistVariables http://pmwiki.org/wiki/PmWiki/PagelistVariables
All other pages associated with page lists use 'PageList...'
like PageListTemplates. I think the page PmWiki.PagelistVariable should
be renamed to PmWiki.PageListVariable (and all links to it adjusted).

> Finally it DOES matter for people who turn on the $SpaceWikiWords
> because it leads to inconsistent presentation.  Defining a
> consistent set of words not to space will give greater consistency with this option turned on or off

It does no harm when  $SpaceWikiWords = true; will present a link like
'[[PageListTemplates]]' as 'Page List Templates', but a link like
'[[page list templates]]' will still appear as 'page list templates'.

The only thing which may need improving may be to have a mechanism to
keep certain words or letters connected by not introducing spaces
even if WikiWord spacing is turned on, so for instance PmWiki stays
'PmWiki' and not 'Pm Wiki', or PIM stays 'PIM' and not 'P I M'.

  ~Hans




More information about the pmwiki-users mailing list