Schema elements
Each XML element of the BDML schema is documented in this section. Clicking on an element will link to its reference page.
Root element
The root element of the BDML xml document is <document>.
The <document> elements of root files may have the following immediate descendants.
| Element name | Description | Direct descendant elements |
|---|---|---|
| <document> | The document root element in root BDML files. This element directly or indirectly contains all other elements. | <metadata>, <part>, <chapter>, <include> |
Document elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <metadata> | Contains metadata entries. Entries can apply to all targets or be target specific. | <author>, <back-matter>, <copyright>, <cover>, <footer>, <front-matter>, <header>, <index-entries>, <index-page>, <link>, <meta>, <numbering>, <relative-root>, <script>, <stylesheet>, <title>, <toc>, <trademark> |
| <part> | A complete part of the document. Documents contain a set of parts. | <chapter>, <include> |
| <chapter> | A chapter of the document. Instead of parts, a document may instead contain a set of chapters directly. In this case, no parts are contained in the document. | <bullets>, <code>, <comment>, <graphic>, <h1>, <h2>, <h3>, <h4>, <h5>, <list>, <lorem>, <para>, <section>, <table>, <xml> |
| <include> | An external BDML document to be included in place of the <include> element. | none |
Metadata elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <author> | The author of the document. | none |
| <back-matter> | Specifies a back matter section in the pdf target of the document. | none |
| <copyright> | Specifies a copyright declaration for the immediate document. | none |
| <cover> | Specifies a cover image for the document. This is HTML specific and can be used to display the cover page at the start of the HTML document if desired. | none |
| <css> | Specifies inline css to use for styling the document. | none |
| <footer> | Specifies a document to be included as the footer. | none |
| <front-matter> | Specifies a front matter section in the pdf target of the document. | none |
| <header> | Specifies a document to be included as the header. | none |
| <index-entries> | A set of index text matches to be used to automatically create the document's index. | <item> |
| <index-page> | The position of the index in the document's back matter. | none |
| <link> | HTML specific link elements to place in the <head> section of the generated HTML document. | none |
| <meta> | HTML specific meta elements to place in the <head> section of the generated HTML document. | none |
| <numbering> | An instruction to enable the full or partial automatic numbering of the document's part, chapter, and heading elements. | none |
| <relative-root> | Specifies the relative folder which acts as the root for relative paths specified in the document. | none |
| <script> | Specify a script to include in the target's header (used for HTML target only). | none |
| <stylesheet> | Specify a CSS stylesheet to apply (cascade) on top of the target's default CSS. | none |
| <title> | The title of the document. | none |
| <toc> | Specify whether an automatic table of contents should be generated from the <part>, <chapter>, and <h*> elements. | none |
| <trademark> | Specifies a trademark declaration for the immediate document. | none |
Index-entries elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <item> | The first level item of the index. | <match> |
Part elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <chapter> | A chapter of the document. | <bullets>, <code>, <comment>, <graphic>, <h1>, <h2>, <h3>, <h4>, <h5>, <list>, <lorem>, <para>, <section>, <table>, <xml> |
| <include> | An external BDML document to be included in place of the <include> element. | none |
Chapter elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <bullets> | An unordered or 'bullet' list. | <entry> |
| <code> | An automatically syntax highlighted code section. | none |
| <comment> | A comment trail for developer discussions. This element is normally not printed other than in a developer HTML translation or direct browser loading. | <question>, <remark> |
| <graphic> | A graphical image. Graphical images may be positioned left, center, right, or inline with the text in a paragraph. | none |
| <h1> | A level 1 heading | none |
| <h2> | A level 2 heading | none |
| <h3> | A level 3 heading | none |
| <h4> | A level 4 heading | none |
| <h5> | A level 5 heading | none |
| <list> | An enumerated list. | <entry> |
| <lorem> | A paragraph of automatically generated filler text. | none |
| <para> | A paragraph of text. Paragraphs may also contain graphics and emphasis elements. | <graphic>, <strong>, <emph> |
| <section> | A grouped sub-set of a chapter's content. | <h1>, <h2>, <h3>, <h4>, <h5>, <lorem>, <para>, <bullets>, <list>, <table>, <graphic>, <section>, <comment> |
| <table> | A matrix of cells for tabular data representation. | <head>, <body> |
| <xml> | A verbatim xml section. | Any well formed XML. |
Para elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <emph> | An emphasis element indicating that the text contents should be emphasised generally via an italic or coloured font. | <emph>, <graphic>, <span>, <strong>, <sub>, <sup> |
| <graphic> | A graphical image. Graphical images may be positioned left, center, right, or inline with the text in a paragraph. | none |
| <ref> | An internal or external hyperlink. | <emph>, <graphic>, <span>, <strong>, <sub>, <sup> |
| <span> | A span of text within a paragraph. | <emph>, <graphic>, <span>, <strong>, <sub>, <sup> |
| <strong> | An emphasis element indicating that the text contents should be emphasised generally via a bold font. | <emph>, <graphic>, <span>, <strong>, <sub>, <sup> |
| <sub> | A span of text in a paragraph with a subscript styling applied to it. | <emph>, <graphic>, <span>, <strong>, <sub>, <sup> |
| <sup> | A span of text in a paragraph with a superscript styling applied to it. | <emph>, <graphic>, <span>, <strong>, <sub>, <sup> |
Bullets elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <entry> | An entry in the bullet list. | <graphic>, <lorem>, <para> |
List elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <entry> | An entry in the enumerated list. | <graphic>, <lorem>, <para> |
Table elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <head> | The header of the table. | <cell> |
| <body> | The body of the table. | <row> |
Section elements
| Element name | Description | Direct descendant elements |
|---|---|---|
| <bullets> | An unordered or 'bullet' list. | <entry> |
| <code> | An automatically syntax highlighted code section. | none |
| <comment> | A comment trail for developer discussions. This element is normally not printed other than in a developer HTML translation or direct browser loading. | <question>, <remark> |
| <graphic> | A graphical image. Graphical images may be positioned left, center, right, or inline with the text in a paragraph. | none |
| <h1> | A level 1 heading | none |
| <h2> | A level 2 heading | none |
| <h3> | A level 3 heading | none |
| <h4> | A level 4 heading | none |
| <h5> | A level 5 heading | none |
| <list> | An enumerated list. | <entry> |
| <lorem> | A paragraph of automatically generated filler text. | none |
| <para> | A paragraph of text. Paragraphs may also contain graphics and emphasis elements. | <graphic>, <strong>, <emph> |
| <section> | A grouped sub-set of a chapter's content. | <h1>, <h2>, <h3>, <h4>, <h5>, <lorem>, <para>, <bullets>, <list>, <table>, <graphic>, <section>, <comment> |
| <table> | A matrix of cells for tabular data representation. | <head>, <body> |
| <xml> | A verbatim xml section. | Any well formed XML. |
Comment elements
Please refer to the <comment> help page for information on comment elements.
Schema metadata
BDML metadata consists of a set of non-renderable metadata elements contained within a single <metadata> element in the BDML file. Metadata elements modify one or more of the translated outputs in various ways. The details of each metadata element are outlined in the following sections.
The metadata section
Each BDML file may have a single, optional metadata section. This section is contained within the <metadata> element.
<document xmlns="http://boradoc.org/1.0"> <metadata> <-- Metadata elements go here. --> <header url="resources/header.bdml" /> <footer url="resources/footer.bdml" /> </metadata> <-- Main body of document follows here. --> </document>
The metadata section of a document may appear anywhere as an immediate descendant of the root <document> element. It is typically placed at the top of the document, in order to separate it from the document's main section.
Metadata elements
There are several metadata element types. Each metadata element type has a corresponding conceptual type. The metadata elements, along with their conceptual types are:
| conceptual type | element name | multiple? | description |
|---|---|---|---|
| root | <author> | no | The author of the document. |
| immediate | <copyright> | no | A copyright notice for the file. |
| immediate | <relative-root> | no | Specifies the relative folder which acts as the root for relative paths specified in the document. |
| immediate | <trademark> | no | A trademark notice for the file. |
| inherited | <footer> | yes | A footer to be repeated on each page. |
| inherited | <header> | yes | A header to be repeated on each page. |
| merged | <index-entries> | no | Index search entry metadata. |
| root | <back-matter> | yes | A back matter section in the pdf translation of the document. |
| root | <cover> | no | A link to an image for the cover of the document. |
| root | <front-matter> | yes | A front matter section in the pdf translation of the document. |
| root | <index-page> | no | The position of the index within the back matter entries of the pdf document metadata. |
| root | <link> | yes | [HTML target only] An HTML link to be inserted into the resulting HTML document's <head> section. |
| root | <meta> | yes | [HTML target only] An HTML meta element to be inserted into the resulting HTML document's <head> section. |
| root | <numbering> | no | An instruction to enable the full or partial automatic numbering of the document's part, chapter, and heading elements. |
| root | <script> | yes | [HTML target only] An HTML script reference to be inserted into the resulting HTML document's <head> section. |
| root | <stylesheet> | yes | A reference to a CSS file to be used to style the document. |
| root | <title> | no | The title of the document. |
| root | <toc> | no | An instruction to enable the automatic creation of a table of contents. |
The table includes a column indicating whether the metadata element can be used multiple times in the metadata section.
Metadata types
There are four conceptual types of metadata. The conceptual type of a metadata entry dictates certain characteristics and behaviour of that entry during the translation.
The conceptual types are:
| concept name | description |
|---|---|
| immediate | Applies to the immediate file only. |
| inherited | Applies to immediate file and is inherited by included files that do not have a similar metadata entry. |
| merged | Entries in the root and all included files are merged into a single metadata entry item. |
| root | Applies only if the immediate file is the root file. |
Included files are BDML files included via <include> elements, and also BDML files included via <header> and <footer> files that may be specified in the metadata sections of documents.
Immediate metadata elements apply only with the immediate file.
There is a single immediate metadata element that affects the semantics of the translation. The <relative-root> element specifies the relative folder which acts as the root for relative paths specified in a document. As the element has an immediate conceptual type, each <relative-root> element affects only the document in which it is found.
Elements affected by the <relative-root> are <link>, <graphic> and <include>.
Inherited elements apply to the file within which they are defined and all descendant (directly or indirectly included) files, unless the descendant file has an identical metadata element of its own. There are only two inherited type metadata elements: <footer> and <header>.
There is a single merged type metadata element: <index-entries>. These elements contain index search entries for semi-automated index building. The <index-entries> elements in the root and all included BDML files are merged into a single <index-entries> element, ready for automated index building during translation.
Root metadata elements apply only to the immediate file when it is the root file. Most of the metadata elements are root type metadata. Consequentially, the majority of metadata for a document will reside in its root BDML file.
Target specific metadata
Metadata elements may be restricted to apply to specific targets. The valid targets in the Bora document processor are PDF, HTML, ePUB, and Mobi.
The target attribute is used to to restrict a metadata element to a single or subset of the valid targets. In order to restrict a metadata element to a single target, the following syntax is used:
<document xmlns="http://boradoc.org/1.0"> <metadata> <-- Apply this header only to the HTML target. --> <header url="resources/header.bdml" target="html" /> </metadata> <-- Main body of document... --> </document>
The target names are not case sensitive.
A metadata element may be restricted to a subset of the targets in the same way, but with multiple space delimited target names in the target attribute.
<document xmlns="http://boradoc.org/1.0"> <metadata> <-- Apply this header only to the Mobi and ePub targets. --> <header url="resources/header.bdml" target="mobi epub" /> </metadata> <-- Main body of document... --> </document>
Some metadata elements are implicitly target specific (example: <link>). These do not need to be labelled with the target attribute. The reference documentation page of such elements states that the element is target specific.