Introduction

This is a living document aimed at both documenting and illustrating the usage of the ConTeXt XML export plug-in for OminOutliner 3. The plug-in is for generating structural markup primarily for use with the ConTeXt typesetting system. It is not focussed on mimicking the layout of OmniOutliner documents, nor does it prevent a user from creating ill-formed XML. It does provide a convenient way of creating documents that can be parsed by a specific, non-validating processor.
The plug-in and accompanying documents are fundamentally the work of just one guy working on his own, so the author cannot make any guarantees against data loss, reliability, validity, frustration, hair loss or impotence. All use is at your own risk, and expect minimal support. The author has a PhD to write, and has already spent a lot of time getting the system working. Contributions made out of gratitude, however, are welcome.
That said, this work stands on the shoulders of giants, most notably:
* The Omni Group and their fine products, keen eye for design, and willingness to listen to users;
* Hans Hagen/Pragma ADE and the ConTeXt macro system, particularly Hans' astonishing responsiveness to users' requests for help and insight; and
* The W3C for the XML, XPath, and XSLT standards, which both Omni and Pragma leverage in their products to great effect.
This plugin would not exist but for each of the above efforts. It is as much a tool for my own writing as a love letter to the above technologies. I hope you get some pleasure and usage from it.

About this documentation

After each section or subsection that abstractly discusses a concept, there is a brief section that demonstrates its usage in OmniOutliner 3. The resulting text or formatting is not going to make particular sense in the resulting converted document, however, so if you are reading this in PDF form, refer to the OO3 document to see how the markup is achieved.

About ConTeXt

ConTeXt is a typographical engine written in the typographical computer language TeX. ConTeXt provides you with a convenient way to encode documents in a structured way and to typeset these documents in various ways on paper, computer screen or web sites.
You can use ConTeXt to create simple documents and complex layouts. From a single source produce traditional paper documents as well as highly interactive electronic documents. Combine text and graphics and other information in your document in different ways. Move around, use and reuse information and typeset in one or more natural languages.

Why do this?

Mac users are a niche market. TeX users on the Mac are a niche. ConTeXt users are a small niche amongst TeX users. The potential overlap with OmniOutliner Pro users is vanishingly small, so why bother doing this?
* I want to do this to satisfy my own urges. I've long dreamed of an iWrite structured content system that allows a me to edit structured text using a variety of structure syntaxes. It hasn't been forthcoming, and the time has come to do something about it. It's much easier to spend a holiday honing and documenting a script than to take a year off effectively reimplementing the nice things I remember about using FrameMaker nine years ago.
* Doing this has taught me a lot about the nature of structured text, and just how difficult a rudimentary iWrite would be.
* It gets me thinking more about XSLT, which, for academic reasons, I should be doing more of right now.
* It's a form of advocacy: I'm happy with the various tools that I've found, and I want to introduce people to them. If Mac users are in the least inclined towards typesetting, XML, or TeX, then they should give ConTeXt a look; neither LaTeX nor XSL-FO is the last word in its respective space. Conversely, ConTeXt users should take a look at the Mac: it runs familiar and powerful UNIX-based tools very well, but also has a first rate GUI and applications like OmniOutliner Pro that combine power with real elegance in design.

Document structure

Sections are marked up as outline items in the main column. A row that is a child of another becomes a sub-section of that section.
This usage is the basic concept behind most export formats from outliners: an outliner item becomes a heading. Currently, ConTeXt maxes out at level 10 headings, or subsubsubsubsubsubsubsubsubsections. The ConTeXt XML export plugin pins any deeper level rows to this maximum depth, so a deeply-nested document will not preserve the structure exactly, but it will not discard any content.
Actually, thesubsubsubsubsubsubsubsubsubsection is a 12th-level heading. There are two heading levels above the section that are unused by this plug-in. Part and Chapter were left open for users to create their own super-structures to stitch multiple outlines together.
Notes that are attached to headings comprise the paragraph text that exists within a section. Nominally they are within a <context:p/> element, but much of this document in the following sections is given over to exceptions.

Demonstration

This entire document's structure is an illustration of how structure works within the frameworks of the plugin, but just to drive the point home, here are some further sections:

A further section

Another section

The last section with OO3 formatting

A level 7 row

Down to level 8

Number nine, number nine

A maximum-depth section

Level 11 is too deep

In the OO3 document, this section is a child of A maximum-depth section, but in the converted ConTeXt XML document, it is technically a sibling of that section. The final level has its numbering turned off so that the depth is not so apparent.

