[IDEA] Inline document for filter operator and action widget

[linonetwo]

Is your feature request related to a problem? Please describe.

I'm going to create a visual editor for filter expression (solves #5058 ) and action widget (for https://talk.tiddlywiki.org/t/plugin-idea-visualize-the-action-widgets-as-workflow-graph/9620/4 ).

I need to filter all filter operator tiddler, and show then on toolbox of visual editor, and display its usage and fields. So I need their documentation to be on their fields. (params can be find in JS export, but I hope they can have description about usages)

Describe the solution you'd like

Move docs from tw5-com to language plugins, and use lingo macro in description field of filter operator and action widget tiddler, so I can wikify the field to display it. And user can see translated description.

And on tw5-com, we use lingo macro to transclude the doc back to doc site. This will make language plugin expand a bit (296 KB for filters, 215 KB for widgets, from tw5-com edition's folder).

Describe alternatives you've considered

I can also copy paste all docs to my visual editor plugin, but it can easily outdated, and the plugin need to contain all i18n files, so it will be 500KB * N huge.

Additional context

Visual editor is cool, isn't it?

[linonetwo]

See also #8230 @Jermolene

[Jermolene]

Hi @linonetwo I agree that it would be very useful to have programmatically integrated documentation for the core primitives.

What I would like to do is to repackage the reference documentation as a plugin so that people can have it available in their own wikis. We would use strict naming conventions so that it would be possible for tooling to extract structured documentation for a particular widget or filter operator. We would need to devise a scheme to allow for translated documentation plugins, and to allow the documentation to be extended by plugins.

[linonetwo]

Plugin title and tiddlers title

@Jermolene Based on #8230 (reply in thread) , Can I put them to docs/zh-Hans folder in the repo, with plugin prefix $:/docs/zh-Hans, simillar to plugins in languages/zh-Hans are $:/languages/zh-Hans. While tiddlers inside plugin are under prefix title: $:/docs/, no zh-Hans, simillar to core language plugins.

Each plugins includes all filter & widget & macros docs in a language. Use namespace like $:/docs/filter-operators/jsonget

$:/docs/filter-operators/jsonget/desc will contains its description. (need extra /description or /desc path after it, so it could finally become a valid JSON)

$:/docs/filter-operators/jsonget/caption will contains its friendly name, this is optional, only when its name is too hard to read.

$:/docs/filter-operators/jsonget/purpose will contains General Operators Order Operators Listops Operators, these will also be translatable, and can generate table based on these tiddlers.

Usage

In WYSIWYG editor and Visual Filter builder, I can get the list by [all[shadows]prefix[$:/docs/filter-operators/]] or prefix[$:/docs/filter-operators/jsonget/], and use some JS to build the result as a JSON. (Or let core provide such a JS method, or even a filter operator.).

And to use it in a list widget, we need a filter operator that gets all $:/docs/filter-operators/xxx but not $:/docs/filter-operators/xxx/yyy/zzz.

Enums

Since we are not going to use tags and fields for docs, some metadata needs to be done by enum.

Filter operators will have enum like Constrcutor NonConstrcutor, based on this concept:

C ... Most steps process the selection of titles that are supplied as their input, but a few construct an entirely new selection instead

This is not translatable, but to use .multid we can't put them in a field, so still have to put this under

$:/docs/filter-operators/jsonget/constructor-type

Still, we are going to generate table based on these tiddlers.

For widgets, $:/docs/action-tiddlers/example-widget/inputs/a/type will have enum like number string date

[Jermolene]

Thank you @linonetwo. I think you are suggesting that docs plugins should act like language plugins in that their content would be switched in and out as the current language changes. That's an intriguing idea and would seem consistent with the latest work on #8435.

Your schema proposal looks reasonable. My instinct would be for each item of data to be stored as a separate tiddler, but I appreciate that that might lead to a proliferation of tiddlers.