On Wednesday, September 30, 2020 at 1:28:12 PM UTC+2, Bob Jansen wrote: Many of the examples in the TW documentation use what appears to be a > macrocall of some sort to perform the example. So you cannot see the actual > statements used, you can only see the result of the macrocall. Not very > helpful really is it. Why not just use simple statements that anyone can > follow after all we are after a real example to see how things are done. >
As Joshua pointed out, that's the use of so called documentation macros. We needed to use them because, the "default" approach is a maintenance horror ... and many users requested a "copy to clipboard" button. eg: To document the action-setfield widget we used a similar wikitext code as follows: ``` <$button> <$action-setfield $tiddler="$:/state/tab-17494383077" text="$:/core/ui/ControlPanel/Appearance"/> <$action-navigate $to="$:/ControlPanel"/> Go to Control Panel "Appearance" tab </$button> ``` renders as: <$button> <$action-setfield $tiddler="$:/state/tab-1749438307" text="$:/core/ui/ControlPanel/Appearance"/> <$action-navigate $to="$:/ControlPanel"/> Go to Control Panel "Appearance" tab </$button> ... and the underlying HTML is ``` <p><button class=""> Go to Control Panel "Appearance" tab </button></p> ``` The nightmare comes now: What if I want to add a class definition to the button widget like so: <$button class=test> How many changes do I need to fix it. ... 3 ... No it's 6 because I actually found out I should have done: <$button class="tc-btn-xyz"> That's the reason, why we use a macrocal for may examples. ... There should be only 1 "source of truth", for examples. ... because *the worst think that can happen is*, that the rendered code works, but the code to be used by the user has a typo. If I wouldn't have highlighted it, you would have searched for hours. ... right? As a side effect, the "copy to clipboard" button is available for many examples. .. That's the one to be used. BUT if you open the tiddler you as a programmer will see this: <$macrocall $name='wikitext-example' src='<$button class="tc-btn-xyz"> <$action-setfield $tiddler="$:/state/tab-1749438307" text="$:/core/ui/ControlPanel/Appearance"/> <$action-navigate $to="$:/ControlPanel"/> Go to Control Panel "Appearance" tab </$button>'/> The code that will be copied to the clipboard is highlighted in light blue. That's confusing. But even more confusing would have been an example the looks right for the user, but doesn't work if you copy / paste the code, to test it. I did add a file to play with. hope that helps -mario -- 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+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/59871019-1f78-422c-a10f-fa05c1f7d4f9o%40googlegroups.com.
test-doc-macro.json
Description: application/json
