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
Priority: 4
Version: 2.2+
OS: n/a

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

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

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

See also

  • NumberedHeaders   Display numbered headers, indented paragraphs and table of contents
  • PageTableOfContents   Adds a clickable table of contents to a page
  • 00027   Table of Contents
  • 00955   Automatic anchors for document sections

See also a remotely related discussion on the mailing list: [2] [3].