[pmwiki-users] Fixing the documentation
Simon
nzskiwi at gmail.com
Mon Jul 20 18:37:02 CDT 2009
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
More information about the pmwiki-users
mailing list