TiddlyWiki Documentation - Syntax

[Stobot]

This is a continuation of a conversation Mohammad started here ( Filter operators: Official documentation (google.com) ). 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) ) 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)

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. 

[Soren Bjornstad]

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" />

[TW Tones]

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

[Mohammad Rahmani]

Hi Stobot,

First many thanks for initiating this and the wonderful mock up! This makes things much clearer!

PLEASE NOTE: do not give up! This is hard and time consuming work! and you do not have many contributors around you!

1. I have tried to use some standards for documentation in all kookma plugins (20+) and I can share my experiences from them

2. As an example, look at Shiraz. It uses a special Tutorial tiddler that populates all documentations

3. There are basic/simple examples and then advanced examples

4. For a closer look see Alert Macro

4.1. There is a short description e.g purpose

4.2. There is a Syntax section followed by purpose

4.3. Next table of contents and attributes

4.4. The attributes table has a column type and it clearly states which parameter is optional which is required! If optional what is the default value

4.5 Then there are some basic examples

4.6. If there is an exception, need special attention, there is Remarks section

4.7. More advanced examples are given later!

Note 1

As Soren noted, DO NOT USE COLORS! 1. colors cause problems when people like to use other color palettes (official palettes have some issues also) 2. cause color blindness problem.

I may suggest going with bold/italic.

Note 2

I may suggest having a constant number of sections for all widgets! e.g (purpose, syntax, content and attributes, examples, remarks)

A template can be used here

Note 3

I really wish you get good feedback from experienced users especially those with pedagogical skills

There are some previous efforts for improving documentation, Good to see

Best wishes

Mohammad

--
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 tiddlywiki+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/71fe27de-65a8-4eff-b2b6-de802e3641aen%40googlegroups.com.

[Mohammad Rahmani]

Stobot,

 I have attached a sample doc from Matlab to get some ideas!

 It is good to see other softwares

In Matlab, they have brought separate sections at the end to describe input argument / output arguments

But as you said first they explained the purpose and the syntax!

Best wishes

Mohammad

On Thu, May 27, 2021 at 4:18 AM Stobot <sto...@gmail.com> wrote:

[Mohammad Rahmani]

I have attached a sample doc from Excel

The same sequence: purpose, syntax, arguments (in/out parameters), remarks, examples

Best wishes

Mohammad

On Thu, May 27, 2021 at 4:18 AM Stobot <sto...@gmail.com> wrote:

[TiddlyTweeter]

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

[TiddlyTweeter]

Mohammad wrote:

I have attached a sample doc from Excel

The same sequence: purpose, syntax, arguments (in/out parameters), remarks, examples

 

Ha. Very good example!

And, YES. We are all Sinners, and especially Microsoft :-)

TT

[Álvaro]

Thanks for the iniciative and the work.

- I think that put only name attribute could be confused for newcomers. They can think that widgets work like a macro, when (I think that) the widget works like a html tag.

- I am rethinking the idea of create a syntax example for each widget or macro. Maybe it is better try to do it in the widget documentation, in the tiddler Widgets in WikiText, and then create a line in each widget linking this tiddler. And the point "Widget attributes can be specified as:" will be more helpful.

My idea would look something like this (Using some doc macro), but I was thinking in macros.

\define tag-init() <
\define tag-end() >

<pre><<tag-init>><<.wid Mywidget>> ''attribute1''="value1" //attribute1//="value1"<<tag-end>>
CONTENT
<<tag-init>>/<<.wid Mywidget>><<tag-end>>
</pre>

But it doesn't look good (in color-contrast) in the name of widget/macro. And i don't know if it is cofused or not, maybe I need apply the style to all string of attribute ( attributeX="valueX"). Or Maybe we don't need if we use a table with column "type" as use Mohammad in their macros.

[Stobot]

Thanks everyone for the feedback!

@Soren

