[pmwiki-users] Fixing the documentation

[Simon]

This has been an interesting discussion. It seems to me that there are two
issues here,
one is the consistency raised in the original example given
viz
* [[Pagelist Variables]]
* [[PageList Templates]]
Is it a PageList or a Pagelist?
Personally I think its a pagelist, because it is a thing in its own right,
and it seems clumsy to write "page list template", although one could argue
for m"page-list template". But I agree it would be best if we
were consistent.

Unfortunately we don't have a rename page available so we are to a large
extent stuck with the original names created, unless we want to copy,
delete, and fix all backlinks..
(Aside: To me this is argument for case insensitive page names).


The other issue is stylistic, and as such agreement may be hard to find.
The approach I have found successful, when focusing on my audiences, is that
wiki or not, they expect content to be presented in natural english,
By this I mean

   - Sentences are cased correctly. Camel Case for the sake of camel case is
   nonsensical to them. For this reason I have disabled link wiki words - "free
   links" are explicitly marked with the [[ ]] markup.
   - words are correctly spaced, eg "PmWiki" is a noun with specific
   capitalisation, "wiki styles" is a phrase
   - links therefore, fit the context and content. Thus at the start of a
   sentence there may be capitalisation, nouns should be capitalised, other
   than that words are lower cased with spacing.

Consequently I am a big fan of $Namespaced, $Groupspaced, $Titlespaced.
How this is achieved, eg [CamelCase |camel case]] or [[wiki style]] or
[[(wiki) trail]] is also perhaps stylistic. I use them all and have not
developed a preference, I'd be reluctant to loose the choice, although I
can't see any reason why, at a config level, it shouldn't be possible to
turn off some of these options if it was really needed to.

If this causes a problem with search then perhaps we should improve the
search algorithm.
OTOH searching for     change log     is likely to give a better result than
    ChangeLog     in any case.

I support the changes Ed has made to
http://pmwiki.org/wiki/PmWiki/DocumentationGuidelines<http://www.pmwiki.org/wiki/PmWiki/DocumentationGuidelines?action=diff>
It would be great if InterMap entries to to "local" wiki could be included
in backlinks, even if we had to add a flag to the intermap entry.

And may I say its great to see the discussions, thanks for hanging in there
Ed

Simon
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20090721/eec84721/attachment-0001.html