Tinderbox is a wonderful tool for developing structured content, then transforming it into different formats, most notably HTML. This project started when I wanted to write Help Books for my apps, and discovered there was only one affordable tool with which to do that. macOS Help Books are essentially small websites, which have to conform to intricate specifications. What better tool to use than Tinderbox?
This first article shows what I have done so far in Tinderbox, to produce a simple website of (X)HTML pages which conforms to Apple’s rules. In the next I will show how to turn that into a Help Book, which can then be built into a Mac app.
Help Books have two types of pages: an index, and a normal page. In sophisticated books, they can be built in an elaborate hierarchical structure, with fancy sidebars with disclose triangles and more. Help Books generated by high-end authoring systems use style sheets (CSS) and JavaScript to do impressive things. This project won’t be so complex. I am going to use a very simple stylesheet, mainly because I think that it improves the look and readability from the default formatting.
Content
To start off, I created two prototypes in a Prototypes container: one for the simpler index page, the other for the more complex normal pages.
To the BodyPage prototype, I added three user attributes, which are needed for metadata for the Help system, and for a footer: $description contains a short summary of the page content, $keywords is a comma-separated list of keywords for that page, and $footer contains my little advertising banner. Each is a simple string which I will complete for the pages, but I set a default banner for the footers.
I then assembled the content of each of the pages. As I already had written documentation in word processor (Nisus Writer Pro) format, this was a matter of copying and pasting, then tweaking the formatting.
I had two screenshots which I wanted to include, and was happy to copy and paste these into the text. However, you need to be careful to scale those to the correct size for the final web pages before inserting them. Using the standard export code for included images, they will be shown at full scale. This may appear confusing, because certain views of a note in Tinderbox scale images differently. For reliable results, you should ensure that they are correctly scaled before dropping or pasting them in.
Links
The next step was to create all the links. I confess that Tinderbox 7 is already making me lazy, and I used its new Quick Links on every occasion, as they are so quick and convenient. The index page consists solely of links to each of the body pages, and I added appropriate links below the body text of each of the body pages too.
I also inserted a couple of external web links, where they were appropriate, using the Make Web Link… command in the Note menu. Again these are very straightforward and quick to insert.
The Tinderbox version of my web pages and Help Book was now complete, so I checked it through thoroughly, and ensured that my metadata and footer attributes were completed.
Templates
One of the most valuable aids to writing export templates is a set of examples of what output should look like. This enables you to set your templates up so that they reproduce, as closely as possibly, what you know already works.
Looking at my example (X)HTML files, it was clear that I needed two slightly different templates – one for the index page, and one for normal pages.
My starting point was the built-in HTML template, added in its own Templates container when you use that option in the Built-in Templates item in the File menu. I then duplicated that HTML template, and gave them appropriate names.
For the index page, I basically had to replace the built-in (X)HTML with the header from my example index page, adjusting the reference to the stylesheet file. In text, this reads:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<link rel="stylesheet" href="basic.css" media="all" />
</head>
<body class="Normal">
<!-- ** Modified Tinderbox Template for index page [section page] ** -->
<h1>^title^</h1>
^text^
^children(/Templates/HTML page/HTML item)
</body>
</html>
There is nothing particularly complex there, as far as Tinderbox is concerned.
The normal or body page was a different matter, as it needed to undergo the same basic changes in the header, add the metadata for description and keywords, apply the stylesheet to the content, and insert a centred footer. Its code therefore reads:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<link rel="stylesheet" href="basic.css" media="all" />
<title>^title^</title>
<meta name="robots" content="index" />
<meta name="description" content="^value($description)^" />
<meta name="keywords" content="^value($keywords)^" />
</head>
<body>
<!-- ** Modified Tinderbox Template for body page [section page] ** -->
<a name="^title^"></a>
<p class="Left Heading1">
<span class="Heading1">^title^</span>
</p>
^text^
^children(/Templates/HTML page/HTML item)
<p class="Center Normal">
<span class="Normal">^value($footer)^</span>
</p>
</body>
</html>
Notice how I access attributes with ^value($attribute)^, which inserts the string from that attribute. The ^title^ in the body is styled according to my stylesheet rather than defaults, and the footer – again included as ^value($footer)^ – is centred rather than left-justified.
That handles all the stylesheet requirements except for the body text in ^text^. To apply my styles to that, I had to alter the attributes which set the HTML output to mark the start of a paragraph. There are two, one for the first paragraph in $HTMLFirstParagraphStart, the other for remaining paragraphs in $HTMLParagraphStart.
So for the BodyPage prototype, I first set its template to that for body pages, then made those two HTML attributes key, and set them to my required values of <p class="Left Normal"> instead of plain <p>.
Although the real proof of my templates would come with exporting from them, Tinderbox gives you the chance to view the generated code, and to preview the resulting page.
Check, test, export
The index page, using the index template, is fairly dull and straightforward: a simple list of links to the four body pages.
A more complex body page, containing its single screenshot, looks good in standard ‘text’ form.
Its (X)HTML closely resembles the examples that I have been using as my target.
It also previews well in Tinderbox.
Content that the result stands a good chance of working, I exported the whole document to a folder containing only the CSS stylesheet. I then opened index.html in Safari, and browsed the exported pages. They work!
If you were simply generating a website, now is the time that you’d check those pages using other browsers. My next step is to transform that small website into a Help Book, in the next article. In the meantime, my Tinderbox document, including the export templates, and the CSS file are here: help2proj
The Eclectic Light Company 