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

Community Projects Documentation
#1
Purpose of this to-do wiki post (Note: *resolved issues have separate wiki below in this thread*)

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.

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 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

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.

Improve $importvariables widget documentation The widget works under very specific circumstances as [discussed](https://talk.tiddlywiki.org/t/problem-importing-contents-of-a-macro-definition-from-a-twcore-shadow-tiddler/2189/7) and this should be documented for end users.
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.

Shortform syntax detalis, explanation

by @twMat

A doc that explains what shortform syntax is, and why, and lists all existing ones and what widgets they are shortforms for and how they differ from them. And either also detail their individual syntax, or link to if this is explained elsewhere.

Better help for boolean logic

As pmario notes here, people often want to know how “or” works in filters. But “or” is too short as a search term! I propose a clear overview of boolean logic concepts for TiddlyWiki (conjunction, disjunction, nesting of those) where people can easily see they can get help with questions of form: “How do I just get {this criterion AND {this OR this}}”?

selection constructor examples, clarification

Selection constructor
…

  • A few operators ignore their input and generate an independent output instead. These are called selection constructors: they construct an entirely new selection.

Which few? This tiddler could use some help.

4 Likes
Request for Help: Documentation/Demo/Working Examples
Would like "this doc needs review" directly on tiddlywiki.com
Curating or flagging threads
Final Checks Before Release of v5.3.0
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.

1 Like
#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.

1 Like
#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