[Pmwiki-users] Re: Pmwiki new version

[Patrick R. Michaud]

On Wed, Jun 09, 2004 at 11:01:18AM +1200, John Rankin wrote:
> 3. I'm less convinced by the directives markup [: ... :]
>    http://www.pmwiki.org/devel/pmwiki.php/PmWiki/Directives
>    for the following reasons:
>    - it looks like an inline markup ([+...+], [=...=] and so on)
>    - it might be needed for a future inline markup (although
>      i can't think what for right now)
>    - it's a bit awkward to type
>    I propose the following alternative
>      [directive parameters] eg
>      [title text]
>      [noheader]
> 
>    This seems to me more consistent with the {$Value} markup.
>    Because there is always a directive word, the [...] markup 
>    won't be confused with normal text.

I don't like the single-bracket alternative, because I'm hoping
to be able to provide compatibility with other wiki markups, and there
are a few wiki engines that use single-brackets for link markup.

The points that it looks like inline markup and awkward to type 
have validity, though.  Perhaps awkwardness is not a big problem
since (I think) directives tend to occur in pages much less frequently 
than other markups.  As far as it looking like inline markup--somehow
[:...:] just "felt" right when I created it, and I actually felt the
fact that it shared the brackets with other markups is a bit of an
advantage, even though it's not "inline".

(And to me [...] looks far more "inline" than [:...:] does.)

Note that I've also been intending to use [:...:] or something like
it for things that generate text, e.g.  [:toc pagename:],  
[:search text:],  [:attachlist:], as well as additional things like
[:table:], [:cell:], [:cellnr:], [:div:], [:nocache:], [:cloak:], etc.
There may be an argument to be made that some of these represent
directives, others are properties, and since others generate content, 
and since they do different things they should have a different markup
syntax.  However, I think that authors will not care about these
distinctions, and will tend to focus on the word (e.g., "noheader", 
"table", "search") as the distinguishing characteristic and not the
characters used to surround it--indeed authors will get annoyed if they
have to remember the "type" of each directive and the punctuation that
goes along with it.

(Note that HTML uses <...> for all tags, including block, inline, comment,
and property markup.  Analogy #2: Perl's use of $, @, and % for different 
types makes for a steeper learning curve than does PHP's use of $ for
all variables regardless of type.)

I'm very open to alternatives to [:...:].  Here's a few ideas just off
the top of my head...
    {:directive param:}     (not too good...looks like a pair of smileys)
    #:directive param:#
    #!directive param!#     
    #!directive param       (always at the beginning of a line)

Pm