I will review this ASAP as I am working on something related Using tiddlywiki documentation when contained in a plugin and as @jeremyruston pointed out there already is a plugin version of the documentation available in the core plugin library $:/plugins/tiddlywiki/tw5.com-docs however it has two limitations;
All the filters do not refer to [all[shadows+tiddlers]] so they do not work properly when the documentation is in the plugin.
I have found an interesting work around for shadow document tiddlers, however if you address the above two issues in your new macros plugin and in a seperate document tiddlers (actual content) plugin we gain a lot.
The documentation macros can be put to use by anyone and in the process learn more about them, to assist with improving the core documentation.
The Documentation is transportable for people to use in their own learning documentation, with the opportunity to update when a new documentation plugin is available.
The new documentation macros along with a documents plugin is a ready source of example test data or code we all know about. People can drop this on an empty wiki and share an example of the problem, they reproduce and face with their code by using data (the doco plugins) we can all obtain and test against common data without confusing it with tiddlywiki.com.
I did just change the name of the thread to: Doc-macros new syntax – Make it easy for doc-macros to be bundled and exported, due to the discussion at GH.
I’ll create a different PR with a new “Bundle doc-macros” button, that makes it easy to export the needed doc-macros, styles and so on to be used with a users documentation edition.
It would still be nice, if someone could test all the doc-macros from the preview, if everything still works as expected
I have long thought it suitable to have a list of standard and core fields we can use to include/exclude when needed. This can simply be a list of fieldnames one per line in a tiddler and we can exclude with -[subfilter{$:/config/standard-fields}] or even better now a function.
When you exclude standard fields what left are custom fields.
Do you think this is the appropriate time to include a little additional smarts into the document macros if not the core?
[Notes on review]
The version Icons are now a little less rounded, black and with bold text, a change?
On your example site the documentation macros are not packaged in a plugin, I thought that was part of the objective?
Within the documentation tiddlers we use both documentation tiddlers (not just the macros) and in som cases standard TiddlyWiki script, do you intend to modify any of these?
Did you only touch [prefix[$:/editions/tw5.com]] tiddlers, you seem not to have some when I look at the modified dates.
4.1 When I did put all these in a plugin and added them to my annotated documentation wiki some are still not working like copy to clipboard in some places at least (Actually I need a little more work here)
More
I would like to see the aforementioned shadows+tiddlers so they work from inside a plugin.
I think excluding the text-field would be OK, but the others are important. There may be a possibility to add an exclude parameter, so the user can decide. I think the fields-operator did not have the include and explude parameters as the docs-macors have been created.
I’ll have a look at this one.
What are “version icons”? If you mean the <<.from-version macro? –
I did not merge the latest master into my dev-branch – will do that soon.
Creating a plugin was a “proposal”, which will not come. I’ll create a “download doc-macros button” instead. Not sure where to list it – yet.
It defines some “filter strings” and a variable savingEmpty set to yes. Internally \define is implemented as a <$set-widget with the scope of the whole tiddler.
I personally want to keep it if I do define “strings” eg for tiddler titles used for $:/temp/, $:/config/ and $:/state/ tiddlers. I still define them that way. It just feels much more natural than useing \procedure for string definitions.
Unlike define and procedure, this need not ever be wikified for use, just use directly, because it is “evaluated in place”, and displays as text, no need for <$text text=<<state-tiddler>>/>
Although I understand static strings need not be wikified, what if you change it?
It is indirectly see here SystemTag: $:/tags/Macro
It is totally fine to make use of it anyway
I think the define macro may actually stay around a long, long time
Jeremy recently suggested deprecated features are only removed with warning, and major release or even a total rewrite.
But then only if it NEEDS to be removed.
When something is depricated, I just work out the new method, which in this case I find is better anyway, and keep in mind the old way.
I try to identify if it’s necessary and influence future improvements or argue against removal if it ever happens.