• Good point about the formatting on the values in the Default section, I'll try parentheses. 
• I ''strongly'' agree that every attribute should have an example. I might have to put that as a secondary effort though to make sure I finish this. 
• Good reminder again on color-blindness. I did end up going with the bold / italic setup so I think I'll stick with that unless I hear of something better
• I like the note about doing source="MyImageTiddler" rather than just source as I have it. I actually did that originally, but after realizing how many attributes some of these things have, I counter-balanced against the length of the syntax mockup. I think you're probably right anyways, and I think your point about a maintained table of example values per type makes sense - good idea. But take a look at something like <$edit-text/> which has 20 attributes. At a certain length, I worry we would lose people, or you then get into a kind of stepped layout where each attribute gets a newline?
• I agree on the order, I did put all the required ones first, and then took some liberty on ones I thought were most common, but alphabetical probably makes more sense. Counter to that might be to bundle (sort together) the ones that go together. 
• Your last point on multiple required attributes is similar to where I was thinking about too. For reference, using your example - <$action-setfield> 
  • Your suggestion: <$action-setfield $tiddler="tid" ($field="field" | $index = "index" | text field) $value="value" />  - what does the text field part mean?
  • I was thinking about the combinations that were valid could all be spelled out. For example either tiddler or field are fine, and if you use index you need tiddler too.
  • So maybe: <$action-setfield ( $tiddler | $field | $tiddler + $field | $tiddler + $index ) $value /> - though again that gets long if there are lots of options like this.

@Tones

• I commented on your other thread on CSS - I agree that's an opportunity for a little more to be added to the documentation also
• I also like the "copy to clipboard" piece. I saw that in many of the examples and will try to implement it by reverse-engineering the core macro that does it. 
• You bring up a lot of other things that while valid, would be massive scope creep on an already large effort, but I'm happy to pencil in for future "phases"
  • Multiple versions of common widgets, like the filtered transclusion example, good point. 
  • Documentation of macros & <$macrocall/> syntax
  • Examples should all work on TiddlyWiki.com - totally agree. I think the whole "recipe book" idea as base data (as is used for some of the filter stuff is a good starting point myself)
  • Test-data / plugins: Good ideas too, as above, I think a small internal dataset like recipes / ingredients etc. are perfect for starting though
  • Send-message vs. action widgets (paraphrasing) also valid thing to further describe
  • Whole learning environment: My personal opinion based on other languages is that I like the core to support main syntax and examples, and leave external sources for more guided training (such as Soren's Grok book and videos)

@Mohammad

• I'll take a look at Shiraz and the Alert Macro as you suggest.
• The general flow you illustrate sounds good to me, and I think is similar to what TiddlyWiki has, but with just a few missing pieces.
• Agree with you and Soren on bold / italic vs. colors, good point
• I agree (mostly) on the consistent outline (constant number of sections), though to keep the scope small, thought would be to split the effort into phases to increase the liklihood of it getting finished. 
  • Syntax and Attributes table would be phase I
  • Examples and other cleanup could be phase II etc.
• I agree on referring to the other languages for inspiration. A saying I'll sometimes use is that "sometimes consistency is more important than accuracy" which sounds counter-intuitive, but if the end result is learning, absorbing material is job 1

@TiddlyTweeter

• I understood where you were going with your comments in the other thread. I think there is definitely a "too far" area, and having much deeper learning can be better handled in other places, with other mediums even
• I agree on the scope, and will definitely not make everyone happy with what I plan on doing, but I think it most prudent to break the effort into phases as mentioned above. If I / we don't do this, the chance of giving up before completion is high
  • Just adding the Syntax section and tweaking the Attribution section is what I'm considering phase I, Examples maybe phase II, and then other areas besides widgets (filter operators, macros, CSS, SVG etc. could come later)

@Álvaro

• That point is really valid and Soren agrees. As I mentioned to him I only worry about the length, but you additionally make the point that without it, people could falsely assume that you can omit the parameter name and have it work in a position-based way, which you can't. So maybe I'll have to relent there.
• I'm not clear on your second point. I will say that the mockup does in fact use a macro as a template as you describe if you scroll down a bit, so all of the parameter information is in fields and the syntax bit is generated centrally so it can be tweaked. If you mean something else, maybe elaborate a bit more?

All, thank you again for the feedback, I'll take another look tonight and incorporate what I can from the above. As mentioned I'll intend to do this in phases and at least make it through Phase I. My day-job is quite strenuous right now (normally 12-hours/day X 5 days and then maybe 4 hours/day on the weekend), so this will go slowly. For those curious, I run a team of project managers, so that's where my background of project managent, scope, requirements etc. comes from. 

Parting questions for now:

• Is there a  better way to get per-tiddler commentary? I think I mentioned doing the Disqus thing, is anyone interested in participating that way? I wish there was a multi-user environment available for this kind of thing. 
• Who has to approve this for it to get implemnted? I know @Mohammad offered to turn the result of this into a pull-request. I still worry we might get to the end of this whole effort and the right person doesn't say yes?

[PMario]

On Thursday, May 27, 2021 at 1:48:35 AM UTC+2 Stobot wrote:

...

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) ) 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. 

