Main navigation

Completing and using a Swift Scrapbook in Tinderbox

Earlier this month, I put together a Tinderbox scrapbook, in which to keep all the snippets of useful Swift code which I have been generating over the last few months. Having got it working to my satisfaction, its completion waited for sufficient time for me to locate and enter more source code.

If you follow this blog on WordPress or Twitter, you may have noticed that has happened. A couple of days ago, Tinderbox’s HTML Export duly generated the seventeen separate files of WordPress ‘markdown’, and a few minutes later I had six quite chunky articles full of Swift code snippets ready to load up to the WordPress servers.

You can now download the first fully-populated version of the document from here: SwiftScrapbook2
and from Downloads above.

This article is not about gloating, though, it is about what I have learned from the scrapbook’s first production run.

First and foremost was how well Tinderbox worked. I didn’t intend posting the articles direct from Tinderbox, but assembled them using MarsEdit. All I had to do was open the exported ‘markdown’, copy and paste it into a MarsEdit Post. I also reviewed them carefully, and made a couple of minor changes, setting some headings in Heading 3 format rather than just bold.

There are a few, very few, places where I had to adjust the splitting of paragraphs or positioning of markup. That took less than five minutes.

One editorial issue which I noticed resulted from my decision not to embed note titles in the exported pages. In the great majority of cases, this worked out well and saved unnecessary duplication. But in a few cases I had written the content of the note assuming that the reader had seen the $Name of the note. I quickly rectified this in the articles, but need to go back and tweak their source notes to save me that little work in the future.

Sorting the notes in the Outline view proved straightforward even with the much greater number of notes that I have in the production document. This is a valuable trick in other situations where you need to order notes, such as when making Composites. If the Composite note has the contents in the wrong order, break it apart and amend the order in the Outline view. When you form them into a Composite again, they should read the way that you want them to.

The Tinderbox update to 7.1 has also been a great benefit. Previous releases haven’t been noticeably unstable or buggy, but they have had occasional moments when they didn’t always behave as expected. This new version seems much more even-tempered, and a true joy to work with at all times.

There is only really one remaining issue which continues to niggle, and that is the conversion of special characters such as the less than and greater than symbols, < and >. These are a pain even in MarsEdit, where I have to enter them in their HTML encoding (as I have done in writing this article). I’m now quite used to doing that, but it does mean that when I copy source code from the scrapbook, I have to manually convert back to the unencoded symbols.

Thankfully, Swift source doesn’t use them a great deal, except as comparison operators, and to form -> in the first line of functions which return a result. Xcode also picks up such issues very quickly as it parses the source live.

Having put in the time to create this collection of over a hundred code snippets, I must now work under the discipline that I will maintain and add to the scrapbook as I write more Swift in Xcode. Then all I will have to do is export the changed sections in markdown format, and I can update the web pages.

That now makes two Tinderbox documents which are saving me time and effort, and keeping me much more organised than I was before.