[pmwiki-users] Documentation of Recipes (Eemeli Aro)
eemeli at gmail.com
Thu Jan 22 04:23:38 CST 2009
2009/1/22 <john.rankin at affinity.co.nz>:
>> I'll accept the argument if you (or someone else?) can give me at
>> least a couple of examples.
> Why isn't one example sufficient? "It doesn't matter
> because only one obscure site is affected"? I'm sure
> that's not what you mean.
Ah, ok. I was wrong. Or at least presented my opinions incompletely.
And indeed I didn't mean that "only one obscure site" could or should
be ignored. Here's a more complete account of my view on including
Cookbook documentation in local storage.
I see a relatively big step in difficulty between just downloading one
file to one directory and adding a command or two to a config file,
versus downloading some package of files and unpacking it to some set
of directories. For this reason I've avoided this path in my own
recipes, but I'll agree that for some recipes it's either necessary or
at least beneficial to include additional wiki pages or other files.
So we ought to have a mechanism or at least a guideline for handling
this, which should include having these pages be accessible from the
wiki in question, under some Group/Page structure. Now, I'm still of
the opinion that the default name for this Group ought to be
"Cookbook", but this ought to be parametrisable, which of course will
make installing new recipes trickier, which isn't a good thing. And
really, the name doesn't matter. I do, however, shy away from
constructs such as "PmWiki.Cookbook-RecipeName", as these add an
unnecessary third level to this page hierarchy. How about
As for the location in which to put these files, how about the
wikidoc.d directory PM mentioned sometime earlier? Or if we leave that
for just PmWiki documentation, adding them to wikilib.d might be
easier. Adding a new PageStore seems rather wasteful, except if
there's extra functionality that requires it.
As PM and others have pointed out, having a web-accessible interface
for adding and editing PHP files isn't a Good Thing. So how about a
command-line app? Give it a recipe name and it'll download a set of
files from pmwiki.org, read some local configuration parameters and
adjusting to those and the recipe's own setup put the right files with
the right names in the right places and the right stuff in the right
config files. Kind of an apt-get for PmWiki. This would also help with
keeping include() and other commands in the right order as well as
checking for any recipe updates and such. In fact, having a tool like
this might help with getting better information about the usage of
recipes as well (provided, of course, that the user in question is ok
Now I'm not saying that this'd be easy, having the thing work properly
across OSes and not mangle hand-tuned config files could turn out
rather tricky. In fact, it might be easier to have the same tool also
manage farm configuration, such that you could use it to eg. enable a
recipe only for a specific wiki on a farm, or to enable it for all but
configure differently for each. Indeed, the mess of config files*
required for a multi-wiki setup could do with some regularisation.
[*] On one of my servers, I have 20 wikis making up 4 sites with a
total of 18 subsites (2 bilingual). These first read a common
farmconfig.php file, then a local config.php file, which calls a
common farmauthconfig.php file; this means that I can configure user
account stuff locally for each, effectively letting me do local and
global configuration both before and after including authuser.php. My
WikiLibDirs array also includes a PageStore that's writable from each
of these wikis for common things such as Site.EditForm, which some of
these wikis of course overwrite locally. In other words, it's a mess,
but I can't think of a better way.
More information about the pmwiki-users