Opened 4 years ago

Closed 22 months ago

# Add a level of indirection to TOC (with PATCH)

Reported by: Owned by: Adriaan de Groot a.degroot@… normal TocMacro normal a.degroot@…

### Description

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


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.

### Changed 4 years ago by Adriaan de Groot

Patch implementing indirect=

### comment:1 Changed 4 years ago by 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.

### comment:2 Changed 2 years ago by Ryan J Ollos

#3536 closed as a duplicate.

### comment:3 Changed 2 years ago by 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?

### comment:4 Changed 2 years ago by anonymous

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

### comment:5 Changed 2 years ago by Ryan J Ollos

Owner: set to Ryan J Ollos new → accepted

### comment:6 Changed 2 years ago by Ryan J Ollos

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

### comment:7 Changed 22 months ago by Ryan J Ollos

Owner: Ryan J Ollos deleted accepted → new

### comment:8 Changed 22 months ago by 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).

### comment:9 Changed 22 months ago by 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.

### comment:10 Changed 22 months ago by Ryan J Ollos

Resolution: → fixed new → closed

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

### comment:11 Changed 22 months ago by Ryan J Ollos

Owner: set to a.degroot@…

### Modify Ticket

Change Properties