syntax: filters - call for improving documentation

[CarloGgi]

Hallo everybody,

I'm quite new to TW and though I love it, going through the online documentation is painful.

Talking about one of the core features of TW, filters, from the online documentation it is very hard to me to grasp exhaustive rules about *where* a filter is syntactically allowed in TW, and given the crucial role filters play in TW architecture, I would suggest that the matter cannot be left unaddressed.

As far as a beginner can see, filters are surely allowed inside `<$list>` and `<$transclude>` widgets, as well as inside macro calls, and they can be assigned to a variable via the `<$set>` widget, but this falls very much short of comprehensively describing their syntactical usage throughout TW. What other widgets are filters allowed inside, and with what syntax? Filters' syntactical usage inside widgets is never described in a dedicated page/section/paragraph of the documentation, one has to gather up information on the matter incrementally, by browsing the documentation page after page.

For example, let's go through the online documentation by starting from page Filters

https://tiddlywiki.com/static/Filters.html

From here we learn that "A filter is a concise notation for selecting a particular set of tiddlers, known as its output. Whenever TiddlyWiki encounters a filter, it calculates the output." Fair enough, now we are left with the question of *where* can  TiddlyWiki encounter a filter.
A few rows below, we come across the example macro call

`<<list-links "[prefix[H]]">>`

from which we can assume that one of the possible places filters belong to syntactically is a macro call.

Let's go further, to page 'Introduction to filters notation'

https://tiddlywiki.com/static/Introduction%2520to%2520filter%2520notation.html

where we can read "Filters do nothing if you just type them into a tiddler on their own. They need a context." The text falls short of giving us any further detail of what a filter's context should be, and the rest of the page gives detailed examples of how to build filters without giving us any clue on *where* we can put them in the code.

All the other documentation pages about filters deal with their syntax, so we get to learn what is a filter expression, a filter run, a filter step, a filter parameter and what are the filter operators, but not a single bit of text shedding some light on *where* can we put filters in the context of TW syntax.

This matter is so crucial and central to the whole architecture of TW, it definitely needs to be addressed in a dedicated section, it cannot be left so opaque and hidden as it currently is.

Thanks and regards,

CG

[Jeremy Ruston]

Hi Carlo

Thanks for your interest. Preparing good quality documentation is a challenge for us, as it seems to be for many open source projects. The documentation needs to be written to serve the needs of a wide range of users; changes and improvements need to be consistently applied to keep things uniform and easy to follow.

Clear, specific feedback like this can be a great help in identifying areas that can be improved.

I'll answer your questions here to keep the discussion moving, but of course it's much more valuable if we can update the documentation to make these points clearer.

Talking about one of the core features of TW, filters, from the online documentation it is very hard to me to grasp exhaustive rules about *where* a filter is syntactically allowed in TW, and given the crucial role filters play in TW architecture, I would suggest that the matter cannot be left unaddressed.

As far as a beginner can see, filters are surely allowed inside `<$list>` and `<$transclude>` widgets, as well as inside macro calls, and they can be assigned to a variable via the `<$set>` widget, but this falls very much short of comprehensively describing their syntactical usage throughout TW. What other widgets are filters allowed inside, and with what syntax? Filters' syntactical usage inside widgets is never described in a dedicated page/section/paragraph of the documentation, one has to gather up information on the matter incrementally, by browsing the documentation page after page.

A difficulty with the terminology is that a filter is written as a string (all filters are expressed as strings; some strings express filters). Further, some of the time we might need to construct or process a filter as a string (for example, concatenating substrings to make a filter). In such cases, one is providing a filter to widgets/macros that expect strings, because we are processing the filter as a string rather than evaluating it as a filter.

For example, let's go through the online documentation by starting from page Filters

https://tiddlywiki.com/static/Filters.html

From here we learn that "A filter is a concise notation for selecting a particular set of tiddlers, known as its output. Whenever TiddlyWiki encounters a filter, it calculates the output." Fair enough, now we are left with the question of *where* can  TiddlyWiki encounter a filter.
A few rows below, we come across the example macro call

`<<list-links "[prefix[H]]">>`

from which we can assume that one of the possible places filters belong to syntactically is a macro call.

Macro calls take generic string parameters. It's up to the specific macro to choose whether or not to interpret a parameter as a filter or some other kind of string.

Let's go further, to page 'Introduction to filters notation'

https://tiddlywiki.com/static/Introduction%2520to%2520filter%2520notation.html

where we can read "Filters do nothing if you just type them into a tiddler on their own. They need a context." The text falls short of giving us any further detail of what a filter's context should be, and the rest of the page gives detailed examples of how to build filters without giving us any clue on *where* we can put them in the code.

Indeed, it does beg questions about the context in which it does work. As I recall it, that line was added in response to queries from users who had interpreted the docs as meaning that filters were evaluated when used in ordinary text.

All the other documentation pages about filters deal with their syntax, so we get to learn what is a filter expression, a filter run, a filter step, a filter parameter and what are the filter operators, but not a single bit of text shedding some light on *where* can we put filters in the context of TW syntax.

This matter is so crucial and central to the whole architecture of TW, it definitely needs to be addressed in a dedicated section, it cannot be left so opaque and hidden as it currently is.

So it seems like the most direct way to address this would be to add a new docs tiddler listing the contexts in which filters can be used, with links to the corresponding docs. I'll add it to my list, or very happy to help you or anyone else make a contribution.

Best wishes

Jeremy

Thanks and regards,

CG

--
To post: TiddlyW...@googlegroups.com
To unsubscribe: TiddlyWikiDoc...@googlegroups.com
More info: http://groups.google.com/group/tiddlywikidocs?hl=en
Visit the wiki at: http://wiki.tiddlywiki.org
---
You received this message because you are subscribed to the Google Groups "TiddlyWikiDocs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywikidoc...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidocs/13fb6a2a-2b9f-479c-ac89-37bc3d76bd64n%40googlegroups.com.

[CarloGgi]

Hallo Jeremy, thanks for your prompt reply.

More clear, detailed documentation is indeed badly needed, TW has a rather steep learning curve and making it lower can only add to the benefit of newcomers.

Just only what you said so far would be a first, very much valuable information enrichment, let me quote it below here:

• A difficulty with the terminology is that a filter is written as a string (all filters are expressed as strings; some strings express filters). Further, some of the time we might need to construct or process a filter as a string (for example, concatenating substrings to make a filter). In such cases, one is providing a filter to widgets/macros that expect strings, because we are processing the filter as a string rather than evaluating it as a filter.

• Macro calls take generic string parameters. It's up to the specific macro to choose whether or not to interpret a parameter as a filter or some other kind of string.

Also, in reply to your closing statement:

So it seems like the most direct way to address this would be to add a new docs tiddler listing the contexts in which filters can be used, with links to the corresponding docs. I'll add it to my list, or very happy to help you or anyone else make a contribution.

my humble answer is: 'yes, definitely!' And not only listing the contexts in a separate tiddler, but also -this will take time, I know- provide each macro documentation page with info on where and how the macro can accept [also] a filter as a parameter value. This can be made much more easy to understand adding examples.

Many thanks and regards,

Carlo.