[pmwiki] Re: [Pmwiki-users] Whitepaper about markup strategy

[Patrick R. Michaud]

On Fri, May 16, 2003 at 07:52:15PM +0200, Bernhard.Weichel at t-online.de wrote:
> >> .b_pre
> >> this is program code
> >>   and this is also program code
> >> .e_pre
> >
> > This one makes some sense, but I don't care for your particular
> > method of coding it with the period in front.
> 
> I don't care of *period* either, but of an explicit markup syntax.

BTW, I've already recommended to many others that we reserve the
equals sign at the beginning of a line for custom block-level or
pragma markups.  This would allow things like

	=pre
	this is program code
	   this is more program code
	=preend

	=title This is a specialized page title

	=notify CustomRecentChanges

I could've used the equals sign for block structured tables, i.e.,
=table, =cell, =cellnr, =tableend instead of [[table]], [[cell]], 
[[cellnr]], and [[tableend]], but at the time I was somewhat addressing
the problem of potential markup conflicts within future versions of
PmWiki.  Bernhard addresses this more explicitly when he writes

> And also If I customize special markup, how can I be sure, that
> future development of PmWiki uses the same markup for other features.

This is actually a problem with any markup strategy, including the
one Bernhard has proposed.  For example, if someone defines a local 
customization using ".b_name" (or "=name") then what's to prevent 
some future development of PmWiki from using that same markup+name for 
another feature, or a similar feature implemented in a slightly different
way.  This is especially true if PmWiki were to adopt the .b_name convention
for all of its markup.

In short, markup syntax alone probably can't completely solve problems of 
semantics or future compatibility--that can only be done by conventions.  
My first attempt at this has been the "=xxx" convention.  Essentially in 
this convention I propose that future versions of PmWiki will never 
define a markup sequence where an equals sign is at the beginning of the 
line, so administrators are free to use this for whatever local 
customizations they desire.

A small problem arises when we desire to add a local customization that
someone has created and make it a standard part of PmWiki.  For example,
if someone creates a really cool feature using "=coolfeature" as the
markup (following the convention), there's no way to easily add the 
"=coolfeature" markup to PmWiki without violating the convention given 
above that says PmWiki will never have a markup sequence with an equal 
sign at the beginning of a line.  So the alternative is that PmWiki
has to use a different markup sequence in the "public" implementation.

BTW, if you're now wondering "well, why didn't Pm tell us about the
=name convention sooner!", I have two answers:
 1. like most systems, the documentation is still catching up to reality, and
 2. you haven't seen anything in PmWiki that uses the "=name" syntax 
    because I'm following the convention.  :-)

As an aside, HTTP and mail systems solve this by using what is known as 
the "x-" convention; an administrator or program author  is generally 
free to define any new header or field as long as it begins with "x-", 
and the standards explicitly reserve the "x-" prefix for such 
customizations.  When the custom "x-" header becomes useful enough to 
be part of the standard, the "x-" part of the name is dropped and an 
official name adopted for the standard.  And yes, this means that
some software packages have to be updated to be able to use the
new standard--but I think that's an inherent part of upgrading and
cannot truly be avoided.

Pm