[pmwiki-users] Keep() function documented

[Patrick R. Michaud]

On Tue, Jul 05, 2005 at 11:34:01PM +0200, Joachim Durchholz wrote:
> >There's nothing to "prevent" someone from doing it, but such
> >nested keeps are generally not restored properly.  That's what
> >I meant by "not legally nestable" -- someone can write a script
> >that does it, but they may not be entirely happy with the results.
> 
> Ah, I see.
> 
> Note that such nesting can easily happen if a markup calls PRR().

Perhaps; more generally I'd suspect it's a misuse of Keep.  In
general, once a particular markup has been processed, its pattern
no longer appears in the string for reprocessing.

> Hmm... I've been thinking about a different approach: introduce a 
> $RedoMarkupRule that, if set, will cause MarkupToHTML to repeat the 
> current rule. The 'restore' rule could then set that variable so it will 
> be automatically repeated until no keep tokens are left.

What would be a good application of this?

> Such a variable would also help with parsing nested constructs of all 
> kinds: let the rule recognise just the innermost construct, process it, 
> and replace it with a keep token, then repeat, until all nesting levels 
> have been processed. 

Unfortunately, such a procedure would also mean that any markups 
within the nesting constructs are not processed, since they've been
hidden from further markup processing (which is what Keep() does -- it
hides things from markups).

I suppose one could restore all of the Keep items immediately after
processing the nested constructs, but this is really not what Keep()
was intended to do in the general case.

> (If the nesting construct may span several lines, 
> this would have to happen before line splitting. ... BTW why does PmWiki 
> split the text into lines? Efficiency reasons, or other considerations?)

Two reasons:  First, the line-by-line model is the mental model that
most authors tend to understand when processing text; it makes sense
to keep that particular model.  Secondly, it's a huge efficiency
boost -- my experiments have shown me that the many pattern matches 
that get performed are *much* more efficient on many small strings 
than they are on one very large one.

Pm