Adding code snippets to TiddlyWiki documentation or otherwise

[TW_Tones]

Folks,

I would like to raise the question of “Adding code snippets to TiddlyWiki documentation or otherwise”.

The Question

As the new and improved ways to contribute to the documentation become available will we enhance the documentation with better examples and snippets?, or should we consider building a separate plugin containing these snippets ?

Background

If you surf your way through tiddlywiki.com you will often find examples that also include a snippet or example of code you can try and or copy to clipboard.

Now in the above example it may be of value to copy to to the clipboard and use this in your own code however it is not going to be that common.

If now you go to WidgetMessage: tm-add-field you see this;

• No examples, no snipits etc…

I would like to populate tiddlywiki.com with more code snippets with the various forms of a given widget so once we find what we are looking for there is a convenient copy to clipboard snippet to make use of that widget in our wikis.

Action send messages are a particularly good case to consider because they are usually part of a larger piece of code such as a button or an ActionSendMessageWidget and an example less likely.

Here is an example of the above with snipits and inline example.

We could

• Introduce a view template to all tiddlywiki.com tiddlers that looks for $:/snippits/tiddlername and displays it below the body and then as we build our snippets plugin if installed all the snipits become visible.
• OR just edit the existing tiddlers to include this extra “documentation”.

An advantage with the separate snippet plugin is it is a separate development effort and not so tied to the formal release of tiddlywiki.com even if it was installed by default.

What are your thoughts?

[btheado]

@TW_Tones

I would like to populate tiddlywiki.com with more code snippets with the various forms of a given widget so once we find what we are looking for there is a convenient copy to clipboard snippet to make use of that widget in our wikis.

I’m in favor of more examples. I learn best from examples and I like it when they are interactive. The ability to copy and paste is also helpful.

@TW_Tones

We could

• Introduce a view template to all tiddlywiki.com tiddlers that looks for $:/snippits/tiddlername and displays it below the body and then as we build our snippets plugin if installed all the snipits become visible.
• OR just edit the existing tiddlers to include this extra “documentation”.

I can think of several questions related to the above. Depending on the answers, they can be considered somewhat independently.

Embed examples in the tiddler or not?

1. WidgetMessage tiddlers (several do have examples already) have their examples embedded.
2. Widget tiddlers for the most part have their examples embedded. The RangeWidget is one exception. It embeds a few examples and transcludes another. ActionCreateTiddlerWidget is another exception and it transcludes examples from several separate tiddlers.
3. Filter operators for the most part have their examples in separate tiddlers. The bottom of each of these tiddlers has a link “Examples”. This link is rendered via the .operator-examples macro call. The duplicateslugs and range operators are two exceptions. For those the examples are embedded.
4. Core Macros all have their examples in separate tiddlers

If the examples are in separate tiddlers, then what naming convention to use?

1. Currently the convention is [tiddlername] (Examples)
2. You are proposing $:/snippits/[tiddlername]

Package the examples into a separate plugin?

@TW_Tones

An advantage with the separate snippet plugin is it is a separate development effort and not so tied to the formal release of tiddlywiki.com even if it was installed by default.

This one I don’t understand enough how it would be implemented in a way to gain that advantage.

[Charlie_Veniot]

I am a big fan of documentation being in one TiddlyWiki, and sample code existing in one or more other TiddlyWikis.

Reference video.

Project Portal aside (it is a Google Site to all things BASIC Anywhere Machine) …

BASIC Anywhere Machine is a TiddlyWiki instance with IDE and code, all about creating, running, storing, maintaining programs.

BASIC Anywhere Machine Programming Reference is a separate TiddlyWiki, all about documentation.

But code from the BASIC Anywhere Machine TiddlyWiki seamlessly shows in the Programming Reference TiddlyWiki, as if it was just one TiddlyWiki, but it isn’t. Code from one TiddlyWiki is shown in the other TiddlyWiki in an iframe, and shown on demand.

It only requires a little bit of “infrastructure” in both TiddlyWiki’s including “tagging” of programs (i.e. code) so the right example programs gets loaded for particular documentation.

Eventually, I’ll have things working in the other direction. Working on a program in the IDE, show contextual documentation.

To each thing a purpose and a place.

Yeah, I love this kind of stuff: knowledge/information/content organized to the gills. Existing in one place, available everywhere.

[TW_Tones]

Separate snippet plugin ?

@btheado

This one I don’t understand enough how it would be implemented in a way to gain that advantage.

If we package all snipits in a plugin it remains independent of tiddlywiki.com and can grow in size, complexity and maintained by anyone, even outside of github. If a user wants to pump up the documentation with a lot of additional code snippets they simple install the plugin and when and if a snippit exists it will be displayed at the bottom of the matching tiddler on tiddlywiki.com (or a copy there of).

If you do have a copy of tiddlywiki.com locally we can also add the ability to collect stats on which snipits you copy, present most recently used, and Most used lists all making the use of snippits a great designer resource.

[markkerrigan]

Mario mentioned this in another thread, but I recalled something about how macros can be defined inline. I would suggest creating a new tiddler (maybe Documentation Example Macros), as the existing Documentation Macros doesn’t address any of the code snippet macros (of which there are several slightly different but similar macros.)

[pmario]

@TW_Tones

We could

• Introduce a view template to all tiddlywiki.com tiddlers that looks for $:/snippits/tiddlername and displays it below the body and then as we build our snippets plugin if installed all the snipits become visible.
• OR just edit the existing tiddlers to include this extra “documentation”.

I think there is an established mechanism to work with “examples” for reference documentation. It’s how Filter Operators work.

eg:

• There is an “all Operator” tiddler and
• “all Operator (Examples)” tiddler

The former contains the reference docs. The later contains all examples. In all Operators there is a macro call at the end of the text: <<.operator-examples "all">> … This macro uses the “all” parameter and creates the link.

You are right. That macro call could be part of a template, but that would be a different undertaking.

So my suggestion is

• We create a similar macro <<.message-examples "tm-add-field">>
• Which links to a new tiddler: WidgetMessage: tm-add-field (Examples)
• Those example tiddlers may be constructed in a way you describe here

It will be important to have a closer look at: https://tiddlywiki.com/#Documentation%20Style%20Guide

The mechanism, how to tackle a change like this is described at: 7 Steps to Improve the TiddlyWiki Documentation

have fun!
Mario

[pmario]

@TW_Tones

Separate snippet plugin ?

I think we have the mechanisms in place. We may need some new macros, but I don’t see a new plugin.

[TW_Tones]

@pmario

but I don’t see a new plugin

The plugin is so the content can be developed and optionally installed.

A well designed plugin of additional snipits could be arbitrarily large and it would be wise not to make it dependant on the documentation macros.