Documentation tiddlers on TiddlyWiki.com in need of work (please contribute to the list)

Community Projects Documentation
#1

This is a list of specific topics or tiddlers on TiddlyWiki.com that are out of date or missing information, and can be worked on without need for prior discussion.

The goal is to provide a starting point for those motivated to work on documentation.

To help keep the listed topics immediately actionable for those wanting to work on documentation, please keep this list focused on specific tiddlers that need work or are missing. More general concerns like “XYZ topic is difficult to understand and needs to be explained in a different way” or “We need a different kind of documentation for topic A”, are better posted in a separate topic and discussed in more detail as to how they should be addressed.

Filter run prefix documentation tiddlers missing for most prefixes.
As of of v5.1.23 and v5.2.0 the filter syntax now supports named filter run prefixes and a rich variety of prefixes that allow filter runs to be combined in very flexible and powerful ways. We have specific documentation tiddlers for the two prefixes added in 5.2.0, that is :sort and :map and reduce. However, all of the other filter run prefixes do not have their own documentation tiddlers.

What needs to be done here is to review https://tiddlywiki.com/#Filter%20Expression and for all of the other filter run prefixes mentioned, documentation tiddlers created using the :sort and :map documentation tiddlers as a template.

Update: All prefixes introduced 5.1.23 and later are documented as described above. All the older prefixes remain to be documented.

Rewrite “Filter Expression” tiddler

The Filter Expression tiddler has grown and become quite difficult to read as we have added more filter run prefixes. This tiddler needs to be re-written to present more intuitively the different filter run prefixes and how they interact, linking to in depth documentation for each.

WidgetMessage tiddlers
All of the tiddlers with prefix WidgetMessage need to be reviewed. Many of them are written from the perspective of a JavaScript developer and do not convey how to use the messages from wikitext.

Examples for insertbefore operator
It seems that insertbefore misses examples. see: https://tiddlywiki.com/#insertbefore%20Operator

Examples missing for haschanged operator
There is a link in the operator documentation but no tiddler for the examples.
https://tiddlywiki.com/#haschanged%20Operator

Update all “WidgetMessage:” tiddlers to include examples with copy to clipboard
By @TW_Tones

Most of these widget messages are used through action-sendmessage eg;

<$action-sendmessage $message="tm-close-tiddler" $param="tiddlername"/>

or within a button or other widget;

message="tm-close-tiddler" param="tiddlername"

This could be automated with a macro you simply pass the message name to it.
<<.messageexamples tm-close-tiddler>>

Also link to an updated Provide examples for the ButtonWidget

Provide examples for the ButtonWidget
By @TW_Tones

  • tiddlers to include examples with copy to clipboard
  • There a a number of different patterns to using the Button Widget this can be collated and documented;

For example;

Send Messages with a button to trigger them.
<$button message=“tm-close-tiddler” param=“tiddlername”>Close tiddler</$button>

A dummy button for documentation, eg this displays an “Open” button and does nothing.
<$button tooltip="This is a dummy button">Open</$button>

And others such as to toggle a tag or field

Edit-text widget

Add to edit and edit-text widgets how to address a missing width attribute when wanting to get 100% width. In the core the widgets are given the class
class="tc-edit-texteditor tc-edit-texteditor-body"

Compare and contrast :sort filter prefix with the various sort operators

For example, +[!sortan[]] might be the shorthand equivalent of :sort:alphanumeric:reverse[{!!title}]. Maybe all of the *sort* operators can be expressed similarly with the :sort filter prefix.

Maybe there are subtle differences which should be mentioned?

Guidance about field-mangler widget vs. action-setfield and action-listops widgets

For the cases I (@btheado) have thought about the action widgets are always better, but maybe I haven’t thought of enough cases? Are there cases when the field-mangler widget is better? Or maybe it is a personal preference?

Whatever the case, these documentation tiddlers should be cross-linked with each other with some advice given on when to use one over the other.

currentTab variable doc is missing
by @twMat

If authored, it should probably include the tags Core Variables and Variables (to show up in those doc tids). Looking at the listing in the Core Variables doc shows we’re inconsistent in how we caption these doc tids, i.e should it be captioned just “currentTab” or should it be captioned “currentTab variable”? The doc tiddler “tabs Macro” is the only doc I can find that references this so the mention of it in that tid should probably be a link.

Improve $importvariables widget documentation
The widget works under very specific circumstances as discussed and this should be documented for end users.

copy-to-clipboard-above-right macro in core is undocumented.

Improve doc on how to contribute translations
by @twMat
The tiddler Translate TiddlyWiki into your language assumes there exists no translation but it does not inform how to edit existing translation tids.

