Query: Is there anyway to put comments with \define pragma?

[@TiddlyTweeter]

Use case...

I'm using Jed Carty's Bob a lot. For my needs i define variant paths at the top of Tiddlers that do things so that I don't have to edit the actions individually ... for example ...

\define fldAt() .\Wikis\$(twName)$\tiddlers\
\define tidsAt() .\Wikis\$(twName)$\tiddlers\*.tid
\define sfName() tw_$(twName)$.html
\define sfTo() ..\..\..\..\pages\tw\tw\tw_$(twName)$
\define hmXp2() ..\twBOB\Wikis\$(twName)$\tiddlers\

<$set name=twName value={{$:/WikiName}}> ... etc

... whilst today I understand what the definitions mean its unlikely in 3 months I will.

My question is: is there a way to be able to add comments (one above each line) so later I can understand the definitions without having to look through the whole code below them?

I haven't seen any documentation on whether you can or workarounds.

Best wishes
Josiah

[Ton Gerner]

Hi Josiah,

When I create macros, I add documentation within triple backticks like so:

\define ...
code1
code2
\end

```
\define ...
code1
explanation code1
code2
explanation code 2
\end
```

Does that work in your case?

Cheers,

Ton

[@TiddlyTweeter]

Ciao Ton

Not really. But thank you. Someone might find that tip useful. In my case I don't need it visible. Its only when I'm editing I need to see it. Though I guess I could use a <!-- comment --> after the defines instead?

But the real issue in the use case is the problem of redundancy. By having two separate blocks (defines & defines with comments) you have to maintain both. It gets cumbersome if you twiddling with the defines and there are many.

I was really wondering whether there was a method of interspersing comments in the actual code.

Best wishes
Josiah

[Ton Gerner]

Hi Josiah,

See https://groups.google.com/forum/#!msg/tiddlywiki/ioUM6pEPUEk/9ROfb4jaAAAJ

Cheers,

Ton

[Eric Shulman]

On Monday, June 25, 2018 at 8:51:03 AM UTC-7, @TiddlyTweeter wrote:

I was really wondering whether there was a method of interspersing comments in the actual code. 

The pragma parsing syntax only allows whitespace *between* macro definitions.  Thus, as you have noted, using HTML comments in-between the macros does NOT work:

<!-- comment before definition -->
\define foo() bar

However, when using a multi-line macro definition, you can use HTML comments *inside* the macro itself:

\define foo()
   <-- comment inside definition -->
   bar
\end

But... this won't work if the macro content is intended for use in other TW syntax (e.g., as a parameter value in a widget call).

One approach that DOES work, is to define dummy "comment()" macros, like this:

\define comment() notes about foo go here
\define foo() bar

\define comment() notes about mumble go here
\define mumble() gronk

and... for readability, you can use dashes as the comment macro names to match the length of the macro being defined after it, like this:

\define ---() notes about foo go here
\define foo() bar

\define ------() notes about mumble go here
\define mumble() gronk

I think the best long-term solution is to update the core pragma parsing to allow HTML-style comments in between macros... but until then, the above method does work today even though it's a bit ugly and awkward.

enjoy,

-e

[@TiddlyTweeter]

Thank you Ton for the pointer.
Thank you Eric for the detailed explanation and useful example workarounds.

In my case I think that "Dummy" define pragma will do the job best till there is a better solution.

Many thanks!
Josiah

[@TiddlyTweeter]

Eric: I think the best long-term solution is to update the core pragma parsing to allow HTML-style comments in between macros... but until then, the above method does work today even though it's a bit ugly and awkward.

I raised an issue at GitHub https://github.com/Jermolene/TiddlyWiki5/issues/3340 though it must have been raised often before?

[@TiddlyTweeter]

For folk interested here is the BEFORE the discussion ...

\define fldAt() .\Wikis\$(twName)$\tiddlers\
\define tidsAt() .\Wikis\$(twName)$\tiddlers\*.tid
\define sfName() tw_$(twName)$.html
\define sfTo() ..\..\..\..\pages\tw\tw\tw_$(twName)$
\define hmXp2() ..\twBOB\Wikis\$(twName)$\tiddlers\

<$set name=twName value={{$:/WikiName}}> ... etc

and here is the AFTER that works ...

\define --------() Path to wiki's tiddler FOLDER

\define fldAt() .\Wikis\$(twName)$\tiddlers\

\define --------() Path to OPEN all .tid files for wiki

\define tidsAt() .\Wikis\$(twName)$\tiddlers\*.tid

\define --------() NAME single-file version of wiki
\define sfName() tw_$(twName)$.html
\define --------() PATH of single-file version of wiki

\define sfTo() ..\..\..\..\pages\tw\tw\tw_$(twName)$

\define --------() Open an EXPLORER of wiki at

\define hmXp2() ..\twBOB\Wikis\$(twName)$\tiddlers\

<$set name=twName value={{$:/WikiName}}>

footnote: the original has no blank lines. Google adds them. Dunno why.