Consider changing variable markers in documentation

[Scott_Sauyet]

I was looking at the documentation for the range Operator, and noticed this block:

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

This really makes it look as though I could write

<$let begin="1" end="5">>
<<list-links filter:"[range[<begin>],[<end>]] ">>
</$let>

But I know that’s not allowable. One rule I’ve internalized for filters is that anything ending in three brackets must be a syntax error. (In fact, any triple brackets in a filter is an error, and every filter run must end in exactly two, with the final one being ].)

So clearly <begin>, <end>, and <step> are meant to be documentation markers, and not real syntax.

I’m wondering if we should introduce some other symbols to represent these documentation markers, ones not likely to be confused with actual syntax elements.

I was considering the guillemets:

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

There is a problem for those used to English keyboard layouts: they’re harder to type. I don’t think there’s any good way around that. TW syntax has claimed all the likely brackets on the keyboard, especially once multi-valued variables are included.

But I don’t think we want our documentation to have this sort of confusion.

Perhaps we could use this instead:

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

with the understanding that « - » represents any of our bracket pairs, [ - ], < - >, { - }, and one day ( - ).

What do you think?

[pmario]

You are right. That needs to be fixed, but I do not really know how atm.

In this case <begin> is not meant to be a variable, but a placeholder. … That’s a mistake, because it is confusing and will lead to syntax errors in filters created by users.

I’ll change it. – soon.

[Scott_Sauyet]

I just noticed this when looking to answer another question. I don’t know if it’s widespread in the documentation.

I can’t fix this from work, but will look this evening if you haven’t gotten to it.

But my question is more generic. I don’t know if there are other similar places. Do we want to figure out a general approach to describing operands/parameters with their braces?

[EricShulman]

The documentation generally uses square brackets to indicate where filter parameters are to be used. However, this suggests the use of literal values only, when in reality, parameters can also be variables or tiddler references.

Thus, when we write something like this:

[range[begin],[end],[step]]

we also imply that you can substitute < and > to specify parameters that are variables, or { and } to specify parameters that are tiddler references.

The key concept that needs to be emphasized is to remind people that the brackets “belong to” the parameter, not the operator, and are used to indicate how that parameter is to be processed… square brackets for literal values, angle brackets for variables, and curly braces for tiddler references.

-e

[Yaisog]

I don’t know how universal this is, but we could use Unicode italic letters to get italics into displayed code blocks, like so:

Italics would then mark the parameter names to distinguish them from the operator names.

These letters could not be typed directly, but there are lots of pages out there to “translate” into them, e.g. Bold and Italic Text Generators - 𝐁𝐨𝐥𝐝 𝒂𝒏𝒅 𝑖𝑡𝑎𝑙𝑖𝑐𝑠

Yaisog

PS: The first line in the codeblock below the “Introduced in v5.2.0…” should probably be [range[𝘦𝘯𝘥]], not [range[𝘣𝘦𝘨𝘪𝘯]].

[pmario]

@Yaisog

I don’t know how universal this is, but we could use Unicode italic letters to get italics into displayed code blocks, like so:

That would be the only operator, where we use that system. It would be new, different and would need some extra explanation. I’ll crate a PR soon.

As Eric mentioned. The braces belong to the parameter and we can use them that way. So if users copy / paste our examples into Advanced Search → Filter tab, they should work, if they use literal values.

Edit: PR is at: [DOCS] Improve "range Operator" documentation. Make placeholder "terms" consistent with filter strings by pmario · Pull Request #9276 · TiddlyWiki/TiddlyWiki5 · GitHub

[Yaisog]

@pmario

That would be the only operator, where we use that system.

This would have to be done consistently everywhere of course. This was more an answer to @Scott_Sauyet’s question “Do we want to figure out a general approach to describing operands/parameters with their braces?” than a fix for the range operator docs.

@pmario

So if users copy / paste our examples into Advanced Search → Filter tab, they should work, if they use literal values.

In both variations, [range[begin],[end],[step]] and [range[𝘣𝘦𝘨𝘪𝘯],[𝘦𝘯𝘥],[𝘴𝘵𝘦𝘱]], the placeholders would have to be replaced by actual numbers (in this case) to work, so it would not make a difference.

Visually, I’m starting to like the italics for the parameter names more and more, as they are very distinctive.

