Code Examples

Technical writers and software designers sometimes need to include examples or program text, HTML or XML code in their notes. Tinderbox 4.1 makes it easy to include these excerpts and to export them gracefully to web pages.

Tinderbox lets you add HTML tags to your notes and normally exports them unchanged. This lets you add special markup to your Tinderbox notes when you need to take control. Occasionally, though, you might want to discuss HTML in your note.

In HTML, a markup language for the World Wide Web, special tags indicate each part of the text. For example, a paragraph begins with <p> and ends with </p>.

In this passage, we want the example tags to be shown to the reader, and we don't want them interpreted as tags by the browser. To do this, we need to replace the opening character of the tag (<) with the special character sequence < , telling the browser that you want to display the < character. This sequence is called an HTML entity.

Tinderbox now recognizes the HTML tags <code> and </code>. Special characters inside <code> tags are automatically converted to entities.

Block-level tags include <h1>.

The note for this example reads:

Block-level tags include <code><h1></code>.

This can also be useful when quoting passages from programming languages are mathematical text, since HTML always attaches special significance to the characters < and &. For example:

if(count<10) { too_small=true; }

In the note, this appears as:

<code> if(count<10) { too_small=true; }</code>

The character sequence <10... is not the start of an HTML tag; to avoid confusing the browser, we want Tinderbox to convert < to <.

Longer code examples may benefit from using the <pre>, which tells the browser to retain white space and line breaks.

if(count<10) {
	too_small=true;
	}

Since <pre> preserves white space and line breaks, Tinderbox doesn't add any paragraph tags inside a <pre> block.

Note that, if you need to use <code> or <pre> in code examples, you should write them as <code> and <pre>, so Tinderbox won't act on the example. It is unlikely that you will require this often, but if you do, a Tinderbox macro could be useful.

How It Works

When exporting to HTML, Tinderbox scans for <code> and <pre> tags. Markup is modified inside these tags as follows:

pre: no paragraph markup is generated. Since line endings will be preserved by the browser, no additional paragraph markup is added.
code: the characters <, >, and & are converted to HTML entities.

Learn About Tinderbox

Using Tinderbox

Application Notes

Syndication

EXCHANGE

Tinderbox Public File Exchange

TINDERBOX

Tinderbox news

Subscribe!

Keep in touch with Tinderbox! Moderated, concise, and timely; we never share your email address.