Ciao Stobot *Looks great. *The idea to have a "widget docs navigator" is spot on IMO.
In the *other *thread people din't so much like my comments on core documentation not needing to change much:-). BUT I think your example illustrates that targeted SUPPLEMENTARY documentation is very good! YES. The downside is the amount of work needed. That said, by constraining to one important aspect of TW in MORE DETAIL I hope would make it more manageable. (FYI I think there are other areas where more detailed docs would be helpful that OTHER people might take up to write. Like use of CSS in TW (understanding its rich cascade) and optimal use of SVG in TW. Just comments TT On Thursday, 27 May 2021 at 01:48:35 UTC+2 Stobot wrote: > This is a continuation of a conversation Mohammad started here ( Filter > operators: Official documentation (google.com) > <https://groups.google.com/g/tiddlywiki/c/mg6byRKEwMA> ). One thing that > has always struck me about TiddlyWiki widget documentation as different > from most other languages is that usually after a short description of the > purpose of the function, there's a syntax example so you can see how it's > put together, where the parameters (in our case attributes) go, which are > required etc. > > In that thread I volunteered to at least mock up a POC to gather thoughts. > As Jeremy correctly pointed out, it'd be of no use to do just 1 widget, > we'd have to do them all. So, I mocked up something flexible here > (Documentation > — Syntax for Widgets (tiddlyhost.com) > <https://docs-syntax.tiddlyhost.com/> ) for people to give thoughts on. > It might make sense to add a Disqus plugin or something if this gets > traction, but I haven't put anything there yet. > > While it seemed pretty cut and dry at first, it turns out there's a need > for some subjective thoughts / preferences on how to handle things. For > example, I think I'd like to show the full widget, even if the "content" is > ignored, to illustrate that fact, but some may disagree and we'd have to > think about how to show the "closed" version? like <$link/> rather than > <$link></$link>. Next would be how best to distinguish the difference > between required attributes and optional ones. Most other documentation > seems to use things like square brackets [] or angle brackets <> for this > stuff, but that would get confusing in TiddlyWiki, so I'm leaning towards > either color (red for required, green for optional) or more gently *bold* for > required, *italic* for optional. > > In the wiki, I've done a couple and have a table that lets you see it > side-by-side with current. See below for an example of the ImageWidget (red > lines to help you see diff) > [image: ImageWidget.PNG] > > It'd be a good deal of work to go through this with this, and there are a > bunch of decisions to be made I'm realizing after trying to do a few > things, like best way to handle when say either tiddler/field/index is > required - how to format that? I built the syntax area as a macro and put > the data in fields, so we tweak things easily. > > So, I'm essentially posting this to gauge interest and get ideas. Because > it'd be so much work, I don't want to start wasting time at something that > either nobody cares much about, or that wouldn't get implemented anyways. > Also I'll mention that Mohammad actually brought up filter operators > originally and I agree that could use the same treatment, so if this was > successful I/we could apply the same effort into those. > > > -- You received this message because you are subscribed to the Google Groups "TiddlyWiki" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/67aa1f9c-2685-4073-a37c-3dbafb02593an%40googlegroups.com.
