[pmwiki-users] Fixing the documentation
Ed W
lists at wildgooses.com
Mon Jul 13 14:23:35 CDT 2009
Hi
> Ed: Exactly what "normal spacing rules" are you referring to here?
>
I misunderstood a PmWiki feature and I *thought* that the
"$WikiWordCount['PmWiki'] = 0;" feature was actually a feature which
controlled which CamelCase words should be expanded. I was wrong though
(but it would have been a useful feature...)
In other words I thought there was an option to prevent "PmWiki" from
being turned into "Pm Wiki" when automatic spacing was enabled. (I have
since reviewed the code and realised what's what though)
The rest of your email sounds like you are agreeing that it would be
useful to draw up a list of (probably only a few) words which are
"correctly" spelt as a CamelCase word and not as a spaced word? We
could then document that list and it would help keep the documentation
consistent going forward
I'm not sure what your rules are on creating new pages, so would someone
mind starting me off with a page please?
Suggested list of "proper nouns" (wrt pmwiki) for that page appears to be:
* PageList (suggest this spelling since it's the current documentation
pagename)
* WikiWikiWeb
* ChangeLog (see: http://en.wikipedia.org/wiki/Changelog)
* AuthUser - this feels unnecessary to me, can I ask for a second opinion?
* PerGroup - feels VERY much unnecessary, can I ask for a second opinion?
* WikiStyles
* InterMap
Replies to your email:
>> * [[AuthUser]] - should this be [[Auth User]]?
>> * [[PerGroup customizations]]
>>
>
> These look correct to me in the original.
>
Err, well yes, but my point was that the "house style" appears to be to
minimise the use of camel case now, so things should only be spelt like
that if are effectively "proper nouns" wrt to this project. I can see
some argument for AuthUser to remain as a single word (although it feels
weak to me?), but [[Per Group Customisation]] feels much better to me
than [[PerGroup Customisation]] (Why is PerGroup a single word? I don't
see why it should be promoted to a consistent camel case spelling?)
>> * [[Custom wiki styles]] - elsewhere "WikiStyles" is quite common,
>> versus "Wiki Styles" here?
>>
>
> I prefer "WikiStyles" to "Wiki Styles"
>
Ok... This is one which is quite widely varied, but not too hard to
argue in favour of it being "promoted" to a CamelCase word. After a
quick scan this word is perhaps the most inconsistently used link name,
so it would be good to choose a house style and stick with it?
>> * [[PageDirectives]]
>>
>
> I can go either way on this one.
>
Then can I recommend we minimise CamelCase words unless they feel
extremely special and a core feature of the application? Therefore lets
make that [[Page Directives]] ?
>> Patrick - can you please give an official opinion on the exceptions and
>> I will work through the docs and try to fix everything? I recommend
>> that these are then put in as the default "don't space" config param
>>
>
> I don't understand what you mean by "don't space" config param,
> though -- can you be more explicit?
>
OK, I misunderstood the PmWiki functions available (explanation at the top)
However, what I would write now is "can we document the exceptions, use
those consistently in the documentation and make the documentation as
strongly consistent as possible"
I think actually there is a second level of consistency we can fix at
the same time (and this has nothing to do with link styles!). This is
down to capitalisation of links, eg should we write:
- Page Directives, or
- Page directives?
Can we get a second list going of anything that people consider SHOULD
be spaced, but SHOULD be spelt in capitals?
I guess these "House Styles" should become a page under the PmWiki
documentation section? Can you start me off with a recommended page
name and paste in the list from the top? Perhaps others will then start
the debate I asked for in the first place and contribute any other words
they feel should be documentated as special?
Regards
Ed W
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20090713/07e13336/attachment-0001.html
More information about the pmwiki-users
mailing list