Consider changing variable markers in documentation

#23

Of course, but I was thinking of something larger than just the parameter. I would really like to add syntax highlighting for any documentation filters.

I’m greedy. I want it all. I would love to colorize and add bold/italics/something. And I want bracket characters distinct from any brackets we actually use. I want those character only for syntax descriptions, though, and absolutely not for examples. But I would like to see most filters we document have enough examples to demonstrate two or three of the different brackets.

1 Like
#24

A post was split to a new topic: Documentation Examples Need to be Improved

#25

Because this will affect the looks in almost every doc tiddler, may I propose that any suggestion here is accompanied by a simple screenshot of how the end result would appear? Maybe we can then even “stack” the screenshots next to one another perhaps in the initial post, for a direct comparison?

What is a good string or block of strings to use as a common example? Is the OP example representative enough?

image

…and any solution needs also work well in the parameter tables (and more?)

image

By the way, does it really make sense to use different colours for the two?

#26

YES! Finally Comic Sans in TW!!!

image

Elegance for the masses! Jeremy will love it!

1 Like
#27

I think the idea would be to put the brackets (whether square or otherwise) into that same font/color… The point to make super-clear to users is that the style of brackets may need to change, in addition to the contents.

1 Like
#28

[range«begin»,«end»,«step»]

This is how I envision this, where a link/popup documents «name» replaced by;

  • literal [value]
  • variable <varname>
  • transclusion {tiddler!!field} and versions there of.

Now please be aware I entered the symbols on my Android device. entering special characters is only about knowing how.

  • using the above it should be simple to colour items between the symbol pairs.

let us now find an equally clear way to represent the suffix, and compound suffix.

  • it would be simple enough to place the current doco behind a click as we introduce this new representation.
Documentation Examples Need to be Improved
#29

While I understand the desire, I would find it fairly onerous… unless we find a tool that already does syntax highlighting for wikitext. I believe they exist for tools like VSCode, but I don’t know if we have an extension to highlighter or prismjs that already handles this. Without that, it would be a great deal of work to first figure out the syntax highlighting, then manually apply all the styles.

For instance, this:

[range«begin»,«end»]

might need to be converted to

<span class="filter-wrap-bracket">[</span><span class="operator">range</span><span class="generic-bracket">«</span><span class="parameter">begin</span><span class="generic-bracket">»</span><span class="param-separator">,</span><span class="generic-bracket">«</span><span class="parameter">end</span><span class="generic-bracket">»</span><span class="filter-wrap-bracket">]</span>

And that doesn’t even cover writing the stylesheet for all this.

While I would love the results, it seems like too much work.

#30

