Introducing the ThoughtAsylum Suite for Drafts

27 Sep 2020

Back in July of this year (2020), I released the first version of the TADpoLe library for Mac app Drafts, and with it the ThoughtAsylum action group. It was the culmination of very slowly taking two years of action creation and bundling it up for others to make use of. Only two months later and things have had to undergo what has been a pretty significant change.

The Trigger

A few weeks ago, Greg Pierce, otherwise known as Agile Tortoise, the developer of Drafts, reached out to suggest breaking up the ThoughtAsylum Action Group. I knew that it was large, but that was part of what I’d always had in mind (more on that below), but what I hadn’t known is that there was a size limitation.

Drafts synchronises content using some sync technology in the Apple iCloud platform. Unfortunately there is a unit limit that is quite large for small chunks of text, but not large enough when you have a chunk of text the size of the ThoughtAsylum Action Group. Everything was working, but by the looks of it, it probably wouldn’t be long until people stopped being able to sync it across their devices as it would simply be too large for Apple’s sync system to manage.

There was no option but to make the library smaller.

The Original Approach

I originally envisaged the ThoughtAsylum Action Group as something people could download and get fairly regular updates to. It would act as a Swiss Army knife, or extensive toolbox of useful and example actions that covered a wide variety of scenarios and requirements. By keeping it in one action group, it was easy for me to maintain, and easy for users to update. One and done makes it easy.

The idea, and as per the instructions, was then that users would create their own action groups that called the ThoughtAsylum actions that they wanted to use. Their own actions could be assigned keyboard shortcuts, default completion actions, icon, colour, different notification levels, etc. Then when the ThoughtAsylum action group had a quick update, they would download it, reap all of the benefits from the update, but lose none of their own settings. They could also freely re-use ‘standard’ actions by having actions in multiple groups that called the original.

I had also created an action that would document an entire action group from an action group’s installation URL. This automated generation saved me a huge amount of time producing documentation, and produced it far more accurately that I would have manually.

To my mind, and I know from the Drafts forums that others have different opinions to mine on this, it always seemed like the best approach to achieve the sort of utility that I wanted to provide, while also making it as easy as possible for people to access and maintain.

The Changes

Step 1: Remove The Embedded Library

A copy of the ThoughtAsylum library was embedded in the ThoughtAsylum Action Group. This served two purposes.

The first was to allow the library to be used to bootstrap its own download using to a file functions within the library. The second is that it allowed for fractionally higher performance than including from file; though the difference became negligible during the development of the action group.

The library action made up over a third of the size of the entire action group when I analysed the installation URL for the action group, so by eliminating this action from the group, I would immediately free up a significant amount of potential space. not enough for long term growth, but certainly it gave me a solid start.

The only issue was the bootstrapping for new users. I wanted to keep it as easy for them to set-up the library (downloading the TADpoLe and Beautifier library files) as easy as running an action. To that end I pulled out copies of the functions in the library and added just what was necessary to retain the same functionality into the TAD-Setup/Refresh action. There are some adjustments around where to read settings from, but for a first step this is fully functional.

At some point I may return to it to work out a way to check for the existence of the library file and settings, but right now it isn’t a priority as I doubt anyone has actually had reason to change any of the settings it uses.

Step 2: Splitting

While step 1 was relatively easy, step 2 was far from it. Given that it had only taken two months to encroach on the sync limits, I wanted to provide some scope for longer term expansion. That meant I needed to look at splitting the one action group into multiple action groups. I really didn’t want to do this as it complicates things for the user and for me as the action builder, but at the end of the day the constraint is there and in order to continue it was a necessity to address this.

I sketched out a few ideas for how I could break up the action group and even put it open to discussion on the Drafts forum. The end result is not different to my initial plans, and differs in some key ways from the suggestions on the forum, but I believe the result is something workable, if more effort for maintenance, and definitely a lot of effort to set-up.

The Structure

The first and most important part was deciding what action groups to have and what they would contain. The list I eventually decided upon was based on seven action groups; about twice as many as I’d originally envisaged moving to. Each retains the familiar castle/tower icon (the closest I could find in Drafts to the ThoughtAsylum icon), but the name and colour vary.

The action group sections were split out from the original ThoughtAsylum action group to the groups as follows.

ThoughtAsylum [GREY]

• Library
• Action Control
• Helper Actions

ThoughtAsylum - Management [ORANGE]

• Draft Status
• Draft Syntax
• Mass Processing
• Tag Management
• Recent Drafts
• Workspaces
• Templates
• Cross-Linking
• Link Note
• Draft Embedding

ThoughtAsylum - Export/Import/Share [BLUE]

• Populate Clipboard
• Share as Content
• Share as File
• Clipboard

ThoughtAsylum - Power User [RED]

• Scripting
• Information
• Slash Command
• Persistent Variable Examples
• Action Groups
• Action Groups - From Install URL
• Sample Content
• URL Encoding/Decoding
• Advanced Logging
• Meta Based File Management

ThoughtAsylum - Writing [GREEN]

• Whitespace Removal
• Sort & Permute Lines
• Delete
• Select
• Move Cursor
• Insert Content: General
• Insert Content: Current Date/Time
• Duplicate
• Markdown
• Drafts Markup
• HTML
• Discourse
• Create Drafts
• Edit
• Previewing
• Editor Insertions
• Text Modifiers
• TextExpander
• Word Actions
• Matched Line Removals
• MediaWiki Syntax

ThoughtAsylum - Tasks & Lists [YELLOW]

• Tasks

ThoughtAsylum - Trove [VIOLET]

• Dictation
• Reader Mode
• Mac Audio
• App Control
• Web
• Online Information

It took about an hour to set-up, move and reorder the groups on my Mac, but the first step was then complete.

The Information

The ThoughtAsylum action group had an extensive set of information within the instructions action. This content is also duplicated onto the Drafts Action Directory listing. It contains information about set-up, the action group, the library, key words to help people find the action group in the directory, etc.

I now needed to tailor this for each of the other action groups and revise the instructions to make sense for the new paradigm of multiple action groups. This was a rather tedious task and took over half a day to restructure and populate. Getting the keywords right was a particular pain, but the result is that each action group has a unique instructions action (uniquely named but with an obvious convention) that is tailored to the action group, but also provides pertinent information about the full set of action groups and the correct (I hope) key words.

The Documentation

I had previously created an action that would document an action group in Markdown based on it’s installation URL being on the clipboard - see TAD-Auto Document Action Group in the ThoughtAsylum - Power User action group. But, with the move to seven groups, that was going to be seven times the effort to generate, and then the additional effort of combining them. This documentation is then made available on this site, to allow people to easily browse or carry out a free text search on the descriptions of the actions that are available.

Fortunately, in a recent release of drafts, the installation URL for an action was made available as an action object property. Since I had already been working with similar installation URLs for action groups previously, I created a function to populate actions with the additional information I needed from their installation URLs. Then by processing each action group in the set I could build out the documentation and automatically combine it. I even added the Jekyll front matter and base content for the page so it will generate the whole page of documentation automatically.

Now I don’t even have to copy any installation URL to the clipboard. The action does everything for me, and as a result, the generation is even quicker than before.

Today’s Update

The new ThoughtAsylum Action Group Suite (TAAGS for short) was released today and you can download the new action groups from the Drafts Action Directory.

As well as these structural changes there were also a number of new actions. The key ones are listed in the change log entry for 2020-09-27, bringing the total number of actions to in excess of 400; though the structure did introduce a bit of a jump in information-based actions about the action groups.

That’s everything set for the future, and hopefully this will give me enough growing room to expand the suite for years to come.