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

[Christian Ridderström]

On Wed, 21 Jan 2009, Petko Yotov wrote:

>> - include a page called Wikipublisher.Wikipublisher in the package's
>>   wikilib.d/
>
> I dislike multiple wikilib.d/ directories added by recipes, for these reasons:
> * Wikis using (good) custom PageStore solutions, may literally be broken if a
>   (badly written) recipe replaces the existing WikiLibs array with something it
>   considers universal.
> * In case the recipe is enabled for some groups or pages only, the docs will
>   magically disappear (unless they are in the same groups or pages).
>
> 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).

I prefer having a separate wikilib.d/ because it allows me to better use a 
version control system (VCS). It's typically possible to have several 
subdirectories belonging to different repositories, but it doesn't work 
having files from diffrerent repositories in a single wikilib.d/.

I often install PmWiki and some of the other stuff using VCS, I find it 
gives me better flexibility and control of what files and of which 
versions I have.

On a somewhat related note, at http://www.lyx.org, I'm using Subversion to 
also control the files in wiki.d/ -- so far I really like that approach 
althogh it's very annoying that line breaks aren't linebreaks inside the 
page files.  On that site I took a slightly different approach and 
imported all the PmWiki files into the repository that also contains all 
the page files. In fact, the entire site is available from a single 
repository for the purpose of making it easy to set up a mirror site.

As for PmWiki running slightly faster without many wikilib.d/, have you 
done any benchmarking?  And if there is a significant difference, perhaps 
caching the directory listings could help? Since the files in wikilib.d/ 
change so rarely, it probably make sense to maintain a separate index 
file for their contents.

>> 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.

Good point.

regards
/Christian

-- 
Christian Ridderström, +46-8-768 39 44            http://www.md.kth.se/~chr