Doc-macros new syntax -- Make it easy for doc-macros to be bundled and exported

[pmario]

Hi folks,
I did upload a docs-edition with fully rewritten (tw 5.3.x syntax) doc-macros. The PR is draft at the moment, but the latest preview is here: https://tiddlywiki5-git-fork-pmario-doc-macros-new-syntax-jermolene.vercel.app/

It’s also proposed: to combine the doc-macros and release them as a core-plugin

The PR contains changes to

• Documentation Macros … the docs tiddler
• doc-macros … the macro definitions
• doc-styles … some minor adjustments
• wikitext-macros … fully rewritten

Help Wanted

I did test every single macro if it still works, but we never can be sure, if I missed something.

So it would be nice if someone could also have a look and review every single macro with different parameters is they really still work.

New Info Boxes

There are also 3 new info boxes, that should make the whole thing a bit more consistent.

Notes

Tips

Warnings

Note & Warning close to each other

Parameters can be found at: TiddlyWiki — a non-linear personal web notebook

PR is at: Doc macros new syntax by pmario · Pull Request #8009 · Jermolene/TiddlyWiki5 · GitHub

Issues are:

• [Bug] doc-macros .note, .tip and .warning inconsistencies #8003 and
• [IDEA] Documentation Macros - documentation should be improved #8004

As always: Feedback is very welcome here or at GH.

have fun!
mario

[TW_Tones]

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;

• It includes core tiddler overwrites that should be removed details here Using tiddlywiki documentation when contained in a plugin - #4 by TW_Tones
• 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.

[pmario]

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

[TW_Tones]

With somewhat limited time, is it sufficient to;

@pmario

test all the doc-macros from the preview **, if everything still works as expected

• Simply reading all the documentation to confirm it continues to work, perhaps comparing the view with tiddlywiki.com.
• I have done some already.

It is looking good. If you look at TiddlyWiki — a non-linear personal web notebook you will notice is displays all the fields and the example look messy as it does on tiddlywiki.com as well. One may exclude the text field as anexample.

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]

1. The version Icons are now a little less rounded, black and with bold text, a change?
2. On your example site the documentation macros are not packaged in a plugin, I thought that was part of the objective?
3. 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?
4. 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.

[pmario]

Thanks for the feedback

@TW_Tones

Do you think this is the appropriate time to include a little additional smarts into the document macros if not the core?

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.

@TW_Tones

The version Icons are now a little less rounded, black and with bold text, a change?

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.

@TW_Tones

On your example site the documentation macros are not packaged in a plugin, I thought that was part of the objective?

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.

Have a look at this response from Jeremy: Doc macros new syntax by pmario · Pull Request #8009 · Jermolene/TiddlyWiki5 · GitHub

@TW_Tones

Did you only touch [prefix[$:/editions/tw5.com]] tiddlers, you seem not to have some when I look at the modified dates.

You are right. I did miss some macros. I’ll change that.

@TW_Tones

some are still not working like copy to clipboard in some places at least

Can you provide a link?

@TW_Tones

I would like to see the aforementioned shadows+tiddlers so they work from inside a plugin.

I did see the “mention”, but the links pointed to “nowhere”. I do not know what you mean here.

[pmario]

I think \define still has some usecases. eg: In https://tiddlywiki.com/#%24%3A%2Feditions%2Ftw5.com%2Fdownload-empty

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.

[pmario]

@TW_Tones

Did you only touch [prefix[$:/editions/tw5.com]] tiddlers, you seem not to have some when I look at the modified dates.

I did just upload a new version, which should cover all doc-macros now.

[TW_Tones]

@pmario

I think \define still has some usecases. eg: In

I agree with this approach, but perhaps not this case, at least in the long run.

• It is deprecated and need not be removed if it is used in a minimal set of cases, especialy to differentiate somewhat “static strings”.

@pmario

I personally want to keep it if I do define “strings” eg for tiddler titles used for $:/temp/, $:/config/ and $:/state/ tiddlers.

Rather than a procedure we can place many such “strings” in a function such as;

\function state-tiddler(suffix) [[$:/state/]addsuffix<suffix>]

• if necessary add +[join[]] at the end.
• 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?

[CodaCoder]

I hope I’m misreading what you’re saying, that \define is deprecated.

It is not. It’s not going anywhere.

I think we’ve been here before.

[TW_Tones]

Remember Deprecated - What does it mean ?

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.

[pmario]

Thanks for your feedback. I’ll close this thread, since I did create 7 PRs at GitHub, which are referenced at: doc-macros, styles and documentation overview tiddler by pmario · Pull Request #8037 · Jermolene/TiddlyWiki5 · GitHub

I did split the whole thing into several PRs, because they will be easier to manage if there goes something wrong, which do not expect. – but anyway.

These PRs are intended to convert documentation macros and templates into the new v5.3.x syntax used with the current state of tiddlywiki.com