The following is a rough outline for how I think the docs for “Filter Run Prefixes” should be organized.
We currently have the docs:
Filter Run Prefix (Examples) (seemingly mis-tagged “Filter Run Prefix Examples”, as that is how the actual examples are tagged. The tiddler should perhaps itself be the tag… but my proposal below would render this tiddler redundant regardless.)
…but there is no tiddler titled only “Filter Run Prefix” (nor in plural form)
There is a doc titled Named Filter Run Prefix which offhandedly mentions “…single-character prefix (+, - and so on)” (and, incidentally, the previously mentioned “Filter Run Prefix (Examples)” only deals with named filter run prefixes).
…but there is no dedicated doc about “Single-character prefix/es”
…but there is the doc Filter Expression which clearly takes aim at being a comprehensive doc about “filter expressions” and/but the majority of it is about most of the filter run prefixes. This approach probably worked well when there were few filter run prefixes (…even if it was always tricky to search for, say, +) but, given the role that filter run prefixes has gained, it is clear we need a new approach:
I propose all filter run prefixes are collected in a single tiddler named “Filter Run Prefixes” that is equivalent to the comprehensive “Filter Operators” doc (more on this below). This tiddler should both present the “filter run prefixes” and the “single-character prefixes” (the distinction is insignificant in practice).
Like with the individual filter operator docs, the individual filter run prefix docs can link to their respective examples.
I am unfortunately not qualified to author the actual text about these things, but here is at least some code to aggregate the relevant named filter prefixes. I have no idea how to aggregate the single-character filter prefixes:
The list also makes it evident that about half the docs on the (named) prefixes are currently missing.
Like with individual filter operators I would like for each filter run prefix to have a separate purpose field so that, like the extremely useful Filter Operators doc, the “Filter Run Prefixes” umbrella tiddler should present a generated table with the headlines “Filter Run Prefix” (with link to that specific doc) and “Purpose” (thus transcluded), etc.
Thanks for your work!
I like the clickable railroad topics, the breadcrumb and the general organization of the documentation, which I find much more logical than previous version.
The order of the Parents breadcrumb looked inverted to me at first, but it’s probably a matter of point of view, and not a big deal to get accustomed to.
Overall a very significant step in the good direction!
The annoying thing for me (and perhaps it’s just me) is that the moment a railroad link is clicked, the context is lost when the new tiddler opens. When you’ve done that a few times, the story starts scrolling (as you’d expect) and the context loss is compounded.
I’m astonished I’m decrying the addition of links… but that’s my feedback. Then I start to use the breadcrumbs – perhaps they’ll help, I wonder?
I’m with @tw-FRed (and later @Scott_Sauyet). That unconventional breadcrumbs order introduces a cognitive stumbling block I cannot get past. Not only are the RR-links breaking the context (again, for me) the breadcrumbs are unintuitively reversed, making my cognitive (context parser?) stumble again
I don’t think you need a better word for parents, I think the breadcrumbs should lead BACK (left) through the notional hierarchy… you know, like they’ve come to be used conventionally.
Aside: (Dear Firefox spellchecker, “unintuitively” is a word.)
Breadcrumbs navigation: Jeremy suggested that this will become a separate PR, but it is currently still part of this one. If it stays, it might need a bit of work, design-wise.
I would still rather pull the breadcrumbs out into a separate PR because I think it will take a bit more iteration to get them right, and that will otherwise hold up the entire PR.
You are right. .. I was thinking about that too. … The first thing was to get the breadcrumbs to actually see the context.
Then I was thinking (but did not implement) about opening the links in there hierarchical order. So higher level info should be at the top of the story river. Depending on how many tiddlers are open already the order should even be sorted.
Let’s say:
Filter
Filter Expression … are open already and “Filter Syntax” is clicked by the user it should look like this
The story river should look like this.
Filter
Filter Syntax
Filter Expression
So the order in the river should be also hierarchical, which IMO makes the content stay in context of a “real story”
And the Open Sidebar would also reflect that order
Thanks, @pmario, I’m glad you understood where I was coming from – I wasn’t entirely sure I’d expressed it clearly. But your response is bang on.
Yes. Perfect, I’d say. And the breadcrumb trail should reflect the same order (IMO).
Obviously, we’d need to document why the river is behaving differently/strangely.
I did have a thought, which I rapidly dismissed: that each RR-link launched a draggable-popover such that the context is still visible without excessive scrolling and the resulting loss of context. But I’m not sure I like that – not a fan of popup docs.
