[pmwiki-users] pmCalendar

Patrick R. Michaud pmichaud at pobox.com
Thu Oct 20 21:38:57 CDT 2005


On Thu, Oct 20, 2005 at 09:18:01PM -0500, Chris Cox wrote:
> Patrick R. Michaud wrote:
> > On Thu, Oct 20, 2005 at 06:03:59PM -0500, Chris Cox wrote:
> >>Try
> >>http://theendlessnow.com/ten/Test/PmCal
> >>
> >>Just shows up as (:pmcal:)
> >>
> >>It's running 2.0.6
> > 
> > Aha!  Look at
> > 
> >     http://theendlessnow.com/ten/Test/PmCal?action=ruleset
> > 
> 
> Well.. I'm still a bit confused about when to use what where.
> Seems that <include will work for pmcal... if I use
> directives, the text from pmcal is not processed as wiki
> markup... comes out as the actual uninterpreted text.

Markup is tricky, especially when they interact as they often
must.

> Since I use includes... I'm assuming I should use
> <include (am I understanding this correctly?).

Ahhh, I see.  The output of the (:pmcal:) directive contains
(:include:) statements, and you want to make sure those get
processed.

The "short" answer is that any markup rule can request that
all markup processing be "restarted" on the current line by
making a call to the PRR() function ("PmWiki Rule Restart").
So, if a directive or other markup generates an (:include:)
statement that needs processing, it makes a call to PRR()
(no arguments), and that tells the markup engine that it
needs to restart processing of the current text starting
with the first rule again, so that it again looks for
[=...=] sequences, handles any (:if:)...(:ifend:) markups,
handles (:include:) statements, splits lines based on newlines,
etc.

Long explanation:

The reason why (:pmcal:) isn't working when it's at the
beginning of a page is because when the page text is
first being processed, (:pmcal:) isn't at the beginning of
a line, and the markup rule is looking for "/^\(:pmcal...".  
Let's look at what happens with a page that contains just 
"(:pmcal:)" and nothing else.

When the HandleBrowse function is called to generate the page,
it starts by adding internal directives for the page's group 
header and footer to the text, thus we end up with page text of

    (:groupheader:)(:pmcal:)(:groupfooter:)

When the 'pmcal' rule is tested now (<include), the (:pmcal:) 
markup isn't at the beginning of a line and so it's not invoked.
Later in processing (after the 'include' rule), the 
(:groupheader:) line is replaced with the value of 
$GroupHeaderFmt, thus we get

    (:include $Group.GroupHeader:)(:nl:)(:pmcal:)(:groupfooter:)

The (:groupheader:) markup rule also makes a call to PRR(), so that
processing restarts at the beginning and the (:include:) line it
generated is processed.  As a result of the restart we also test
the 'pmcal' rule again, but (:pmcal:) still isn't at the beginning 
of a line so nothing happens.

A similar sequence happens for (:groupfooter:), so that we 
eventually end up with (assuming the GroupHeader and GroupFooter pages
are empty):

    (:nl:)(:pmcal:)(:nl:)

The (:nl:) directives are internal directives that mean "add a newline
here to separate things if we need it".  They're used to handle
the transition from the GroupHeader text to the main text--if the
GroupHeader doesn't end with a newline, we want to add a newline
at the (:nl:) to make sure that the first line of the markup text
is really on its own line.  (And the same for the GroupFooter page,
we want to make sure that its first line is really on a line by itself,
but we don't want to add extra newlines that might generate vertical
space.)

Here the (:pmcal:) doesn't need to be separated by newlines from
the text before and after it, so the (:nl:) markups just "disappear"
and we're left with:

    (:pmcal:)

However, since we've already passed the 'pmcal' rule, and there aren't
any other directives here that might restart processing, the output
just remains (:pmcal:) and that's what we get on the screen.

Currently the 'pmcal' rule calls a "pmcal" function, if that function
were to make a call to PRR(), then it ought to be possible to have
the pmcal rule occur in the 'directives' section and not be '<include'.
By the time processing gets to the 'directives' section, the (:nl:)
markups have been handled and the markup text has been split into
separate markup lines, so (:pmcal:) will be processed even if it's
at the very beginning of the markup text.

Pm




More information about the pmwiki-users mailing list