6 DocBook dialect

6.1 Supported root elements

Both the <book> and the <article> root element are supported.

For docbook-to-pdf conversion: A <book> root results in a book-like output (with a front page, ToC, etc.). The <article> root results in something more memo style.

6.2 Document information

Document information: The only document information elements recognized are (any others are ignored):

<info>
  
  <title> ... main title ... </title>
  <subtitle> ... subtitle ...</subtitle>
  <pubdate> ... publication date ... </pubdate>
  <author>
    <personname> ... author name ...</personname>
  </author>
  
  <orgname> ... organization ... </orgname>
  
  <mediaobject role="top-logo">
    <!-- Use either role="top-logo" or no role attribute. -->
    <imageobject>
      <imagedata fileref="..." width="...(opt)" height="...(opt)"/>
    </imageobject>
  </mediaobject>
  
  <mediaobject role="center-page">
    <imageobject>
      <imagedata fileref="..." width="...(opt)" height="...(opt)"/>
    </imageobject>
  </mediaobject>
  
</info>

All elements are optional.

6.3 Chapter/Section structure

For books, <preface>, <chapter>, <appendix> and <sect1> to <sect9> are recognized and handled. Anything above <sect3> will not be numbered.
In articles only <sect1> to <sect9> are allowed.

6.4 Block constructions

the following block level constructions are recognized and handled:

Paragraphs: Normal <para> elements recognize the following role attribute values (multiple, whitespace separated, values allowed):

`@role` value	Description
`break`, `smallbreak`	Inserts an empty line, either full or small height. The contents of the `<para>` element is ignored.
`break-before` `break-after`	Adds extra whitespace before or after the paragraph
`header` `keep-with-next`	Keeps this paragraph with the next one together on a page.
`keep-with-previous`	Keeps this paragraph with the previous one together on a page.

Lists: Both <itemizedlist> and <orderedlist> are allowed.

Tables: Both <table> and <informaltable> are allowed. An example of a formal table above. An informal table below.

Example	of
an	informal table

Add role="nonumber" to a table to stop it from getting a number:

[*** Element entrytbl not supported for HTML conversion (phase: main)]

Blurp	Blorb
Example	of
an	unnumbered table
An `<entrytbl>`

A table can have multiple <tgroup> elements.

You can add a nested table in a cell using the <entrytbl> element (currently for PDF only).

<spanspec> elements are ignored.

Tables are notoriously difficult in that FOP cannot compute column widths automatically. To amand this (a little bit) add colspec/@colwidth information. There is also a mechanism for columns with code (set in a fixed-width font), see 6.7 Fixed-width column mechanism.

