Ordinary Human Language

by Brian Crane

Exporting a Letter--Single Page Instructions

Writing the letter is easy.

All I have to do is:

Here’s finished letter to Michael Ondaatje.

When I’m done, if it’s the only letter I need, the easy export is cut-and-paste or “print.” Both options work great.

But let’s imagine that this wasn’t a lame fan letter used as an example in an exercise, that in fact, it were something I’d likely need to write a lot. In that case, it’d be worth converting my letter to an export template.

Once you have a concrete example of the output you want in hand, it couldn’t be easier to create an export template allowing you to produce a version of that output from any note.

Suggested First Steps

In any Tinderbox project where you will be using export, I think it’s a good idea to:

Converting the Letter to a Template

In order to turn my specific letter into an export template, I need to tell Tinderbox:

1. where to insert information (i.e. indicate the “blanks” in Mad Lib or the fill-in fields in the form letter); and
2. where to find the information to insert.

Both are easy.

Indicating “blanks”

In a template, if I write “Dear Michael Ondaatje,” Tinderbox will export that text exactly as I have written it. If instead I want TBX to supply automatically the author information from whichever note I’m exporting, then I simply replace the specific author name by a bit of export code.

Export code—like queries, like actions—can seem at first glance intimidating. The options are extensive, their uses as well.

Here’s the secret: all you need to make any of the basic templates in this series is:

^value()^

Anywhere you place this code in your template, you are telling Tinderbox to insert a piece of information stored in a note’s attribute. You are in other words, creating a blank line (or a fill-in field) in your template. (I’ll talk about the two exceptions to this procedure when creating a book note template.)

Pointing to Information

In a Mad Lib, each blank line had a brief instruction printed under it tell you what kind of information was needed to fill the blank. Tinderbox needs the same kind of instructions, and you give it by naming the attribute that holds the information it should use.

To do this, you simply place the name of the attribute inside the parenthesis in the export code: e.g. ^value($Authors)^.

That’s all there is to it.

The Changes Required in My Letter

Looking over my letter to Ondaatje, I can see two places where I would need to change information if I wanted to write to a different author: his name and the title of his book.

In my sample book notes, the author’s name is stored in $Authors and the books title is stored in $BookTitle. So to convert my letter to Ondaatje into a template, I would replace “Michael Ondaatje” by ^value($Authors)^ and “The English Patient” by ^value($BookTitle)^.

When I’m done, the letter now looks like this:

These changes made, set the prototype for the letter to “HTML Template” and you’re good to go. You can do this by:

The next step is to assign the template and to preview the output.

Make the Template

To do these following steps, you’ll need to have made the Text Pane Selector visible. If you haven’t yet, click Window->Show Text Pane Selector to add the necessary buttons to the top of the Note Text Pane.

Assign the Template to a Note

When I export a note, I am telling Tinderbox to export the template assigned to that note using the note’s attributes to fill in any blanks in the template. This only works if a note has been assigned a template.

There are two basic ways to assign a template to a note.

The easiest is to click on the HTML button in the Text Pane Selector (see above). If you have never assigned a tem®plate to a note, then clicking this button will bring you to a drop-down menu listing all the available templates in your file. You simply select the template you want from that list.

If you have previously assigned a template to a note, this drop-down menu is not available. In this case, you can assign a new template by pulling up the Get Info… pop-up by either:

Once there, type “HTMLExportTemplate” into the search box and use the dropdown menu there to select the template you want.

Preview Your Export

Once you have assigned your template to your note, clicking the Preview button in the Text Pane Selector will show you what your note will look like when exported.

This preview is selectable! Which means that if you want to export only a single note and like what you see, then you can select the preview text and past it in whichever other application you want. (You can also simply choose Export Selected Note from the File menu…but honestly, why would you if you can just cut-and-paste?)

If I assign my letter template to my note for The English Patient, the preview looks like this:

The text is correct—all of the export code has been replaced by real info—but the formatting isn’t right. In some cases, I won’t mind: I’ll be doing something where it’s no hassle to do the final formatting in my word processor—I’m a wiz with Nisus Writer’s Find & Replace—and I’ll just cut and paste the text as is.

But in cases where I want Tinderbox to polish the text before export—maybe I’m preparing 50 letters—I just need to give it some formatting instructions.

Formatting the Output

Up to this point, creating an export template has been pretty simple.

You’ve written a sample and then turned it into a form letter by replacing it’s specific information with a single bit of export code. That code creates a blank space in your text that Tinderbox fills using information found in an attribute you’ve named as part of the code.

Yes, entering this code involved typing a strange character. But if you are like me, after an initial panic, you found the key on your keyboard and after you got used to it you started to feel kinda fancy typing it as part of your “code.” (Yeah! I’m not old! I code! Take that Millennials!)

Adjusting a template to format the output is not any harder, but like that character, it can be unsettling at first because formatting in templates is done using HTML.

The HTML You Need

First off: you don’t need to know HTML to format Tinderbox output. You need to know three basic things: how to create paragraphs, how to italicize, and how to bold text. All of them are very easy, especially if you’ve ever used any version of Markdown in a text editor.

Create a Paragraph

In word processors, you create a paragraph by hitting RETURN (maybe twice) and possibly TAB. This doesn’t work in Tinderbox (or HTML).

To create a paragraph, you place

at its beginning and

at its end.

Italicize Text

When you make text italics in a note, Tinderbox will italicize it for you in the output. But if you are exporting information from an attribute that can’t hold italicized text (e.g. $BookTitle), then you have to tell Tinderbox to italicize the information when it exports.

To italicize text in your template, you place

at its beginning and

at its end.

Make Text Bold

Tinderbox treats bold text in your notes exactly as it does italicized text.

In cases where you need to tell Tinderbox to make text in your template bold, you place

at its beginning and

at its end.

Formatting the Letter Template

If I want to use these tags to format the letter template, I need to make two changes: the paragraphs need to be identified and the title of the book I’ve read needs to be italicized. Once I’ve added the necessary tags, the template looks like this:

Yes, it’s intimidating if you’ve clicked here and are looking at it without starting with a written sample letter. But if you have started with the sample, then you can see how the sample has been converted to a template by replacing specific information with export instructions and by indicating formatting using two simple codes.

And the pay-off? When this work is done the export produces tailor-made letters for each of my three author notes. They look like this:

All the Rest…

This letter example is purposefully simple, but using these three HTML tags it is possible to create a wide variety of more useful outputs. So for most of us most of the time, these tags are all we need.

Here’s the good news though: Tinderbox speaks HTML. Which means that as you pick up additional tags, you can use them to create greater variety in your output.

Or, if you’re great at Nisus, you can stick to the export basics, copy-paste and get fancy there. It’s up to you.

For other export examples, go here.

Posted July 8, 2017