Can Hierarchical Navigation Benefit TW Documentation?

Everything is hard to maintain if human intervention is needed, because it’s error prone and it’s very likely to be forgotten.

It should be possible to programmatically list tiddlers which have more than one parent that happens to be in the TableOfContents. We need only indicate one of those to be the “true parent” and thus privilege that path. This could be done with one byte or even just one bit applied if we had the mechanism.

  • I have not tested this yet but I don’t think the TOC is too intertwined.
  • For future content we can also demand this standard.

As we know the TOC uses tagging to structure its contents. Unlike TocP which in effect enforces single parents by design, tags can be used in an ad hoc way that does not obey the rules of hierarchy.

My preferred approach would be to remove tags so we had one primary parent and move those tags link and backlink into the tiddlers content like a see also reference.

  • This is a once off transformation and does not loose information.
  • Going forward we insist on one parent, for new or edited contents items.

It we had this over again I would enforce this with TOCP driving the hierarchy and tags only use as additional cross referencing, or the use them as tags should be.

  • Then the hierarchy would be a deterministic tree we can programmatically implement.
  • We have many ways to implement cross heirachy references in tiddlywiki so we do not compromise any freedoms.

Yes. There is an “automatic” path that is used by the algorithm. If the wrong path is used there is the exclude parameter, which can be used to switch paths. … That’s not perfect, but the easiest way I could come up with.

In the current TW documentation that’s not allowed and probably never will be. I did discuss this issue somewhere at GH and Jeremy says, that having several tags for 1 tiddler will have to stay that way. (Can’t find that conversation atm.)

I was suggesting something similar but inverted: when for a given tiddler the algorithmic default path to the root is not the one you want to promote, you can add a parent field to say, “Go this way instead”. The start of the path should only change when you alter the tags of the tiddler, so it should be straightforward to change then and there. The rest of the path might change if an ancestor node on the hierarchy changes paths, but we shouldn’t have to worry about that from within this tiddler.

It’s maintenance, but not terrible, I believe.

My own idea is coming clearer. Let’s imagine it first as a plugin. It might make more sense in the core, but we can start with a plugin. There is one tiddler that serves as configuration for the plugin, and (for now) it has just a list field, showing the root tags we want to present as part of the hierarchy. On tw-com, perhaps these are just Reference and Features, or perhaps it’s almost everything in the Contents tab. The order of the values in the list serves to help choose the default path when there are multiple options. The length of the path would also help – shorter paths are preferred.

To present this, we have the path presented in the format I have above and which @pmario improved in his version (with the flat left-hand edge on the first entry,) I’m thinking of a presentation a little different from @TW_Tones’s suggestion of boxes showing the alternative hierarchies. Instead, the whole bar might sit inside a dropdown, allowing you to make an alternative path visible.

Where this would be placed is still an open question to me, but I’m leaning toward shrinking it a little and putting it above the title:

Reference > Widgets > Message Handler Widgets >
Link Catcher

If there are multiple paths, the default one is shown, with a dropdown:

Reference > Mechanisms  > 
Drag and Drop Mechanism

Which, when expanded shows the others, probably overlaid, not in-lined, but this should show the idea:

Reference > Mechanisms >
  Features > Drag and Drop > 
  Features > Importing Tiddlers >
Drag and Drop Mechanism

And which on a change, might look like this:

Features > Drag and Drop > 
Drag and Drop Mechanism

If that’s the one we would prefer for a default, we could add a field to Drag and Drop Mechanism: location-parent: [[Drag and Drop]].

We would also probably need to be able to collapse longer paths

Foo >  Bar > … > Grault > Garply >
Waldo

and expand them on click of the ellipsis:

Foo >  Bar > Baz > Qux > Quux > Corge > Grault > Garply >
Waldo

But that bit wouldn’t be necessary for a proof-of-concept.

I have not yet dug into either of your implementations, but hope to do so soon for code to inspire me (or just to steal! ;-)) I don’t yet know if this idea is within my TW abilities. But I hope to look soon.

1 Like

I love it. The user would understand easily the concept of the hierarchical navitation and how use it, we just need to find how to display it without it add too noise in the ui and it has enought visibility.

About how to create the hierarchy and preference, I had thought idea similar to @Scott_Sauyet , it is about creating as many lists as levels there are in the ToC and these list can be ordered to generate a preference. It would be more easily maintainable than the idea of a tiddler that stores all paths. I was playing for a while with the idea and the filters, but I didn’t find how to make it work.

In my location bars example shared above and there Location bars — Exploring breadcrumbs and hierarchies a button is used to generatet a datatiddler only one link to each parent is maintained. At the moment the last wins.

  • It is here any trigger or algorithm can be used to choose which is the primary parent and store that.

The location bar is designed to also show alternative parents outside the branch.

  • although as I have recently replied, I belive to be an unambiguous TOC, we can author the contents differently then can use the location bar algorithm, without change because there will be only one parent.
1 Like

Yes I saw it before, it great but the use the tag pill could create confusion althout there are

I only found your “tree toc” tiddler, I didn’t find how it was created. I don’t know how create the data, but the primary parent for each tiddler is unmantaible, IMHO. If the doc would have changes in its structure and we would make any error that break how it works. I think with the ordered lists of different level of ToC would be a simple solution to avoid and solve possible problems, and these lists would be easily maintainable.

Use the contents tab to open any tiddler in the tree, to see it working.

