[IDEA] Use Dynamic Variable Markers in Documentation

[pmario]

Created by @etardiff - Copied over from Talk:

I said I wasn't going to attempt a custom widget, but apparently I couldn't help myself. Here's a self-contained example (raw code follows at the end of the post): Sample $docs.filters.tid|attachment (2.0 KB) (Now revised as discussed in post # 55, below)

It converts code like this...

<$docs.filters>
[range«end»]
[range«begin»,«end»]
[range«begin»,«end»,«step»]
</$docs.filters>

into output like this:

I have to confess that I had no idea how to type guillemets myself. (For my fellow Windows users, it's Alt-174 for « and Alt-175 for »; the numbers must be typed on your numpad.) I'd really prefer a more standard character for use on TW-com, but I copy-pasted a few of them anyway to use as quick delimiters; they are, if nothing else, easy to read, and unlikely to appear in sample filters.

Other notes:

• I used $wikify to capture the value of <$slot $name=ts-raw /> for use in filtering, but surely (hopefully?) this isn't best practice...?
• I used <<color primary>> to add some quick, palette-responsive color to the parameters. For a more polished version, we might prefer a more thoughtfully chosen palette. (Perhaps a different color for each type of parameter?)
• I didn't put a lot of effort into styling the $select widget, but IMO, it would look better either outside the bounds of the <pre> block or inline with the first line of code.
• I added a quick tooltip to the $select to help clarify its use, but obviously, a <<lingo>> macro would be preferable. We could also include more explanatory text before or after the codeblock; here, I was trying to keep the display as clean as possible.

---

I did very little testing, so all corrections, enhancements, and other feedback are much appreciated!

Here's an updated version that should correct the issue: Sample $docs.filters.tid|attachment (2.0 KB)
I'll update the code in my previous post as well.

In addition to correcting to account for multi-word values (just a matter of adding quote marks around the parameter), I added a couple of additional lines to my .param-display function:

\function .trim-label() [<.param-type>!match[string]] :then[<label>trim[]] ~[<label>]
\function .param-display()
[<.param-type>match[variable]then[<XX>]]
~[<.param-type>match[transclusion]then[{!!XX}]]
~"[XX]"
+[search-replace[XX],<.trim-label>]
:map[<.param-type>match[variable]then{!!title}search-replace:g[ ],[-]else{!!title}]
\end .param-display

• The final :map run replaces any spaces in the parameter with hyphens when displaying variable parameters. I didn't make the same substitution for {!!field}-type parameters since field names can theoretically include spaces, but we certainly could do so there as well.
• .trim-label removes any leading or trailing space from non-literal parameters --- and here, I did trim fields as well. You could have a field name with a trailing space, but IMO it's asking for trouble, and not something we want to promote.

As a side note, I'm not entirely happy with my use of search-replace to substitute the param name; I chose it primarily because it felt more efficient than using addprefix and addsuffix (which can also be problematic when used with brackets, particularly [ --- which merely looks like a mistake --- and ] --- which actually disrupts the filter parsing). If anyone has a more elegant solution, I'd love to hear it.

I'll also note that while I do see the appeal of adding this extra functionality to all the sample filters, I really designed it while thinking of the syntax illustration "filters" currently used for filter operators like range (https://tiddlywiki.com/#range%20Operator) and search-replace (https://tiddlywiki.com/#search-replace%20Operator). The addprefix tiddler doesn't seem to have one at present (perhaps because it's harder to abstract?), but if I were writing one, I might do something like

Cat Garden [[Favourite Armchair]] +[addprefix<prefix>]

or the following, in my proof-of-concept syntax:

<$docs.filters>
Cat Garden [«Favourite Armchair»] +[addprefix«prefix»]
</$docs.filters>

Sample $docs.filters.zip