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…

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 v…

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), fu…

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.

[image] 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. H…

Perhaps this can be added to hints and tips?

Here’s one thread where there was a bit more discussion: [image] 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.

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 inste…

[image] 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 …

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>>// …

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 …

Consider changing variable markers in documentation

Springer September 9, 2025, 1:08am 18

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