Recent Changes - Search:
PITS /

01475: Community poll for PageList link/category arguments

Summary: Community poll for PageList link/category arguments
Created: 2021-12-25 06:22
Status: Closed, added for 2.3.0
Category: Feature
From: Petko
Assigned:
Priority: 55
Version: 2.3.0
OS:

Hello. This is to help us decide how to implement 2 additions to the PmWiki:PageLists.

Note: Any changes will not break existing installations, i.e. all your current templates and directives will continue to work like before. The changes are to add new features.

The poll is now closed. The solution implemented for 2.3.0 is:

  • link=PageA,PageB lists pages linking to "AT LEAST ONE" among PageA and PageB.
  • link=+PageA,+PageB lists pages linking to "BOTH" PageA and PageB.
  • category=Images lists pages declared in the [[!Images]] category
  • link=!Images will work the same way, but will not be documented or supported.

Thanks to all who participated. --Petko

Context

In PmWiki 2.2.x series, PmWiki:PageLists can have a link=Page argument that allows to list pages linking (targeting) to the specified page. This can be used to automate "backlinks", for example in category listings, and uses a very efficient page index so it is fast.

In PmWiki 2.2.x series, a category link [[!Images]] for the above purposes behaves exactly like [[Category/Images]], i.e. there is no way to differentiate when a page contains a category declaration or simply links to a category page.

Improvements

Two improvements have been requested over the years by experienced wiki users:

PITS:00908 A more flexible way to define multiple link targets, as in link=Page1,Page2, wildcard patterns like link=Group.*, and negations like link=Group.*,-*.RecentChanges

  • A cookbook recipe exists that does this: Cookbook:PageListMultiTargets. Such a functionality can now be added to the core.
  • A question was raised whether we should implement some of it differently, notably link=A,B vs. link=+A,+B.

PITS:00447 A way to list separately pages containing the declarative [[!Images]] category markup, or the normal link markup [[Category/Images]].

  • Like before, without breaking existing installations, link=Category.Images will list pages containing both [[!Images]] and [[Category/Images]]. We will add a new way to list one or the other.
  • This will require to rebuild the page targets attributes and the page index, either by editing then saving all pages containing categories, or using a script from Cookbook:ReindexCategories.
  • A question was raised whether we should reuse the link= argument, or create a new argument, e.g. category=.

Possible implementations

Please read the possible solutions and the rationale, and add yourself to the section which agrees with you. You can also comment, or suggest a different solution.

Multiple targets options

Option a): link=PageA,PageB should list pages linking to "AT LEAST ONE" among PageA and PageB. link=+PageA,+PageB should list pages linking to "BOTH" PageA and PageB.

This is how Cookbook:PageListMultiTargets currently works.

It is consistent with other PageList arguments such as name=PageA,PageB or group=Group1,Group2, although these are inclusive for obvious reasons (a page can have only one name and one group, but multiple links and categories).

Support:

  1. Petko (weak support)
  2. SteP
  3. Dfaure
  4. simon I prefer the extra functionality
  5. gb same as Simon
  6. DannyB I like this

Oppose:

  1. ...

Option b): link=PageA,PageB should list pages linking to "BOTH" PageA and PageB. There will be no way to list pages linking to AT LEAST ONE among many.

Note, link=+PageA,+PageB will still work if you formerly used the recipe.

This is consistent with how search terms work in pagelists and searches (ALL must be present). It is also simpler to write, and probably more intuitive.

Support:

  1. Petko (weak support) I like the simplicity, but I wonder if I would some day need the "AT LEAST ONE" case above.

Oppose:

  1. ...

Category options

Option 1): link=!Images should list pages declared in the [[!Images]] category

We reuse an existing link= argument, and the "!" prefix is the same as in the category link markup [[!Images]].

Support:

  1. SteP I like that it matches exactly what authors write inside square brackets. I wonder how scalable it would be if perhaps in the future PmWiki introduced other symbolic modifiers inside square brackets.
  2. simon (weak support) I agree with SteP, and I like the idea that having both link=! and category= provides more functionality

Oppose:

  1. Petko (weak oppose) I'm afraid it might be confusing as the exclamation mark "!" means "negation" in conditionals and templates, as in (:if !name HomePage:), although in the link=, name= and group= arguments the negation is a minus sign. It may be especially unreadable if there are multiple categories and negations like link=!Images,-!Media,-!Markup
  2. Dfaure I always had difficulties with the confusion between link and categories as those are not always incarnated thru real pages.
  3. simon on reflection I'd like to keep the concepts of page and tag (aka category) separate, even though I kind of like the idea of having both options available

Option 2): category=Images should list pages declared in the [[!Images]] category

A separate pagelist argument is easy to understand and intuitive to use. It will make the pagelist directives more readable.

Support:

  1. Petko
  2. kellerfrau
  3. Dfaure Cf. previous vote
  4. simon (strongly support) I agree with Dfaure that a category is not a page. Using page markup (e.g. link=) is just a work around or kludge that reuses an existing markup and conflates two separate concepts. Categories are tags, or classifiers, and not pages (and in fact a "tag" may not have a Category/Tag page in existence), this markup clarifies implementation decisions and separates the concept of tags from pages.
  5. gb for better readability
  6. DannyB

Oppose:

  1. ...

Comments

Your comments and suggestions are welcome.

Comment from NeilHerber December 27, 2021, at 02:36 AM : Although I have several fields in my farm, none of them use PageLists, so I have no strong (or even valid!) opinion on these proposals. However, I do support the continuous improvements that Petko has been making. Thanks!

I now realize that the group=ABC argument duplicates the name=ABC.* functionality, and this has never been a problem. The proposed category= function is even different from link=Category.*, so it is reasonable to have a separate argument. Petko December 29, 2021, at 08:07 PM

if a directive has, say, "link=" twice what is the outcome?

Like with name= and group=, the last one wins. However, if there is a links= argument (for people having previously used the recipe, per "not break existing installations"), that one will be copied into link=. So if you have both link= and links=, the last links= wins. --Petko December 28, 2021, at 06:29 AM