Wiki macros for generating `<div>`s and `<span>`s with classes

[Christian Boos]

My original request was:

I would like to have a wiki notation for highlighting sentences in a page, in a more striking way than just bold or italic.

Typical use cases would be for short words like "FIXME" or "TODO", that should immediately stand out from normal text, so that it would be clear that those are inlined comments to the text itself.

The proposed syntax would be: * TODO *

and would be rendered as: TODO

That particular example will be supported by the ​th:WikiGoodiesPlugin.

However, this ticket raises the more general concern that Trac core should have a macro that supports generating <div>s and <span>s with classes. This is even more necessary with 0.11, as there, the HTML processor blocks no longer support leaving elements open.

[Christian Boos]

patch against 0.9b1 (or close) for the proposed feature

[Christopher Lenz]

I think this kind of stuff should be provided as a generic wiki macro, for example:

[[Block(warning)]]
==== Attention ====

Make sure you have PySQLite >= 1.1 installed to use SQLite 3.x.
[[Block]]

and (possibly):

[[Inline(todo)]]FIXME: better explanation[[Inline]]

These would get rendered as opening <div> or <span> tags, with the argument as value of the class attribute. When the macros are used without argument, a closing tag is rendered. Alternatively, we could provide four macros named [[BeginBlock]], [[EndBlock]], [[BeginInline]] and [[EndInline]]. Not sure which is better here (verbosity vs clarity).

I don't think we should be adding any more specific syntax constructs for specialized kinds of blocks. Different folks have very different requirements here, so instead of adding bloat to the core syntax, I'd rather see us adopt a generic solution like the one proposed above.

[Christian Boos]

For the block syntax, I think I have a good idea: as the macro syntax already accept mimeview processors (e.g. [[html(...)]]), why not make it symmetrical, and allow blocks to call macros:

 {{{
 #!Block(warning)
 ==== Attention ====

 Make sure you have PySQLite >= 1.1 installed to use SQLite 3.x.
 }}} 

As for the notation proposed in this ticket, I think it's really a matter of verbosity vs. usability. Having to specify a todo style for a content saying also TODO would be a bit too verbose for most users. I'd prefer to have something shorter to type (and as expressive):