We do have Gitter.im and Discord for "slow pace" discussions and the GG here for immediate feedback. So IMO no new service is needed.

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.

The overall structure seems to be OK

 

For example, I think I'd like to show the full widget, even if the "content" is ignored, to illustrate that fact,

I'm in favour, that this info gets a more prominent place.

BUT

but some may disagree and we'd have to think about how to show the "closed" version?

If there is a "closed version" it should also be mentioned in the "Syntax" area.

 

like <$link/> rather than <$link></$link>.

 

Next would be how best to distinguish the difference between required attributes and optional ones.

I would be OK with "bold" and "italic" ... BUT every attribute should have _only_ 1 formatting. ... So  bold-italic should _not_ happen.

 

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. 

As written above. .. +1

 

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. 

That's a good decision, so we can change the layout globally. ... It may evolve over time, once more and more operators get added.

 

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.

Till now it looks good!

 

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. 

+1

-mario

 

[PMario]

On Thursday, May 27, 2021 at 4:19:24 AM UTC+2 Soren Bjornstad wrote:

 

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" />

I do like this example. We'll see how it looks like with widgets, that have many possibilities. Especially the "early" widgets, like <$button..> which have a "black box" like of behaviour.

-m

[Mohammad Rahmani]

Best wishes

Mohammad

Sure! I help with PRs! No worries on this and if you like I can prepare a short slideshow to teach you how to do so! I am sure Saq and Jeremy will be there to answer our questions and give advice on how to do this!

 

On Thursday, May 27, 2021 at 2:56:35 AM UTC-4 TiddlyTweeter wrote:

Mohammad wrote:

I have attached a sample doc from Excel

The same sequence: purpose, syntax, arguments (in/out parameters), remarks, examples

 

Ha. Very good example!

And, YES. We are all Sinners, and especially Microsoft :-)

TT

--

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 tiddlywiki+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/9936c0a8-f090-4973-bdc6-d4551b5e5879n%40googlegroups.com.

[TW Tones]

Folks,

When documenting code perhaps mouse over and alt text could be used along with highlighting so an optional items being bold nd green could support screen readers and the color blind with mouse over text? We do have  rich environment available after all. I am sure there are standards we can follow.

Tones 

[Stobot]

Progress and feedback gathering:

• The main suggestion I wanted to take a look at first was adding "metasyntactic variables", which was suggested by many of you. I had expressed my concern with length, so want to show that below and at the link to get feedback. 
• Added these attribute strings in a dictionary so they can be shared /consistent between widgets
• Added parenthesis around defaults that are not variable names

Review here:

Documentation — Syntax for Widgets (tiddlyhost.com)

So on the site now I show a V1 (original), V2 (adding the metasyntactic variables), and V3 with them, but splitting each attribute into a new line. It's not clear to me which is best because I change my mind depending on how many attributes there are. While V3 I think makes it easier to read for widgets with MANY attributes, I wonder then if it's worth just combining the syntax and attribute table altogether since it'd probably fit all side by side (think syntax as col1 of a table with the description, defaults as other columns... 

