[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