[Pmwiki-users] Re: markup musings, with missing #7 restored

Christian Ridderström chr
Fri May 21 08:27:10 CDT 2004


On Thu, 20 May 2004, Patrick R. Michaud wrote:

> These are just some random thoughts I've had about link markup and
> the like over the past couple of weeks -- I'm only posting these to
> see what anyone has to say about these ideas, not because I'm planning
> to adopt any of them.

What do you mean with link markup in this context, anything that
translates into <a href='...'>..</a>? Or is it more about how we create 
links to other wiki pages? I guess I'm wondering what the purpose of the 
link markup is...

> 1.  Link markup should be something relatively easy to type and read
>     inline with the markup.  The best candidates seem to be [...],
>     [[...]], and {{...}}.  
> 
>     [...] has advantages of being easier to type and perhaps 
>     easier to read, but disadvantages of possibly being
>     confused with other existing markup or occuring in normal text.

I think [...] is too common in normal text.

> 2.  Any page target specified inside of link markup should be a
>     "free link", i.e., able to contain spaces and selected other
>     special characters.  
> 
> 3.  (Corollary to #2)  If separate link text is to be used instead
>     of the target, it has to be delimited from the target by something
>     other than a space.  The most common choice seems to be
>     the vertical brace:
> 
>         [free link | link text]
>         [[free link | link text]]
> 
>     but nested brackets to separate the two also has merit.
> 
>         [[free link] link text]
>         [free link [link text]]
> 
>     I tend to prefer the | versions because it more clearly appears to
>     me that the link text is indeed "replacing" the target text and
>     is not somehow "parenthetical".

If we are talking about clarity, how about:

	[[link text -> someGroup/in this page]]

where the order has been switched and '->' indicates that the 'link text' 
is pointing to SomeGroup.InThisPage. Actually, if '->' is needed this 
should work as well:

	[link text -> free link]

since I don't think you normally write '->' inside [...].

> 4.  Character entities should be supported inside of any alternate
>     text, if not inside of the target itself (but possibly stripped
>     when building the target name).  Thus 
> 
>         [PmWiki | Pm&quot;s favorite wiki engine]

But you would you allow [PmWiki | Pm's favourite engine]?
 
> 5.  Suffix characters immediately following the link should be
>     appended to the link, thus "[[document]]ation" would link to
>     "Document" but display "documentation" as the link text.

Nice. In this case I definitely think [[document]]ation looks better than 
[document]ation.

> 6.  It's useful to be able to suppress part of the target name when
>     creating the link text.

To be honest, I rarely use this feature. This could of course be because I
don't like the current syntax -- it doesn't feel intuitive to me and I 
can't remember how it works :-( So in order for people to use this, I 
think simple is more important than powerful.

>     Currently PmWiki uses '|' for this, as
>     in {{free link|s}}, but another approach would be to use a 
>     matched character sequence such as braces or parentheses.  This
>     would also allow suppression somewhere other than the end.  
>     Possibilities/examples:
> 
>         [free link{s}]ing  -- links to FreeLinks, displays as "free linking"
>         [free link(s)]ing  -- same but using parens instead of curly braces

Using '(' is slightly better than '{'. In addition to looking better, the 
Swedish keyboards make it more difficult to type '{' compared to '('.

> 8.  Perhaps a good way to implement alternate text (images, acronyms,
>     abbreviations) is to simply introduce a new markup for it.  In playing
>     around with the above ideas I came up with [(alt text)], which would add
>     a alt= or title= attribute to whatever immediately preceeds it.  Thus:
> 
>         Attach:filename.jpg[(my photos)] 
>         [W3C | Attach:w3c.jpg][(World Wide Web Consortium)]
>         HTML[(HyperText Markup Language)]
>         [http://www.pmichaud.com/toast][(Strawberry Pop-Tart Blow Torches)]

I don't easily understand the syntax above... IMHO it needs to be more
explicit. For instance, is 'my photos' a title or an alternate text?
(Assuming that both are valid).

And it took me a while to figure out the meaning of

         [W3C | Attach:w3c.jpg][(World Wide Web Consortium)]

so I think it's getting to complicated :-(

> 9.  Reference links (link text automatically numbered as [1], [2], [3]) 
>     are not that commonly used, so it's useful to build a special 
>     markup for them rather than overloading an existing markup.  A good
>     choice may be to simply use '' or '#' as alternate link text:
> 
>         [http://www.pmichaud.com/toast|]  
>         [http://www.pmichaud.com/toast|#]

Are '|' allowed in URIs? I've seen it used, but I don't know if those are 
valid URIs.

>       
> 10. It's worth considering the markup choices being made by other wiki

Definietly, if nothing else to get more ideas.

>     PmWiki and other engines.  The 600-pound gorilla is Wikipedia

lol

>         [[free link]]           -- link to "FreeLink" displays as "free link"
>         [[free link]]s          -- link to "FreeLink" displays as "free links"
>         [[free (link)]]         -- link to "FreeLink" displays as "free"

I like the three above, but not the one below:

>         [[free link | clickme]] -- link to "FreeLink" displays as "clickme"

but maybe that's because my brain is so used to interpret '|' as a pipe or
a logical operator, i.e. using 'clickme' instead of 'free link' is
optional and not something that is forced. Actually, my brain probably 
thinks of 'clickme' as an alternate text for 'free link'...

Hmm.. using that thought combined with my earlier idea about '->' we would
use:

	[[clickme | title text -> free link]]

which should result in a link with the text 'clickme' and the title 'title 
text' pointing to the page FreeLink. Flipping around this (i.e. using 
'<-' instead of '->' we would instead be using:

	[[free link <- clickme | title]]

I don't know which is more intuitive, putting the link target first or
putting the link text first.

/Christian

-- 
Christian Ridderstr?m                           http://www.md.kth.se/~chr





More information about the pmwiki-users mailing list