[Patch] WikiProcessors lacks detailed help

[Mikael Relbe]

I've recently discovered the detailed help-feature of WikiMacros, which is activated by adding a question sign (?) after a macro name. Example:

[[TitleIndex?]]

This will show the detailed help, instead of the result. This is very handy during side-by-side edit to quickly find out the details of the macro.

This feature does not work for WikiProcessors, which would be a-nice-to-have feature, and natural since a processor really is a macro. Example:

{{{
!#TitleIndex?
}}}

This yields the normal output and not the help information as intuitively expected due to the behaviour of WikiMacros.

It would also be nice if all in-built processors (div, span, table etc) are capable of providing help information that could be brought up during side-by-side editing.

[Remy Blank]

Nice idea! Note that, while all macros are WikiProcessors, not all WikiProcessors are macros. But that shouldn't prevent implementing your idea.

Want to give it a go? Then set the milestone for your expected timing. Otherwise, you can set it to next-major-0.1X.

[Mikael Relbe]

t10201_wikiproc-help_r10730.patch​ is my take on this.

Help information is provided for wiki macros when using wiki processor syntax by adding a question sign (?) after the name. Help information are not provided for built in processors.

This is perhaps a first step towards a more complete solution, which would involve extending built in processors to provide help information, if we think that's necessary.

I think this patch should be applied anyway. What do you say?

[Mikael Relbe]

Replying to rblank:

Note that, while all macros are WikiProcessors, not all WikiProcessors are macros.

I fully understand that now, after digging around in the code :)

[Mikael Relbe]

Apply on trunk r10730

[Remy Blank]

Replying to mrelbe:

I think this patch should be applied anyway. What do you say?

Yes, the patch looks good on a first read. I'll apply it (hopefully tonight).

The documentation for the built-in processors could be placed in the docstring of the respective processing function. The difficulty will be for the MacroList macro to find the info.

(Temporarily putting on my to-do list.)

[Remy Blank]

After testing the functionality, I find the current behavior rather confusing:

