Modify

Opened 2 years ago

Closed 5 months ago

Last modified 5 months ago

#12197 closed enhancement (fixed)

Add a level of indirection to TOC (with PATCH)

Reported by: Adriaan de Groot Owned by: a.degroot@…
Priority: normal Component: TocMacro
Severity: normal Keywords:
Cc: a.degroot@… Trac Release:

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

Attachments (1)

indirect.patch (2.9 KB) - added by Adriaan de Groot 2 years ago.
Patch implementing indirect=

Download all attachments as: .zip

Change History (12)

Changed 2 years ago by Adriaan de Groot

Attachment: indirect.patch added

Patch implementing indirect=

comment:1 Changed 2 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 8 months ago by Ryan J Ollos

#3536 closed as a duplicate.

comment:3 Changed 8 months 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 8 months ago by anonymous

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

comment:5 Changed 8 months ago by Ryan J Ollos

Owner: set to Ryan J Ollos
Status: newaccepted

comment:6 Changed 8 months 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 5 months ago by Ryan J Ollos

Owner: Ryan J Ollos deleted
Status: acceptednew

comment:8 Changed 5 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 5 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 5 months ago by Ryan J Ollos

Resolution: fixed
Status: newclosed

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 5 months ago by Ryan J Ollos

Owner: set to a.degroot@…

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The owner will remain a.degroot@….
The resolution will be deleted.

Add Comment


E-mail address and name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.