I think a macro can easily be written that given a filter syntax such as [range«begin»,«end»] can easily display this as desired including a tooltip for each item, including reference to [{<.

It does raise in my mind that even [range«begin»,«end»] is too much as it is a closed filter run, when more often it is within a larger filter run.

  • that is the range widgets atomic structure is range«begin»,«end»
  • how do we indicate the optional step parameter? eg;
    • range«begin»,«end»⟨,«step»⟩
    • note ⟨ ⟩ used to replace [ ] which is commonly used to indicate optionality.
    • can we include default values?
#31

This is a very good point. I don’t have any great ideas on this now, but I do think we should spend some time on it.

Aside:

It’s interesting to realize that Jeremy’s thoughts on this are significantly different from mine. I’m headed to bed now, so I’m going to search for the reference. But somewhere he said he thinks of, say,
[tag[Something]get[field-name]] as [[tag[Something]] and [get[field-name]] concatenated in a way that drops the trailing ] from the first one and the leading [ from the other. My thought has always been of tag[Something] and get[field-name] concatenated and wrapped in [ - ]. The two ideas are complementary, but still to me radically different. Mine seems more closely aligned to the filter railroad diagrams, but I’m sure his has a historical justification mine is missing.

#32

You mean that you want to include the a shortened version of https://tiddlywiki.com/#Filter%20Parameter into the documentation for every filter parameter? Why not just link to that tiddler in the “parameter” heading of the summary table? Oh wait, that’s already being done. :confused:

#33

Mine thought too, FWIW. Wrapping in [ ] at the end is a bit like dotting my 'I’s and 't’s at the end of writing a word. I don’t actually write my filters like that, but that’s how a parse them.

#34

Of course these do not work if used apart, the issue Jeremy and many others of us face is our knowledge of filters is similar to toys we remember from childhood. So precise its hard to view with naive eyes/minds.

eg tag«something» and get«fieldname» and joined; [tag«something»get«fieldname»]

Not really, “I think want”, the syntax to read range«begin»,«end» and direct the user to documentation and examples that show the use of “Hard/Soft-Direct/indirect” or the more user friendly “literal/transclusion and variable”.

  • Ideally with a tooltip on the syntax
1 Like
#35

I’ve been watching this topic for a bit now, and I have a simple suggestion about the variable markers that I’m surprised nobody’s brought up.

Couldn’t we just use all-capital letters for the variable markers, such as BEGIN / END / STEP?

As pointed out in previous posts:

  • Color poses a problem for colorblind users.
  • Bracket characters like < > are part of regular TW bracket use, so we should avoid using them as they’re confusing for new/light users, as Scott points out in the OP.
  • Double-chevron characters like « » aren’t part of all standard keyboard layouts and may be difficult/annoying for some people to insert. They might also be confused for other standard TW bracket use by new users, and certainly don’t help with the “no double brackets” rule they’re trying to remember.

Additionally:

  • The “bold and italic text generators” Yaisog mentioned earlier may not all output screen-reader friendly glyphs. I’ve previously seen people pointing out such a side effect out on other sites: when their screen reader runs into those “fancy” italic/black-letter/cursive strings of text that you see some people using on social media, it can start spitting out illegible “garbage” for them.
  • Applying basic styling like italics could pose a problem for users who override page CSS for visual reasons. Their variable markers could disappear entirely!

But capital letters:

  • are generally not currently used in our documentation, so they’d stand out as “something is different here”
  • can be typed on any keyboard layout
  • don’t add additional characters (thus keeping the docs’ size down)
  • use no bracket characters so there’s no chance of confusing users as to whether the brackets are supposed to be included or not
  • pose no problem with CSS styling or any overrides to it
  • are perfectly accessible to people using screen readers (as far as I am aware, correct me if I’m wrong)
  • and most importantly, should(?) be an easy find-and-replace on the existing documentation

Especially if paired with a standardized note prefacing the examples such as “Terms in ALL CAPS are placeholders for your values”, then wouldn’t an all-caps method be both easy to create and simple to understand?

[range[END]]
[range[BEGIN],[END]]
[range[BEGIN],[END],[STEP]]

Personally, I use all-caps as a variable placeholder all the time in my personal documentation notes for both TW and Linux, because it’s instantly obvious how I have to substitute my actual value into a string when I see UUID-GOES-HERE or [[YOUR_FILTER_RUN]].

*Edited to simplify the prefacing “note”

4 Likes
#36

I do like that idea. Will be worth a test.

#37

I think that is definitely worth considering.

But there is still a flaw: What needs to be substituted is not END, but [END] (with the brackets). While this could be substituted with [42], it could also be substituted with {!!last-value} or <my-counter>. And that is hard to convey if we continue to use a bracket that is valid syntax.

This is not a problem for the examples, if @Springer and I get our way and lists of example contain several of these options. But for the syntax overview, I would really like to see a fix.

I don’t have the answer. I don’t really like the guillemets. Unless you’re French, « and » are probably difficult to type. But I’m struggling to find something that works which actually is easy to type. The only obvious alternative – ( and ) – is claimed in a current PR.

#38

I think I see what you’re trying to say about the substitution, but if I’m reading it right, it’s not as much of a issue with the usage of all-caps themselves as it is with the explanation text I included, correct? (“Terms in ALL CAPS are placeholders for your values or variables.”)

I just tossed that phrase in there as a general placeholder explanation, but I see now that it would be smarter to omit the “or variables” at the end. Otherwise it could confuse new users who, as you pointed out, don’t know yet that you also need to replace the [ ] around the “END” when you replace the value with a variable. (Update: I’ve edited the note in my prior post accordingly.)

  • Improving the documentation about variables to include a section on how to use a variable as an operator parameter – which is strangely missing from “Variables in Filters”! – is another topic entirely, but would cover the above new-user help, because then they’d know they need to substitute [END] instead of just END.
#39

If you tell people that they have to replace the uppercase text, they will understand that [range[5],[10]] is likely legitimate. But there’s no reason that they would recognize that [range<stop>,<start>] is also legitimate, as is [range{My Contants!!first},{My Constants!!last}]. That’s the problem with using [ - ] or < - > or { - } to designate the parameters that need to be changed.

Most TW users do not read some linear tutorial about using filters, but first poke around trying to solve their immediate problems. A user might happen to see someone’s use of range[5], understand what it does and visit the range Operator documentation to figure out how to extend it to have both a start and end parameter. If they want to use their variables, they might well try this version:

<!-- BROKEN -->
[range[<start>],[<stop>]]

because they’re substituting the uppercase text of BEGIN and END with their variable references. If they want to try again, perhaps they’ll notice the small link Learn more about how to use Filters, and visit Filters, which is too high level for them, but its list of links to follow starts with Introduction to filter notation, which sounds helpful,. When they get there, though, they see an introduction and a second section, which together have thirteen filter examples, every one of which uses literal values in square brackets. Only if they’re intrepid will they go onto the second section, titled “Special parameters”. There’s a good chance they will have given up on this as not helpful by now, and “special parameters” doesn’t sound like it’s going to help.

And that’s why I think we need to somehow make it more explicit that any brackets meant to be replaced by real ones are dummies. But again, this is a large change, time consuming and fiddly.

1 Like
#40

clearly the solution is to have all the brackets at once! ⦕ ⦖ (or is the correct order ⦖ ⦕ ?! Ok ok, what about 〖 〗

(seriously, I remain a fan of « » in part because they’re trivial to type under linux at least (compose+<+<) but even so, the danger of any unicode exploration is difficulty and confusion, another example of which is that the following are all different characters, but may look identical (or very very similar) depending on your local fonts «《 ⟪. Crucially, to the casual explanation, all would be described the same and I can easily imagine them all ending up in documentation without extra care :frowning: )

#41

A quick additional thought:

It’s not ideal for printed or screen-reader purposes, BUT:

a hover effect on parameters might be very helpful, where

[range[18],[65]]

is what you see, but if you hover over [18] the expression [18] gets a background-highlight effect, and the tooltip shows

[18] (hard parameter)
{!!minimum-age} (indirect)
<changecount> (variable)

or something like that. Just brainstorming here…

Certainly something like this can help. In practice, still, the problem is that mid-level users often are uncertain exactly where/how a variable can be swapped in. Having filter parameters jump out somehow, with clarity about the common ways that curly and angle brackets look in practice, would be ideal.

2 Likes
#42

While I’m not generally a fan of obscuring TW mechanisms behind documentation macros, I do think that a procedure (or perhaps a <$docs.filters> widget, as @Scott_Sauyet suggested) might be the best way to balance ease of input with the need for more sophisticated (and ideally, transparent) display. Here’s a quick, procedure-based mockup of the sort of dynamic display I would find most useful myself, borrowing some inspiration from @EricShulman’s earlier suggestion:

\function .docs-param-config() [[$:/temp/docs-config/]] [<storyTiddler>] +[join[]]

\procedure .docs-param(label)
	\function .param-type() [<.docs-param-config>get[text]] ~string
	\function .param-display()
		[<.param-type>match[variable]then[<XX>]]
		~[<.param-type>match[transclusion]then[{!!XX}]]
		~"[XX]"
		+[search-replace[XX],<label>]
	\end .param-display
<<.param-display>>
\end

\procedure .docs-param-select()
<$select tiddler=<<.docs-param-config>> class="tc-float-right" default="string">
	<option>string</option>
	<option>variable</option>
	<option>transclusion</option>
</$select>
\end

<pre><<.docs-param-select>>
[range<<.docs-param end>>]
[range<<.docs-param begin>>,<<.docs-param end>>]
[range<<.docs-param begin>>,<<.docs-param end>>,<<.docs-param step>>]
</pre>

Sample output:
image

Obviously that <pre>...</pre> section is terrible to type or read; my main goal here was simply to show the sort of dynamic display I was envisioning. Ideally the code needed to turn

[range[<begin>]]
[range[<begin>],[<end>]]
[range[<begin>],[<end>],[<step>]]

(or similar) into a <pre> block with the appropriate macros could itself be contained in a hypothetical <$docs.filters> widget, but I haven’t done much work with custom widgets myself and am not very confident with the $slot mechanism, so I’ll leave that as an exercise for anyone who feels inspired. I took a crack at this in a later post in this thread.

Edit: I think @Springer’s concern about screen readers may apply here too… while the filters themselves would be plain-text (and could be easily copy-pasted, etc.) the selection mechanism might be less transparent…

3 Likes