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

Petko Yotov 5ko at 5ko.fr
Wed Jan 21 01:29:05 CST 2009


I am changing this threat title as I hope to hear the opinions of more users 
and recipe authors. More of my comments are below.

On Tuesday 20 January 2009 01:18:10 John Rankin wrote:
> On Tuesday, 20 January 2009 11:21 AM, Petko Yotov <5ko at 5ko.fr> wrote:
> >On Monday 19 January 2009 21:44:49 John Rankin wrote:
> >> - include a wikilib.d directory as part of each package with
> >>   that package's documentation; activating the package would
> >>   automatically look for a wikilib.d directory and add it to
> >>   the wiki page directory array (could be done by the package
> >>   itself
> >
> >Several recipes, like some skins of HansB, are shipped with some config-
> > or content- pages in a custom PageStore directory. The same way recipe
> > authors can add documentation in wiki files.
>
> The PublishPDF library does this too, to distribute Site.XXXTemplate
> files that support various form-based interactions using the wikiforms
> recipe. But so far I haven't used this approach for documentation.
>
> >> - adopt a convention that package documentation will be in a
> >>   PmWikiPackages group, so the PmWiki.Packages page can use a
> >>   (:pagelist:) to point to package documentation that forms
> >>   part of a pmwiki distribution
> >
> >Or in Cookbook/, Site/ groups (or PmWiki/ and PmWikiFr/, PmWikiDe/ for
> >translations), but have an additional category, a tag or a
> >message.
>
> A standard category (e.g. [[!package]]) makes a lot of sense -- then a
> visit to Category.Package will "just work" (as long as people know and
> follow the convention). Good thought!
>
> >FWIW, my own recipes are downloaded with no included documentation. It is
> >simpler for me to prepare them, and I can at any time improve the
> >documentation on pmwiki.org. If the user finds no docs on his wiki, he'll
> > go to pmwiki.org, get the latest infos, read comments and possibly see
> > that he may/must upgrade.
>
> That's the approach I took with PublishPDF, only the documentation is now
> big enough that I also set up a separate site at www.wikipublisher.org.
> What I was missing was a good way to include brief documentation that the
> casual reader would find but wouldn't inadvertently interfere with other
> things on the site. For example, wikipublisher.org has a Cookbook group,
> and other wikis may too, so including a Cookbook page doesn't seem like
> the right thing to do.
>
> Based on your comments and the module guidelines page, I'm thinking that
> what I'll do is:
>
> - 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).


About the page names, I have a slight preference to place them in existing 
wikigroups (or agree on a new, fixed wikigroup). It could be named 
PmWiki/RecipeThumblist2 for example, with a Recipe- prefix. If I have a wiki 
using pagelists and searches, and I have excluded the service/conf/doc 
wikigroups, and a recipes create new wikigroups, I'll have to re-edit all my 
pages containing pagelists.

Standardization of Recipes and documentation should be done after considering 
many things and side effects, and discussing with other users and recipe 
authors, I hope that they will participate.

That said, I'll probably continue to *not* include documentation for my 
recipes in recipe downloads, for the reasons I mentioned above.

> - link this to Cookbook.PublishPDF on pmwiki.org and to wikipublisher.org

Absolutely.

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


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

Thanks for pushing for improvements of PmWiki !!

Petko



More information about the pmwiki-users mailing list