Formatter argument for macros

[jpereira@…]

Hi,

We've ran into a problem, where inside a macro provider we must know what kind of formatter has been used. More specifically, this occured when using the WikiTemplate plugin, it has to return unformatted wiki text for the OutlineFormatter, or formatted text for a Formatter.

In Trac's source, I found TODO comments, stating that you intend to pass the formatter to the macro renderer. One could easily pass an extra argument to the WikiProcessor constructor, but it seems like from there to the macro renderer, you'd have to break the API by adding an extra argument (or alternatively, adding an extra property to one of the objects passed into the function, like req).

We really don't want to break compatibility with your code, so what's your plan on this situation? Would there be any interest in an extra pair of hands working on this?

Thanks in advance,

• Jorge Pereira

[Christian Boos]

Well, right now the macros aren't even called in other formatters (only in Formatter).

But I agree that once the formatter is given to the macros as an argument, this can change. The API need to change, no question about that, so suggestions and requirements are welcomed at this point.

[jrp@…]

Hi,

Sorry for the delay in replying, but I'm not getting a warning email from the ticket system. We did have to hack so that macros would get called for the OutlineFormatter. Some thoughts about this:

• Macros that generate content, like WikiTemplate, really need to be called for other formatters. In our case, we needed it so we could break down the main Wiki page in multiple Included pages.
• Would it make more sense to pass the current formatter object as part of the enviroment? That'd mean no API change, but it doesn't look as "clean".
• Given the formatter object or its .flavor, the macro itself should know how to behave.
• It could be interesting that a macro would indicate to the processor that it'd be returning wiki text, and not formatted html. In the case of included files, that's quite important.

Thanks for listenning,

[Christian Boos]

With 0.11, macros have now access to the formatter instead of the request, as their first argument. That was part of the WikiContext refactoring, checked in in r4452. The request itself can still be obtained from the formatter, of course.

Replying to jrp@eufinity.com:

We did have to hack so that macros would get called for the OutlineFormatter.

Some thoughts about this:

• Macros that generate content, like WikiTemplate, really need to be called for other formatters. In our case, we needed it so we could break down the main Wiki page in multiple Included pages.

In 0.11, the WikiTemplate should render the wiki content relative to the parent (i.e. the current) content, I guess. So relative links within the template are relative to the page embedding the template, not to the template itself…

• Would it make more sense to pass the current formatter object as part of the enviroment? That'd mean no API change, but it doesn't look as "clean".

No, that doesn't work. Environment is "global", whereas the formatter is tied to some specific transaction (= thread).

An API change was the cleanest thing to do, in the long run (remember, this is still pre-1.0, so we don't need to add fancy methods like render_macro2 in order to preserve backward compatibility ;) ).

• Given the formatter object or its .flavor, the macro itself should know how to behave.

Well, the .flavor is one thing. There will be probably a output mime-type as well in the near future, so that, e.g. a LaTeX macro can simply pass its content through when rendering the Wiki page to LaTeX…

• It could be interesting that a macro would indicate to the processor that it'd be returning wiki text, and not formatted html. In the case of included files, that's quite important.

Yes, that's an approach worth considering.

Altough the Formatter argument for macros was done in r4452, I'm not yet closing the ticket, as the above shows that there are remaining open points here.

Also, see related #4431 and #3089.

[Christopher Lenz]

See also #4568.

[Christopher Lenz]

Replying to cboos:

An API change was the cleanest thing to do, in the long run (remember, this is still pre-1.0, so we don't need to add fancy methods like render_macro2 in order to preserve backward compatibility ;) ).

I tend to disagree here. While 0.11 is breaking backwards compatibility left and right already, we shouldn't use the “not 1.0 yet” argument for cases where providing backwards compatibility would not be hard to do.

In this case, I think it would've been better to add a second extension point interface or method, although I'm not yet sure about the naming (render_macro2 is admittedly ugly.)

[Christian Boos]

Ok, API reverted in r4621. render_macro keeps using a req as before (0.9 and 0.10) and there's now a new method expand_macro which takes the formatter as its first parameter.

render_macro itself is now deprecated and will be removed in a later release (probably 0.12).

I'll carry on with the few remaining details mentioned in comment:3 in #4431. The major point addressed by this ticket has been implemented.