[pmwiki-users] fmt=#headerinclude

[Patrick R. Michaud]

On Wed, May 24, 2006 at 12:21:14AM +0200, christian.ridderstrom at gmail.com wrote:
> >How is that page intended to be any different from the
> >existing one at...?
> >
> >   http://www.pmwiki.org/wiki/Cookbook/PagelistTemplateSamples
> 
> I'll answer that by first listing the current pages I could find that are 
> related to pagelist. Here's the pages I found:
> 
> * PmWiki/PageLists		- primary doc. page of (:pagelist:)
> * Pmwiki/Directives#pagelist	- gives syntax of (:pagelist:)
> * PmWiki/DocumentationIndex	- just refers to PmWiki/PageLists
> * PmWiki/MarkupMasterIndex	- some syntax of (:pagelist:)
> 
> * PmWiki/PagelistsExplained	- redirected to Cookbook/PagelistExplained
> * PmWiki/PagelistExamples	- the page I suggested
> * PmWiki/PagelistVariables	- describes variables related to pagelist
> 
> * Site/PageListTemplates	- default page that defines formats
> 
> * Cookbook/PagelistExplained	- more details. Why in Cookbook/ ?
> * Cookbook/PagelistTemplateSamples - examples of user-defined templates,
> 				  as well as illustration of results
> 
> * Cookbook/PageList		- No idea... remove?
> * Cookbook/PageListWikiTrail	- separate recipe
> * Cookbook/PageListTemplates	- old recipe. depreceated. remove?
> * Cookbook/CompactPageList	- probably an obsolete recipe. remove?
> 
> This is quite a mess in my opinion... If it is possible, I'd suggest we 
> remove the recipe pages we can. Perhaps move the pages into a separate 
> group called CookbookOld/ or something.
> 
> I also don't see why 'PagelistExplained' is in the cookbook. I think 
> (:pagelist:) deserves a proper "advanced" documentation page. But maybe I 
> don't get the purpose of the page.

Cookbook.PagelistExplained was created before we had the documentation
in PmWiki.PageLists (in fact, much of PmWiki.PageLists was created based 
upon Cookbook.PagelistExplained).  When we created the PmWiki.PageLists 
page, we didn't eliminate the old page because they aren't exact 
duplicates.  I agree that it's now confusing to have both, so if 
someone wants to do one last check of Cookbook.PagelistExplained
and then remove it, that'd be great.

But as others have noted, there are a lot of "old" pages in the
PmWiki and Cookbook groups.  We don't necessarily want to remove
them entirely, because sometimes they have useful content, but maybe
we should get them out of the way of searches and the like.  I propose
that we create an "Archive" or "Attic" wikigroup where we can move
some of these older pages, and that pages in this group won't 
participate in the standard searches unless list=all is specified.

> My idea for PmWiki/PagelistExamples was that it would be a place to 
> illustrate the result of the pagelist formats defined that are defined by 
> *default* at Site.PageListTemplates. 
> [...]
> However, assuming there's no performance penalty in adding documentation 
> to Site.PageListTemplates about the formats supplied with PmWiki, maybe 
> that documentation should simply go *with* the actual format definitions.

I think it's more logical to document it in Site.PageListTemplates
(and no, there's no real performance penalty in doing so).

One of the things to remember about (:pagelist:) (and building
examples with it) is that (:pagelist) can be very expensive on the server
side.  This is why I've tended to keep working pagelist examples
in the Cookbook and not in the distributed docs, so that it hits
pmwiki.org's server and not everyone who happens to download PmWiki.

> As sidenote: I think we should have a bit more consistent naming of these 
> pages (PageList vs Pagelist). I'd prefer just 'Pagelist', since there is 
> no capital 'L' in (:pagelist:).

My tendency has been to use "Pagelist".  I went with "PageLists" for
the main documentation because it's really described as "page lists",
but we can change that as well.  :-)

Pm