The Zone Intermediate Format

The Zone system uses a two-stage rendering pipeline. The source document can be written in a variety of formats, but is converted to an intermediate format when imported into the document archive. The final renderer then converts from the intermediate format to presentation HTML, on the fly.

The intermediate format is basically a stripped-down HTML page, stored as XML, and with a minimum of site-specific styling. Extended semantic information is provided via a mix of classes, conventions, and a few custom tags.

Structure #

<zone:document xmlns:zone="http://effbot.org/zone">
 <head>
  <title>...</title>
  <link...>
 </head>
 <body>
  ...
 </body>
</zone:document>

The outermost element can be either “zone” or “zone:document”.

Tags #

“link” (in the “head” section) is a related document. The renderer usually understands the following “rel” values: “contents”, “next”, “prev”, “alternate” (links to translations), and “copyright”.

“a”, where “href” is a link URI, is a smart link. See below.

“zone:image”, with src and md5 attributes, where src is a data URI with an embedded image, and md5 contains the MD5 digest of the image data. See below.

“zone:link” (where zone: points to http://effbot.org/zone) is a smart link.

“zone:title” expands to the title of the target document, when used inside a “link” or “a” element.

Image Tags

For convenience, images are usually embedded in the source documents, using data URI:s. The renderer extracts these and stores them in a cache directory. It then replaces the element with a pointer to the cached image, with proper width and height settings.

For this to work, the data URI must have the following format:

<zone:image src="data:image/format;base64,data" md5="digest" />

where format is one of jpeg, gif, or png, data is base64-encoded data, and digest is the MD5 digest of the image data.

The Zone loader automatically converts img tags with data URI:s to zone:image elements.

Smart Links

To be added. For now, see An Alternative Python Reference: Targets.

Classes #

The following classes have semantic meaning:

When used with P:

“info” denotes an author/date paragraph, in the zone standard style (fields separated by vertical bars).

“note” denotes a note to the reader. The first phrase in the paragraph should be the note type, in bold (usually one of Note: or Warning:).

“fixme” denotes a note to the author or reviewer. This is usually removed in publication-level rendering. Use sparingly.

When used with DIV:

“example” denotes an example section.

“figure” denotes an illustration of some kind.

“sidebar” denotes a sidebar. It may be rendered inline (but with a border or other visual separation), so it should make sense also if appearing in context.

“note” and “fixme” can also be used on DIV, to mark larger sections of text. See above.

When used with PRE:

“python” denotes a Python code sample, or an interpreter session.

“xml” denotes an XML or HTML sample.

“c” denotes a C or C++ sample.