• [[Inline(todo)]]TODO[[Inline]] → bad, too verbose
• [[TODO]] → would be <span class="todo">TODO</span>
• [[WARNING: don't do that]] → would be <span class="warning">WARNING: don't do that</span>

That notation would feel very similar to the one used for macros.

[Christian Boos]

Another proposal:

[[todo]]
That would create a div with class="todo"
And it could contain a nested 
[[urgent]]
div with class="urgent"
[[/urgent]]
[[/todo]]

and:

[[todo]]That would create a span with class="todo" [[/todo]]

Using XML-like markup like <underline>...</underline> would be another option, but this would introduce backward incompatible changes.

[Christian Boos]

Yet another proposal:

[[div(todo, background: #dfc, border: 2px dotted #0d0)]]

That would create a div with class="todo",
and it could contain a nested 

[[div(urgent, font-style: italic)]]
div with [[span(underline)]]class="urgent"[[/span]]
[[/div]]

[[/div]]

which would be rendered:

That would create a div with class="todo", and it could contain a nested

div with class="urgent"

Of course, we should provide a standard set of classes that could be of general use (like todo, warning, … we already have system-message). Additional classes should be added in customized templates, so generally there wouldn't be a need to specify manually the CSS.

And the macro itself:

class DivSpanMacro(Component):
    """
    Begin (`div` or `span`) or end (`/div` or `/span`) a division or a span,
    using the first argument as the class name.
    
    The remaining arguments are optional and allow configuring directly
    the style of the rendered element. Each argument is a `key:value` pair.
    """
    implements(IWikiMacroProvider)

    def get_macros(self):
        for name in ('div', '/div', 'span', '/span'):
            yield name

    def get_macro_description(self, name):
        return inspect.getdoc(DivMacro)

    def render_macro(self, req, name, content):
        # /div or /span: end the block
        if name[0] == '/':
            return '<%s>' % name
        args = content.split(',')
        # div or span: we expect the 1st argument to be a class name
        if len(args) == 0:
            raise Exception("Missing class name.")
        html_class = args[0]
        keyval_re = re.compile('^([-a-z0-9]+):(.*)')
        quoted_re = re.compile("^(?:\"|')(.*)(?:\"|')$")
        style = {}
        for arg in args[1:]:
            arg = arg.strip()
            match = keyval_re.search(arg)
            if match:
                key = match.group(1)
                val = match.group(2)
                m = quoted_re.search(val) # unquote &#34; character "
                if m:
                    val = m.group(1)
                style[key] = val
        styles = '; '.join(['%s:%s' % x for x in style.iteritems()])
        style_attr = styles and ' style="%s"' % styles or ''
        return '<%s class="%s"%s>' % (name, html_class, style_attr)

[Christopher Lenz]

I don't agree about the builtin styles… if users need divs/spans with custom classes, they should be providing the CSS to do the layout. Also don't like allowing authors to specify inline styles, really.

Also, I still favor an explicit and somewhat more verbose syntax for blocks/divs:

[[BeginBlock(todo)]]
Bla bla bla bla
[[EndBlock]]

(I prefer the “block” to “div” as “block” is clearer about the intent IMHO.)

For spans, how about:

[[Inline(todo, I really need to do [ticket:123 this])]]

i.e. just include the text in the macro parameters.

We could provide [[BeginInline(todo)]] and [[EndInline]] for cases where spans need to be nested, which I think should be a really rare case.

Not stricly opposed to using “/” to end a block/span, need to think about that some more. :-P

[Christian Boos]

If you want to do:

[[Inline(todo, I really need to do [ticket:123 this])]]

then you'd need a recursive step of parsing, on the arguments. We do that elsewhere too (titles for example) but that's not optimal (also, I wonder if there wouldn't be an alternative solution for parsing titles without recursion).

Not being verbose was precisely what motivated me to fill this ER, because one can already do that being verbose:

[[html(<div class="todo">)]]
Bla bla bla bla
[[html(</div>)]]

So, not sure what do here… looks like a draw :)

[Christian Boos]

For the record, the latest version of the div & span macro (for source:trunk@2500​)

[Matthew Good]

I don't think that those keywords are relevant. Please do not make edits to the tickets here for testing purposes. There is a ​demo site for that.

[Pedro Algarvio <ufs@…>]

Have any of you seen ​WikiTemplates Plugin? I does what you want. Yeah, syntax aint that simple but it has much more potentiality.

[Chris Ryland <cpr@…>]

I'd vote for something drop-dead simple, such as

[[[ Normal Wiki text block, but formatted in a colored box like but in a different color, perhaps. ]]]

This could serve as pretty much anything: note, warning, todo, etc. Perhaps one could provide a small set of "icons" as called out at the start, e.g.,

[[[ #Note This is important. ]]]

That seems like the least syntax, and is easily remembered as parallel to .

[Chris Ryland <cpr@…>]

(Whoops, there are some missing triple-curly braces in that previous post.)

I'd vote for something drop-dead simple, such as

[ Normal Wiki text block, but formatted in a colored box like pre-formattet text but in a different color, perhaps. ]

This could serve as pretty much anything: note, warning, todo, etc. Perhaps one could provide a small set of "icons" as called out at the start, e.g.,

[ #Note This is important. ]

That seems like the least syntax, and is easily remembered as parallel to pre-formatted text.

[Christian Boos]

I think I'll move the original request over to my TracHack:WikiGoodiesPlugin …
(i.e. having * TODO * render as TODO)

As for the more general macro, well, I don't know, maybe I'll get a better idea later.

[Christian Boos]

See above, moved to ​TracHacks:WikiGoodiesPlugin.

[Christopher Lenz]

I do not agree with closing this. Being able to generate custom <div> and <span> elements in wiki text should be a core feature, especially now that HTML processor blocks no longer support leaving elements open!

[Christian Boos]

Well, I was referring to my original request.

Maybe should start a fresh ticket, don't you think?

[Christopher Lenz]

Seeing how all the relevant comments are in this ticket, and the summary has been adjusted, I don't think opening a new ticket would do any good.

[Christian Boos]

Well, OK, so I'll also adapt the description, to make this clear.

Any new idea on the topic, by the way?