[pmwiki-users] Pre-announcing 2.2.0 non-beta release, new release manager

[John Rankin]

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/

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

- include a [[!package]] tag (or some other convention) on the page

I can then use Wikipublisher.Wikipublisher as a "test page" too, which
solves another problem.

Right now, the appropriate category to use is probably [[!recipe]]
or [[!skin]] for skin documentation.

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.


JR
-- 
John Rankin
Affinity Limited
T 64 4 495 3737
F 64 4 473 7991
021 RANKIN
john.rankin at affinity.co.nz
www.affinity.co.nz