Consider changing variable markers in documentation

[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

[Yaisog]

Instead of reinventing the wheel and presenting the reader with yet another variation of displaying source code, why don’t we follow e.g. MDN as the reference for all things web-related.

As far as I can tell, they use the Prism library and, more importantly, color to distinguish keywords (blue), function names (red), literal strings (green) and other stuff (black):

taken from String.prototype.startsWith() - JavaScript | MDN

In the upper image, searchString is a parameter that is explained below the code block, similar to how tiddlywiki.com does it. In examples, you’d color the parameter green if it’s literal, like so:

This would be much easier to understand than trying to find another form of bracket that is not used by TW yet, as well as looking familiar to anyone that has used the MDN Docs before.

[TW_Tones]

Some thopught should be given to color blind users, we have a few. Perhaps just enabling alternative colors.

• Perhaps we can document how to generate filters then use them such that we can programaticaly alter the “literal” parameters in the suffix.

[Springer]

@TW_Tones

Some thopught should be given to color blind users, we have a few. Perhaps just enabling alternative colors.

A while back, I wanted a “pie-slice” color scheme that would be visually distinguishable across most kinds of human color vision variation. So I did some research.

Here’s an explanation of some of the standards I was reading about, by Paul Tol, and here’s the palette I chose. This is the set of colors that (according to Paul Tol) avoids creating confusion for most viewers (Next to each swatch is the basic three-digit color, and then a suggested darker variant for each.)

[TW_Tones]

Perhaps this can be added to hints and tips?

[Springer]

Here’s one thread where there was a bit more discussion:

Accessible Text

This popped into my work inbox. The Basics of Accessible Documents and I wondered what we can do in TW to make our docs more accessible, best practice and all that.

[Yaisog]

I would expect that the team that is trying to document the web for everyone (MDN) already did put some thought in making it work also for color-impaired people, though I cannot be sure.

However, the color discussion sidetracks the original discussion and the argument that we should use color instead of more brackets to make our documentation better instead of reinventing the wheel every time. I fear we are going down the usual path of concentrating on the disadvantages and details of each proposal so much that we cannot agree on making a change at all, even though the current solution is much worse in many ways.

Implementing a particular set of colors would be the easiest part of realizing this. The hard part would be to create and maintain rules for e.g. prismjs to do the actual coloring. The upside then would be that we have a method for basic syntax highlighting that could also be used for displaying tiddler source code.

[Scott_Sauyet]

@Yaisog

However, the color discussion sidetracks the original discussion and the argument that we should use color instead of more brackets to make our documentation better instead of reinventing the wheel every time.

The color discussion is worth having, too, though. I don’t object if they’re commingled. The basic question is simply how do we make filter examples in the docs wiki more clear.

I’m wondering if the best bet would be to introduce new widgets that would allow us to parse and format filters in a universal way. The range Operator starts like this:

The `range` operator produces a list of numbers counting up or down.  It is useful for counting and numbering.

<<.from-version "5.2.0">> The range operator has been updated to use multiple parameters. Prior to this version, the range operator only had one parameter, with the three parts delimited by `,`, `;` or `:`.

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

The behaviour depends on the number of parameters:

|Parameter |Output |h
|`<end>` |Whole numbers up to `<end>` |
|`<begin>,<end>` |Numbers from `<begin>` to `<end>`, spaced by whole numbers |
|`<begin>,<end>,<step>` |Numbers from `<begin>` to `<end>` spaced out by `<step>` |

But I’m thinking that we could perhaps do this:

The `range` operator produces a list of numbers counting up or down.  It is useful for counting and numbering.

<<.from-version "5.2.0">> The range operator has been updated to use multiple parameters. Prior to this version, the range operator only had one parameter, with the three parts delimited by `,`, `;` or `:`.

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

The behaviour depends on the number of parameters:

|Parameter |Output |h
|<$docs.filter>«end»></$docs.filter> |Whole numbers up to <$docs.filter>«end»></$docs.filter>  |
|<$docs.filter>«begin»></$docs.filter> docs.filter «end»>> |Numbers from <$docs.filter>«begin»></$docs.filter> to <$docs.filter>«end»></$docs.filter> , spaced by whole numbers |
|<$docs.filter>«begin»></$docs.filter>,<$docs.filter>«end»></$docs.filter>,<$docs.filter>«step»></$docs.filter>   |Numbers from <$docs.filter>«begin»></$docs.filter>  to <$docs.filter>«end»></$docs.filter>  spaced out by <$docs.filter>«step»></$docs.filter>  |

And then the highlight module (or prismjs, if that won’t work) would be used to set colors, fonts and other styles for our filters.

But I still think that an unambiguous bracket not used by TW would help demonstrate that we mean any of the different possible brackets. Since these would be used only for syntax description and not for specific examples, I don’t think it would add much confusion, and I think it would clear up some current confusion… That’s why I used, for instance, «begin»> above.

[EricShulman]

I think I would prefer italics rather than the double-chevron chars. It provides a visually distinct appearance, but avoids entering special characters or any issues with color perception.

and it’s easy to implement using a .docs-param(p) procedure, like this:

\procedure .docs-param(p) //<<p>>//

The `range` operator produces a list of numbers counting up or down.  It is useful for counting and numbering.

<<.from-version "5.2.0">> The range operator has been updated to use multiple parameters. Prior to this version, the range operator only had one parameter, with the three parts delimited by `,`, `;` or `:`.

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

The behaviour depends on the number of parameters:

|Parameter |Output |h
|`end` |Whole numbers up to `end` |
|`begin,end` |Numbers from `begin` to `end`, spaced by whole numbers |
|`begin,end,step` |Numbers from `begin` to `end` spaced out by `step` |

[nemo]

I’m the reverse - I don’t think the distinction should rely on fonts style and colourisation, but leverage a distinction at the character level. Whether that’s a unicode « » (for me that’s significantly simpler to type than <<.docs-param > but YMMV) or something in the traditional ascii range if it can be found (would [range[%begin%]] conflict with other wikicode things? I’m not a windows guy, but I’m aware of batch scripting enough to recognise that as a batch script variable)

[Scott_Sauyet]

@EricShulman

it’s easy to implement using a .docs-param(p) procedure

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.

@EricShulman

I think I would prefer italics rather than the double-chevron chars.

@nemo

I’m the reverse - I don’t think the distinction should rely on fonts style and colourisation, but leverage a distinction at the character level.

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.

[twMat]

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?

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

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

[twMat]

@Scott_Sauyet

I’m greedy. I want it all. I would love to colorize and add bold/italics/something. And I want […]

YES! Finally Comic Sans in TW!!!

Elegance for the masses! Jeremy will love it!

[Springer]

@twMat

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.

[TW_Tones]

[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.

[Scott_Sauyet]

@twMat

I propose that any suggestion here is accompanied by a simple screenshot of how the end result would appear?

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.

[TW_Tones]

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?

[Scott_Sauyet]

@TW_Tones

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.

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.

[Yaisog]

@TW_Tones

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.

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.