I18n Document about actionString's input variable

[linonetwo]

Command palette allow trigger actionString with tag tags: $:/tags/Actions.

I'm writing some AI action string that have some input prompt from variable, and output to a temp tiddler or user tiddler, tiddler name is get from variable too.

How to write metadata on fields or parameter widget, to tell Command palette plugin, what variable does it need? Like JSDoc. And it should allow i18n in name/description, so user can know what each variable means.

My solution

I thought tw's metadata use # to mean . in json. So this

caption: <<lingo ShowControlPanel $:/plugins/linonetwo/ai-actionstring/language/>>
tags: $:/tags/Actions
title: $:/plugins/linonetwo/ai-actionstring/Qwen
variables#prompt#caption: <<lingo Prompt/Caption $:/plugins/linonetwo/ai-actionstring/language/>>
variables#prompt#description: <<lingo Prompt/Description $:/plugins/linonetwo/ai-actionstring/language/>>
variables#prompt#defaultValue: Summarize this tiddler
variables#output#caption: <<lingo Output/Caption $:/plugins/linonetwo/ai-actionstring/language/>>
variables#output#description: <<lingo Output/Description $:/plugins/linonetwo/ai-actionstring/language/>>
variables#output#defaultValue: $:/temp/ai/output

means

{
  variables: {
    prompt: {
      caption: 'i18n value',
      description: 'i18n value',
      defaultValue: 'i18n value',
    },
    output: {
      caption: 'i18n value',
      description: 'i18n value',
      defaultValue: 'i18n value',
    }
  }
}

So I can reflect the usage of this action string tiddler in command palette's UI.

And if you agree with this pattern, I think it will also work for #8154 , so we can also add doc for build-in filter operator and action widget, and show then in a low-code UI.

Another not so tiddlywiki way

Use a schema field or variables-schema field, and put a JSONSchema in it. But it will be harder to edit.

I'm using this approach in https://tiddly-gittly.github.io/super-tag/ , but I don't think it will suit for tw-core.

Put in another tiddler

Maybe can use a data tiddler, and transclude it in variables-schema field.

[Jermolene]

Hi @linonetwo I agree that the ability to programmatically extract structured documentation would be very useful. I commented more fully over at #8154 (comment).

[linonetwo]

@Jermolene This involve another topic to discuss, action tiddler may have input and output, how to describe them using fields? Could there be a standard?

[Jermolene]

Hi @linonetwo as you note, one possibility would to be put all the documentation for a widget, action tiddler or other primitive into a single tiddler, using different fields for the separate items of data.

However, I think such an arrangement would be quite awkward for authoring. Two other alternatives:

• Storing the documentation as a big blob of structured JSON. Again, this would be rather unwieldy for authoring unless we had a full-fledged JSON editor
• Storing the documentation for a primitive as multiple separate tiddlers, using a naming convention to structure them

I favour the second approach. An action tiddler might be documented as follows:

• $:/docs/action-tiddlers/example - the root documentation tiddler for the primitive. The text field would contain the 50 word overview of the purpose of the primitive
• $:/docs/action-tiddlers/example/description - general description of the primitive
• $:/docs/action-tiddlers/example/inputs/a - description of the input "a"
• $:/docs/action-tiddlers/example/outputs/b - description of the output "b"

[linonetwo]

This is easy to write with .multid file, but I think this will produce 2~5k system tiddlers, will this impact performance?

[Jermolene]

Hi @linonetwo my general position is that many use cases require TiddlyWiki to be able to cope well with large numbers of tiddlers and so we must optimise performance in those cases. If the core starts to use more shadow tiddlers for example, we could choose to see that as an opportunity to drive further optimisation.

In the case of the docs tiddlers there might be a case for figuring out a mechanism for excluding them from the shadow tiddlers list.

[pmario]

... In the case of the docs tiddlers there might be a case for figuring out a mechanism for excluding them from the shadow tiddlers list.

TW should be able to handle several wiki-stores. IMO shadow is somewhat special since it contains the UI and plugins.

IMO "docs" or "content" plugins in general could use a "content-store", which is only visible with [all[content]] filter. This would make it possible to use [all[content+tiddlers]] or [all[tiddlers+content]]

just a thought