[Pmwiki-users] intuitive learning

[Patrick R. Michaud]

On Thu, Feb 26, 2004 at 08:37:14AM -0500, Lloyd Budd wrote:
> Why does
> 
> 	[[{{philosophy}}values]]
> 
> displays as "[1]" , but
> 
> 	[[{{philosophy}} values]]
> 
> displays as "values"?  What is the feature here?

Links of the form [[http://www.cnn.com]] or [[WikiWord]] are called
"citation links" and display as "[1]", "[2]", etc.  This markup actually
comes from the original Wiki (http://c2.com/cgi/wiki).  

PmWiki extended this markup to allow arbitrary text to be used for the
link text, thus [[http://www.cnn.com alternate text]] becomes a link to CNN
and is displayed as "alternate text".  The key difference is the space 
after the link.

FreeLinks are an easier way of specifying references to pages without
having to use WikiWords or do double-bracket sequences.  Thus, the
markups {{wiki word}} and {{philosophy}} are links to pages called
"WikiWord" and "Philosophy" but display as "wiki word" and "philosophy".
We also often need to add alternate endings to a word, so PmWiki includes
any text immediately following a free link as part of the link text, so 
that {{wiki word}}s  is still a link to "WikiWord" but the 's' is included 
in the link text; i.e., the link displays as "wiki words".  

So, in your first example above, [[{{philosophy}}values]], PmWiki is 
treating the "values" part as part of the free link, and since there's 
no space after the link name, it's displayed as a citation link  ("[1]").

In the second example, [[{{philosophy}} values]], PmWiki sees this as
a link of the form [[reference alt text]], so it's creating a link to
"Philosophy" and displaying the text as "values".

There's probably a reasonable argument to be made that this isn't very 
intutitive, but it is consistent.  And I haven't really seen another
system that is more intuitive and offers the same sort of flexibility.

It might also be worthwhile to introduce the convention that the 
[[reference alttext]] syntax allows page titles instead of WikiWords 
for the reference part, eliminating the need for the free link markup 
for single-word page names.  Thus one could write [[Philosophy values]]
instead [[{{philosophy}} values]].  Any votes in favor/against?

Pm


BTW, don't forget that {{free links}} have a powerful alternate ending
structure using the "cut syntax".  Thus {{philosophy}} and 
{{philosoph|y}}ies both link to the same page but display as "philosophy"
and "philosophies".  I often find this to be much easier to work with 
than having to write [[{{philosophy}} philosophies]].