Is it possible to remove duplicate wikitext code when showing both codeblocks and the result of rendering them?

#1

I hope this isn’t a "premature optimization"™ scenario, but I’m wondering about duplicate wikitext code in my documentation tiddlers. I’ll explain with an example.

Consider a tiddler named New Tiddler. I want to document how functions work. I start with a simple wikitext snippet:

\function multiply-by-two(number)
[<number>multiply[2]]
\end

<<multiply-by-two 4>>

I want to show the code in the tiddler, then show its effect. So I copypaste everything:

\`\`\`
\function multiply-by-two(number)
[<number>multiply[2]]
\end

<<multiply-by-two 4>>
\`\`\`

renders as:

\function multiply-by-two(number)
[<number>multiply[2]]
\end

<<multiply-by-two 4>>

Note: I backslash escaped the triple backticks from the actual tiddler text so I can have nested triple backticks here in the forum. But you get the idea.

This does not work properly, since \function pragma must be at the beginning of the text field. My tiddler content becomes:

\function multiply-by-two(number)
[<number>multiply[2]]
\end

\`\`\`
\function multiply-by-two(number)
[<number>multiply[2]]
\end

<<multiply-by-two 4>>
\`\`\`

renders as:

<<multiply-by-two 4>>

Cool, it works now. But I have a copypasted piece of text - the function definition is present twice. What if I try to extract it to another tiddler?

I create another tiddler: New Tiddler 1 and put the definition of my function there:

\function multiply-by-two(number)
[<number>multiply[2]]
\end

Now I need to modify New Tiddler to remove the function definition from there.

For the code block piece, I can use a codeblock widget:

\function multiply-by-two(number)
[<number>multiply[2]]
\end

<$codeblock code={{New Tiddler 1}}/>

\`\`\`
<<multiply-by-two 4>>
\`\`\`

renders as:

<<multiply-by-two 4>>

My code block is now visually split into two parts, but this is a minor inconvenience.

But trying the same trick with the actual function definition:

{{New Tiddler 1}}

<$codeblock code={{New Tiddler 1}}/>

\`\`\`
<<multiply-by-two 4>>
\`\`\`

renders as:

<<multiply-by-two 4>>

does not work :frowning:

I can make it work with an \import pragma though:

\import [[New Tiddler 1]]

<$codeblock code={{New Tiddler 1}}/>

\`\`\`
<<multiply-by-two 4>>
`\`\`

renders as:

<<multiply-by-two 4>>

After much pain, I still only solved half of the problem. What if the wikitext code block that uses the definition is not just one line <<multiply-by-two 4>> but much bigger? This requires eliminating duplicate code again. Should I proceed the same way - extract it to another tiddler then transclude it: the regular way for executable code and the codeblock widget way for the code block?

Even if it works, my “optimization” leaves me with three tiddlers instead of one. Is this good? Are there better ways to achieve this perhaps?

#2

With a few tweaks to how your functions are defined, this definitely looks possible, using just one parameterized template tiddler.

First, create that template tiddler. Give it a title like ShowExample and add its content:

\whitespace trim
\parameters (definitions:"", demoCode:"")

<$codeblock code=```$(definitions)$

$(demoCode)$```
/>

renders as:

<pre>
<$wikify text=```$(definitions)$

