If you write clearly, others can update to match the jargon, and perhaps learn where the jargon itself is too obscure.
That’s the idea. The documentation should be collectively developed. I might start something, only to have Springer correct my misunderstanding, and then you could further improve the readability, and later, when there is a new version with a minor change, perhaps Mario will update to explain the changes.
But everyone’s idea of a basic question is quite different. One person’s first question is how to add italics, another’s is how to customize a list of links, a third is how to make a plugin to communicate with an external site.
Perhaps; it really depends on A, B, and C,… and perhaps on X and Y as well.
It also depends on what you mean by “workable examples”. Most examples beyond simple formatting will depend on filters and lists… which in turn depend on the data in your wiki. So an example like this
Using a TagWidget Inside a ListWidget.json (605 Bytes)
A slightly more performant option is to use the `variable="transclusion"` attribute in the list widget.
In this case, the variable `<<transclusion>>` has to be used inside the list widget instead of the
`<<currentTiddler>>` .
<$macrocall $name=".example" n="1" eg="""<$list filter="[tag[HelloThere]]" variable="transclusion">
* <$link to=<<transclusion>>/> is tagged with: <$list filter="[<transclusion>tags[]]"> <<tag>> </$list>
</$list>"""/>
will work great if you download it and drag the file to tiddlywiki.com. But it uses the .example macro, which is part of that page, but not of the default edition. And even if you grabbed that too. for this to be a useful demo, your page will have to have tiddlers with the tag HelloThere. If you don’t, you won’t see anything.
Depending upon what you mean by that, you may find that many of TW features are simply out of reach. If for instance you are uninterested in learning about filters and lists, then you reduce TW mostly to a way to format and organize your text. If you ignore transclusions, then some of the key reuse that makes TW so powerful is lost.
If however, you simply mean that you’ll learn whatever Wikitext you need, but will steer far clear of even touching JavaScript, then you’re in very good company. Many of the advanced users here work that way.
What I meant by different newbies having different questions was that your post included this:
This list is very specific to you and to your usage. Another newbie might not think in terms of “files”. (While we understand what you mean, it’s not how we discuss tiddlers here.) She might have no idea why you want to create a button to create a new tiddler, as it already exists and is visible in all the common editions. She might intuitively understand the need for tags and fields. But she might still be stymied by other things which come to you naturally.
That’s why we need to organize the information we present, but there is no obvious way to determine the best organization.
How to create a tiddler should certainly be part of the basics. But all these others are going to be much more sophisticated. As I said, my work on a Recipe Edition has fallen down, but assuming that I can do that soon(ish), and assuming that we can create other similar editions, perhaps we can give new users the ability to use TW for various specific purposes. But these would be useful samples; hopefully the curious could then learn how to modify TW for their own purposes, but they wouldn’t serve as tutorial-level documentation.
Can I suggest that at first you just do it in a standalone wiki available to the public (Tiddlyhost, GitHub, wherever), and then send us a link to whatever tiddlers you would like to see incorporated in the documentation. Once you have something to contribute, there are tools to let you contribute suggestions directly to the documentation.
First off, that tiddler really should make the initial “railroad diagrams” a link to the Wikipedia page or some other good source of that information.
I agree that this tiddler is hard to understand. A big part of the reason is that it is so meta. It uses Railroad diagrams to describe the syntax for creating Railroad Diagrams! It would be nice to use different color schemes for the two levels of diagrams used.
But first of all, this is a fairly specialized tool. It is used for describing grammars, almost always for programming constructs. You can see how it looks in Filter Syntax and then by clicking on the diagram terms such as Filter Expression, drilling down through the levels of the filter syntax. A good example is Filter Step:
This should look something like railroad diagrams, which show what tracks a train can run on across the yard. A train can’t make a hard turn, so only certain options are allowed from any position. In this diagram, we can either start with a ! character or skip it. Those two options come back together, and from there we can either omit the operator/suffixes bit (by, according to the note, defaulting to “title”), or go through the operator/suffixes bit, and again we come back together, to require a parameter, and either continue on or add a comma and another parameter. The operator/suffixes section allows us to either include or skip an operator, then include any number of suffixes (including none at all), each preceded by a :.
This captures all grammatical filter steps. This does not mean the string in question makes logical sense, but it is at least syntactically correct.
The filter step compare:number:lt[3] would proceed like this:
- We start at the left end of the track
- We skip the
!, riding on the top branch - We have an operator of
compare, on the main track - We have the token
:followed by the suffix ofnumberon the main track - We follow the lower track back to the main branch
- We have the token
:followed by the suffix ofeqon the main track - We have the parameter of
[3]on the main track - We finish on the right end of the track
But again, this is a fairly specialized tool. It is excellent at making the Filter syntax more clear, but unless your wiki is describing grammatical constructs, you’re not likely to ever need it.
Tiddlywiki seriously blurs the distinction between writing content and creating an application. One of the main points of wikitext/filters/widgets is to make it so you don’t need advanced programming language features to write more dynamic views of your content.
Edit: this is very much worth reading: Improving TiddlyWiki Documentation, as is 7 Steps to Improve the TiddlyWiki Documentation .