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

[Patrick R. Michaud]

On Fri, May 21, 2004 at 04:27:03PM +0200, Christian Ridderstr?m wrote:
> On Thu, 20 May 2004, Patrick R. Michaud wrote:
> 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...

I mean the markup used to create links to other pages (both internal 
and external.  Currently PmWiki uses [[WikiWord link text]], [[WikiWord]],
[[http://... link text]],  [[{{singleword}} link text]], and 
{{free link|s}}ing as the markups to create links with anchor text
other than the target.  I'm look at ways of reducing the number of
syntaxes used and making it easier for new folks to learn.

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

It's not just clarity, it's also ease of entry and understanding by
new users.  -> is nice, but I might get confused about what appears where.

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

Yes, of course!  It wasn't meant to be exclusive, only to show that it
should support something that is not currently supported in PmWiki.

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

I agree that I like the look and function of parens better than curly
braces in this context.  I only put forth curly braces under the theory
that (a) someone might want to have a paren in the free link text, and
(b) parens could be valid characters inside of a URL.  OTOH, MediaWiki
(Wikipedia) uses parens for this, and I just remembered that PmWiki
already excludes parens from URLs (one has to use %28 and %29), so
(b) doesn't really make much of a difference.

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

For an image, it's alt= text.  For anything else, it's title= text.
Have any suggestions that would be "more explicit"?  And except for 
the addition of the parens, this is basically what was proposed in 
http://www.pmichaud.com/pipermail/pmwiki-users_pmichaud.com/2004-March/003537.html  so...

My basic idea for this syntax was that

   http://www.pmichaud.com/toast/ptart-1c.gif[(Toaster and Pop-Tarts)]

comes out with "Toaster and Pop-Tarts" as the alt= text for the image.
By analogy,   Attach:filename.jpg[(my photos)]  does the same.  And,
by extension, if the thing in front of the [(...)] markup isn't an
image, then it's given a "title=" attribute instead, as either an
acronym or a link.

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

I was just following my own constructions, so that I would expect

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

to come out as

    <a href='$ScriptUrl/$Group/W3C' ...><img src='.../w3c.jpg' 
      alt='World Wide Web Consortium'></a>

I admit it's a little on the complex side, but we're also talking
about doing a fairly complex (and likely rare) thing--i.e., linking 
to a wiki page using an attached image as the link text with an 
alt= attribute.  There is a good argument to be made that it should
instead read

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

I don't know if this is better, worse, or just illustrates that this
markup is a bad idea.  :-)

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

According to RFC 2396, '|' are unwise within URIs and should be escaped.
Regardless, PmWiki already excludes '|' from the $UrlPathPattern, if only
to keep it from causing problems with table markup  ||http://...||

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

In the past I've generally taken the position that the target goes before
the text--certainly this is what PmWiki does (as well as most other
wiki engines, PhpWiki being a notable exception).  This is what
happens in the HTML world -- the target appears (in the <a ...> tag)
before the text.  OTOH, in written languages, the target often appears
after the text (think footnotes or endnotes).  Still, for better or worse,
the most widely used models seem to put the targets first.

Pm