Looking for Tiddlywiki Macros: Good programming style, Documentation

[Mohammad]

I am looking for how develop and document Tiddlywiki macros.

I am interested in:

1. Good programming style
2. Macro documentation

I appreciate to have your comments, resources and ...

If you have your own procedure and methods, I highly appreciate to share them.

Best regards

Mohammad

[Mohammad]

See my announcement of YAZD project here

https://groups.google.com/d/msg/tiddlywiki/1btgb6dmiBU/-L1nllP5AgAJ

I proposed a coding practice here. I also noted the recent efforts by S.S. on documentation here: https://tiddlywiki.com/prerelease/#Improving%20TiddlyWiki%20Documentation

I appreciate to give me your feedback and share your thoughts

Initial draft

How to create and document a macro in Yazd collection?

Start

• from right sidebar, List of Macros, click on New macro button
• fill in the required fileds as recommended below

Macro name

• use semantic name
• all in lower case
• single word recommended
• if multi words is used, connect them using a dash -
  • example: print-items

Macro parameters

• parameters all have an initial value
• single word parameter name is recommended
• multi words parameter shall be used in camel case form
  • example: saveTiddler

Macro tiddler

• 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

Stylesheet and Viewtemplate

• a macro can have dedicated CSS. These css are stored in a tiddler as below
  • tiddler name stalysheet/macro-name
  • tagged with $:/tags/Stylesheet and yazd
• a macro can have dedicated viewtemplate. It is stored in a tiddler as below
  • tiddler name viewtemplate/macro-name
  • tagged with $:/tags/Viewtemplate and yazd

Documentation

• documentation is placed inside the macro tiddler, after macro definition
• a template has been provided, fllow it
• in calling macro use named parameters
  • example: <<mymacro p1:"hello">>

Extra examples

• for more examples create a tiddler named doc/macro-name
• follow the same instruction for documentation as described in the macro definition template

Links:

1. Coding practice: https://tw-scripts.github.io/Yazd/#Coding%20Practice
2. Macro summary: https://tw-scripts.github.io/Yazd/#Macro%20Summary

@TonyM

Regarding having snippets in editor toolbar or having one extra button to insert the macro calls, I would be happy to have your plan.

Best regards

Mohammad
 

[S. S.]

Mohammad,

This is all a good idea. I would say my best learning comes from seeing other people's macros (& code), and even from looking at the code of macros used inside tiddlywiki.com. This has allowed me to make all my macros myself, but then, I do not have complex requirements! I believe I only use 1 outside macro exactly as the original author made it, and that is Tobias' Advance Search in Fields: $:/.tb/ui/AdvancedSearch/Field

You may also consider including:

Data tiddler

• a macro that has an associated data tiddler can be named as below:
  • tiddler name data/macro-name
  • tagged with yazd

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.

Regards

[Mohammad]

S.S
Many thanks for all your comments and thoughts.

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

[@TiddlyTweeter]

Ciao Mohammad

I 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 end up coding something twice;

           -- knowing what I don't know -- i.e. knowing when to ask for help. 

In terms of helping users gain better style I suggest ...

           -- taking code that works by someone and peer review it with suggestions to improve it.

               I personally am not any kind of good coder. But I do play with macros.

               I would welcome critique to improve them.

What is the best way to document?

           -- personally I find well designed example macros  by good coders the best documentation.

               This you are doing and I'm using the macros you wrote to help understand how to

               write clearer code.

Just thoughts

Josiah

[Mohammad]

Many thanks Josiah!

Evaluation and critical comments are very important for improving the code!

Agree with you, I personally believe learn to through examples is the best way to learn Tiddlywiki!

 

Cheers

Mohammad

On Friday, March 22, 2019 at 9:50:35 PM UTC+4:30, @TiddlyTweeter wrote:

Ciao Mohammad

I 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;

[@TiddlyTweeter]

Ciao Mohammad

To give an example ...

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

When I have something working I'll ask for feedback.

Best wishes

Josiah 

[TonyM]

Mohammad,

How are we supposed to get the macros we add to the wiki to you, so you can update the master. I would assume here https://github.com/tw-scripts/Yazd

Using a fork of our own etc...?

However this github location only has a single index.html not the independent tiddlers like on TiddlyWiki5.

Regards

Tony

[Mohammad]

Hi Tony!

 There is two methods to do this:

1. Recommended: Fork and create pull request
2. The other:  download a copy, create a new macro using the provided template, send email to me!

--Mohammad