Beginner question: How do you document the tiddler codes in your app

#1

I’m just getting into Tiddlywiki. While developing my little TW ‘app’, I have trouble keeping track of the codes embedded in various tiddlers. My beginner’s question : How best to dump out contents of various tiddlers with embedded codes to a single text file so I can refer to them without having to check multiple places in the TW5 file ?

These tiddlers are already tagged. The json export function does it but not in a very readable format. My best idea is to write a LIST widget to display the title, text, tags and custom fields of each such ‘codes’ tiddler, and copy the list output to a text file. But this need seems common enough that I guess this community would already has some clever ways to do it, probably with plugin. So how do you do it ?

Thanks in advance!

#2

Hi and welcome,
I’m not really sure, what you mean with “codes” in your tiddlers. …

Can you provide eg: 2 tiddlers with some content and the info, how the “output” should look like.

It’s not important to have some wikitext code. … Just a description in English text.

#3

What I do on my wikis is that I created a “description” template that allow me to display some text on any tiddler I want, using a “description” field. It’s fine for documenting a single tiddler, but for multiple tiddlers using a list widget sound like a good idea, why not using that ?

#4

Oh, I’m not referring to the javascript codes in tiddlywiki. My apology for not being clear.

I have tiddlers with data contents and “code tiddlers” with filters and such for organizing and presenting the contents (sample below to present a list of bookmarked URLs). I have trouble trying to keep track of the ‘codes’ (i.e. filters, macros and variables :frowning: ) distributed among these “code tiddlers” even while I’m writing them and these are simple functions! I believe I will have trouble trying to recall how they do what they do a few months down, particularly those little tiddlers that use tags to latch onto the system tiddlers to get work done.

Right now, i cut and paste these “code” fragments to a text file for an overview and quick reference while working on them. When I’m done, I suppose I will just consolidate all of them into one text file and add some comments for my future self. I’m not sure that’s the best approach though, so checking with the community what’s the best practices to document what you did in TW. I have no doubt that you will be using TW somehow to do it :wink:

\define tid_icon(imgpath,ticon)
<$set name="var_icon" filter="[<currentTiddler>has:[bmicon]]" value="[img[$imgpath$/$ticon$]]" emptyValue="[img[$imgpath$/blank.png]]">
<<var_icon>>
</$set>
\end
\define t_titleurl(t_url, t_title, t_text, t_status, t_plain)
[[$t_plain$|$t_url$]] $t_text$ ($t_status$) //[[edit|$t_title$]]//
\end
<$set name="tagSelected" value={{@Bookmarks!!selection}}>
<hr>@@font-size:1.5em;Tag "<<tagSelected>>" : <$count filter="[tag<tagSelected>!tag[#TW5BM]!bmstatus[9]]"/>@@ <br><hr>
<$action-sendmessage $message="tm-close-other-tiddlers" $param="@Bookmarks"/>
<$set name="hash" value=" :[0-9a-f]{12}:"><ol>
<$list filter="[tag<tagSelected>!tag[#TW5BM]!bmstatus[9]each[bmstatus]get[bmstatus]sort[]]" variable="tstatus">
<$list filter="[tag<tagSelected>!tag[#TW5BM]!bmstatus[9]bmstatus<tstatus>!sort[modified]]">

<li><$macrocall $name="tid_icon" imgpath={{@Startup!!imagpath}} ticon={{!!bmicon}} /> <$macrocall $name="t_titleurl" t_url={{!!bmurl}} t_title={{!!title}} t_text={{!!text}}  t_status={{!!bmstatus}} t_plain={{{[<currentTiddler>search-replace::regexp<hash>,[]]}}}/></li>
</$list>
</$list></ol>
</$set>
</$set>
#5

I use Thinkup plugin! It allows me to add notes and todos per tiddler
So, each code tiddler has comments and todos but when you export the code to JSON, Plugin, etc… only pure code is exported and all notes and ToDos remain in your development environment.

1 Like
#6

Hi @jacng,

If your code tiddlers are tagged “code”, you can create a tiddler called Documentation containing:

<$list filter="[tag[code]!is[draft]]">
<pre><$view field="title"/>

<$view field="text"/></pre>
</$list>

Example: code-doc.json (488 Bytes)

Fred

#7

A few small tips

  • Keep in mind it can be helpful to name tiddler containing your macros and wikitext code with the $:/ prefix so they do not come up in every day searches. Macros can be made global with the $:/tags/Macro tag.
  • For Version 5.2.1+ any tiddler you wish add a field code-body = yes and it will display as code when viewing.

The following installed on a wiki adds a “ctrl-click to edit” the code body when viewing a code tiddler. code-view-edit.json (1.5 KB)

  • By using ctrl you can still select code to copy it.
  • I just added alt-click to copy the full text to the clipboard.

I have some other tools for searching for an documenting macros defined in a wiki. Just ask if you want them. I will share more generally at a later date.

#8

Hi all, Thanks for the feedbacks ! Appreciate it :slight_smile:

Let me summarise my learnings so far:

  • Fred, I’m going to be using that list filter you wrote many, many times to dump out my ‘code tiddlers’. It’s probably trivial for you to write it, but would take me at least couple of hours to Google and come out with something equivalent :slight_smile: I find it useful to have these codes-in-progress handy on a text file OUTSIDE the TW file as I will be editing the ‘code tiddlers’ themselves during development and often lost track of changes while repeatedly testing (i.e. madly changing [ to < to { and then try adding another layer … :exploding_head: ) and figuring things out.

  • I just found a discussion on inline commenting in TW codes (https://groups.google.com/g/tiddlywiki/c/fDS5-rJXQjM). I had some problem early with inline commenting and refrained from adding any since, as I already have my hands full trying to get the ‘codes’ to work properly in the first place. Will experiment with it later when I’m more familiar with TW.

  • Tone, thanks for the tips! Yes, I think it’s good practice to tag all my non-data tiddlers with my own system tag. I will also add and likewise tag some tiddlers within the TW to store documentation notes to myself. This seems most straight forward to do for the moment.

  • TW itself does seems ideal for keeping track of the many little tweaks (CSS, UI changes etc) needed to make a ‘TW app’ works correctly and to keep track of notes/todo/etc during development. I’m still learning the basics of TW, will watch out for such applications as hinted by Mohammad and Tone.

Jack

#9

The discussion you pointed out, is from 2011 and for TiddlyWikiClassic. So it’s not valid for TW5

In TW 5.2.0 the comment syntax has been improved. It can be used now everywhere. So you can use it like this:

<!-- some info about the next macro definition -->
\define tid_icon(imgpath,ticon)
<$set name="var_icon" filter="[<currentTiddler>has:[bmicon]]" value="[img[$imgpath$/$ticon$]]" emptyValue="[img[$imgpath$/blank.png]]">
<<var_icon>>
</$set>
\end

This wasn’t possible with “older” versions. Also see: https://tiddlywiki.com/#HTML%20in%20WikiText

#10

Ah, thank you ! I will get around to try that … just realised also I’m on TW 5.1.23 because I’m using external lib codes not (yet) compatible with 5.2 TW file format.