OmniOutliner ConTeXt XML Export Manual

wedge 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.
wedge ConTeXt export: basic usage

wedge 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.
wedge 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:
wedge 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.)
wedge 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.
wedge ConTeXt export: normal usage

The following functions depend on OO3 Pro-only features, specifically the named styles.
wedge 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.
wedge 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.
wedge Installation and running

* 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 &gt; New From Template menu. The export option will be available within the File &gt; 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.
wedge 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.
* 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 Visit the SourceForge website to subscribe to the list.
wedge ConTeXt export: advanced features

wedge 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 &lt;user:sauce&gt;duration&lt;/user:sauce&gt;. 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.
wedge 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 &amp; 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.
* 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. Logo