[pmwiki-users] Fixing the documentation

Ed W lists at wildgooses.com
Sun Jul 12 18:48:48 CDT 2009


Hans wrote:
> 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.
>   

You seem to just be arguing that you don't care about any other use case 
than the current one?

Quite clearly there is only one possible $MakePageNamePattern which is 
compatible with the current documentation and that's the one that we are 
using now - so this rather negates the benefit of being able to change 
the thing.. End result is that it's a much less useful feature than you 
think it is...

Look - I sense you are arguing from a theoretical position - just setup 
a new wiki and apply the following to your config:

  $PageNameChars='-[:alnum:]';
  $MakePageNamePatterns = array(
    "/'/" => '',                           # strip single-quotes
    "/[^$PageNameChars]+/" => '-',         # convert everything else to 
hyphen
    "/(^\\-+)|(\\-+\$)/" => '',            # trim hyphens front and back
    "/\\-{2,}/" => '-',                   # trim duplicate hyphens
    '/((^|[^\\w])\\w)/e' => "strtoupper('$1')",
    );

What you will see is that it actually works extremely nicely for about 
90% of things.  The documentation is broken in just a handful of places, 
mainly due to inconsistencies which look accidental, rather than this 
great big theoretical "feature" that you are postulating.

Additionally PM has publicly stated that he supports development towards 
allowing the URL to be changed to have a "-" (or whatever) separator.  
These minor inconsistencies in the documentation are one of the few 
remaining things preventing that general direction of development (I 
presume you see the benefit of being able to use varied URL construction 
functions?)


I really don't see why you aren't behind this to be honest?  What is 
this big theoretical feature buying you in practice?


>> 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 

Well clearly this isn't always true - PM has already stated that he 
wants to see "PmWiki" written as such without a space.  The remaining 
seems worthy of just bashing out what we think is the "proper noun" and 
then go from there

I hardly see you can call it a feature that parts of the documentation 
casually refer to "WikiStyles" and later parts refer to "Wiki Styles"?  
Consistency is the bread and butter of strong documentation

> 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,

See - that's my point exactly - all except for a very small amount of 
arbitrary (and what appears accidental) deviation every now and then

Why don't we just set some strong rules now (ie define all the proper 
nouns relevant to this project) and push ahead on that basis?


> 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.

OR possibly because of random inconsistency?!!   Why are you assuming 
order exists in chaos?

Here's another equally valid theory:

PmWiki is a wiki which is moving from a historical basis of being 
heavily CamelCased to a new basis where links are explicitly stated.  
Some of the documentation was written a long time ago and still has some 
CamelCaseLinks left in it...

>  This is done by no means consistently, and
> often natural word links are employed as well, to improve readability
> by constructuing natural sentences.
>   

Perhaps you think I am arguing the opposite way?

Nearly all of PmWiki is now CamelCase free and there are just some 
scattered remnants in the documentation.  I propose to continue this 
cull and remove most of the last few percent of them. 

However, I sense that there are a small number of words that people 
still feel are most correct to continue to CamelCase, eg PmWiki.  Lets 
collect this opinion now and get rid of the rest?

> 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).
>   

Excellent - so now we seem to be heading down the same track?

My question is whether this should be [[Page List Variable]] or 
[[PageList Variable]] ?  Whilst of no importance with the current file 
naming, it clearly has an effect if we want to allow different page file 
names!  Pick one and then lets be consistent

>   
>> 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'.
>   

Yes, I was implicitly imagining this feature already existed, but in any 
case yes the point is that once these "proper nouns" are defined they 
can be excluded from automatic spacing.



Seriously though - try my suggestion above - I'm not asking everyone to 
contort themselves to make this work - I'm saying that we gain a useful 
feature which seems on the general development path, all for the sake of 
changing 1%-4% of the links in the documentation to be internally consistent

Regards

Ed W
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20090713/e166c3f6/attachment.html 


More information about the pmwiki-users mailing list