$(demoCode)$``` name="result"><$text text=<<result>>/></$wikify>
</pre>

Next, in your New Tiddler, wrap the function definition up like so:

\procedure definitions()
\function multiply-by-two(number)
[<number>multiply[2]]
\end multiply-by-two
\end definitions

Explanation: Macro and and procedure definitions without parameters behave like ordinary variable definitions, so wrapping your function definition in \procedure definitions() ... \end definitions makes the whole function definition available as a string variable. Wrapping it up like this also has the advantage that each code example can contain multiple definitions.

To render everything, transclude ShowExample in New Tiddler:

\procedure definitions()
\function multiply-by-two(number)
[<number>multiply[2]]
\end multiply-by-two
\end definitions

<$transclude
    $tiddler="ShowExample"
    definitions=<<definitions>>
    demoCode="<<multiply-by-two 4>>"
  />

Using a WikifyWidget is perhaps not ideal in terms of performance, but I think this is necessary to evaluate the function definition pragma in the template tiddler.

Hope that solved your problem or gave you some ideas.

1 Like
Where do pragmas end?
#3

you can write a procedure to do something like that:

\procedure codeExample(code)

<pre><$text text=<<code>>/></pre>

renders as:

<<code>>
\end

\function multiply-by-two(number)
[<number>multiply[2]]
\end

<!-- simple -->>
<<codeExample """<<multiply-by-two 4>>""">>

---
<!-- more felxible: -->
<$transclude  $variable="codeExample"  code="""<!--This is what it looks like across multiple lines-->
<<<
	<$transclude
		$variable="codeExample"
		code="<<multiply-by-two 4>>"
	/>
<<<
<!--------------------------->
"""/>
1 Like
#4

I am using a template tiddler that is a literal copypaste of your example, and I have noticed a problem with CSS wikitext markup:

\`\`\`
@@color:#ff0000;background-color:#00ff00;Colored text with background
@@
\`\`\`

renders as:

@@color:#ff0000;background-color:#00ff00;Colored text with background
@@

<$transclude
    $tiddler="CodeTemplate" demoCode="@@color:#ff0000;background-color:#00ff00;Colored text with background
@@" />

The first, inline snippet, is rendered with custom text color and background.

The second, transcluded through the template, is not.

#5

Also, demoCode should probably use triple quotes by default, because when copypasting wikitext that contains ", it confuses the parser.

Example:

<$vars foo="bar">
<<foo>>
</$vars>

By copypasting it into demoCode, one gets:

<$transclude
    $tiddler="CodeTemplate"
    demoCode="<$vars foo="bar">
<<foo>>
</$vars>
"
  />

which is not ok.

But

<$transclude
    $tiddler="CodeTemplate"
    demoCode="""<$vars foo="bar">
<<foo>>
</$vars>
"""
  />

works.

And

<$transclude
    $tiddler="CodeTemplate"
    demoCode='<$vars foo="bar">
<<foo>>
</$vars>
'
  />

because it doesn’t mix the quotes.

#6

Found another rough edge:

\procedure definitions()
\function list3() 1 2 3 4 5 6 7 8 9 10 +[format:titlelist[]join[ ]]
\end list3
\end definitions

<$transclude
    $tiddler="CodeTemplate"
    definitions=<<definitions>>
    demoCode="""<<list3>>
"""

this renders as:

\end list31 2 3 4 5 6 7 8 9 10

If I don’t use the optional name of the function in the \end marker, as in:

\procedure definitions()
\function list3() 1 2 3 4 5 6 7 8 9 10 +[format:titlelist[]join[ ]]
\end
\end definitions

then the rendered content is just

1 2 3 4 5 6 7 8 9 10

which is correct. No it is not :frowning: While it produces the expected output for this code snippet, apparently it breaks the parser and further wikitext markup after the transclude widget is rendered the wrong way.

PS: I hope multiple posts highlighting you by name are not disturbing. I’m just posting as I keep refactoring my knowledge base wiki and hit these edge cases.

Wikify widget does not produce the expected output when input contains a function definition
#7

If you’re nesting one or more functions/procedures/macros inside another procedure, all labels of all \end markers except the very last are actually non-optional — except for single-line declarations, which shouldn’t have \end markers at all. So any of these options should work:

  1. list3 on a single line, \end definitions 
\procedure definitions()
\function list3() 1 2 3 4 5 6 7 8 9 10 +[format:titlelist[]join[ ]]
\end definitions
  1. list3 on a single line, \end only
\procedure definitions()
\function list3() 1 2 3 4 5 6 7 8 9 10 +[format:titlelist[]join[ ]]
\end
  1. list3 on multiple lines, \end list3, \end definitions 
\procedure definitions()
\function list3()
1 2 3 4 5 6 7 8 9 10 +[format:titlelist[]join[ ]]
\end list3
\end definitions
  1. list3 on multiple lines, \end list3, \end 
\procedure definitions()
\function list3()
1 2 3 4 5 6 7 8 9 10 +[format:titlelist[]join[ ]]
\end list3
\end

Conversely, the following does NOT work…

\procedure definitions()
\function list3() 1 2 3 4 5 6 7 8 9 10 +[format:titlelist[]join[ ]]
\end <!-- this is the problem! -->
\end definitions

… because the parser treats the first unlabeled \end as the end of the parent procedure definitions.

For relatively short functions like this one, I’d generally favor option #2, or option #1 if definitions is particularly long and you want the \end label for clarity.

I’ll also admit that I haven’t read Roland’s solution carefully; this is intended only as generalized pragma advice.

#8

Perhaps this needs to be “carved in stone” explicitly in the docs :confused:

Note that the \end marker can optionally specify the name of the function to which it relates, enabling function definitions to be nested inside procedures, macros or widget definitions.

This is a quote from https://tiddlywiki.com/#Pragma%3A%20\function and as a non-native English speaker I certainly didn’t interpret the enabling function definitions to be nested inside procedures, macros or widget definitions as using the name of the function after the \end marker becomes mandatory in this case, perhaps my thought flow was driven by inertia by the optionally word.

#9

I think that’s a reasonable criticism. The Pragma: \procedure tiddler is somewhat clearer on that front:

Procedure definitions can be nested by specifying the name of the procedure in the \end marker.

And the accompanying code also illustrates a nested procedure (though it doesn’t note that special-button is optional in the final \end):

\procedure special-button(caption:"Click me")
\procedure actions()
<$action-sendmessage $message="tm-notify" $param="HelloThere"/>
\end actions
<$button actions=<<actions>>>
<<caption>>
</$button>
\end special-button

I suspect that the “Pragma: \procedure” tiddler got a more detailed explanation than its \function equivalent because, unlike procedures and macros, you can’t nest anything else inside a function pragma. But I agree that adding an example of a \function in a \procedure would probably improve the clarity.

#10

Using the template to render styled output in this way won’t work because of several reasons.

For starters, I misunderstood your original question. It mentioned functions, not styled output, so I assumed that that wasn’t going to be part of the requirements (although “renders as” should have clued me in).

My originally proposed solution displays plain text results wrapped up in a <pre> tag. This is how text like the results from evaluating functions is usually displayed. The crucial part of the template is here (notice the <$text> widget, which renders plain text):

...
<pre>
<$wikify text=```$(definitions)$

