Overview

The document processor

The document processor is a command line software application which translates BDML documents into one or more final target presentations. The target presentation documents supported by the procesor are PDF, HTML, ePUB, and Mobi (Kindle). This documentation provides information on the usage and functionality of the Bora document processor. It also provides details on using the accompanying BdmlHtml.xsl XSLT stylesheet for direct browser loading of BDML files, transformed from BDML into HTML during loading by the web browser.

The BDML schema reference provides information on the semantics and usage of each XML element defined in the schema, their attributes, and the relationships between the elements. In order to write documents in BDML, a minimum amount of XML knowledge is required. Any text editor or XML editor can be used to write the XML.

The markup language

BDML was created in 2007 with the aim of providing a feature complete technical writing markup language with the smallest set of schema elements, intuitive usage, and an easy, layered learning curve.

Documents

A complete document ready for translation consists of:

one or more BDML files containing the source document;
zero or more CSS files representing the styling of the translated documents;
zero or more image files for image references in the source document.

A complete document ready for translation may consist of a single BDML file. A more complex document would consist of a tree of BDML files and associated image files, plus one or more CSS files. From the same sources, translations to multiple targets may be achieved.

The Bora document processor has built in default CSS stylesheets for each supported target. Users can begin writing their documents with the default CSS styling, then extend the default styling to suit their own requirements.

A BDML file contains the following:

a set of <part> elements or <chapter> elements which group the content of the document into parts or chapters;
an optional metadata section, containing non-renderable configuration items.

BDML documents have a single BDML file root. Optional <header> and <footer> elements in the metadata section and <include> elements in the main body of the document introduce other BDML documents into the main document. In addition, external resources may be specified such as CSS files in the metadata of the root BDML file and images in the BDML XML body.

Document structure

BDML content can be structured in two ways:

as parts which contain chapters;
directly as chapters.

Part based documents group chapters into parts. Chapter based documents do not have any parts.

A part based BDML document has the following form:

<document xmlns="http://boradoc.org/1.0">
  <metadata>
    <header url="resources/header.bdml" />
    <footer url="resources/footer.bdml" />
    <stylesheet url="resources/pdf.css" target="pdf" />
    <stylesheet url="resources/html.css" target="html" />
  </metadata>
  <part title="First Part">
    <chapter title="First chapter">
      <h1>A heading</h1>
      <para>A paragraph of text</para>
    </chapter>
    <chapter title="Second chapter">
      <h1>Another heading</h1>
      <para>Another paragraph of text</para>
    </chapter>
  </part>
  <part title="Second Part">
    <chapter title="Third chapter">
      <para>A paragraph of text</para>
    </chapter>
    <chapter title="Fourth chapter">
      <para>Another paragraph of text</para>
    </chapter>
  </part>
  <part title="Third Part">
    <include url="chapter5" />
    <include url="chapter6" />
  </part>
  <part title="Fourth Part">
    <include url="chapter7" />
    <include url="chapter8" />
    <include url="chapter9" />
  </part>
</document>

A chapter based BDML document has the following form:

<document xmlns="http://boradoc.org/1.0">
  <metadata>
    <header url="resources/header.bdml" />
    <footer url="resources/footer.bdml" />
    <stylesheet url="resources/pdf.css" target="pdf" />
    <stylesheet url="resources/html.css" target="html" />
  </metadata>
  <chapter title="First chapter">
    <h1>A heading</h1>
    <para>A paragraph of text</para>
  </chapter>
  <chapter title="Second chapter">
    <h1>Another heading</h1>
    <para>Another paragraph of text</para>
  </chapter>
  <include url="chapter3" />
  <include url="chapter4" />
</document>

Typing BDML directly requires a minimal amount of knowledge of XML and CSS. Copying an example BDML document and modifying it is a good way of getting used to the XML format.

A future release of the Bora document processor, currently in the planning stages, will include a word processor type graphical interface.

Translation targets

The Bora document processor supports translation into PDF, HTML, ePUB, and Mobi (Kindle) formats from a single BDML document. The processor has built-in default CSS for each target.

Additional CSS may be specified in the root BDML document. Each CSS file may be specified for all targets, a subset of targets, or a single target. HTML, ePUB, and Mobi targets can normally use the same CSS with optionally some minor target specific differences specified in separate target specific CSS files. The PDF target translation can also be based on the same CSS when a target specific CSS file containing more substantial CSS is included.

Simple documents may use the built-in CSS and just specify BDML content. Complex, multi-target documents will tend to consist of one or more BDML files, a main CSS file, and a small additional CSS file for each target.