Basic Implicit Tags

There is a limited amount of export that can be done using the features present in OmniOutliner 3 (non-pro). In it, the export transform watches for font changes to italic (where it outputs to <context:em/>), bold (<context:b/>), and fixed fonts (<context:type/>). The fixed font watching uses a bit of a crude heuristic: if the font contains any of the words Monaco, Mono, Typewriter, or Courier, then it is presumed to be a monospaced font, and therefore has the <context:type/> tag associated with the text. (Note that this is a poor assumption for fonts like American Typewriter, but the line had to be drawn somewhere.)

Demonstration

Italic fonts are tagged as emphasised text.
Bold fonts are tagged as bold text.
And Monospaced fonts are tagged as verbatim text.

Grouped Implicit Tags

Certain tags are designed to be used in a group, as well as on their own. A prime example of this is with the monospaced font implicit tags. A multiple line group of such monospaced typing is translated to a <context:verbatim/> environment, with component paragraphs re-interpreted as <context:line/>s.
Another implicit tag is itemize markup. There's no neat, compact way of giving explicit tags to a set of items, so we use something resembling a Markdown syntax. One denotes a list by starting a paragraph with a list marker followed by a space. The list markers are *, -, ., and 1.. If the first list marker is 1., then it is a numerical itemize, otherwise, it's a symbol list. The itemize continues until there is a paragraph that begins with a non-list marker (usually ordinary text). Note that after the first list marker, the following markers don't matter; the list type is entirely determined by the first marker.

Caveats

XSLT is not the best tool for detecting such multiply-nested structures in the OO3 file format, but if you start a line with either an implicit or explicit <context:type/> or <context:itemize/> tag, then the rest of the line and all following lines with that format are interpreted as a verbatim or itemize run.
Currently, the itemize parsing is somewhat primitive: it can only handle number or symbol lists, and at only one level. As the focus is on structural markup, there is no attention paid to which list marker is used.
ConTeXt collapses spaces at the beginning of verbatim lines, so it's currently not the best option for program listings.

Demonstration

Here is a numerical list:
1. It starts with a "1."
2. The following list marker doesn't matter.
* As long as there's a list marker, the list continues.
6. This can be considered a feature, as one can insert into a list without renumbering.
Here's a symbol list:
- The only list marker that matters is the first one.
* There is no need to keep the same symbol for following lines.
- In fact, the list marker used doesn't change a thing.

- A gap in the list results in a blank item. In order to return to paragraph mode, you need to start a line with a non-list marker.
This is a normal paragraph.

Default Explicit Tags

Put briefly, the name of a style becomes the name of a tag. In the template document, there are a number of basic tags provided, corresponding with ConTeXt XML elements, like:
* context:em (emphasized/italics)
* context:b (bold)
* context:type (typewriter)
* context:formula (math formulas)
* context:quote (quotations)
* context:framed (boxed text)
The final four in the above list are special, in that they adapt to in-line and solo contexts: as with grouped implicit tags, a <context:type/> style on its own, starting a paragraph, will trigger a series of verbatim lines until the style is interrupted. A simple in-line formula converts to a display formula, and an in-line quote changes to a stand-alone quotation when on a line alone. A framed element will convert to a framedtext element in the same situation.

Implementation details

In case there are questions about false or missed triggers of this solo-vs-inline detection, the exporter looks at the first two styled runs: if the first run matches the style and (there is no second run or the second run also matches); then there is a solo style.
Verbatim, quotations, and framed texts all expand to encompass multiple contiguous paragraphs. A quotation paragraph followed by another quotation paragraph will be consolidated into a single quotation, with paragraphs separating them.
The formula/dispformula tags use the compact TeX math notation. If you need MathML, then you can enter it manually (see below in the section on embedding literal tags).
A framed element is implemented internally as a ConTeXt \inframed command, as it's more useful within a textual flow.

Nesting

Because of OmniOutliner's styled text model, tags don't always nest very cleanly. In general, a combination of in-line styles must appear the same regardless of nesting, in order to be used effectively in this context. That is, markup that is notionally nested like this:
<a>one <b>two</b></a>
should typeset the same way as the following, in order to be guaranteed of getting good results:
<a>one </a><b><a>two</a></b>
Obviously, this is not true of every possible style, even in the restricted ContML model. Emphasized and bold nest well with each other, and most of the pre-defined tags nest well in the following solo and/or multiline environments:
* Itemize,
* Quotation, and
* Framed text.

