Add anchors to each macro listed by [[MacroList]]

[Ryan Ollos <ryano@…>]

I have found that it would be useful to have anchors for each of the macros listed by the WikiMacros macro. I'd find this useful for cases were I am referring a user to a particular macro. Rather than writing See TicketQuery at WikiMacros#AvailableMacros, it would be useful to have a direct link to the macro, such as WikiMacros#TicketQuery.

This seems simple enough that I could probably implement it if the maintainers agree it would be a useful patch. I'd work on this over the weekend after #8810 is closed so that it could be added to the 0.12 release.

[Ryan Ollos <ryano@…>]

The macro I was referring to is [[MacroList]].

[Ryan Ollos <ryano@…>]

This would be similar to the anchors provided by the [[TracIni]] macro, e.g. TracIni#trac-section, and presumably I could use the code in that macro as a guide for implementing this patch.

[Remy Blank]

Good idea, please go ahead! And change the milestone to 0.12 when you attach your patch.

[Christian Boos]

But even before that, it would be good to check if the feature is not already implemented ;-)

See e.g. WikiMacros#TitleIndex-macro.

[Remy Blank]

I assume Ryan would have noticed when he would have started on the implementation :-)

[ryano@…]

Replying to cboos:

But even before that, it would be good to check if the feature is not already implemented ;-)

I didn't realize there was an anchor here because I was looking for the little icon that appears when hovering over, for instance, TracIni#trac-section. In that case, a tooltip is also displayed that reads Link to this section.

Would others find it useful to have the icon that appears when hovering over the wiki macro title? (Not sure what the technical term for that icon is).

Is there another way I could know that the anchor exists? If not, I would definitely vote for adding the hover-over icon and tooltip, and am willing to implement a patch.

[ryano@…]

Also, if we do go ahead with a patch, would it be appropriate to target for 0.11.6 if I complete over the weekend? It seems like this shouldn't break anything, and is similar in nature to #5758, which was incorporated into a minor release.

[Ryan Ollos <ryano@…>]

Minor changes to MacroListMacro and TracIniMacro

[Ryan Ollos <ryano@…>]

Okay, I gave it a shot. I appreciate any feedback.

Changed each macro to be listed as a level 3 heading. Did the same for the TracIniMacro since it is contained within TracIni#Reference which is a level 2 heading.

I hope its alright if I reopen for feedback. I changed the version to 0.12dev since that is what I developed the patch against.

[Remy Blank]

I like the idea of having the section markers, and your patch is a good start. But in the current state, it doesn't pass XHTML validation, due to the <dd> tags.

I suggest the following changes:

• Don't wrap the description in a <dd>. It's not necessary, because the description is already a list of valid block elements.

• Wrap the title texts in <code> tags, as was the case for [[MacroList]], and add the same to [[TracIni]] for consistency.

[Remy Blank]

Any news on this (re. comment:9)?

[anonymous]

Replying to rblank:

Any news on this (re. comment:9)?

Yes, I plan to work on this by the weekend. Sorry for the delay, my company just finished a big milestone, and also I'm not a web developer so it will probably take me a little time this weekend to get it working. Thanks for your help!

[Ryan Ollos <ryano@…>]

Replying to anonymous:

Replying to rblank:

Any news on this (re. comment:9)?

Yes, I plan to work on this by the weekend. Sorry for the delay, my company just finished a big milestone, and also I'm not a web developer so it will probably take me a little time this weekend to get it working. Thanks for your help!

Sorry for another delay. I'll work on this the 26th or 27th.

[Ryan Ollos <ryano@…>]

Patch implmenting suggestions from comment:3

[Ryan Ollos <ryano@…>]

Replying to rblank:

I like the idea of having the section markers, and your patch is a good start. But in the current state, it doesn't pass XHTML validation, due to the <dd> tags.

I suggest the following changes:

• Don't wrap the description in a <dd>. It's not necessary, because the description is already a list of valid block elements.

• Wrap the title texts in <code> tags, as was the case for [[MacroList]], and add the same to [[TracIni]] for consistency.

I attempted to implement these changes in macro.py.patch2. Please let me know what you think.

On a side note, I setup the development environment as described in TracDev/DevelopmentEnvironmentSetup. I start tracd using:

sudo tracd -r --port 8000 test

I found that I fairly frequently had to kill and restart tracd because the changes I made to macros.py were not being automatically refreshed. Any idea of what could be wrong with my setup?

[Ryan Ollos <ryano@…>]

Two other issues:

