[pmwiki-users] want opinions on a new cookbook recipe format

[Patrick R. Michaud]

On Tue, Mar 07, 2006 at 12:53:01PM -0600, Chris Cox wrote:
> Susan wrote:
> > Does this (:directive:) code mean authors will have to produce a line of 
> > letters and get things in the right order to fill in the fields? Or will 
> > there be a template or form? They've already written the recipe, there 
> > should be as few stumbling blocks as possible to them sharing it.
> 
> If it's driven by a directive, you'd fill in the parameters in
> whatever order you want and then pmwiki could decide on
> what is displayed and how.  

I'm not sure PmWiki should always be making this decision, even
for consistency's sake.  Sometimes it may be important that a
recipe include a heading that isn't part of the standard set
we provide, or that it makes more sense for the headings to be
in a different sequence than the default.

In general I think the recipe author will knows best, and if a 
recipe author is wrong, we have dozens of other co-authors
available to correct it.

> (:cookbook
>  Name='PmCalendar'
>  Summary='Calendar designed for PmWiki where each day is a separate wiki page.'
>  Version='1.0rc6'
>  Status='Stable'
>  Prerequisites='pmwiki-2.0'
>  Maintainer='ccox'
>  Categories='Calendar,PIM'
> :)

To me, this is:

    Name: PmCalendar
    Summary: Calendar designed for PmWiki where each day is a separate wiki page
    Version: 1.0rc6
    Status: Stable
    Maintainer: ccox
    Categories: [[!Calendar]] [[!PIM]]

where PmWiki can still enforce rules on the specific properties if
it wishes via specialized markup rules, or grab all of the values
and then reformat them and re-order them in a different way.

To see how this could work, consider something like:

    Markup('^Property:', 'fulltext', 
      '/^(?!Summary)([A-Z]\\w+):(.*)$/me',
      "StoreProperty(\$pagename, '$1', PSS('$2'))");

    Markup('^Summary:', '>^Property',
      '/^Summary:(.*)$/me',
      "DisplayProperties(\$pagename, PSS('$1'))");

The first markup rule captures all of the lines except for
"Summary:", and calls a StoreProperty function which stores each
values into an array somewhere and returns an empty string.  
This has the effect of removing all of the properties (except 
Summary:) from the markup, and storing them in an array where
they can be added by a later rule.

The "Summary:" rule is the later rule -- it replaces the 
Summary: line with whatever we want, which can include the 
(reformatted) values from the other lines that we captured
earlier and in whatever order we wish to enforce upon them.

I'm not saying this is how the Cookbook stuff will ultimately
work, but it shows how it *could* work, and still remain 
extremely markup friendly for authors.

(If we want the first rule to only capture specific properties
instead of anything beginning with a capital letter, we simply
list the specific names we want to capture in the markup rule 
instead of using the [A-Z]\\w+ pattern.  Or we let the StoreProperty
function make that decision for us.)

Pm