Query - how to refer to widgets in documentation

[clutterstack]

Hi all,

I've had a quick search, but I'm not sure I've found all the discussions on this.

Looking through the docs at tiddlywiki.com, I'm not certain how best to refer to a widget.

If I look at some fairly recently-modified tiddlers, such as ActionConfirmWidget, widget names are bolded using WikiText (e.g. ''action-confirm'' widget). In other places it might be written and linked with CamelCase (which I understand has fallen out of favour, but works well for existing CamelCase tiddler names). Documentation macros such as .wid are used in some places, as well.

Is there a "right" way to do this in 2021? Are the documentation macros preferred?

Thanks,
Chris

[Jermolene]

Hi @clutterstack we use camel case titles like NavigatorWidget to link to each widget docs, but within the docs for a widget we'll typically just use the name of the widget in bold.

I don't think there's much usage of the <<.wid>> macro at the moment.

It's hard to keep stuff like this consistent so any improvements are welcome.

[pmario]

... It's hard to keep stuff like this consistent so any improvements are welcome.

I think the "doc-macros" where mainly implemented / introduced 1 contributor. The advantage, if we use them consistently, is that changing the macro once can change the formatting globally.

BUT We didn't reach "consistent usage" yet ;)

[clutterstack]

Not sure I'm making things more consistent...I went with the wikitext bolding for widgets and macros but used documentation macros for parameters, variables, and fields in my PR (#5477).

Of course open to adjusting if people have strong opinions for going forward.

[pmario]

You did ask. That's a good thing! Thx.

If you create new documentation you are always welcome!!