Thanks for your review and response @Alvaro please revisit the example.

  • Just a matter of how it looks was not the key issue here, to me it was the content of the location bar.
  • That is why they are in the kbd format, This is an “unpublished POC”, however I would like to apply the styling mentioned earlier in this thread to differentiate.
    • It is important in my view to still use tag pills, even if they do not look like them, I have just installed my “reimagine tags” package that adds a lot of smarts to tag pills.

I have added $:/PSaT/location-bars to the Home tiddler a link to the package involved but;

  • This is generated with a single button click in “Table of Contents tree capture - trimmed” also added to Home.
  • I don’t agree, you just need to alter the algorithm in the capture button as needed, but whilst the content proports to be a pure hierarchy it is not, and we could make it so, by moving multiple parents into cross references. See my previose replies on this.
  • That is almost exactly what I have done, it just happens to be an ordered list in a data tiddler. Thus you can just check if any tiddler title is a member and what is its place in the heirachy (full branch to it). Set once, query many times, not need for a large variable to be maintained.
  • By storing it in a data tiddlers, you can use this for different views/releases, or to manage a publishing step, and submit a single tiddler change through Github.

This thread is quite large now

@Scott_Sauyet is it possible for you to tell be how to apply this format to a subset of tag pills with CSS?
image

I wouldn’t maintain anything, only try to create this block when the tiddler is rendered.

I haven’t dug into the TOC code, but something vaguely similar should work, albeit in the reverse direction. A ViewTemplate would look at the tiddler’s tags, the tags of those tag tiddlers (if they exist), and the tags of those, recursively, until we’ve run out of parent tags, or hit one of our configured root tags. In order to prevent cycles, there would have to be a way to exclude ones we’ve already seen in the current path. Then the paths that led to one of our root tags are individually reversed, sorted according to our ordering and possible local overrides. If there are no paths, we show nothing. If there is exactly one, we show it. If there are multiples, we then handle the group them, perhaps like I suggested, or like @TW_Tones showed, or maybe in some way we haven’t yet considered.

The CSS I used is in Can Hierarchical Navigation Benefit TW Documentation? - #10 by Scott_Sauyet. To update it to work on some group of tag pills would entail giving that group a class name such as the "breadcrumbs" I used and replacing a.crumb with something matching the markup generated for the tag pill. I can try to look at it soon, but the next two days are pretty busy.

But that was just a rough proof-of-concept. I think @pmario’s latest improves on it quite a bit. I don’t know, though, if he’s using actual tag pills, or other button/link styling.

Here I capture the tree by finding which tiddlers tag the current one, then in a given tiddler, lookup the tree for it from the captured list.

  • Since only one “path” is available for a given tiddler, I then do something similar to your approach above, but just separately list the other “alternative parents”.
  • But since I already have a definitive path to the root just show the tag pill of these other “false parent” tiddlers, if they exist. You can go to the tiddler to discover its branch.
    • No I am not controlling which is a true or false parent yet.

I’ll look again soon, when my brain isn’t telling me it’s bedtime. But at the moment, I’m not understanding this well enough. I cannot figure out where the variable branch is actually set.

I could be entirely missing the point. I worry about this top-down approach, though. On my – admittedly underpowered – device, this takes about five seconds to run. Won’t it need to rerun on every tag change anywhere?

That’s the “field” mode in the breadcrumbs macro. … It basically uses the list-field by default and lists the whole “trail”.

  • With tags you “only” can go up in the history.
  • With lists you show the full path if you want. So even elements in the middle can show parents and child’s.
    • That would be a different usecase … So can not be tested atm
1 Like

Get some sleep, return at your leasure.

  • Was in a disabled button, now enabled within ## Table of Contents tree capture - trimmed
    • Because the button reused the list of tiddlers and their branches, so was a very big button. Fixed
  • It traverses the tree, building the branch as it goes, and saves in the data tiddler, branch from a given tiddler wins.

I will tidy it up a little for your next visit.

  • Depends, yes to update the tree, if there was a new or retagged tiddler in the TOC, but it will continue with its old status fine.
  • My use case was the relatively static tiddlywiki.com contents tree. Sometimes the need for an intentional update is helpful.
    • I may do it differently if it was for dynamic content, but I would make the new content obey the rules.

Just curious, the list field is typically empty on tag tiddlers unless the order was changed?

That’s right. It basically is a “manual” process to create it. By default it’s “list” but it can or even should be a different name eg: “story”, “trail” or “path”

Those lists need to be created and maintained manually. … That’s the difference between tag-like and list-like history definitions.

1 Like

@TW_Tones , I know that it isn’t your finished idea. I talk about visual aspect of your example, because I had the feeling that you felt that I was not paying attention to your proposal and it was not like that, only that I had nothing more to add than what was added by the rest.

Yes, I saw the button and its macros, but there is some point where I get lost and I can’t see where/when/how the datatiddler is being generated. I am stuck.

My mistake, I wrote “we” thinking about the community. I didn’t talk about anyone.

My idead is pointed here, instead of have many lists for trail/path, we can have create a basics structure of paths with ordered lists by preference. This has a minor cost of mantain but I don’t know how I will be the computational cost.

Sorry, cross-communication here. I meant that I would hope we could do this entirely without any maintenance, just an initial configuration listing the roots of the hierarchy, that everything else would be automated, using something related to the TOC macros.