Examples - fairly simple = Image

Examples - more complex = Edit-text

[Ste]

I have no idea if this would be more hassle than it's worth or would be a workable work flow but could text stretch or stretch text be used to present a condensed version which could be expanded? 

https://links.tiddlywiki.com/urls/7f9e7e60ed40b5098996

https://links.tiddlywiki.com/urls/618ef8913574d547c412

[Mohammad Rahmani]

I love this bold/italic format! Now at a short glance one understand how to call the widget!

If readability does matter, then V3 is the most readable but may take more space and look lengthy!

My experience says having a standard form for all widgets makes learning them easier!

I also recommend to keep the table! as it has a column of explanation to all attributes! in other words the table is a descriptive tool clarify everything while the syntax is only an abstract form!

Lets see what other says!

Best wishes

Mohammad

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/e126ce9d-38b6-4d15-83ff-9108397b070dn%40googlegroups.com.

[Odin]

I like V1 the best in combination with the table. This way the part in the codeblock in a quick overview that can be copied. And if an user needs more information, they can look it up in the table.

Op zaterdag 29 mei 2021 om 19:01:03 UTC+2 schreef Mohammad:

[TiddlyTweeter]

Stobot wrote:

Review here:

Documentation — Syntax for Widgets (tiddlyhost.com)

So on the site now I show a V1 (original), V2 (adding the metasyntactic variables), and V3 with them, but splitting each attribute into a new line. It's not clear to me which is best because I change my mind depending on how many attributes there are. While V3 I think makes it easier to read for widgets with MANY attributes, I wonder then if it's worth just combining the syntax and attribute table altogether since it'd probably fit all side by side (think syntax as col1 of a table with the description, defaults as other columns... 

The Right column, "New", I think is excellent, because it is comprehensive ...

I would consider ...

1. ... moving the  "Attributes" table to the top ...
2. ... using either <$reveal>... or <details>... to hide sections so its not too overwhelming and the end-user can expand only the sections they need to see.

Just thoughts

TT

[PMario]

On Saturday, May 29, 2021 at 6:10:32 PM UTC+2 Stobot wrote:

Examples - more complex = Edit-text

I personally would favour Version 1 for the Intro overview.

The valure-options as shown in Versioin 2 should be part of the detailed description in the "Attributes table"

Just my thoughts.

-mario

[PMario]

On Monday, May 31, 2021 at 10:06:33 AM UTC+2 TiddlyTweeter wrote:

... using either <$reveal>... or <details>... to hide sections so its not too overwhelming and the end-user can expand only the sections they need to see.

At the moment Jeremy doesn't accept PRs that contain the <details> element, because it doesn't store open/close state.

I think, we need a <$details> widget, that can handle persistent state, in the core first.

-mario

[TiddlyTweeter]

TiddlyTweeter wrote:

... using either <$reveal>... or <details>... to hide sections so its not too overwhelming and the end-user can expand only the sections they need to see.

PMario replied: 

At the moment Jeremy doesn't accept PRs that contain the <details> element, because it doesn't store open/close state.

I think, we need a <$details> widget, that can handle persistent state, in the core first.

HA! <details> is super simple. ADD "open" or remove it. 

   Should be a doddle. 

It is NOT intelligent like <$reveal> which handles well complex situations, but in MANY use cases <details> binary sate is all you need.

Side comment

TT

[Stobot]

Great continued feedback. I'll keep going, but just to mass-reply:

PMario

• I agree that the "closed version" should be in a small general syntax notes area - maybe right below the syntax block. Things like:
  • Each attribute can be given as "Text Value", {{Trancluded Value}}, or <<Macro Value>>
• Still thinking through how to handle the "or" situations (need tiddler value or tiddler and field, or just field, or tiddler and index...)
  • Soren had the one example which might be great. I currently don't understand it clearly though, so will think on how to simplify it