Demonstration

Emphasized, bold, and verbatim text are already familiar. By using these explicit tags, it's slightly more robust. Here are a couple of verbatim lines with the <context:type/> explicit style:
a b c d e f g h i j
1 2 3 4 5 6 7 8 9 0
In-line math is given a formula tag: e=mc^2 like so. Display math has the same tag, only it's on a line by itself:
S=\sqrt{\frac{\sum_{n}{\left(\log_{2}(\frac{f(n)}{1000})-c\right)^{2}\cdot P^{\prime}_{x}(n)}}{\sum_{n}P^{\prime}_{x}(n)}}
A quote is easily entered. An entire paragraph acts as a block quote.
A full quotation occupies a paragraph on its own. This scheme allows you to enter tags that nest within the quotation environment, such as italic, bold, verbatim, m^at\hbar, or framed text.
A framed bit of text has limited use, but...
A framed paragraph makes for a useful aside. This could be a sidebar, additional information, a block quote, or an intermezzo, as they are known in the ConTeXt world. Keep in mind that you can customize the framedtext environment.

Attachments and includes

I've tried to make attachments as intuitive as possible, given the interface available within OO Pro. My one-size-fits all approach will not suit everybody, but the expectation is that you will take the exported XML and make refinements as necessary, if you have special demands.
In general, attachments are of two varieties: links to existing content (where only an alias is stored) or where the target is stored within the oo3 file bundle itself. The Export plugin attempts to treat both cases uniformly.

Images

ConTeXt can handle a variety of image types. Currently, the supported types are PNG, JPG, GIF, and PDF. An image attachment of one of these types will be treated as a float element, with the content being the image itself. The label on the attachment conveniently becomes the float's caption.
Note that under the current implementation, the linked files must end with the three letter extension (lower-case) listed above.

Includes

Text (.txt), XML (.xml), and TeX (.tex) files that are included as attachments are referenced as an include element, meaning that the whole document will be included and processed appropriate to its type. This could be a handy way of including standard text elements, local configurations, or source code, for example. The label on the attachment is not currently used.

Links

Any attachment that is not a local file: reference is considered to be an external link, and is therefore inserted into a link element. The label on the attachment is used as the link text in the exported file.

Demonstration

Textual includes:attachedattachedattached
Images:This is the OO3 logo.This is a PNG of the Pragma logo.
Links: This is OmniOutliner on the web. And a link to the official ConTeXt website.

Installation

The ConTeXt XML export package comprises the plugin itself, documentation, sample files, ConTeXt support file, and a template.
- The plugin itself (ConTeXt.ooxsl) gets installed into ~/Library/Application Support/OmniOutliner 3/Plug-ins.
- The template (ConTeXt.oo3template) is best put in ~/Library/Application Support/OmniOutliner 3/Templates.
- The ConTeXt module (t-oo-03.tex) should be placed on your search path. If you are using gw&tex;, this is best in ~/Library/texmf/tex/context/third.
- You can place the documentation and sample files anywhere on your hard disk.
It is not necessary to use the template: it's merely a convenience to get users started with a set of default styles. It can easily be customised by other OOPro users.

Exporting

After restarting OO3 Pro, the template should be available under the File > New From Template menu. The export option will be available within the File > Export&dots; dialog box. Select ConTeXt XML Export from the File Format: pop-up menu.

Generated files

An oo3 file, once exported, will have an extension of .xml. If all attachments are aliases, then there will be a single xml file. If there are any attachments that are actually embedded within the oo3 file, it becomes an .xml directory, with the appropriate attachement files and a main.xml file, which contains the body of the original oo3 file.

Invoking ConTeXt

To run ConTeXt, simply run texexec --pdf filename.xml. The main support module (t-oo-03.tex) is loaded by the generated XML file, so there's no need to do additional support file loading. If there is an .xml directory generated, then run texexec on the main.xml file therein.
If you have installed XeTeX and want to use it as an alternative engine, simply invoke texexec --xtx filename.xml.

Using GUI Applications

In the near term, neither TeXShop nor iTeXMac correctly recognize XML files as being processable by ConTeXt, but feature requests have been made to developers of both. Until your favorite application supports push-button typesetting of XML files, launch texexec from the command line.

General issues and gotchas

