Comments (and macro options) in macro definitions

[tobibeer]

Idea: To comment a macro definition line, the macro must be a multi-line macro.

So...

\define path(plugin) \\ Returns path to plugin
$(plugin-root)$/$plugin$
\end

The \\ above is literally superfluous, i.e. meaningless! You could as well do...

\define path(plugin) --> Returns path to plugin
$(plugin-root)$/$plugin$
\end

In fact, to not waste this opportunity, a certain syntax used at the beginning of the remainder on the definition line could be reserved for macro options, e.g.

\define path(plugin) {option:"value", foo:"bar"} | Returns path to plugin
$(plugin-root)$/$plugin$
\end

If you needed any more comments in your macro itself, chances are you will be able to use HTML-style comments after all.

\define complex(foo) | does quite a lot
<!-- NO FOO -->
<$reveal type="match" text="" default="""$foo$""">
really, no foo
</$reveal>
<!-- GOT VALUE -->
<$reveal type="nomatch" text="" default="""$foo$""">
indeed, we got foo
</$reveal>
\end

Groups Discussion

https://groups.google.com/forum/#!folder/TiddlyWiki/tiddlywikidev/BSBSUblhZbQ

[Jermolene]

Hi @tobibeer right now, if you include HTML comments in a macro definition two things can happen:

• If the macro is rendered with the macrocall widget or the equivalent shorthand syntax, then the HTML comments will be parsed and ignored as the macro is parsed
• If the macro is used as an attribute of an element or widget, then the comment will come through directly in the attribute

The reason for the difference, of course, is that in the second case the text of the macro is not parsed and wikified.

The proposal here would require the HTML comment syntax to be parsed when the macro definition itself is parsed. I think it would be unacceptably confusing to have the same syntactic structure parsed in two different ways.

So, we'd be left with something simpler: a special comment format for macro definitions. For example:

\define test(text) $text$ #ignore me, as well, dear parser
#ignore me, too
$text$
#and me, please ignore
\end

The trouble is that there is no restriction on the text of a macro (apart from not containing \end), so there is no character we can safely use without breaking backwards compatibility.

[tobibeer]

Although the parsing may be a tiny bit more expensive, html comments are as safe and can be equally as easily stripped as any other comment format.

The benefit of using html-comments would be that:

