mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-28 02:50:27 +00:00
bfcb386343
* Restructure and optimize `CheckboxWidget` docs * Minor improvements * Use new tab macros and some reformatting * Fix bug in widget-attr-link tooltip * Minor layout tweaks * First try at a Widget Documentation Style Guide * Add new tabs-related macros to overview * Update CSS, add tm-scroll and rename macros * Avoid RSoE with tm-scroll, improve CSS for tab-links * Handle doc-tab-links within tab tiddlers better * Reflect macro name changes in their docs * Update Widget Doc Style Guide
37 lines
2.7 KiB
Plaintext
37 lines
2.7 KiB
Plaintext
created: 20230318160840043
|
|
modified: 20230325162525198
|
|
tags: [[Reference Tiddlers]]
|
|
title: Widget Documentation Style Guide
|
|
|
|
Widget documentation generally consists of
|
|
|
|
* an introductory summary of the widget's function
|
|
* an overview of attributes and how the widget content is handled
|
|
* more detailed attribute explanation when required
|
|
* examples
|
|
|
|
The //Content and Attributes// section should describe how the content of the widget is used, followed by a table of the possible attributes, each with a short description of a single sentence. The attribute names in the table and elsewhere in the tiddler should be rendered with the <<.var .attr>> macro. The <<.var .from-version>> macro should be used as first item in the description to designate the version at which a parameter became available.
|
|
|
|
A subsection should be used for parameters that need an //extended description//, possibly with separate examples. When there are more than 2 such subsection necessary, the subsections should be split into their own tiddlers, and the <<.var .doc-tabs>> macro should be used to transclude them into the widget documentation tiddler as tabs.
|
|
|
|
* The <<.var .doc-tabs>> macro is used without parameters
|
|
* The <<.var .doc-tabs>> macro must not be used more than once within a single documentation tiddler
|
|
* The tiddlers to be included in the tab group should be tagged with the respective widget documentation tiddler and have a <<.field description>> field set to <<.value tab>>
|
|
* The <<.field caption>> contains the tab button text. It should be as short as possible. For the attribute name, the <<.var .attr>> macro should be used in the <<.field caption>>
|
|
* The tab tiddlers should start with a level-2-heading that links to itself, so that they may be opened from within the tabs
|
|
* They can contain examples if these are specific to the topic of the subsection
|
|
|
|
In the attribute table, the <<.var .widget-attr-link>> macro can be used to turn attributes into a button that activates the respective tab. The <<.var .widget-attr-link>> macro is used like this
|
|
|
|
```
|
|
<<.widget-attr-link text:<display text> target:<title of corresponding tiddler> >>
|
|
```
|
|
|
|
Elsewhere, the <<.var .doc-tab-link>> macro can be used to activate the respective tab
|
|
|
|
```
|
|
<<.doc-tab-link text:<display text> target:<title of corresponding tiddler> tooltip:<tooltip to show when hovering over the button> class:<additional classes> >>
|
|
```
|
|
The parameters <<.param tooltip>> and <<.param class>> are optional.
|
|
|
|
Both link macros scroll to the tab group additionally to setting the selected tab. They can also be used within the tab contents tiddlers themselves. If a tab tiddler is opened outside the tab group, <<.var doc-tab-link>> will open the tiddler containing the tab group if it is not yet open, and scroll to its tab group if it is. |