$(demoCode)$``` name="result"><$text text=<<result>>/></$wikify>
</pre>
...

This part could be changed to render styled output instead (but don’t edit anything yet):

...
<div>

<<wikitext>>

</div>
...

The <div> tags aren’t strictly necessary, I just added them for clarity. They can also be styled to e.g. add a border.

The blank lines around <<wikitext>> are however necessary for the result to render in block mode.

I’d suggest keeping the original template tiddler and creating a modified clone, because these two templates are for two different use cases.

Rename the original to something like CodeExampleTemplate, and name the cloned and modified template to something like StyleExampleTemplate.

Here’s the template in it’s entirety:

\whitespace trim
\parsermode block
\parameters (wikitext:"")

<$codeblock code=<<wikitext>>/>

renders as:

<div style="border: 1px solid; border-radius: 3px; padding: 0 15px; min-height: 2em;">

<<wikitext>>

</div>

Use it like so:

<$transclude
    $tiddler="StyleExampleTemplate"
    wikitext="""@@color:#ff0000;background-color:#00ff00;Colored text with background@@"""
  />
#11

You’re right, I should have used triple quotes. But even those will lead to a problem if the quoted content contains triple quotes. One way to deal with this is to excise the code into its own tiddler, as you had originally planned, and use a transcluded attribute value.