Reference Explorer for Plugins and Codes

#1

There are several tools out there have a reference or node explorer like

  • Soren Zettelkasten edition (tzk)
  • Kookma Mehregan
  • Shiraz Node explorer
  • Dave Gifford Stroll
  • TiddlyStudy
  • TiddlyResaerch

These work very good for common use cases (they normally exclude system tiddlers, and donot deal with macros, variables, …)

BUT I like to have a reference manager to be used for codes/plugins/themes/packages to show

  1. reference to host tiddler for a macro used in current tiddler
  2. reference to host tiddler of variables
  3. reference to host tiddler of imported variables

TBH: Debugging TiddlyWiki codes can be very tedious, if codes does not follow some best practices

Relink somehow helps here

NOTE: This feature, tool is in my wish list, in the hope that a volunteer creates such a tool someday!

2 Likes
#2

We should have a wishlist tag to organize similar posts in the forum.

CC @moderators

1 Like
#3

@Mohammad I have built a few things already for personal use, there are two approaches;

  • Use facts and assumptions about tiddlywiki to search and list code objects in the wiki.
    • eg search for \define
  • Introduce conventions that support code documentation and debug:
    • Eg Add to code tiddlers a commented area with information such as macro syntax, that is then searchable.

To support documentation that can be accumulated but the community we need some shared “No touch” solutions which allow core shadows to be annotated without editing them. Again I have built a few, but not published them yet.

I will look for some sharable examples.
[Edited] Here is examples I created earlier.

  • <<? macroname>> searches and lists where macroname is defined. macro-help.json (2.8 KB)
  • View template for tiddlers tagged $:/tags/Macro that lists macros and parameters found there in macro-tools.json (1.5 KB)
1 Like
#4

So here is an example about what I am thinking.

  • This is but one approach, others may be fields like macroname-syntax

Consider a de facto standard within hidden comments and within code as a subset. The within the comments <!-- keyword: information --> or for multi-lines.

<!--  keyword: information
 keyword2: information2
 keyword2: information3 -->

So for example in a macro definition

\define macroname(p1 p2:"default")
<!-- description: My macro to do great things -->
<!-- p1: first parameter
        p2: second parameter
--> 
<!-- documentation: [[documentation tiddler]] or link -->
Hi $p1$ using $p2$ setting
\end
<<macroname tony mode>>

So using my macro-tools we can find the macro definition, the parameters in use and their defaults and parse the comments.

For additional information in the keyword: info form to fill out the macros details.

  • This we could call ‘‘parsable comments’’.
  • Note also this may include a link to a tiddler or web address in the example above of documentation: in fact any content except <!-- and -->
  • It is well known that the internals ignore both comments and text below the definitions.

Further an additional method is required to document core macros without editing core tiddlers. For example if you use my macro help tool the following;
<<? toc>> returns;
Snag_29e542ee
this could look for a tiddler $:/doco/$/:core.macros/toc and display that if it exists, so you can create a “doco” tiddler to document a core tiddler, and a macro within it, include with “parsable comments”.

3 Likes
#5

Thank you @TW_Tones
Very nice solutions. These are absolutely useful. We may have some PEP like Python for best practice in WikiTexting!