Unfortunately this system still suffers some of the drawbacks of any TeX-based system. Of particular notice is the limitation on filenames: it's safest to avoid using spaces or underscores in any filenames, especially attached or included files.
You should also be aware of the implications of embedded versus linked files. An embedded file is often frozen, unlikely to be updated, and not used in multiple files simultaneously. A linked file reference, as used by the ConTeXt export, uses a static path reference, and so is unlikely to be usable directly on other systems.

Support

Support requests will be accepted at oo2contml-users@lists.sourceforge.net. Visit the SourceForge website to subscribe to the list.

User-defined Explicit Tags

A user may add her own named styles to a document. If they are are in a suitable namespace (contain a prefix and colon in the name) and are otherwise suitable as a valid XML name, then they are output as an XML element. For example, if you have a named style called user:sauce, then the resulting element tag for the duration of that style is <user:sauce>duration</user:sauce>. Because of limitations of the output architecture, a limited number of namespaces are allowed:
* fx:
* fu:
* fs:
* context:
* user:
* local:
* config:
Note that these tags are intended for light markup, and keep in mind that it's up to you to create the commands to deal with the markup! The problems with other tags (e.g., nesting) are present here, so they're not a solution to everything. You must define the elements in ConTeXt and load the definitions yourself, so this should be considered an expert feature.

Demonstration

This is not so easily demonstrated in an output document as rendered by ConTeXt, so for proof that this works, examine the generated XML file. I have defined a named style exclusive to this document called user:blue. It happens to be rendered in OO Pro as blue text. That paragraph would be exported to XML as <user:blue>blue text</user:blue>. It is up to your local definitions and ConTeXt commands to translate that markup into something useful to be rendered on the page.
Again, the same issues with nesting are present. Even though the context:em named style is fully contained within our custom markup in the following, our custom tag starts and stops three different times: [blue and italic text]:
<user:blue>blue and</user:blue>
<user:blue><context:em> italic</context:em></user:blue>
<user:blue> text</user:blue>

Embedding Literal Tags and Entities

Custom XML tags are possible by simply embedding the code. Nearly everything is unescaped and passed through to &context; for parsing. There is absolutely no validity checking on these tags, so be careful. However, this is the way you can get arbitrary nested tags and markup. Keep in mind that every carriage return translates into a new <context:p/> tag, so all of the tags must fit into a single paragraph. You could embed MathML by these means, for example.
Ampersands are the only characters that are handled specially. If you are writing standard text, you shouldn't run into too many unnatural implications. An ampersand on its own, followed by a space, is escaped and turned into & in XML. An ampersand that is not followed by a space, but some text, is assumed to be part of an XML entity. An entity is an XML-specific escape sequence, such as &context; (&context;). Numerous standard entities are defined in the &context; file xtag-ent: explore that file for other escape sequences.

Demonstration

You can use other ContML tags manually. An obscure one is <context:hide/>, which hides text. It can be used this way: [<context:hide>this is hidden</context:hide>].
[<context:hide>this is hidden</context:hide>]
This feature can easily be misused: it's one of the quickest ways of getting malformed XML, so be careful. Most of the entities are not particularly useful (i.e., named glyphs), but if you need to typeset &tex;, &latex;, or &context;, you have a way!

Customising styles

Styles can be customised within a specially named level 1 row. A row named %Config will be interpreted differently from the norm: rather than being a heading, it marks all of its immediate children (level 2 rows) as being configuration commands. Each level 2 row lends its name to an element. Each row 3 child of that, in turn, is interpreted as an attribute within that element. A value in the second column is the value to that particular attribute.
This is better illustrated with example documents, so see the sample-docs folder for brief sample documents that illustrate different style commands. If you want to dig further, take a look at This Way #8, a magazine introducing elements of foXet, which was a huge influence on how this package was put together. Don't forget that nothing is a substitute for reading the standard documentation for &context;!
You can customize styles using a custom file (in &tex; format, rather than XML) called oo-user.tex, and placed anywhere in the search path. This file can be used to load font definitions, define custom elements, or otherwise define custom styles. It is automatically loaded if it is present.

Encoding issues

Documents are encoded in UTF-8, which, being Unicode, is very capable of handling any text given to it. However, &tex; is rooted in an eight-bit world, and as such, has a difficult time handling more than eight-bit character encodings. As a result, the output characters are sensitive to which font encoding is used. &context; does a good job of interpreting and faking characters beyond a font's normal repertoire, but it has its limits. You might consider using &xetex; as an alternative &context; engine: it is Mac-friendly, gives you access to familiar Mac fonts, and can handle Unicode extremely well.

OmniOutliner ConTeXt XML Export Manual