My previous article explained how I developed a Tinderbox document for authoring and exporting in a standard LaTeX format. This aims to clarify some of the issues that I encountered there, and corrects some of my errors.

Default settings for attributes and $IsTemplate

You may have been a bit mystified by my previous discourse on the importance of getting the $IsTemplate attribute set correctly. It comes back to a potential trap which I’m sure no one else has ever fallen into, but which I managed to: unintentionally setting the default value for an important attribute.

It may appear tempting when making sweeping changes to a Tinderbox document, such as transforming HTML output to LaTeX, to try to make them in default values of attributes. It is much better to leave those well alone, to expose all changed attributes as key to specific notes, and to change their values in those notes. You should then not run any risk of setting $IsTemplate true for the whole document, which makes every note (template, or prototype) a template.

When you alter the Default value of a system attribute in the Document Inspector, that value is applied across the whole of the document. There are circumstances in which you can inadvertently set one attribute to the default value of another too.

Let’s say that you want to set $HTMLEntities to true. In the Document Inspector, select the System tab, the HTML Category, and HTMLEntities Attribute. Click in the Default box, type in the value true, and press Return. Then open the Attribute popup menu again, and select the IsTemplate item.

Sometimes the Default value is not updated to reflect that current for $IsTemplate, but is left displaying the true which you just typed in for $HTMLEntities. Then switch to the Prototype tab of the Properties Inspector, and create a new note. Instead of it being a non-template, you may see it automagically gain the Template flag.

When you add these system attributes as key to a template or prototype, and change their values there, there is no danger of such problems.

Being a Template changes export behaviour greatly

Leaving any given note as a template when it is not would not be so important if it were not for the fact that templates and non-templates behave very differently when exported to HTML. Despite following my own instructions to be assiduously careful in checking that all notes and (most) prototypes are not templates, I was caught out by this in the previous article.

One curious difference between templates and non-templates is their behaviour when exporting characters which are outside the pre-Unicode HTML character set, like … (horizontal ellipsis). When used in a template, that will be exported in its traditional HTML escape form & #x2026; ; when used in a note which is not a template, it will appear as a regular Unicode character.

You’ll also find that much of your markup changes in an exported template, breaking many of the changes which you made in HTML attributes.

Exporting lists

I was a little confused when constructing ordered and unordered lists, reporting their partial failure. In fact both work excellently, but when you are working for HTML or LaTeX export, you should use quick lists, rather than those offered in the Text section of the Format menu (which is still fine for documents which will not be exported).

Quick lists are constructed using * (unordered) and # (ordered) tags, which can be used in multiples as needed for sublists. Although they’re not as pretty in the text of notes, they’re much quicker and more practical.

Outline views

Although I mentioned the importance of using Outline views when developing export formats, I perhaps didn’t stress that enough. Map views are great for laying out notes within a document and within containers, but do not show the note hierarchy or the export order.

Outline views readily show all the templates, prototypes, and regular notes in a document, in their position within the hierarchy, and in the order in which they will be exported. It is far quicker to navigate their hierarchy, thus to develop and correct the notes within it.

Thanks, as always, to Mark Anderson for pointing out some of my errors and misconceptions. My mistakes remain my own.