[pmwiki-users] Re: Modified (:markup:)

[Patrick R. Michaud]

On Sun, Mar 20, 2005 at 05:56:09PM +0100, chr at home.se wrote:
> 
> Sounds good for now I guess, but I wonder if it isn't the original syntax
> of (:markup:) that is partially to blame here. 

Could be -- I just put it together quickly and didn't have many examples go
go on.

> We've always used [=...=]
> to "escape" something from being parsed. Now we are suddenly using [=...=]
> as a grouping mechanism to pass arguments... 

Well, it's more than that -- we're using it to pass *unparsed* arguments.
That's important.  And it's not "sudden" -- we've done similar things
in several Cookbook recipes -- for example the Beautifier, CodeBlock, and 
SourceBlock recipes.

> OTOH, maybe it should then be written as
> "(:markup Here is a link [[link]]:)"?

Only if you want to disallow directives as an argument, or require them to
be escaped also.

> In addition, I'm very uncertain about how the whitespace is really
> interpreted by (:markup:), i.e. what whitespace is really significant?  

I never intended (:markup:) to be so precise that whitespace would be
an important issue.  

> Btw, if we assume that the argument to (:markup:) should be given *inside*
> the brackets, we could imagine writing
> 	(:markup [=(:nolinkwikiwords:)=]:)
> [...]
> 	(:markup [=An escaped link directive, [=[[link]]=]=], cool?:)
> resulting in the following string for markup():
> 	"An escaped link directive, [=[[link]]=], cool?

Er, no, if only because the order of operations is misplaced here.  The current
(:markup:) directive takes place very early in the sequence -- even before [=...=]
is processed.  If, as I assume you mean, we move (:markup:) after the [=...=]
processing, it would see

    (:markup <keeptoken>1<keeptoken>=], cool?:)

where "<keeptoken>1<keeptoken>" indexes into the $KV array with a value of
"An escaped link directive [=[[link]]".  So, (:markup ...:) then
has to (smartly) de-process the keep tokens in its arguments and reprocess
them.  And we still haven't solved the issue of nested [=...=]'s.

And I *really* dislike the idea of directive markups that span multiple
lines in a single directive, as in

(:markup [=
* Here's an example list
* more list
=]:)

That's *really* hard to read.

> Here's a relatively simple example...
>   (:markup:)You can use [=[==]...=] to escape things.(:markupend:)
> 	    ------------  --  -----------------------
> 	   "You can use [=...=] to escape things."

This example illustrates almost perfectly the problem with nested [=...=]'s
of any sort -- there are a lot of people who would've quite reasonably 
expected the above to produce:

    "You can use [==]... to escape things."

Of course, the [== ... ==] convention resolves this nicely:

   You can use [==[=...=]==] to escape things.
or even
   [==You can use [=...=] to escape things.==]

and there's little confusion.

Ultimately I don't know that there are many cases where I want or
need to be able to do (:markup:)...(:markupend:) all on a single line.  Almost 
by definition it's going to output something that is a block, so I'm thinking
that (:markup:) should be restricted to being on a line by itself, with any
trailing whitespace (including the newline) stripped before processing the
contents.  Then we can also allow (:markup:) with a single escaped string 
on the same line.  If you really want to allow non-escaped strings on the same
line, we might be able to do that too, but obviously nobody's ever used 
(:markup:) in this way (because it doesn't work), so it sounds an awful
lot like a gratuitous feature.

> I have a feeling this might conflict with earlier cases where I've written
> similar text just in order to escape things properly... and in addition I
> get the feeling we're opening a huge can of worms with this... might work
> though.

It still works because [=...=] processes exactly the same as before.
I've already implemented and tested it on pmwiki.org.

> Hmm... what about becoming more verbose instead? What about something like 
> this:
> 
> 	(:markup:) (:arg:) ...
> 	whatever we like [= ...=]
> 	(:argend:)
> 	(:markupend:)

Too verbose to be useful/usable.  Simple is definitely the answer we're 
looking for, or else we should just get rid of it entirely.

Pm