Tinderbox’s missing export system


The joy of Tinderbox tinkering

When I first started using Tinderbox, I dreamed of one day being able to export my notes in an attractive, interactive form—something like a blog, but one that expressed the intelligent relations that make Tinderbox such an exciting note organizing environment.

As an outliner, organizer, and relationship explorer, Tinderbox is peerless. Damien Karass has called it the Emacs of personal content management and visual information display. It is also a great environment for thinking—especially for developing structure out of nothing. Few can deny the superiority of Tinderbox Map View over ordinary mindmappers.

Who among us can forget the first time we plopped notes like blobs of paint in Map View and thought, Here is a place that pulls me into the pregnant chaos of free-form arrangement? Or the first time we collected notes with an agent and discovered how easy it was to link appearance to content? This changed our attitude towards note taking.

As an academic writer, I found this to be both a boon and a threat. When I finished my coursework and began dissertation writing in earnest, I took a Dissertation Writing Seminar. When the issue of software came up, I had been warned that Planet Tinderbox was a place of distraction. Perfect—just what I wanted. We are biologically compelled to procrastinate every 45 minutes anyway. Why not procrastinate inside your writing environment? Exploring relationships in Map View—reducing whole essays to colorful connectable dots and moving them around—isn’t a bad way to decompress during a writing marathon.

Over time, I nurtured an intricate ecosystem of notes. Building the unity of your TBX from nothing gives it a structural integrity unique to Tinderbox, and is a remarkable process deserving of detailed discussion elsewhere.

The challange of Tinderbox export

However, when it came time for a final product, my little Tinderbox world was always left behind. Tinderbox is indeed the place for notes. But getting them out in a beautiful hypertext object has been possible only for those with the time and patience to undertake a massive and months-long project.

Comments in the Tinderbox Forum also suggest that export is the issue that most befuddles new—and veteran—Tinderbox users. A glance through the Tinderbox Forum suggests that while the majority of users readily enjoy its outlining, mapping, and collecting capabilities, Tinderbox’s export capabilities are underused and under-appreciated.

Most writing programs are WYSIWYG and don’t even have scriptable export templates. A few are text based and use markup, such a LaTeX and Markdown. Tinderbox is of the latter kind—it executes under the separation of concerns model, specifically, that of presentation and content. However, it does not include any ready-made markdown (macros) for the most common tasks, such as easy insertion of media, cited quotes, and tables

Sure, you can invoke the automatic HTML template, but this only exports barebones title and text. I wanted an integrated export with all the bells and whistles you get in the average WordPress website. I knew that exporting something amazing was possible, but there was no way to do it out of the box.

Until now.

Feedback and further simplification

When I released BoxPress last year I was touched by the positive feedback I received. Most people do not have the time to build a rich and intelligent website export system from scratch. I knew I had met a need. Many wrote that BoxPress was the reason they bought Tinderbox in the first place.

However, other users were disappointed. The biggest problem was that I had written BoxPress for Tinderbox 5. The dashboards looked awful in TinderboxSix and some of the export code no longer worked.

The second biggest problem was unclear documentation. Through interaction with users by email, I learned that some Tinderbox users have no interest coding whatsoever and want Tinderbox export to be as fancy and easy as using an iPhone. Some people buy Tinderbox for its facility, and not for the pleasure of tinkering with a piece of complicated machinery. I also learned that many people do not like reading long-winded documentation.

This was a hard pill to swallow. I new I had to rewrite BoxPress not only to be TB6-compatible, but also to make it foolproof for utter noobs.

And so I began a massively tedious year-long rewriting project. My goal: to build an export system that would let new users experience the joy of seeing their note ecosystem reborn as an elegant and integrated website immediately and without any effort or work.

Other users wanted to extend BoxPress. Making that possible meant rewriting and modularizing the code, and improving the comments. I even made a dedicated variable note to hold values and display them for debugging purposes. This makes BoxPress an excellent Tinderbox teaching tool. Once interested users see how export, macros, stamps, rule, and agents work together to form an integrated writing environment, they will be motivated to reverse engineer the simple mechanisms of BoxPress and to extend it themselves.

Wish list for my ideal export system

