[Pmwiki-users] markup musings - notation idea

[Patrick R. Michaud]

On Fri, May 21, 2004 at 09:42:00PM -0500, John Feezell wrote:
> Perhaps a depth concept would help in solving this problem.
> 
> Let one bar "|" mark the beginning of "link text"
> Let two bars "||" mark the beginning of "alt text"
> Case 7:
> [[acronyms || alt text]]
> [[HTML || HyperText Markup Language]]

Excellent suggestion.  My big problem with this is that

   [[W3C || World Wide Web Consortium ]]

could be interpreted as either a link to a page called W3C
or an abbreviation -- it's not clear which is intended.  This is
a case of overloading the link markup (double brackets) for 
something that's not a link--it's an abbreviation or acronym--
and it'd be nice if somehow [[...]] *always* meant link.  

However, the markup is remarkably clean related to the other
proposals I've seen, so perhaps the (bizarre) solution is to
use an empty target to indicate abbreviations.  Thus the markup 
would be

   [[|W3C || World Wide Web Consortium]]

Note the leading pipe.  I admit this looks really bizarre,
but it's entirely consistent with the general case, and building
acronyms is not something I expect to be commonly performed in
the markup anyway.

So, just to play a bit further, here's my proposed revision of the general
case and examples of its use in specific cases.  The idea is that simple
and common things should be simple and common, while complex things should
be possible.

General case:
[[target (hidden) | link text || alt text]]suffix

Case 1 - plain links to other pages
[[target]]
  [[installation]]
  [[documentation index]]
  [[WikiWord]]
  [[http://www.pmichaud.com/toast]]

Case 2 - with a suffix added to the link text
[[target]]suffix
  [[installation]]s
  [[WikiWord]]s

Case 3 - suppressing part of the target in the link text
[[target (hidden)]]
  [[install(ation)]]
  [[documentation (index)]]
  [[WikiGroup(s)]]
  [[text formatting rules(#bullets)]]
  [[(Attach:)file.doc]]

Case 4 - providing explicit link text or image
[[target | link text]]
  [[installation | How to install PmWiki]]
  [[PHPDiffEngine | Diff engine in pure PHP]]
  [[http://www.pmichaud.com/toast/ | Strawberry Pop-Tart Blow-Torches]]
  [[PmWiki | Attach:pmwiki.gif]]

Case 5 - providing title= and alt= attributes in links
[[target || alt text]]
[[target | link text || alt text]]
  [[Installation || Guidelines for installing PmWiki]]
  [[Attach:next.gif || Next]]
  [[http://www.pmichaud.com/toast/ptart-1c.gif|| Figure 1. Preparation]]
  [[PmWiki | Attach:pmwiki.gif|| PmWiki]]

Case 6 - acronyms/abbreviations
[[|acronym || alt text]]
  [[|HTML || HyperText Markup Language]]
  [[|BASIC || Beginner's All-purpose Symbolic Instruction Code]]

There is still room for ambiguity here, especially around the assignment
of alt= attributes.  For example, since "Attach:filename.gif" and 
other bare urls are already converted into inline images, there's a 
good argument to be made that [[Attach:filename.gif]] should be 
rendered as a link to filename.gif and not become an inline image.  
This would be consistent with the rest of the [[...]] markup, which 
always generates a link.

But if this is the case, then the markup for adding an alt= attribute
to an inline image ought to be [[|Attach:filename.gif || alt text]], 
similar to an acronym/abbreviation, since [[Attach:filename.gif || alt text]] 
would normally be how one adds title= attributes to a link.
Somehow it seems "wrong" to me that the very common action of 
specifying an image's alt= attribute is more complex (albeit by one
character) than the less common action of specifying a title= 
attribute for links.

Of course, there's nothing that says we have to keep such a rigid
consistency.  We can always declare that [[Attach:filename.gif]] does 
indeed inline the image, and that [[Attach:filename.gif || alt text]]
provides an alt= attribute to the image, and if someone wants a textual
link to an image rather than an inlined image then they have to do 
something like [[Attach:filename.gif | Attach:filename.gif ]] as 
PmWiki does now.  But I do kind of like the pleasing symmetry that 
arises from [[|Attach:filename.gif || alt text]], since it's clear
that [[|...]] never generates a link.

Again, excellent suggestion, and I'll greatly appreciate comments
from others.

Pm