Program listings: For program listings use the <programlisting> element
The easiest way to handle this turned out to put longer program listings in external files and use an <xi:include parse="text"> construction:
<programlisting><xi:include href="ref" parse="text"/></programlisting>
Or use a <![CDATA[ construction around the piece of code.
For PDF generation it is possible to use so-called callouts to draw attention to parts of a program listing. These callouts can become links (both ways) using the right markup. For example:
```
xquery version "3.0" encoding "UTF-8";
module namespace x101log = "http://www.exist-db.org/book/namespaces/exist101"; 
declare function x101log:add-log-message($message as xs:string)
  as empty-sequence()  
…
};
```
[*** Element calloutlist not supported for HTML conversion (phase: main)]
Figures: Both <figure> and <informalfigure> are allowed. Width and height can be set on the image data.

Add role="nonumber" to a <figure> to stop it from getting a number.
In running the conversion pipelines, you can specify (as an option) a special "global" directory that contains global images (and other resources). When an image is located in this global directory add a role="global" to the <figure> element. Any directory information in @fileref is ignored.
Bridgeheads: The <bridgehead> element inserts a bridgehead paragraph (bold, underlined and with an empty line before):
This is a bridgehead...
Simple lists: The <simplelist> element inserts a simple list:
- An entry
- Another entry...
Variable lists: The <variablelist> element inserts a variable list list (also very useful for explaining terms, definitons, etc.):
The first entry
The explanation of the first entry!
The second entry
The explanation of the second entry!
Notes, warnings & cautions:
This is a note! … (<note>)
This is a warning! … (<warning>)
This is a caution! … (<caution>)
If you add a <title> element, the standard title will be replaced by its contents.
Sidebars & tips:
Title of the sidebar
Contents of the sidebar. … (<sidebar>)
Title of the tip
Contents of the tip. … (<tip>)
Examples: The <example> element inserts an example:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. …
Add role="nonumber" to an example to stop it from getting a number.
Block quotes:
[*** Element blockquote not supported for HTML conversion (phase: main)]

6.5 Inline elements

the following inline elements are recognized and handled:

<emphasis>: Sets emphasis.
Use role="bold" or role="underline" to set a specific type of emphasis.
<literal> or <code>: Creates a piece of literal, mono-spaced text.
Lot's of other elements that have to do with programming (like <function>> and <varname>) have the same effect.
<link>: Outputs some link (e.g. a web address). Use one of:
- @xlink:href for an external web address.
- @linkend for an internal id.
The visible contents will consist of either the contents of the <link> element or (if empty) the contents of @xlink:href or @linkend. Like this or like this http://www.xatapult.nl.
For HTML, add role="newpage" to get a new page/tab when clicking on the link.
<inlinemediaobject>: Inserts an inline image , like this.
In running the conversion pipelines, you can specify (as an option) a special "global" directory that contains global images (and other resources). When an image is located in this global directory add a role="global" to the <inlinemediaobject> element. Any directory information in @fileref is ignored.
<citation>: Inserts a citation between square brackets like this: [CITATION].
<command>: Use to indicate an exetuble program or a user provided command, like this: git checkout origin
<email>: Use to indicate an an email address, like this: info@xatapult.com
<filename>: Use to indicate an a filename, like this: blabla.xml
<replaceable>: Use to indicate text to be replaced with user or context supplied values, like this: add your own stuff here
<keycap>: Use to indicate a keyboard physical key, like this: Return
<superscript>, <subcript>: For super- and subscripts, like this: XX^super YY_sub
<userinput>: Use to indicate data entered by the user, like this: data entered here
<quote>: Use for adding a quote: [*** Unrecognized element: <quote xml:id="d3702e6023"> (phase: inline)].

<tag>: Indicates an object from the XML vocabulary. The class attribute signifies what:

`@class` value	Result example(s)
`attribute`	`@attribute` `@class`
`attvalue`	`"attribute value"` `"some value for an attribute"`
`emptytag`	`<element/>` `<docbook/>`
`endtag`	`</element>` `</docbook>`
`pi`	`<?processing-instruction x="y"?>`
`comment`	`<!-- Some comment line... -->`
Anything else defaults to `element`	`<element>` `<docbook>`

For HTML, add role="newpage" to get a new page/tab when clicking on the link.

<xref>: Inserts a cross-reference to the id referenced by @linkend

Use role="page-number-only" to get just a page number.
Use role="simple" to always get: page #
Use role="text" to only get the (unquoted) text only in cases where a "…" on page … would normally appear.
Use role="capitalize" to force the reference string (for chapters/appendices/pages/figures/tables/…) to start with an upper-case character (so you can be sure a sentence that starts with an <xref> always starts with a capital).

Otherwise it depends on what is pointed to:

Target	Result/Examples
To anything that holds an `xreflabel` attribute	paragraph with xreflabel attribute
To a chapter or appendix	chapter # or appendix #
To a section	6.2 Document information
To a table (with a number), like this one	table 6-4
To a figure (with a number)	figure 6-1
To an example (with a number)	example 6-1
To anything else	First paragraph: para Unnumbered table: table

<footnote> Adds a footnote[*** Element footnote not supported for HTML conversion (phase: inline)]
There are lots of elements that are ignored. For instance all the <gui…> elements, <orgname> and many more (but the list is not (yet) DocBook complete).

6.6 Other constructs

To-be-done marker: Start a to-be-done marker with [TBD and end it with ]. For instance: [TBD this needs to be done...]

6.7 Fixed-width column mechanism

FOP (in the current version, 3Q19) cannot compute the column-widths automatically. It divides the space and you can set a fixed column-width (with colspec/@colwidth). For the case that a column contains code stuff (text in a fixed-width font) and you want the column-width to be dependent on the text in such a column, there is a (unfortunately a bit complicated) mechanism for this.

The fixed-width column mechanism consists of two parts:

Dynamically compute the column width

This part is optional.

Add a role attribute to the <colspec> element with, as one of the roles, code-width-cm:min-max, where min and max are (positive) doubles. For instance <colspec role="code-width-cm:1.2-4">. min and max are the minimum and maximum column-widths, expressed in cm.

The PDF conversion will now look in all the contents of this particular column for entries <code role="code-width-limited">. Based on the length of these entries it computes an optimal column-width, but always between min and max.

Output code width-limited

If a table entry contains contents in a <code role="code-width-limited"> element, it tries to make it fit within the available column-width. If necessary the line is split to prevent overflowing of table cell contents.

This is (currently) not completely fool-proof: if the contents contains whitespace or hyphens, it is assumed to line-break correctly by itself. That, of course, does not guarantee correct results. So it may need a little experimenting before things look right.

A column that contains <code role="code-width-limited"> contents must have a column width set in cm (either directly with <colspec colwidth="…cm"> or by the dynamic mechanism described above).