Tones

• I'm not that familiar with screen readers etc. but if you want to take a crack at an example to help me understand, I'd be happy to look at it

Ste

• I'll check out the stretch text thing. Others have suggested details which seems to have similar aims (though is non-core)

Mohammad / Odin / TiddlyTweeter

• I think version 1 is good myself, and version 3 for completeness. Might think about the best method to include both - via some mechanism like stretch-text / details / reveal / tabs (most core-ish I think)

<details> (PMario / TiddlyTweeter)

• Funnily enough the *only* thing that I can see useful about the <$details> widget is that it *doesn't* store the state (which keeps size & # of changes down).
• To TiddlyTweeter's point, if <$details> stored state, wouldn't it just be a less-flexible <$reveal>?

Thanks all, I'll keep plugging along and circle back to get more feedback in a while. 

[TiddlyTweeter]

• To TiddlyTweeter's point, if <$details> stored state, wouldn't it just be a less-flexible <$reveal>?

RIGHT. Point is it is just a dumb state that requires NO state tiddlers at all. You can simply, directly, change the toggle state.

It is mostly ONLY useful for ON/OFF situations. 

For that it is elegantly simple in code!

TT

[TW Tones]

Stobot et al

I'm not that familiar with screen readers etc. but if you want to take a crack at an example to help me understand, I'd be happy to look at it

Nor am I but alt apparently making use of alt text is important for images at least. No what I am saying is making use of the other features like mouse over, tooltips etc... Of late I have being getting into draggable payloads, especially of content as I describe in On syntax formats below. Just drag a syntax form into your tiddler and edit.

On Syntax formats

To me version one is almost useless, it resembles the list of parameters already documented. But you still need to refer to the rest of the document. Using version one as a code snipit still requires a lot of work. I would favor version 2 but one for each of the different configurations, ie a subset of parameters for each common form of the widget. 

The details widget.

I use the html one a lot more know since something changed to make it more reliable. It does store the initial state (open or closed) just not the ongoing state, and in a larger number of circumstances this is all you need. Also keep in mind that even the existence of the details widget can be inside a list/reveal itself which is conditional. It is ideal for more or less content. Using the summary tag you can actually place macros in the details "heading" to show the number of something there inside the details tag (I do not think $details does this). 

Not with standing this, there is the details widget in a plugin https://tid.li/tw5/plugins.html#DetailsWidget and 14kb in size, but I have not used it much lately.

I wish we could get the equivalent of the old TWC nested sliders plugin but perhaps this can be emulated in Mario's "Custom Markup" as he has also demonstrated the the details widget can.

That reminds me;

We could document a lot more features and methods in tiddlywiki or a separate wiki that are not just about widgets, macros tweaks and filters, but also making use of html and css. For example using css to toggle content display: none; and possibly classes such as nest nest1 nest2 would stand in for the nested sliders plugin. 

Although the reality is the Custom Markup plugin may be the most valuable plugin since "relink" and possibly of even more consequence.

Regards

Tones

[TW Tones]

Sorry, 

I meant to add I think version three could be at the bottom of every definition with all parameters, copy or drag.

Tones

[Simon Baird]

I'm not following all the tech discussion here, but I like the idea of accessible, standard documentation that's trivially easy to author.

One good example that comes to mind is the documentation for ansible modules. There are lots of them, and they all have consistent, (mostly) understandable docs. Perhaps there are some ideas there you could borrow or steal.

A particularly useful section is the examples. For widgets a set of good examples would be handy, and perhaps easier to use casually than the formal syntax definition. 

Example:

https://docs.ansible.com/ansible/2.9/modules/copy_module.html#copy-module

(Find many others here:)

https://docs.ansible.com/ansible/2.9/modules/modules_by_category.html

--

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 tiddlywiki+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/0c6f9683-e1de-49ff-a61c-04986da6eaa1n%40googlegroups.com.

--

simon...@gmail.com