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="d2e5834"> (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).