A good export system would do the following:

  • It would filter content. Not every note will export. A good TBX will automatically filter some things, but also give the user an easy way to toggle export manually (or by means of a simple agent).
  • If would connect content. Not every note will export as its own webpage. A good TBX will automatically compile some things, atomize other, and give the user an easy way to toggle this manually.
  • It would build on a good open source web framework and inherit its responsive grid system and semantics.
  • It would have groups of stamps that let you do amazing things quickly. There are Key Attribute Setters that swap-out functionally clustered key attributes sets. There are Attribute Cleaners that erase kindred groups of modifications and return them to their prototype (default) settings. There are Export Togglers that turn export for self or children on an off and change the badge accordingly. There are Day/Night Color Schemers that work with System Preferences > Accessibility > Invert Colors to toggle colors between day and night writing schemes.
  • It would have good set of templates and boilerplate notes.
  • It would be brimming with lots of smart macros so that the new users would never have to write a line of CSS or HTML. Macros would use optional args to be as simple as possible, and well-named. Images, audio, video, panels, quotations with cite, and other specialized export should be do-able with macros that are brief and semantic.
  • It would solve the Tinderbox Bookmarking Problem—the problem of how to link to notes that are not exported as webpages but as compiled subsections of their ancestors.
  • It would solve the Tinderbox Related Links Problem. Basic links (the ones you make by dragging lines from note to note) do not export properly for subsections. In a good export system basic links of subsections would be automatically included and work properly.
  • It would provide an easy way to let you export tab-separated and even Mac OS tables as fancy HTML tables on export.
  • It would provide a pre-organized framework to be filled-in by content. Organization and arrangement efforts should be spent on projects, not on the glial cells holding the whole website together. By taking the guesswork out of overall note arrangement, BoxPress lets the writer focus on writing. For example, there should be a place where to put notes to protect them from export, and another where they will automatically be exported in some ready-made way. Changing prototype should change export utterly and predictably, yet still mesh with the rest of the webpage.
  • Windows would be pre-specialized with ready-made tabs. Take as much anxiety out of the writing process as possible.
  • The export system proper—the templates, boilerplate, containment hierarchy, macros, and stamps—would be clear enough to permit extension. Macros, and their nice semantic organization inside BoxPress, should be well-documented and provide models for the user’s own macros.
  • Export would be controllable by the use of keywords. Numbering—inside properly hanging indents—could be turned on and off with the click of a checkbox. Granularity should be controlled just as easily. Same for toggling the export of a post’s title, date, and image.
  • Adding a Table of Contents would be as easy as entering a number for its outline depth.
  • Finally, it would provide a means for applying, storing, and managing styles. At first I thought of using Tinderbox rectangles to wireframe the webpage. While using Tinderbox to build a wireframe for my personal website, I had a revelation. Stylistically, a webpage is an assemblage of rectangles. A Tinderbox Map View is also an assemblage of rectangles. Could I mock-up a webpage using notes in Tinderbox and then import the attributes of the latter into the CSS of the former? Yes—by using ^value()^. And so the famous BoxPress WYSIWYG Styles Dash was born.

Building writing morale

With these goals in mind, BoxPress was born. It started as an archetypal blog-type webpage layout on top of the Bootstrap framework. Then grew an arsenal of macros for images, audio, video, panels, wells, and (much later) tables. Then specialized prototypes were born, each with its own export style. Then came granularity control and export options for numbering, dating, and glossary entries. And with the recent addition of SmartButtons, SmartDates, Research Prototypes, and responsive HTML imagemaps, BoxPress has evolved into the premiere GUTES for all your Tinderbox projects.

As I coded the templates, macros, stamps, and agents, I built from the expectation that these things would eventually be used by others. For example, when I saw that a personal macro had universal utility, I would make it unsaturated, reduce the number of args to the minimum, and write documentation so that others could use it.

In this way, personal export victories became user-friendly features.

Finally, special care has been taken along the way to make the UX as intuitive as possible for new users. This has been my guiding light, because the point is to encourage more and better writing by making a final polished product available with a click.

Tinderbox is the most exciting writing environment around. It just needed an export system as flexible as intelligent and flexible as Tinderbox.