I never learn a filter operator from the summary table given in the docs, see for example:
where is input? where is suffix? where is parameter?
The below is semantic, it can be used like
[<input>butlast<parameter>]
One question is how to show the syntax.
[<input>operator:<suffix>:<suffix><parameter>]
It would be beneficial to include this in the documentation. I assumed that since <> is used for variables, it might not be feasible to use it in the syntax.
I think Introduction to filter notation is a great start, and I wish it were one click away from each filter operator doc, not two clicks. (via Filters). But it is not nearly enough. Anyone who’s twiddled with TW filters for more than a week or two will likely understand this:
[tag[Person]] :filter[get[age]compare:number:gteq[18]]
But that’s not covered by this introduction. While I’m a big fan of the railroad diagrams, that’s mostly for developer sorts, and it’s already deep into the weeds. Answers like @pmario’s above is great, except that it will also confuse beginners. You mean I have to put the input in angle brackets?
I don’t have a great solution, though. I think a LOT of changes are necessary for the documentation. But I really don’t know where to start.
One thing that I think would be a good start would be to transclude the Examples tiddler for each operator and not just link to them. I think the table you point to is fine. But there needs to be more explanatory text and examples immediately at hand.
I did use the angel brackets <> as a placeholder similar to the syntax you used in your OP.
It is important to say, that suffix can not be TW variables. It has to be text.
That’s right. Explaining our filter syntax is complex, because we can not use elements that are part of the filter syntax itself.
What about using colored blocks like this (just a draft, someone else should find better suited colors 
)?
Applied to search-replace operator:
Source code:
\procedure i(_) <span class="tc-fop-block tc-fop-input"><<_>></span>
\procedure o(_) <span class="tc-fop-block tc-fop-operator"><<_>></span>
\procedure s(_) <span class="tc-fop-block tc-fop-suffix"><<_>></span>
\procedure so(_) <span class="tc-fop-block tc-fop-suffix tc-fop-optional"><<_>></span>
\procedure p(_) <span class="tc-fop-block tc-fop-parameter"><<_>></span>
\procedure po(_) <span class="tc-fop-block tc-fop-parameter tc-fop-optional"><<_>></span>
\procedure m(_) <span class="tc-fop-meaning"><<_>></span>
<style>
.tc-fop-syntax{
line-height: 2em;
}
span.tc-fop-block{
font-family: monospace;
border: 3px solid;
border-radius: 0.5em;
padding: 0 0.2em;
margin-left: 0.05em;
margin-right: 0.05em;
}
span.tc-fop-input{
background-color:lightgray;
border-color: darkgray;
color: gray;
}
span.tc-fop-operator{
background-color:mistyrose;
border-color: pink;
color: deeppink;
}
span.tc-fop-suffix{
background-color:plum;
border-color: orchid;
color: darkorchid;
}
span.tc-fop-parameter{
background-color:aliceblue;
border-color: lightsteelblue;
color: steelblue;
}
span.tc-fop-meaning{
font-family: sans;
font-weight: 400;
}
span.tc-fop-optional{
border-style: dashed;
}
</style>
!! General filter operator syntax:
@@.tc-fop-syntax
<pre>[<<i input>><<o operator>>:<<s suffix1>>:<<s suffix2>><<p parameter1>>,<<p parameter2>>]</pre>
"""
<<i input>>: <<m "Input values for the considered filter operator">>
<<o operator>>: <<m "Filter operator name">>
<<s suffix>>: <<m "Some filter operators use one or more suffixes to change their behavior. Suffixes must be literal values.">>
<<p parameter>>: <<m "Optional. Parameters for the filter operator.">>
"""
@@
<$transclude $variable=".tip" _={{Filter operand brackets}} $mode="block" title="Operands (parameter values):"/>
---
! Examples
---
! search-replace Operator
<<tag "Filter Operators">> <<tag "String Operators">>
!! Purpose
Returns each item in the list, replacing within each title the string specified by the first parameter with the second parameter.
!! Syntax
@@.tc-fop-syntax
<pre>[<<i "input">><<o search-replace>>:<<so "flag-list">>:<<so "regexp-mode">><<p search-term>>,<<p replacement>>]</pre>
"""
<<i "input">>: <<m "a [[selection of titles|Title Selection]]">>
<<s "''Suffix'':">> <<m "''search-replace'' operator uses a rich suffix, see below for details.">>
<<so "flag-list">>: <<m "''g'' for global mode to replace all matches, ''i'' for case-insensitive mode, ''m'' for multiline mode, ''gim'' for all (optional).">>
<<so "regexp-mode">>: <<m "''regexp'' to treat the first parameter as a regular expression (optional).">>
''Parameters'':
<<p "search-term">>: <<m "string or regular expression that should be replaced">>
<<p "replacement">>: <<m "string that should replace the search-term">>
"""
@@
<$transclude $variable=".tip" _={{Filter operand brackets}} $mode="block" title="Operands (parameter values):"/>
operators-syntax.json (3.8 KB)
(uses doc macros, try it on tiddlywiki.com)
Fred
I was thinking the exact same thing on my bus ride home. I was just checking in on the discussion before I set out to try it, and you already have it working! Very nice!
Colour should never be your only form of coding.
It’s a nice idea but would still need a secondary solution for accessibility.
Thanks for your feedback @Ste_W
Yes, I’ve been thinking about this too.
Even if it’s not currently implemented in this draft, using procedures + CSS would allow:
<span> elements, like tooltiptexts and aria attributes.We could even consider adding ontological attributes to ease computational reading of this documentation.
Fred