[pmwiki-users] Documentation of Recipes (was: Pre-announcing 2.2.0...)

john.rankin at affinity.co.nz john.rankin at affinity.co.nz
Wed Jan 21 13:05:59 CST 2009


> I dislike multiple wikilib.d/ directories added by recipes, for these
> reasons: [...]
>
> I have a preference for adding the docs in the standard wikilib.d
> directory
> and not forcing a new one for two reasons:
> * it is simpler;
> * PmWiki runs slightly faster (considerably faster if 12 recipes add 12
> custom
> wikilib directories).
>
Could you lead me by the hand a little please? First, I note the
module guldelines state authors *should* use a local wikilib.d/
(although I agree with your reasons not to).

If we use the pmwiki/wikilib.d/ directory, how do recipe pages
get in there and how do we avoid their being over-written when
upgrading pmwiki?

In the case of PublishPDF, this is critical, as the Site.XXXTemplate
pages are data required to drive the configuration, rather than
being passive documentation pages. If they are not present, the
recipe doesn't work. I haven't been including documentation, but
I think it needs an introductory page.
>
> <snip>

>> - include a [[!package]] tag (or some other convention) on the page
>
>> Right now, the appropriate category to use is probably [[!recipe]]
>> or [[!skin]] for skin documentation.
>
> I prefer [[!PmWiki Recipe]] and/or [[!PmWiki Skin]]. Wikis could be used
> for
> other things like food recipes, or software packages and skins, we
> shouldn't
> occupy categories that might have other uses by the websites.

That's cool, although I also agree with the comment that some
site administrators may not like their categories to be augmented
in this way. Any suggestions?
>
>> Does this seem like a reasonable approach? If so, I can add it to
>> the module guidelines page. And I suggest somewhere in the PmWiki
>> documentation (i.e. in wikilib.d/) there could be a page that lists
>> pages in the [[!recipe]] category, so readers can discover what's
>> installed above and beyond the standard pmwiki distribution.
>
> Excellent idea, but let's first hear what others think. OTOH, if you are
> the
> author of the only recipe that ships with documentation, you can probably
> do
> what you feel is correct and common sense. :-)

I'll wait to see what others think.

JR





More information about the pmwiki-users mailing list