How to create and document a macro in Yazd collection?
- from right sidebar,
List of Macros
, click onNew macro
button- fill in the required fileds as recommended below
- use semantic name
- all in lower case
- single word recommended
- if multi words is used, connect them using a dash
-
- example:
print-items
- parameters all have an initial value
- single word parameter name is recommended
- multi words parameter shall be used in camel case form
- example:
saveTiddler
- each macro is stored in a separate tiddler
- a macro can have several sub-macros. These are helper macros used by main macro
- tiddler tiltle is in lower case and has a macro prefix as
macro/name
- example:
macro/timer
- tiddler tagged with
yazd
and$:/tags/Macro
- tiddler has the following fields
- description [required]: one line description including keywords
- syntax [required]: a one line text shows how call the macro with its all parameters
- author [optional]: the name of developer
- url [optional]: the possible page
- a macro can have dedicated CSS. These css are stored in a tiddler as below
- tiddler name
stalysheet/macro-name
- tagged with
$:/tags/Stylesheet
andyazd
- a macro can have dedicated viewtemplate. It is stored in a tiddler as below
- tiddler name
viewtemplate/macro-name
- tagged with
$:/tags/Viewtemplate
andyazd
<<mymacro p1:"hello">>
- for more examples create a tiddler named
doc/macro-name
- follow the same instruction for documentation as described in the macro definition template
I do not know what method you are using to group the extra tiddlers associated with a macro so I cannot suggest an extended naming scheme, but you should consider the possibility of multiple template & data tiddlers. It is unlikely that a well made macro should need multiple stylesheets & docs.
- a macro that has an associated data tiddler can be named as below:
- tiddler name
data/macro-name
- tagged with
yazd
I added the data tiddler.
As tou said, I try to keep the macro as simple as possible, but time will show us what other requirements is needed.
Best regards
Mohammad
-- getting clear what I want to DO ... by which I mean a functional understanding before actually coding;
Ciao MohammadI guess that three factors are important for me ....
-- getting clear what I want to DO ... by which I mean a functional understanding before actually coding;
-- understanding, when necessary, modularity. So I don't up coding something twice;
-- Working with Commander and trying to utilise its components is instructive
-- I set myself the task of integrating with it for an advanced SNR module
-- And without overwriting any of the Tiddlers in the plugin