• milestone:0.12 says that Genshi's trunk is required ( ​[G1072] or more recent). TracDev/DevelopmentEnvironmentSetup#Wheretogoformoreinformation says that the branch Genshi advanced i18n should be used with the Trac trunk. Are these two statements in conflict, or am I misreading this?
• After I updated Genshi to the latest trunk version, running setup.py for Trac was failing because the version of Genshi was listed as 0.6dev-r0. Manually editing Genshi.egg-info/PKG-INFO to Version: 0.6dev-r1092 seemed to solve the problem, but I suspect I was doing something wrong in configuring the development environment.

[Remy Blank]

Nice job, Ryan! Patch applied in [9000]. I had to fix the test cases for the recently-added [[Macro?]] syntax, though.

One general comment: please make sure you use spaces for indentation, and not tabs. The last patch had a few tabs.

About your other issues:

• If you run tracd with the -r option, changes to the source code should be detected, and a message like the following should show that the server was restarted:

  Detected modification of /home/joe/src/trac/trunk/trac/wiki/macros.py, restarting.
  

• You don't need to run tracd as root with sudo, just run it as a normal user.
• I have removed the note about the advanced-i18n branch of Genshi in TracDev/DevelopmentEnvironmentSetup@16.
• The 0.6dev-r0 is due to your Setuptools not liking Subversion 1.6. You should update Setuptools to ≥0.6c11, or better, use Distribute.

[Ryan Ollos <ryano@…>]

Replying to rblank:

• You don't need to run tracd as root with sudo, just run it as a normal user.

Thanks for the suggestions. I haven't seen the issue since changing the permissions on my tracdev directory from root to a normal user, and starting tracd without the sudo command.

[Ryan Ollos <ryano@…>]

Replying to rblank:

One general comment: please make sure you use spaces for indentation, and not tabs. The last patch had a few tabs.

Previously, several time when I was editing macros I would make a minor change were I was almost certain the syntax was correct and Trac would say that the macro could not be found. It was quite frustrating …

I haven't seen this at all since I started following your suggestion, so now I'm thinking this might have been due to using tabs. Would you expect that whatever parses the macro to fail in certain cases were there are tabs in the macro? Is this a general rule in python, or something specific to Trac?

[Remy Blank]

Replying to Ryan Ollos <ryano@…>:

Would you expect that whatever parses the macro to fail in certain cases were there are tabs in the macro? Is this a general rule in python, or something specific to Trac?

That's Python-specific, and due to the fact that in Python, indentation matters. If you have tabs in your source code, Python has to guess the tab width, and if you have a mix of tabs and spaces for indentation, it guesses wrong.

[Ryan Ollos <ryano@…>]

Replying to rblank:

• The 0.6dev-r0 is due to your Setuptools not liking Subversion 1.6. You should update Setuptools to ≥0.6c11, or better, use Distribute.

The upgrade of setuptools did fix the issue. Regarding Distribute, I didn't see any reference to that in TracDev/DevelopmentEnvironmentSetup. Is the use of Distribute documented somewhere else? I searched around the Trac wiki, but didn't find any documentation with reference to this package.

[Remy Blank]

Distribute is a drop-in replacement for setuptools.

(Please ask such questions on the MailingList, and keep discussion on tickets on-topic. Thanks.)

[Ryan Ollos <ryano@…>]

Changes made just now on TracIni page are associated with this ticket: wiki:TracIni?action=diff&version=164

[Ryan Ollos <ryano@…>]

I stumbled upon a related issue today. With many macros installed, the WikiMacros page becomes fairly long, and it would be nice if the PageOutline allowed for quickly jumping to the documentation for the macro that one is interested in.

However, the macros are not listed in the PageOutline, even though they are level-3 headings.

The heading Available Macros does show in the PageOutline, and its html is:

<h2 id="AvailableMacros">Available Macros</h2> 

However, the Image Macro does not, and its html is:

<h3 id="Image-macro"><code>[[Image]]</code></h3>

Is the PageOutline macro mis-behaving in this case?

Would you want the macros to be listed in the PageOutline? I for one would find it to be useful.

[Ryan Ollos <ryano@…>]

For that matter, it might be even nicer looking if we could somehow use the anchor name, e.g. Image-macro, perhaps after removing -macro, for the entry in the PageOutline, rather than e.g. [[Image]].

[Christian Boos]

This is because the MacroList macro output is "transparent" to the formatter used by the PageOutline macro. Once we produce some kind of structured output when parsing the wiki markup (#4431, at the top of my list for the next major release), all kinds of new features become possible:

• the page outline can contain headings generated by macros or embedded blocks
• the page outline can be restricted to some scope (e.g. generate page outlines of levels 3-4 for the current level 2 section)

See #4140 for discussing the specifics of the PageOutline macro in the context of the WikiDom.

Then also have a look at 0.12/WikiMacros, which shows the newly introduced short list of macros: [[MacroList(*)]] (or [[?]]). I could modify that one to add a (more ...) link for each entry, leading to the appropriate WikiMacros#<name>-macro.