There is also a contradiction: The above link explicitly says you don’t need “knowledge of Node.js or GitHub” but the dev tiddler explicitly states the exact opposite.

Missing reference to new pragma parsermode

The new in v5.2.4 pragma \parsermode is not listed in the tiddler Pragma.

AutoSave tiddler (last modified in 2016) has missing link to SaverModule. This tiddler, especially with missing link, but also with the “if” phrasing up front, may be scary to a newbie.

image
image1668×406 48.4 KB

4 Likes
Would like "this doc needs review" directly on tiddlywiki.com
Request for Help: Documentation/Demo/Working Examples
Final Checks Before Release of v5.3.0
Curating or flagging threads
Request for Help: Documentation/Demo/Working Examples
Clarification on the use of hashmap(s)
#2

Resolved:

1 Like
#4

@twMat Errors, missing docs are fine to list here, basically anything that is easily actionable without need for discussion. The idea is to make it easier for those that are motivated to work on documentation to have some immediately actionable items to work on.

New ideas and different ways of presenting things are better posted as new topics, like your idea for flagging docs tiddlers for review on tw-com. Here it just adds clutter and will probably be overlooked.

#5

@twMat I have removed “:intersect doc is missing”, I assume you refer to the prefix run and not operator (since there isn’t one), in which case it is covered under the very first item on the list “Filter run prefix documentation tiddlers missing for most prefixes”

#6

I removed my separate idea and started a new thread as per your suggestion. Thanks.

#7

@TW_Tones the following would require discussion and is not immediately actionable, and should therefore be posted as separate topic:

Many of the widget attributes throughout the documentation have minimal explanations and examples rarely cover all attributes.

Perhaps we need tiddlers for each attribute name (or selected ones) with more details eg tabindex aria-label autocomplete to name a few. Just search for them in tiddlywiki.com and you will see they can be too brief, and occur in more than only one tiddler. Most of the time any additional details would be the same, there may be a need for disambiguation sometimes.

My argument here is establishing a mechaisium for the additional info by popup or link.

#8

Submitted PR 6174

1 Like
#9

Maybe there could be a section at the bottom of the top post wiki where resolved items are posted, so there can be some sense of momentum? I know in theory I could just add the section, but thought I would ask first.

#10

Good idea. I had thought about posting comments for resolved items but that would fast get messy.

I have repurposed the second post in the thread (one of mine) as a second wiki post for resolved items. Please feel free to edit as you see fit. We also need not always link to PRs for resolved items either.

#12

Bump. Just because it’s an important thread.

1 Like
#13

Clearly. First I’ve seen it. Thanks!

#14

Well, I tried. I got one done. The problem seems to be that the macro that produces the examples can’t also demonstrate a ‘production ready’ example that itself uses macros, which apparently is the preferred method. There was some talk of creating an example macro that could do this, but I don’t know what the outcome is. There was also some talk about removing ‘paramObject’, which I assumed would have been long gone if Jeremy wanted it gone since it’s a simple fix. So that’s ambiguous also.

So I think we need an example of an example that will pass muster.

#15

I took a crack at this a while back but it also still needs further work that I have not had the opportunity for: tm-open-window documentation improvements by saqimtiaz · Pull Request #6232 · Jermolene/TiddlyWiki5 · GitHub

#16

I have noted Brian (@btheado) has done great job on improving documentation and add new materials!

Thank you Brian!

#17

The problem I was thinking about was with the demonstration macro. There was an expressed desire to have demonstrated actions moved to a (demonstrated) macro. But the examples come at the bottom, and AFAIK you can’t define a macro mid-page.

1 Like
#18

There is a useful trick that we use in the docs in a few places – the typed block syntax works by embedding an entire wikitext context, which allows macro definitions. For example:

Some text at the top

$$$text/vnd.tiddlywiki
\define something() else

<$text text=<<something>>/>
$$$
3 Likes
#19

Is there, indeed? How did I miss that (beyond the obvious, RTFM)? :blush:

For anyone else that needs the lowdown, it’s documented in plain sight here:

https://tiddlywiki.com/#Typed%20Blocks%20in%20WikiText

1 Like
#20

If that may make you feel better @CodaCoder , I knew about the typed block thing and yet never made the connection that it allows to define macro inside … thanks a lot for this tip @jeremyruston !

Is there a way to make the macro inside the typed block accessible globally ?

Some text before

$$$text/vnd.tiddlywiki
\define something() else

inside : <<something>>
$$$

outside : <<something>> --> possible to make it work ?
2 Likes
#21

No – it behaves as if the same content were transcluded from another tiddler.

#22

copy-to-clipboard-above-right macro in core is undocumented.

1 Like