Also, there are more operators with this documentation issue, search-replace being one, prefix another that I found without much searching. prefix uses the angle brackets also for the suffix, which makes it look like the suffix can be a soft parameter, which it cannot. That is even more confusing than the OP. Before we start making changes here and there, there should be a clear definition of our notation and that should be applied consistently throughout. This might affect a lot of or all operator docs tiddlers and is potentially a lot of work which we certainly don’t want to do multiple times.

[Scott_Sauyet]

@Yaisog

These letters could not be typed directly, but there are lots of pages out there to “translate” into them, e.g. Bold and Italic Text Generators - 𝐁𝐨𝐥𝐝 𝒂𝒏𝒅 𝑖𝑡𝑎𝑙𝑖𝑐𝑠

I do wonder if a parser extension for the docs would allow us to automate this. I’d love it if the brackets were in bold-italic, and the text in italic.

@Yaisog

Visually, I’m starting to like the italics for the parameter names more and more, as they are very distinctive.

I agree. They, at the very least, make it clear that something is going on.

@Yaisog

Also, there are more operators with this documentation issue, search-replace being one, prefix another that I found without much searching. prefix uses the angle brackets also for the suffix, which makes it look like the suffix can be a soft parameter, which it cannot.

Good catches. I probably won’t find time before the weekend to do a more systematic look, but I’m not even sure it’s worth spending too much time on that, as you make a good argument for doing more than just a minor fix of operand/parameter brackets.

@Yaisog

Before we start making changes here and there, there should be a clear definition of our notation and that should be applied consistently throughout. This might affect a lot of or all operator docs tiddlers and is potentially a lot of work which we certainly don’t want to do multiple times.

Yes, and I think this discussion belongs here rather than on GitHub—of course, both is also possible—because this affects the general population of users more than that of developers.

[TW_Tones]

[range[𝘣𝘦𝘨𝘪𝘯],[𝘦𝘯𝘥],[𝘴𝘵𝘦𝘱]],

If we consider this when reading the documentation the outer [ ] is not negotiable. However as Eric points out the ones around a parmater can be replaced;

eg [range<𝘣𝘦𝘨𝘪𝘯>,{𝘦𝘯𝘥},[𝘴𝘵𝘦𝘱]]

So perhaps what is needed here In the documentation only is a replacement for the braces around parameters currently [ ] for a similar but different symbol. forexample

[range⟦𝘣𝘦𝘨𝘪𝘯⟧,⟦𝘦𝘯𝘥⟧,⟦𝘴𝘵𝘦𝘱⟧] where ⟦ and ⟧ can be [literal] or {tiddler!!field} or <macrovariable>

[Scott_Sauyet]

Yes. That’s what I was thinking.

But I also like @Yaisog’s suggestion of italicizing the variable names… although probably not the method of using mathematical Unicode symbols. That would make cutting and pasting too difficult.

[TW_Tones]

@Scott_Sauyet

That would make cutting and pasting too difficult.

Of course tiddlywiki.com uses documentation macros and it would be simple to write a macro to support the displaying of filters with the desired formating and even mouse over eg replace with [{<

[nemo]

@Scott_Sauyet

But I also like @Yaisog’s suggestion of italicizing the variable names… although probably not the method of using mathematical Unicode symbols. That would make cutting and pasting too difficult.

I dont see the issue with using italic-via-unicode - copy and paste shouldn’t be any different than any other text, and these characters have been in unicode for nearly 25 years at this point - predating TW itself.

It might be more awkward for screen readers though, vs using «this» style of bracketing? (I also think the latter is easier to type, since it’s just two characters ever, rather than 26 character arranged in an unknowable range of combinations, that would make the only reasonable way to generate it be via a converter (I almost said “third party” but I’m sure a TW based conversion tool would be trivial for some of the folks here!). But it’s still an overhead to writing doco I’d expect.

tl;dr: I think « » style bracketing is preferable to 𝑢𝑛𝑖𝑐𝑜𝑑𝑒 𝑖𝑡𝑎𝑙𝑖𝑐𝑠

[pmario]

As I wrote, I did already create a PR that matches the current documentation style-guide

• I did add a line of introductory text about the placeholders
• I did add simple examples directly at the explanation table. So confusion should be minimal
• I did add a description about dynamic parameters using variables and transclusions
• I did add working examples

I did also search for other operators, that use angle brackets as <placeholders>. I think those tiddlers have to be changed in a similar way. Those placeholders confuse users to create non working filter expressions.

The Docs-PR-Maker edition is a great way to submit documentation changes that follow the style guides.

have fun!
-m