[pmwiki-users] Pagelist documentation (was: fmt=#headerinclude)

[christian.ridderstrom at gmail.com]

On Wed, 24 May 2006, Patrick R. Michaud wrote:

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

When you say check, do you mean a last check that there is nothing in 
Cookbook.PageListExplained that isn't in PmWiki.PageLists?

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

Ok. This would however probably imply that an author reading 
PmWiki.PageLists on that page only see a brief description of the formats, 
together with a reference to Site.PageListTemplates for further details 
and documentation on the available formats. Is this ok, or do we prefer to 
keep all the documenation of PmWiki stuff inside the PmWiki/ group?

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

So at the very least it'd be important to have something like 'count=10' 
in all the examples.

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

I think we should really be using a consistent naming here. However, it 
should probably be based on what we write in normal english. So, do refer 
to the directive as the page list directive, or the pagelist directive?
Do we call the lists 'page lists' or 'pagelists'?  Since English isn't my 
native language I'd like some input here.

cheers
/Christian

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