1. we already use them in tiddlers (unless we're looking at js tiddlers)
2. those complex macros that beg for comments are mostly those that contain html-like contents, so a html-style comment feels natural
3. we would not have to be concerned with anything like:

there is no character we can safely use without breaking backwards compatibility

[tobibeer]

So, there is actually no parsing, but a simple string-replace in the proposed approach:

would require the HTML comment syntax to be parsed when the macro definition itself is parsed

[Jermolene]

I agree that comments would be useful within macros, but we can't re-use the HTML comment syntax.

So, there is actually no parsing, but a simple string-replace in this:

That's another name for a simple parser :)

But the trouble is subtler: it's about the ambiguities of the same syntactic element being parsed differently in different places. Not to mention what happens if you want to use a macro to generate HTML comments.

We need a different syntax. It's muddling the layers to re-use the HTML comment syntax.

One possible way forwards that maintains backwards compatibility might be to use a character combination that is already caught by the existing (simple) parsing for $param$ and $(variable)$.

[tobibeer]

Not to mention what happens if you want to use a macro to generate HTML comments.

Why would anyone want to do that? If you want hidden stuff, there are other ways to go about that. No need to keep html comments alive to actually be rendered into, well, html.

I can sure think of a more elegant format over html-style-comments... but then we'd have the same thing as in TW2 where you would have a ton of variants, one for this place, one for that place, one for rendering, one not to.

[Jermolene]

Why would anyone want to do that? If you want hidden stuff, there are other ways to go about that. No need to keep html comments alive to actually be rendered into, well, html.

Because TiddlyWiki needs to be able to generate arbitrary HTML documents, and comments are an important part of HTML documents (they are used for much besides commenting, too).

The problem is really basic: macro syntax and HTML syntax are at different layers. They intentionally use different syntax so that they can be used together. Using the same syntax at different layers is confusing and brittle.

[tobibeer]

Ok, so we need another format. I take it, js style comments won't do for the same reasons?

I changed the OP to using /% ... %/... as an arbitrary placeholder for a comment format.

[tobibeer]

# would be no good as it is valid wikitext at the beginning of a line

anything involving $ would be very confusing

A single character sounds problematic to me, besides I would want to be able to use blocks, not just one-liners.

Maybe...

\% single line comment

/%
comment block
%/

[Jermolene]

That's right; macros to generate JS code are quite an interesting area, and I wouldn't want to close that off. An alternative might be \\ to match the backslashes used to introduce macro definitions.

So, we come to the second concern, which is backwards compatibility. But then again, perhaps we should be too concerned about that: an alternative might be to introduce a completely new syntax that establishes new rules:

\macro test(text) #ignore me, as well, dear parser
#ignore me, too
$text$
#and me, please ignore
\end

But I think there would need to be more improvements than merely comments to warrant such a change.

[tobibeer]

But I think there would need to be more improvements than merely comments to warrant such a change.

Why so?

Anyway, I think the TW2 syntax...

/% I am a hidden comment %/

...should work just fine, and possibly apply to wikitext as well... unless you're saying that we can't remove those from a macro, because "What if we want a macro to output wikitext comments?" I'd say: then we'd be entirely defying their purpose.

[tobibeer]

If you feel like you want to overload this in any way...

/%-{option: "value", foo:"bar"}- I am a hidden comment %/

We can sure do so, but it shouldn't be a barrier to getting basic comments going.

[tobibeer]

@Jermolene, changed the title.

[Jermolene]

...should work just fine, and possibly apply to wikitext as well... unless you're saying that we can't remove those from a macro, because "What if we want a macro to output wikitext comments?" I'd say: then we'd be entirely defying their purpose.

If we supported that same syntax within macro definitions and ordinary wikitext then we'd be back where we started, with a layering violation :)

Why so?

Introducing a new macro format has massive implications in terms of documentation and cognitive load for everyone who has to learn about it. I'd want to make that investment deliver more than just comments.

[tobibeer]

So what would be a good title for this issue?

[tobibeer]

Could be as simple as adding this to the right spot:

macrotext = macrotext.replace(/\/%((?:.|\n)*?)%\//mg,"");

[chris2fr]

It'd be nice de comment a macro above the macro.

@macro my-list Creates a list 
@param filter text The filter to be used 
\define macro my-list( filter )
<$list filter="""$filter$"""/>
\end

My example is a bit involved, and I don't even know if I would bother commenting as rigorously as that. Using the @ might confuse when we want to refer to people. ?, & or : might be a good comment characters? Now about tests... ;)

[chris2fr]

Hey, here is a different way of doing this

\define my-list:"Creates a list" ( filter:"text of the filter")

[chris2fr]

Or even less intrusive

\define macro:my-list ( filter:"text of the filter") "Creates a list"
\define my-list( filter)
<$list filter="""$filter$"""/>
\end

[tobibeer]

@chris2fr & @Jermolene,

I very much like the simplicity of a comment on the definition line!

However...

• We need no superfluous documentation macro.
• While anyone is free to use any, I think we would not need any quotes.
• If one wants to comment their macro definition line, the macro must be a multi-line macro!

So...

\define path(plugin) \\ Returns path to plugin
$(plugin-root)$/$plugin$
\end

The \\ above is literally superfluous, i.e. meaningless! You could as well do...

\define path(plugin) --> Returns path to plugin
$(plugin-root)$/$plugin$
\end

If you needed any more comments in your macro itself, chances are you will be able to use HTML-style comments after all.

\define complex(foo) | does quite a lot
<!-- NO FOO -->
<$reveal type="match" text="" default="""$foo$""">
really, no foo
</$reveal>
<!-- GOT VALUE -->
<$reveal type="nomatch" text="" default="""$foo$""">
indeed, we got foo
</$reveal>
\end

I updated the OP to reflect this idea.

[tobibeer]

@Jermolene, also added this to the OP:

In fact, to not waste this opportunity, a certain syntax used at the beginning of the remainder on the definition line could be reserved for macro options, e.g.:

\define path(plugin) {option:"value", foo:"bar"} | Returns path to plugin
$(plugin-root)$/$plugin$
\end

[buggyj]

may be we could use the widget syntax and remove all text between its tags when parsing the macro

\define amacro () <$comment> a comment widget could be removed</$comment> .... \end

[pmario]

@Jermolene .. This one can be closed. We do have comments in macro definitions.

[Jermolene]

Thank you @pmario