A new \rem pragma?

I suggest a new pragma : \rem which would only be useful to add a comment anywhere without any side effect whatsoever. Thus, it would still be possible to use it anywhere, even where other pragmas are useless.


\rem this function is a kludge
\function wotItOut() [[nice stuff indeed]]

I really miss a way to add comments.

If possible, a shorter form of the \rem pragma would be \\ which would be more readable. Or \#. Compare:

\\ this function is a kludge
\function wotItOut() [[nice stuff indeed]]

\# this function one is bugged
\function troubles() [[buggy stuff indeed]]

1 Like

See “Pragma Comments” at https://tiddlywiki.com/#HTML%20in%20WikiText


Thank you @saqimtiaz !

But this <!-- comment --> pragma is not described in the offical doc for “pragmas” nor in searching “pragma”.

Besides, I thought a pragma was to be initiated by a \ as all described pragmas are. And as is stated in the “pragmas” tiddler of the doc:

Pragmas occupy lines that start with `\`.

Would it not be a good idea to call it otherwise than pragma comments?

\rem This is sweet

<!-- This is pig-ugly  (sorry, pigs) -->

Though I’d prefer \\ if it’s possible, then this becomes possible in a keystroke…

\\ Testing without rules
\\rules blah blah blah

Pragmas comments are said such that “Comments can now be freely intermixed with pragmas as well as within the main body of a block of wikitext.”

Well. not within a filter run inside a pragma! The following code is broken just because of the pragma comments.

\function .firstLevel(depth)
  <!-- Since we start at depth=1 for the root part, we don't subtract one to the root of subparts for comparison. -->

This code work OK:

<!-- Since we start at depth=1 for the root part, we don't subtract one to the root of subparts for comparison. -->
\function .firstLevel(depth)

But the comments is not where we would want it to be. Still, better than nothing!

Really, I think we need to work hard on the doc. But going the way of tickets is not efficient. Going the way of a wiki with history like mediawiki is a better way. A tiddlywiki with history could be great too, but anyway we need an overhaul of the dooc before we have that history!

That’s what the words “within the main body of a block of wikitext” is trying to convey: these comments are only part of wikitext syntax, and thus not part of the (different) filter syntax.

The discussion about comments in the “pragma section” of a tiddler is long over and the final version has been published with v5.2.0 from Oct. 2021.

The functionality is there since 2 years now.

The add pragmacomment wikirule #5287 pull-request and it’s discussion has been the initial suggestion
which was replaced by Add “commentpragma” html style rule #5726 which got merged into TW v5.2.0

Clearly not.   

calling it pragma comment is missleading. If I can’t comment a function, then is that really a pragma comment? See the doc example with a classic macro: it should have been possible. It’s quite possible that functions did not exist at the time of writing. But now they do.

And they need comments within their code.

a comment filter op that does nothing could help if nothing else. That would also be a nop filter op. Let’s see:

\function .firstLevel(depth)
  +[nop[Since we start at depth=1 for the root part, we don't subtract one to the root of subparts for comparison]]

Still, that’s a kludge.

@pmario. That’s quite possible. But this is not b reason per se not to ask it again if enough things have evolved since then. Adding functions and procedures qualify as a lot of things IMHO.

May I recall that I ask for comments pragma because of sublety inside a function? Is that not a legitimate reason to ask for them?

Hi @jypre it sounds like what you’re asking for is a way to embed comments within filter expressions (and thus functions). That’s a reasonable request, and something that’s come up before.

The filter comment syntax doesn’t need to look like an operator. It could be a any string of characters that would not naturally occur in a filter.

One possibility might be to extend the existing support for HTML-style comments <!-- comment -->, but I wonder whether it might be a mistake to make it easier for people to confuse filters with wikitext.

Some simple options would work well in situations where filters can be spread across multiple lines – for example, we could support -- comment at the end of lines:

-- Since we start at depth=1 for the root part, we don't subtract one to the root of subparts for comparison
1 Like

I find it counter intuitive to have comments inside a filter, because unlike inline procedures, macros and custom widgets they have a very specific syntax. It would be similar asking for comments inside a variable;

<$let name="value <!-- comment here will not work -->" 2ndname="yes">

where you can do this

<$let name="value" 2ndname="yes"> <!-- comment herewill work -->

or even this

<$let name="value" 2ndname="yes" note="The values set the operation of the next section"><!-- note here will work -->**strong text**

So I have also used comments like this;

\define note()  
you can define the same "variable multiple times", only the last is valid, but if you never use `<<note>>` who cars.
\function myfilter() [tag[TableOfContents]]
<!-- filter above contents top tiddlers -->
\procedure my-proc()
<!-- comments here work but may alter block or inline mode -->
\end my-proc
\define note() Anything else you want here
\define note() <!-- Anything else you want here is more obviouse in comments -->
\function myother.function() [tag[About]]

If we introduced a comment that is allowed inside a function, we need also to permit that being escaped.

Other options would include /* */ // but honestly intuitivly I do not think functions should inculde comments. Although here is a work around.

\function .note(note) [match[neverhappens]then<note>else<currentTiddler>]
\function my.function(tag) [tag<tag>] +[format:titlelist[]join[ ]] ~[.note[Place a documentation note here]]

<$list filter="[my.function[TableOfContents]enlist-input[]] ~[[another note of no consequence if result never empty]]" >


The above is just a proof of concept, here I use the short else ~, it also trys and pass through titles if the result is title(s) (not in this example) but more research is needed.

This makes me ask what if we introduce a :note filter run prefix that does absolutely nothing?

\function my.function(tag) [tag<tag>] +[format:titlelist[]join[ ]] :note[[Place a documentation note here]]

Finaly if you do want to use <!-- comments --> this provides an editor toolbar button to wrap and unwrap selected text with comment braces. editortoolbar-comments.json (1.4 KB)

I do this at the top of many macro tiddlers:

\define COMMENT()



Good thing is, even if they’re “all” in play, you only end up with one.

If the truth be knoiwen I do not do this commenting as much as I could but I do try and make the code self documenting. I have not tested it in public except for my posts here, and I dont get a lot of feedback (Could be good, could be bad?). But my own self documenting seems to work for me reading my own code at least.

@TW_Tones I think your :note proposal is the best idea on the subject as far as filter are concerned. Work fine for me!

Most of my code is undocumented as finnally pretty logical. But sometimes as in my given examples, they are counter-intuitive and dessert a short confirmation that what is written is really intended and not a bug. And the note should be near to the problem.

If you are going to add comment for function and macro, I would suggest store them with the variable. So we can get comment when serving autocomplete in TW5CME — CodeMirror Editor Enhanced Framework for TiddlyWiki5

@linonetwo I’m sorry but I don’t see what you mean. Could you provide an example? I was unable to get help from your link.

I think what @linonetwo is saying is that it would be useful if these comments could be accessible to autocomplete mechanisms. This would allow to editors to display a popup hint when the user has typed a function name. The suggestion is that the comments be stored within a new field in the internal representation of a variable.

That implies that there would be a structured syntax for attaching comments to variable definitions. For example, we could use your suggestion of \rem or perhaps \doc, perhaps requiring it to be placed at the top of the definition:

\function left-to-upside(a,b)
\doc This function reads from the left hand column and writes to the upside down column

Spooky timing.

I’m doing (now completed) this:

<!--$ left-to-upside
  @param a <number> The first number to be added to...
  @param b <number> The second number.
  @comment Filter op. Adds two numbers.
\function left-to-upside(a,b)
\doc This function reads from the left hand column and writes to the upside down column

Example display:

1 Like

It may make sense if creating a new pragma such as the \doc pragma above to consider if more features can be added.

For example an option have the content of the doc tiddler be displayed when viewing the tiddler “rendered”, perhaps support for documenting syntax like the parameters defined in the parent pragma and the default values.

An example may be \doc syntax: <<proc p1:"">> allowing later in the tiddler to use <<doc syntax>> to display all doc lines with the prefix syntax so you only need to type this once and can choose if its visible as well. A wikify option as well.

  • We can also use custom parser on a tiddlers text to display all lines prefixed ‘\doc’ or specifically ‘\doc syntax’
  • We can also makes a self documentation tiddler that seeks out global tiddlers and extracts a summary in \doc pragma.

I started to build a similar mechanism inside comments like this;

title: My macros is for ...
syntax: How to call as a macro ...
syntax: How to use in a filter ...

Then scan the tiddler for comments and display the lines beginning keyword: in the order they are found.

  • I gave up when doing this because it was the development of a unilateral standard and they are rarely adopted by the community.
  • Perhaps this is the opportunity to develop a community standard for better self documentation.