Folks,
In a similar vein I wanted to build a CSS reference which is hierarchical
and a search for a given css key work would show the names of the possible
parameters. Basically such a solution could be applied to the tiddlywiki
widgets etc...
However In the past the TiddlyWiki documentation has being wanting for me,
I would like to contribute more but there is too much to know about the
documentation macros to submit changes. An independent site for
contributions that someone then translates to formal documentation later
may be help full.
Here are some things I would like to see, and thus a contribution from me
on this matter
- I would like the ability to copy the full widget with ALL possible
parameters to the clipboard and paste into my design, basically a *full
syntax*.
- The larger widgets there are usually multiple common forms. such as
the list widget, each of these forms with only the relevant parameters
should also be listed for copy to clipboard.
- The default list widget
- Point to the filtered Transclusion equivalent
- List with an external template in use
- A list with a nested list with the result of the first referenced
in the inner list
- One of the biggest issues for me with the tiddlywiki examples and
documentation is far to often they use literals such as a tiddler name in
examples when in the real world they are best used in a view template or
toolbar and make use of the currentTiddler, or a found tag etc.. Examples
or syntax
- All documented macros should also provide a macrocall syntax as well
eg <<tag tagname>> AND <$macrocall $name=tag tag=<<tagname>>/>
- Examples should be designed to work on tiddlywiki.com with the content
available so people can make use of a rich data filled tiddlywiki to learn
from.
- We could provide plugins containing test data to support the
illustration of methods, data you can drop on an empty.html and be able to
test , against this data eg topical and non-tropical fruits etc..
- There are other prevalent gaps. For example all message tiddlers
should link to the "action send message widget", or button widget (send
message form), and the .Thus test against this data provide a list of
messages.
Also
My feeling is we need to consider the whole learning and designing
environment when documenting tiddlywiki, its not just is the information
there in all its richness, but how to practice it, and incorporate it into
our designs. this is not difficult just ask ourselves each time we revisit
a widgets documentation;
- Can a user take what's here and do practical experiments?
- How can this be an easy to use design resource?
In a related matter I realise most messages need a trigger such as a button
and many a parameter. So a generic button to invoke a message and supply
the parameter allows not only easy testing but a simpler way to design.
Basically in the long run it would be nice to provide a code patterns
resource/database.
Regards
tones
On Thursday, 27 May 2021 at 12:19:24 UTC+10 Soren Bjornstad wrote:
> 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/084ccc84-3930-4a46-8393-07f0db4ea510n%40googlegroups.com.
