I'm liking this idea!
Thoughts on this mockup specifically:
- I'm thinking maybe "required" and "inherited css" should be in
parentheses to indicate those are not actually values?
- Maybe a couple of key examples that demonstrate most of the attributes?
- I agree on no brackets for required/optional. Please don't use red and
green only as the distinguisher, that makes it unnecessarily difficult for
color-blind people. You could use red and blue, or better yet also make one
of them italic or something. Or maybe go simple and just do *bold* for
required attributes and normal font for optional ones?
- When CLI tools do this, they usually provide a metasyntactic variable
for each value to make the syntax complete, rather than just listing the
attribute name. So maybe something like:
<$image source="MyImageTiddler" width=N height=N tooltip="tooltip"
alt="alt text" class="my-css-class"/>
- We could transclude the values from a series of tiddlers that store
the "standard" value for each type of attribute or named and reused
attribute (e.g., "class"), so that it is consistent across all of them.
- If there's a default value, it would make sense to list that. Not
sure how to distinguish that from a variable...maybe a different
font/color?
- I hadn't even thought of this before, but why are these attributes
in the order they are? Would it make more sense to have all required
attributes in alphabetical order, then all optional ones in alphabetical
order?
- For the part where one of multiple attributes is required, what about
e.g.,
<$action-setfield $tiddler="tid" ($field="field" | $index = "index" |
*text* field) $value="value" />
On Wednesday, May 26, 2021 at 6:48:35 PM UTC-5 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/4d8fb719-357f-4711-8a7b-d7a0aca34a0dn%40googlegroups.com.