• While macros can indeed be used as wiki processors, for most macros it doesn't really make sense to use them as such.
• The documentation is shown with [[Macro()]] syntax, which is confusing when you are looking for info about a {{{#!wikiprocessor}}}.

A wiki processor can either be:

• Built-in
• A macro
• A mimeview renderer

Only the documentation for the first and last items are really useful in a processor context. Instead of the current approach, I would suggest the following:

• Create a "processorlist" wiki processor that is "forced" when the name of a wiki processor is followed by "?" (as you did for the "macrolist" processor).
• Collect documentation from built-in processors and mimeview renderers, but not from macros. For the former, it could be the function docstring. For the latter, you may have to extend the IHTMLPreviewRenderer interface with a get_renderer_description(mimetype) method that returns the description for the given MIME type.

Now, the IHTMLPreviewRenderer is marked as pending deprecation in favor of IContentConverter, so I'm not sure extending it is a good idea. Moreover, it doesn't support enumeration of supported MIME types, so you won't be able to get the full list of supported wiki processors.

Thoughts?

[Mikael Relbe]

Replying to rblank:

After testing the functionality, I find the current behavior rather confusing:

I agree that the relationship between wiki processors and macros is confusing.

• While macros can indeed be used as wiki processors, for most macros it doesn't really make sense to use them as such.

I created this ticket when I was working on the box-processors in ​th:WikiExtrasPlugin, which offers some intricate options which are hard to remember.

• The documentation is shown with [[Macro()]] syntax, which is confusing when you are looking for info about a {{{#!wikiprocessor}}}.

Agreed.

A wiki processor can either be:

• Built-in
• A macro
• A mimeview renderer

Only the documentation for the first and last items are really useful in a processor context. Instead of the current approach, I would suggest the following:

• Create a "processorlist" wiki processor that is "forced" when the name of a wiki processor is followed by "?" (as you did for the "macrolist" processor).
• Collect documentation from built-in processors and mimeview renderers, but not from macros. For the former, it could be the function docstring. For the latter, you may have to extend the IHTMLPreviewRenderer interface with a get_renderer_description(mimetype) method that returns the description for the given MIME type.

But how do we provide help info when a macro is called using the processor syntax? This was my original request, with the aforementioned box macros/processors in mind.

Now, the IHTMLPreviewRenderer is marked as pending deprecation in favor of IContentConverter, so I'm not sure extending it is a good idea. Moreover, it doesn't support enumeration of supported MIME types, so you won't be able to get the full list of supported wiki processors.

Thoughts?

The defalt behaviour of the MacroList macro is to show nothing when no documentation is found for a macro. The default behaviour is the same here for wiki processors.

However, I do agree that documentation should be added for built in processors and mimeview renderers, though we have to consider i18n as well.

But I really want documentation to show up when the {{{#!macro?}}} syntax is used. Macros could be excluded when an overview is requested by {{{#!?}}}.

To be fully consistent with existing solution, a ProcessorList macro should be built in, analogous to MacroList, which could be used when rendering {{{#!processor?}}} and {{{#!?}}}. In case {{{#!macro?}}} is requested, the MacroList macro could be used, as demonstrated by the patch (but confusing since the documentation is shown with [[Macro()]] syntax; that has to be solved).

[Mikael Relbe]

Is it possible for a plugin to define a wiki processor?

[Remy Blank]

Replying to mrelbe:

Is it possible for a plugin to define a wiki processor?

Right, you've nailed it. No, there's no way to do that. You can define an IHTMLPreviewRenderer, but that's not the same. So your argument stands, and macros must be shown in the help as well.

[Mikael Relbe]

Replying to mrelbe:

Is it possible for a plugin to define a wiki processor?

Yes, by this patch: t10201_wikiproc-refactored_r10730.patch​ (Replaces former patch.)

A wiki processor is a Trac component of WikiProcessorBase. Wiki processors can be added by plugins. (Implementation of all existing built in processors moved to new module trac/wiki/processors.py)

The macro [[ProcessorList(processor)]] shows information about a wiki processor. [[ProcessorList(*)]] shows all processors.

However, the documentation is still shown with [[Name]] syntax when you are looking for info using {{{#!Name?}}}, unless a processor named Name is defined alongside with a macro of the same name (one such example is Span (wrong, span is a processor, only)).

Documentation is still not presented for mimeview renderers, but should be easy to add (I think, haven't checked the internals of mimeview yet).

What do you think? Am I on track? (I've merely just shuffled around existing code, no new bells'n'whistles really.)

[Mikael Relbe]

The re-factored processors work when using Trac normally, but test cases fails. I am going to fix that.

[Mikael Relbe]

The patch t10201_wikiproc-refactored_r10730.patch​ was updated (perhaps a bad thing to do, I'm just trying not to clutter up the ticket with bad patches, hope you don't mind me doing like this).

All formatter test cases are now ok (an error in the span processor was discovered and corrected).

[Mikael Relbe]

WikiProcessors re-factored. Apply on trunk r10730 (replaces former patch).

[Mikael Relbe]

t10201_wikiproc-refactored_r10730.patch​ was updated again (found another small issue).

[Mikael Relbe]

I think the patch is ready for review now. There are a couple of things that can be improved:

• The class WikiProcessor in trac.wiki.formatter should be renamed to something else due to the introduction of WikiProcessorbase class in the new module trac.wiki.processors. Suggestion for new name: WikiExpander.
• The macro ProcessorList is new, and its implementation is merely a copy-paste of the existing MacroList. This could be improved in order to reduce the footprint.
• Documentation is not presented for mimeview renderers.

[Mikael Relbe]

New approach, apply on previous patch

[Mikael Relbe]

New approach: t10201_wikiproc-refactored_r10730-2.patch​ to be applied on previous patch.

This approach, which you might find more tasteful, defines WikiProcessorBase as a descendant to WikiMacroBase to make it easy to code a wiki macro and/or wiki processor within the same class.

For documentation purposes, to be able to mix presented "macros" and "processors", an intermediate class WikiMacroProcessorBase is introduced as well.

The class hierarchy is:

class WikiMacroBase(Component)

class WikiMacroProcessorBase(WikiMacroBase)

class WikiProcessorBase(WikiMacroProcessorBase)

Only WikiMacroBase or WikiMacroProcessorBase objects are listed by MacroList macro, or by the shortcut [[?]] (not by {{{#!?}}}).

Only WikiProcessorBase or WikiMacroProcessorBase objects are listed by ProcessorList macro, or by the shortcut {{{#!?}}} (not by [[?]]).

Note that WikiMacroProcessorBase objects are listed for both variants.

The footprint of MacroList and ProcessorList is reduced compared to the former patch. The context "processor list" or "macro list" is messaged to the get_macro_description function (however, backwards compatible with 0.12 in the same spirit as args were recently introduced to the expand_macro function).

Try the following:

[[MacroList]]
----
[[ProcessorList]]
----
[[Span?]]
----
{{{#!Span?
}}}

Span shows up in documentation of both macros and a processors. Note that the presented example for span depends on the context.

Though all macros are processors, not all are presented as such; just those that are WikiMacroProcessorBase or WikiProcessorBase objects.

This means that all existing plugins providing a macro that are more suitable to be presented as a processor, or both, must be changed to inherit from either WikiMacroProcessorBase or WikiProcessorBase in the new module trac.wiki.processors.

I think I prefer this variant myself.

Thoughts?

[Remy Blank]

The last approach makes the most sense to me. We have made some efforts in the past to unify macros and processors, and this pulls in the same direction.

My only concern is the WikiMacroProcessorBase and WikiProcessorBase classes. AFAICT, they are only used to differentiate between macros and processors when generating the documentation. Can we find a less invasive way to achieve that, without requiring two additional classes in the hierarchy? Also, don't forget that macros don't necessarily derive from WikiMacroBase, they only have to implement IWikiMacroProvider. So the differentiation mechanism must somehow pass through that.

Still, great work! I would like to apply this as soon as the issue above is solved. If you would like me to suggest something more precise, would you mind pushing your Mercurial repository to e.g. BitBucket, so that I can pull your changes and build on them?

[Remy Blank]

Moving unfinished stuff post-1.0.

[Christian Boos]

Very interesting. I somehow managed to miss this ticket last year.

Sounds like material for 1.1 to me ;-)

[Ryan J Ollos]

Retargetting tickets to narrow focus for milestone:1.2. Please move the ticket back to milestone:next-dev-1.1.x if you intend to resolve it by milestone:1.2.