Add a level of indirection to TOC (with PATCH)

[Adriaan de Groot]

I have a whole bunch of wiki pages that together make up the user guide for something. On each page of the user guide, I use the [[TOC]] macro to provide a table of contents for the whole guide:

[[TOC(UserGuide/)]]

This, hoewever, sorts the pages by page name, so in the table of contents the page Advanced shows up before Getting Started. I can fix the ordering by naming the pages in order:

[[TOC(UserGuide/GettingStarted, UserGuide/Advanced)]]

This has a downside: I need to repeat the list of pages everywhere and if I ever add a page (say, UserGuide/Beginner) then I need to go through and add that page all over the place.

You can kind of see this in action in the macro [[TracGuideToc]], which is a custom TOC that lists the relevant pages in order (probably other stuff, too, but here it's important that it lists pages in a sensible order, not alphabetical by page name, and is used all over the Trac guide).

The attached patch adds a keyword option to the [[TOC]] macro, allowing it to read the contents of a different page and use that as the page list, as if the contents were listed as individual pages in the macro call itself.

Example:

[[TOC(indirect=TOC/Guide)]]

This reads the wiki page !TOC/Guide and adds each line from it to the list of pages to display. Lines starting with # are ignored, so it's possible to put a little documentation / content on the page without affecting the resulting TOCs. Suppose that that wiki page contains the following:

# This is a TOC page for the User Guide
UserGuide/GettingStarted
UserGuide/Advanced

The lines that don't start with a # are treated as page names, so this is equivalent to

[[TOC(UserGuide/GettingStarted, UserGuide/Advanced)]]

Advantage is that you can change the page !TOC/Guide and all the TOC macros that refer to it through indirect= update as well; this means that the custom index macro can be replaced with a page listing the pages for the TOC in the right order and an indirect= parameter.

[Adriaan de Groot]

Patch implementing indirect=

[Adriaan de Groot]

The patch applies to my copy of TOC macro is is version = '11.0.0.3'; the line numbers may be a little skewed because I have applied the allactive patch from #12196 as well.

[Ryan J Ollos]

#3536 closed as a duplicate.

[Adriaan de Groot]

I've been using this patch in Trac 1.0.1 for .. more that 22 months now; would it be useful to update the patch for the current TRAC release?

[anonymous]

This plugin has no maintainer and needsadoption. Would you be interested to adopt it and becoming the maintainer?

[Ryan J Ollos]

I'll review the patch. Rebasing the patch on the latest 0.11 branch​ would be helpful.

[Adriaan de Groot]

Er .. sorry, should have replied instead of thinking "I'll get around to that". I can rebase to whatever makes sense right now -- why would 0.11 branch be the base to use?

As far as adopting the TOC macro as a whole, I could, although I'd put on a different hat to do so (not my work-work hat, but my Open Source hat).

[Ryan J Ollos]

In 16416:

11.0.0.7: Add from parameter for reading page list from another page

Based on patch by Adriaan de Groot.

Refs #12197.

[Ryan J Ollos]

The 0.11 branch should be forward compatible to at least the current 1.2-stable.

I renamed the parameter from indirect to from, which I hope is more descriptive of the behavior (i.e. from=page).