PITS /

01224: Enhance [[PmWiki/page list templates]] to process anchors

Summary: Enhance page list templates to process anchors

Created: 2010-09-20 15:28

Status: Open

Category: Feature

From: simon

Assigned:

Priority: 4

Version: 2.2+

OS: n/a

Description

A proposal to discuss the design for, then provide the pagelist functionality using Page List Templates to process anchors in a page or pages.

The following extensions are suggested

enhance order by adding anchor for order=anchor
add variables {=$Anchor}, {>$Anchor}, {<$Anchor}, {=$Anchorspaced}, {$$AnchorCount}
enhance "template first" and "template last" to allow for (:template first {=$Anchor}:), etc
enhance "template each" to allow for a qualifier (anchor, name (the default if not supplied), group), eg (:template each anchor:), (:template each group:), etc, note the default (:template each:) is the current (:template each name:), aka "page" which would be more meaningful, but not consistent

An example

(:pagelist name=thispage anchor=* fmt=#mytoc:)

[[#mytoc]]
(:template defaults order=anchor:)
(:template first {=$Name}:)
!!!!  {=$Namespaced} table of contents
(:template each anchor:)
* [[{=$FullName}#{=$Anchor}|{=$Anchorspaced}]]
(:template last {=$Anchor}:)
{$$AnchorCount} sections
[[#mytocend]]

Note that this feature would be improved if anchors were generated automatically for headings in a page, especially if generated anchors were prefixed by a standard prefix (eg "a_", "a.", or "a:")^[1] that allowed them to be identified as having been generated. The anchor should include the "depth" of the heading in the prefix, eg "a.3.".

Question: Does this really need to be a pagelist feature? Or could it be something completely separate that lists anchors for a given page? In other words, are there use cases where listing anchors for multiple pages is needed? (And, if so, could it be handled by including some sort of (:anchorlist ...:) in the pagelist template?)

I believe that this is a case where augmenting an existing feature will provide benefits that can't be anticipated until people start using it. Personally I can see a number of potential benefits from having a pagelist being able to select similarly named anchors from across a range of pages.

simon October 10, 2010, at 05:21 PM