4.1. Markdown support

In addition to HTML, an ebook page may be written in Markdown. However for this to work, the file extension of the page written in Markdown must be md, markdown, mdown, mkdn, mdwn, mkd, rmd, text or txt.

The encoding of a Markdown file is, by default, the system encoding (e.g. window-1252 on a Western PC).

If you want to explicitly specify the encoding of a Markdown file, please save your file with a UTF-8 or UTF-16 BOM (Byte Order Mark) or add an encoding directive inside a comment anywhere at the beginning of your file. Example:

<!-- -*- coding: iso-8859-1 -*- -->

Heading
=======

## Sub-heading

Paragraphs are separated
by a blank line.

The above example should work fine because ebookc understands the GNU Emacs file variable called coding.

Out of the box, the Markdown parser is configured to support the commonmark 0.28 “Markdown dialect” plus all the following extensions:

• Abbreviations
• Admonitions
• Attributes
• Definition lists
• Footnotes
• Ins
• Strikethrough and subscript
• Media tags
• Superscript
• Tables
• Typographic characters
• YAML front matter

However, thanks to the flexmark-java software component used by ebookc to implement Markdown support, all this can be configured by passing some load.markdown.XXX options to ebookc.

For example, pass

• -p load.markdown.profile GITHUB
• -p load.markdown.less-extensions true
• -p load.markdown.gfm-tasklist true

to ebookc in order to parse the Github-flavored Markdown dialect and to enable a minimal set of extensions plus the task lists syntax extension.

Supported “Markdown dialects” are COMMONMARK, COMMONMARK_0_26, COMMONMARK_0_27, COMMONMARK_0_28, FIXED_INDENT, KRAMDOWN, MARKDOWN, GITHUB_DOC, GITHUB, MULTI_MARKDOWN, PEGDOWN, PEGDOWN_STRICT. See Markdown Processor Emulation.

Parameter -p load.markdown.less-extensions true is a shorthand parameter instructing ebookc to reset its extensions to the following minimal set of extensions:

• Strikethrough and subscript
• Superscript
• Tables
• YAML front matter

The above minimal set of extensions corresponds to what’s described in the Markdown Cheatsheet.

All supported Markdown syntax extensions are documented in Section 4.1.1. Supported Markdown extensions.

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification 
is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>

!!! note ""
    Support is limited to bug reports.

<blockquote class="role-note">
  <p>Support is limited to bug reports.</p>
</blockquote>

!!! tip "How do you do a hard reboot on an iPad?"
    Press and hold both the **Home** and **Power** buttons 
    until your iPad® reboots.

    You can release both buttons when you see Apple® logo.

<blockquote class="role-tip">
  <h4 class="role-admonition-title">How do you do a hard reboot on an iPad?</h4>
  <p>Press and hold both the <strong>Home</strong> and <strong>Power</strong> 
  buttons until your iPad&reg; reboots.</p>
  <p>You can release both buttons when you see Apple&reg; logo.</p>
</blockquote>

attributes -> '{' attribute_spec ( S attribute_spec)* '}'

attribute_spec ->   name=value
                  | name='value'
                  | name="value"
                  | #id
                  |.class

The *circumference { .first-term }* is the length of one circuit along the
circle, or the distance around the circle. {#circumference title="See
https://en.wikipedia.org/wiki/Circle"}

<p id="circumference" title="See https://en.wikipedia.org/wiki/Circle">The <em
class="first-term">circumference</em> the length of one circuit along the
circle, or the distance around the circle.</p>

Please send your bug reports to ebookc-support@xmlmind.com, a public,
moderated, mailing list. More information in
http://www.xmlmind.com/ebookc/support.html.

<p>Please send your bug reports to <a
href="mailto:ebookc-support@xmlmind.com">ebookc-support@xmlmind.com</a>, a
public, moderated, mailing list. More information in <a
href="http://www.xmlmind.com/ebookc/support.html"
>http://www.xmlmind.com/ebookc/support.html</a>.</p>

Glossary:

LED
: Light emitting diode.

ABS
: Antilock braking system.

ESC
ESP
: Electronic stability control, also known as Electronic Stability Program.

: On motorcycles, ESC/ESP is called *Traction Control*.

  > Ducati was one of the first to introduce a true competition-level 
  > traction control system (**DTC**) on a production motorcycle.

EBA
: Emergency brake assist.

<p>Glossary:</p>
<dl>
  <dt>LED</dt>
  <dd><p>Light emitting diode.</p></dd>

  <dt>ABS</dt>
  <dd><p>Antilock braking system.</p></dd>

  <dt>ESC</dt>
  <dt>ESP</dt>
  <dd><p>Electronic stability control, also known as Electronic Stability
  Program.</p></dd>
  <dd><p>On motorcycles, ESC/ESP is called <em>Traction
  Control</em>.</p>
  <blockquote><p>Ducati was one of the first to introduce a true
  competition-level traction control system (<strong>DTC</strong>)
  on a production motorcycle.</p></blockquote></dd>

  <dt>EBA</dt>
  <dd><p>Emergency brake assist.</p></dd>
</dl>

The differences between the programming languages C++[^1] and Java can be
traced to their heritage.

[^1]: The C++ Programming Language by Bjarne Stroustrup.

C++[^1] was designed for systems and applications programming, extending the
procedural programming language C[^2].

[^2]: The C Programming Language by Brian Kernighan and Dennis Ritchie.

      Originally published in 1978.

<p>The differences between the programming languages
C++<a class="role-footnote-ref" href="#__FN1"></a> and Java can be traced to
their heritage.</p> 

<div class="role-footnote" id="__FN1">
  <p>The C++ Programming Language by Bjarne Stroustrup.</p>
</div> 

<p>C++<aclass="role-footnote-ref" href="#__FN1"></a> was designed for systems 
and applications programming, extending the procedural programming language
C<a class="role-footnote-ref" href="#__FN2"></a>.</p> 

<div class="role-footnote" id="__FN2">
  <p>The C Programming Language by Brian Kernighan and Dennis
  Ritchie.</p>
  <p>Originally published in 1978.</p>
</div>

Audio example: !A[Falcon calling](media/falcon.mp3|media/falcon.wav).

<p>Audio example: <audio controls="" title="Falcon calling">
  <source src="media/falcon.mp3" type="audio/mpeg">
  <source src="media/falcon.wav" type="audio/wav">
  Your browser does not support the audio element.
</audio>.</p>

Video example: !V[Funny big bunny](media/bbb.mp4).

<p>Video example: <video controls="" title="Funny big bunny">
  <source src="media/bbb.mp4" type="video/mp4">
  Your browser does not support the video element.
</video>.</p>

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1,1 | Cell 1,2 | Cell 1,3 |
| Cell 2,1 | Cell 2,2 | Cell 2,3 |

<table border="1">
  <thead>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
      <th>Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 1,1</td>
      <td>Cell 1,2</td>
      <td>Cell 1,3</td>
    </tr>
    <tr>
      <td>Cell 2,1</td>
      <td>Cell 2,2</td>
      <td>Cell 2,3</td>
    </tr>
  </tbody>
</table>

| Header 1 | Header 2        | Table Header 3 |
| -------- | :-------------: | -------------: |
| Cell 1,1 | Table cell 1,2  | Cell 1,3       |
| Cell 2,1 | Cell 2,2        | Cell 2,3       |

<table border="1">
  <thead>
    <tr>
      <th>Header 1</th>
      <th style="text-align: center;">Header 2</th>
      <th style="text-align: right;">Table Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 1,1</td>
      <td style="text-align: center;">Table cell 1,2</td>
      <td style="text-align: right;">Cell 1,3</td>
    </tr>
    <tr>
      <td>Cell 2,1</td>
      <td style="text-align: center;">Cell 2,2</td>
      <td style="text-align: right;">Cell 2,3</td>
    </tr>
  </tbody>
</table>

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1,1 + 1,2     || Cell 1,3 |
| Cell 2,1 + 2,2 + 2,3         |||
| Cell 3,1 | Cell 3,2 | Cell 3,3 |
[Table caption here]

<table border="1">
  <caption>Table caption here</caption>
  <thead>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
      <th>Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="2">Cell 1,1 + 1,2</td>
      <td>Cell 1,3</td>
    </tr>
    <tr>
      <td colspan="3">Cell 2,1 + 2,2 + 2,3</td>
    </tr>
    <tr>
      <td>Cell 3,1</td>
      <td>Cell 3,2</td>
      <td>Cell 3,3</td>
    </tr>
  </tbody>
</table>

---
title: The C Programming Language
author:
  - Brian W. Kernighan
  - Dennis Ritchie
description: |
    One of the best-selling programming books published 
    in the last fifty years, "K&R" has been called everything 
    from the "bible" to "a landmark in computer science" and 
    it has influenced generations of programmers.
date: 1988-03-22
---

<head>
  <title>The C Programming Language</title>
  <meta content="Brian W. Kernighan" name="author" />
  <meta content="Dennis Ritchie" name="author" />
  <meta content="One of the best-selling programming books published 
                 in the last fifty years, &quot;K&amp;R&quot; has been called 
                 everything from the &quot;bible&quot; to 
                 &quot;a landmark in computer science&quot; and it has 
                 influenced generations of programmers." name="description" />
  <meta content="1988-03-22" name="date" />
</head>

4.2. Automatic resource management

XMLmind Ebook Compiler automatically copies all the resources referenced by the ebook specification and the input HTML pages to the output directory in order to create a self-contained deliverable. Creating self-contained deliverables is generally desirable and for some output formats, like EPUB, this is really required.

For example, if you run (single-page HTML output format):

ebookc doc.ebook out/doc.html

all the resources of doc.ebook are copied to out/doc_files/.

Other example, if you run:

ebookc -f webhelp doc.ebook out/webhelp/

all the resources of doc.ebook are copied to out/webhelp/_res/.

What is a resource?

By default, XMLmind Ebook Compiler considers that any file [15] referenced by the ebook specification or an input HTML page using a relative URI is a resource. This is generally the case of images, audio and video files, CSS stylesheets, scripts files referenced by the ebook specification and the input HTML pages.

In this example, image "cc-by-sa.png" is obviously a resource and file "creativecommons.html" not being an input HTML page, is also considered to be a resource:

1
2
3
4
5

<p>All the above tutorials are licensed under the
<a href="creativecommons.html"><img src="cc-by-sa.png"
alt="CC BY-SA"/>Creative Commons License</a>,
which means that everyone is welcome to distribute, modify, translate, etc,
any of them.</p>

How to specify "not a resource; do not copy it and keep its relative URI as is"?

The automatic resource management of ebookc may be turned off globally by setting option proc.ignoreresources to "true".

If you want to specify that only some of the resources of an ebook are external and as such, should not be processed by ebookc, please use

• value "external-resource" for standard attribute rel (HTML link elements have this attribute);
• proprietary attribute data-external-resource for elements like img which do not have attribute rel.

Example:

1
2
3
4
5
6

<p>All the above tutorials are licensed under the
<a href="creativecommons.html"
rel="external-resource"><img src="cc-by-sa.png" alt="CC BY-SA"
data-external-resource=""/>Creative Commons License</a>,
which means that everyone is welcome to distribute, modify, translate, etc,
any of them.</p>

In the above example, files "cc-by-sa.png" and "creativecommons.html" are not processed as resources.

Option externalresourcebase may be used to specify an absolute or relative URI to be prepended to external resources having a relative URI. Example: -p proc.externalresourcebase "../../samples/".

How to specify "this is a resource too; copy it to the output directory"?

By default, XMLmind Ebook Compiler considers that any file referenced by the ebook specification or an input HTML page using an absolute URI is not a resource. Example:

1
2
3
4
5
6

<p>All the above tutorials are licensed under the
<a href="https://creativecommons.org/creativecommons.html">
<img src="https://creativecommons.org/cc-by-sa.png"
alt="CC BY-SA"/>Creative Commons License</a>,
which means that everyone is welcome to distribute, modify, translate, etc,
any of them.</p>

In the above example, files "https://creativecommons.org/creativecommons.html" and "https://creativecommons.org/cc-by-sa.png" are not processed as resources.

If you want to specify that some files having absolute URIs are in fact resources and as such, should be processed by ebookc, please use

• value "resource" for standard attribute rel (HTML link elements have this attribute);
• proprietary attribute data-resource for elements like img which do not have attribute rel.

Example:

1
2
3
4
5
6
7

<p>All the above tutorials are licensed under the
<a href="https://creativecommons.org/creativecommons.html"
rel="resource">
<img src="https://creativecommons.org/cc-by-sa.png"
data-resource="" alt="CC BY-SA"/>Creative Commons License</a>,
which means that everyone is welcome to distribute, modify, translate, etc,
any of them.</p>

In the above example, files "https://creativecommons.org/creativecommons.html" and "https://creativecommons.org/cc-by-sa.png" are processed as resources.

Sub-resources

In the following example, files "styles.css", "creativecommons.html" and "cc-by-sa.png" are automatically processed as resources:

1
2
3
4
5
6
7
8
9
10
11

...
<head>
  ...
  <link href="css/styles.css" rel="stylesheet" type="text/css" />
</head>
...
<p>All the above tutorials are licensed under the
<a href="creativecommons.html"><img src="cc-by-sa.png"
alt="CC BY-SA"/>Creative Commons License</a>,
which means that everyone is welcome to distribute, modify, translate, etc,
any of them.</p>

Moreover, if file "creativecommons.html" contains XHTML —that is, can be parsed by XMLmind Ebook Compiler— its resources are processed too as if "creativecommons.html" were an input HTML page.

This is also the case for resource "styles.css". The resources found in a CSS stylesheet (e.g. file "texture.png" in "background-image: url(images/texture.png);" or file "core_styles.css" in "@import url(lib/core_styles.css);") are automatically detected and processed by XMLmind Ebook Compiler.

However, if she/he finds this clearer, the ebook author may also explicitly specify the sub-resources of CSS stylesheets using extra link elements in the headcommon of the ebook specification or in the head of an input HTML page. Example:

1
2
3
4
5
6
7
8
9
10
11
12

...
<head>
  ...
  <link href="css/images/" rel="resource" type="inode/directory" />
  <link href="css/styles.css" rel="stylesheet" type="text/css" />
</head>
...
<p>All the above tutorials are licensed under the
<a href="creativecommons.html"><img src="cc-by-sa.png"
alt="CC BY-SA"/>Creative Commons License</a>,
which means that everyone is welcome to distribute, modify, translate, etc,
any of them.</p>

Notice attribute rel="resource" which makes even clearer the purpose of this link. Also notice type="inode/directory" which is needed because "css/images/" is a folder and not a simple file.

4.3. Conditional processing

XMLmind Ebook Compiler can conditionally exclude some contents found in the ebook specification or in the input HTML pages. To put this feature into use, the ebook author must:

1. Specify one or more data-* attributes on the elements to be conditionally excluded. Examples: data-edition="complete", data-output-format="docx odt pdf rtf wml".

   These data-* attributes are often called profiling attributes because they are used to define several profiles for the same document.

   It's up to the ebook author to choose the names and allowed values for the profiling attributes.

   The ebook author may allow only a single value for a given profiling attribute. Example: attribute data-edition may contain only a single value, one of "complete" or "abridged".

   Or, on the contrary, the ebook author may allow a given profiling attribute to contain several values separated by space characters. Example: attribute data-output-format may contain one or more of "docx", "epub", "frameset", "html ", "odt", "pdf", "rtf", "webhelp", "wml".

2. Pass one or more profile.* parameters to the ebookc command-line option. These profile.* parameters must match the chosen profiling attributes. Example: -p profile.edition abridged -p profile.output-format pdf.

   Note that unless you pass a profile.* parameter, the corresponding data-* attribute is not given any special meaning by XMLmind Ebook Compiler. For example, without -p profile.output-format VALUE, attribute data-output-format is considered to be just an ordinary attribute.

How some elements are conditionally excluded by XMLmind Ebook Compiler is best explained by an example:

1
2
3
4
5
6
7
8
9
10

<p>See YouTube demo:</p>

<p data-edition="complete" data-output-format="epub frameset html webhelp">
<iframe src="https://www.youtube.com/embed/6MgZBZ4XHzU"
height="360" width="640"></iframe></p>

<p data-edition="complete" data-output-format="docx odt pdf rtf wml">
<img src="images/YouTube_play_icon.svg" alt="..."/> 
<a href="https://youtu.be/6MgZBZ4XHzU"
target="_blank">https://youtu.be/6MgZBZ4XHzU</a>.</p>

For an element to be excluded, suffice for a single profiling attribute to be “excluded”. A profiling attribute data-X is “excluded” if none of the values it contains matches a value contained in the profile.X parameter passed to ebookc.

For example, with -p profile.edition complete -p profile.output-format pdf, the embedded video

1
2
3

<p data-edition="complete" data-output-format="epub frameset html webhelp">
<iframe src="https://www.youtube.com/embed/6MgZBZ4XHzU"
height="360" width="640"></iframe></p>

is excluded because despite the fact that data-edition="complete" is “included”, data-output-format="epub frameset html webhelp" is “excluded”.

Other examples, if you pass ebookc

• no profile.* parameter at all, the above example will contain both the embedded video and the YouTube link to the video.
• -p profile.edition abridged, the above example will contain neither the embedded video nor the YouTube link to the video.
• -p profile.edition complete, the above example will contain both the embedded video and the YouTube link to the video.
• -p profile.output-format epub, the above example will contain just the embedded video.
• -p profile.output-format pdf, the above example will contain just the YouTube link to the video.
• -p profile.edition abridged -p profile.output-format pdf, the above example will contain neither the embedded video nor the YouTube link to the video.
• -p profile.edition complete -p profile.output-format pdf, the above example will contain just the YouTube link to the video.
• -p profile.edition complete -p profile.output-format "epub pdf", the above example will contain both the embedded video and the YouTube link to the video.

4.4. Transclusion

XMLmind Ebook Compiler has good support for transclusion, that is the ability to include contents found in an input HTML page into another input HTML page. This feature is implemented using a standard mechanism called XInclude.

Example, "page1.html" contains paragraph having id="notice":

1
2

<p id="notice" class="important">Interest rates are subject
to fluctuation without notice.</p>

Because this paragraph has an id, it's possible to include it in "page2.html":

1
2
3
4
5
6

<p>Paragraph found in page2.html.</p>

<xi:include href="page1.html" xpointer="notice" 
  xmlns:xi="http://www.w3.org/2001/XInclude" />[16]

<p>Other paragraph found in page2.html.</p>

The corresponding output HTML page will then contain:

1
2
3
4
5
6

<p>Paragraph found in page2.html.</p>

<p id="notice" class="important">Interest rates are subject
to fluctuation without notice.</p>

<p>Other paragraph found in page2.html.</p>

Note that transclusion works fine not only between two input HTML pages, but also:

• within the same input HTML page (see example below),
• between two ebook specifications,
• within the same ebook specification.

However transclusion does not work between an input HTML page and an ebook specification.

1
2
3
4
5
6
7

<p id="notice" class="important">Interest rates are subject
to fluctuation without notice.</p>

... ELSEWHERE in page1.html ...

<xi:include href="" xpointer="notice" 
  xmlns:xi="http://www.w3.org/2001/XInclude" />

Transclusion is most often used between the input HTML pages and a “utility HTML page” which is not an input HTML page but which contains useful “snippets”.

Example, excerpts from "snippets.html":

1
2
3
4
5
6
7
8

<ul>
  <li><span id="ebookc">XMLmind Ebook Compiler</span>.</li>

  <li><span id="xxe">XMLmind XML Editor</span>.</li>

  <li><a href="http://www.xmlmind.com/" id="xmlmind"
         target="_blank">XMLmind</a>.</li>
</ul>

Now, including snippets in an input HTML page:

1
2
3
4
5
6
7
8
9

<p><xi:include href="snippets.html" xpointer="ebookc"
xmlns:xi="http://www.w3.org/2001/XInclude" /> is free, open source software
developed by <xi:include href="snippets.html" xpointer="xmlmind"
xmlns:xi="http://www.w3.org/2001/XInclude" />.</p>

<p><xi:include href="snippets.html" xpointer="xxe"
xmlns:xi="http://www.w3.org/2001/XInclude" /> is a commercial product
developed by <xi:include href="snippets.html" xpointer="xmlmind"
xmlns:xi="http://www.w3.org/2001/XInclude" />.</p>

6.1. Valid XHTML5

Your source HTML pages must contain valid[17] XHTML (“plain HTML” cannot be parsed by ebookc) and preferably valid XHTML5, because ebookc anyway generates XHTML5 markup.

The html root element must have 1 head and 1 body child elements. The head child element must have 1 title child element.

1
2
3
4
5
6
7
8
9
10

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="UTF-8" />
    <title>...</title>
  </head>
  <body>
  ...
  </body>
</html>

If you plan to use XMLmind XML Editor as your ebook authoring tool, do not forget to add attribute class="role-ebook-page" to the html root element of your source HTML pages. XMLmind XHTML Editor detects this attribute and this will cause the editor to replace its stock "XHTML" menus and toolbars by extended "XHTML" menus and toolbars.

6.2. Headings

You may use headings (h1, h2, h3, etc) normally, without worrying about the role as a book division (chapter, section, etc) that will be given to your input HTML page.

By default, book attribute adjustuserheadings="true!article" specifies that the levels of your headings are to be automatically adjusted (except inside article elements, which are considered to be independent, self-contained content) to make them consistent with the level of the title of the book division.

Example, input HTML page contains:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="UTF-8" />
    <title>Troubleshooting</title>
  </head>
  <body>
  <h1>Symptoms</h1>
  ...
  <h2>Intermittent symptoms</h2>
  ...
  <h1>Most common causes</h1>
  ...  
  </body>
</htm>

The above input HTML is referenced as a subsection of a chapter in the book. Therefore the title of the subsection is represented by an h3 element. The output HTML page containing the subsection then looks like:

1
2
3
4
5
6
7
8

<section class="role-section2">
  <h3 class="role-section2-title">Troubleshooting</h3>  
  <h4>Symptoms</h4>
  ...
  <h5>Intermittent symptoms</h5>
  ...
  <h4>Most common causes</h4>
  ...

If you want to prevent this from happening, please add attribute adjustuserheadings="false" to your root book element or add a class attribute to some or all of your headings. A heading having a class attribute is understood by XMLmind Ebook Compiler as being “not an ordinary heading which could be modified”.

6.3. Examples

An example is a figure element which has a class attribute containing "role-example". This kind of figure is listed in the "List of Examples" (that is, book element lox) only if it also has a figcaption child element. Example:

1
2
3
4
5
6
7
8
9
10
11

<figure class="role-example">
  <figcaption>"Hello World" program in the C language</figcaption>
  <pre>/* Hello World */
#include &lt;stdio.h&ght;

int main()
{
    printf("Hello World\n");
    return 0;
}</pre>
</figure>

is rendered as:

/* Hello World */
#include <stdio.h>

int main()
{
    printf("Hello World\n");
    return 0;
}

§ Program listings

A program listing can have its lines automatically numbered and/or can feature syntax highlighting. This is done by adding "role-listing-NUMBER-LANGUAGE-tabWIDTH" to the class attribute of a pre element. Options NUMBER, LANGUAGE, tabWIDTH, may be specified in any order. Moreover some or all of these options may be omitted.

• NUMBER, a strictly positive integer, specifies the number of the first line of the program listing. This option may be omitted if you don't want automatic line numbering.
• LANGUAGE, one of (case-insensitive): "bourne" (or "shell" or "sh"), "c", "cmake" (or "make" or "makefile"), "cpp", "csharp", "css21" (or "css"), "delphi", "ini", "java", "javascript", "lua", "m2" (Modula 2), "perl", "php", "python", "ruby", "sql1999", "sql2003", "sql92" (or "sql"), "tcl", "upc" (Unified Parallel C), "html", "xml", specifies the programming language or markup language used in the program listing. This option may be omitted if you don't want syntax highlighting.
• tabWIDTH where WIDTH is a positive integer, specifies whether tab characters should be expanded to a number of space characters. WIDTH is the maximum number of space characters for an expanded tab character, hence this value specifies the location of “tab stops”. Example: <pre class="role-listing-1-java-tab4"> means expand tabs to up to 4 space characters in this line-numbered Java listing. Other example: <pre class="role-listing-tab0-shell"> means: do not replace tabs in this Bourne shell listing. When tabWIDTH is omitted, it is equivalent to having an implicit tab8.

Example 1 (in the following C program, lines are indented using tab characters):

1
2
3
4
5
6
7
8

<pre class="role-listing-1-c-tab4">/* Hello World */
#include &lt;stdio.h&ght;

int main()
{
        printf("Hello World\n");
        return 0;
}</pre>

is rendered as:

1
2
3
4
5
6
7
8

/* Hello World */
#include <stdio.h>

int main()
{
    printf("Hello World\n");
    return 0;
}

Superfluous indentation is removed too

Note that in addition to replacing tab characters by a number of space characters, the tabWIDTH facility also removes the space characters which are common to the beginning of all text lines. That is, it removes the superfluous “indentation” in the program listing, if any.

Moreover, the tabWIDTH facility also removes the (useless) space characters found just before a newline character.

See example 2 below in which the indentation is automatically removed.

Example 2 (implicit role-listing-1-tab8; first line "    /tmp/" starts with 4 space characters):

1
2
3
4
5
6
7
8
9
10
11

<pre class="role-listing-1">    /tmp/
    /usr/                            
        bin/
        lib/
        <b>local/</b>
                <b>bin/</b>
                <b>lib/</b>
                <b>src/</b>
        src/
    /var/                            
</pre>

is rendered as:

1
2
3
4
5
6
7
8
9
10
11

/tmp/
/usr/
    bin/
    lib/
    local/
            bin/
            lib/
            src/
    src/
/var/

6.4. Equations

An example is a figure element which has a class attribute containing "role-equation". This kind of figure is listed in the "List of Equations" (that is, book element loe) only if it also has a figcaption child element. Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<figure class="role-equation">
  <figcaption>Special relativity</figcaption>
  <div>
    <math display="block"
          xmlns="http://www.w3.org/1998/Math/MathML">
      <mrow>
        <mrow>
          <mi>t</mi>
          <mo>’</mo>
        </mrow>
        <mo>=</mo>
        <mrow>
          <mi>t</mi>
          <mo>&#x2062;</mo>
          <mfrac>
            <mn>1</mn>
            <msqrt>
              <mrow>
                <mn>1</mn>
                <mo>-</mo>
                <mfrac>
                  <msup>
                    <mi>v</mi>
                    <mn>2</mn>
                  </msup>
                  <msup>
                    <mi>c</mi>
                    <mn>2</mn>
                  </msup>
                </mfrac>
              </mrow>
            </msqrt>
          </mfrac>
        </mrow>
      </mrow>
    </math>
  <div>
</figure>

is rendered as:

Few web browsers natively support MathML, so it's recommended to add a link to the MathJax script to your input HTML pages containing equations[18]. This typically done as follows (this loads latest 3.x version of the MathJax mml-chtml component):

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="UTF-8" />
    <title>...</title>

    <script async="async" id="MathJax-script"
            src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/mml-chtml.js"
            type="text/javascript"></script>
    
  </head>
  ...

6.5. Admonitions

An admonition, that is, a warning, a tip, a notice, etc, is a blockquote element which has a class attribute containing "role-ADMONITION", where role-ADMONITION is one of the following class names:

Example:

1
2
3
4
5
6
7

<blockquote class="role-important">
  <h4>How to check your oil</h4>
  <p>You need to check your car’s oil before any long trip
  to avoid major damage.</p>
  <p>The process for how to check your oil is simple and involves
  using the dip stick to see levels and test quality.</p>
</blockquote>

is rendered as:

How to check your oil

You need to check your car’s oil before any long trip to avoid major damage.

The process for how to check your oil is simple and involves using the dip stick to see levels and test quality.

6.6. Footnotes

Simple footnotes

This first and simplest form for a footnote is a span element which has a class attribute containing "role-footnote".

Example:

1
2
3

<p>Yoko<span class="role-footnote">Written with kanji <i>ko</i>, meaning
"child". The syllable <i>ko</i> is not generally found at the end of
masculine names.</span> is a Japanese feminine given name.</p>

is rendered as:

Yoko[19] is a Japanese feminine given name.

General footnotes

When you need a footnote to contain paragraphs, lists or tables or when you need to reuse the same footnote at different locations in your document, you'll have to use the second, more general, form for a footnote.

This second form is a div element which has a class attribute containing "role-footnote" and an id attribute.

Moreover, you'll also have to insert an a element at the location where you want the footnote marker to be displayed. This a element, which points to the footnote div, must have a class attribute containing "role-footnote-ref".

Example:

1
2
3
4
5
6

<p>Yoko<a class="role-footnote-ref" href="#ko"></a>is a Japanese
feminine given name.</p>

<div class="role-footnote" id="ko">Written with kanji <i>ko</i>, 
meaning "child". The syllable <i>ko</i> is not generally found 
at the end of masculine names.</div> 

is rendered as:

Yoko[20] is a Japanese feminine given name.

6.7. Cross-references

No need to specify the text of a link when this link points to a book division (chapter, section, etc) or to a table, figure, example, or equation having a caption.

Example, the following empty links point respectively to section "Admonitions" and to table "Admonition classes" found in this section:

<p><a href="admonitions.html"></a> contains
<a href="admonitions.html#admonition_classes"></a>.</p>

are rendered as:

Section 6.5. Admonitions contains Table 6-1. Admonition classes.

The text which is automatically generated for these empty links may be configured using attribute xreflabels of element book.

Links specified using attribute data-xml-id-ref

It's also possible to create links using the a element and proprietary attribute data-xml-id-ref rather than (or in addition to) standard attribute href.

Attribute data-xml-id-ref must contain the value of the xml:id attribute of a book division found in the ebook specification. This allows the creation of links to locations that do not exist in the input HTML pages, but which will be created in the output HTML pages.

Example, <a data-xml-id-ref="ch04"/> points to the following chapter:

1
2
3
4
5

<chapter xml:id="ch04">
  <head><title>...</title></head>
  <section href="ch4/s1.html"/>
  <section href="ch4/s2.html"/>
</chapter>

In input HTML page "ch4/s2.html", you may refer to the first section of the chapter by writing <a href="s1.html"/>. But how to refer to the chapter itself? Notice that this chapter has no input HTML page to refer to.

The solution to this problem is to add proprietary attribute data-xml-id-ref to an a element. For the above example, it's <a data-xml-id-ref="ch04"/>.

Note that writing <a href="s1.html" data-xml-id-ref="ch04"/> is an even better option because href="s1.html" is used as a fallback link target in case xml:id="ch04" is not defined in the ebook specification.

6.8. Index terms

Creating index terms by hand (other than copying an index term to paste it elsewhere) is tedious and error prone. It's strongly recommended to use the specialized dialog box of XMLmind XML Editor to do that.

An index term is represented by a a element having attribute class="role-index-term" containing text —the primary word or phrase in an index term— and possibly nested span elements having the following roles: "role-term", "role-see", "role-see-also".

index_term -> end_of_range | term

end_of_range -> <a class="role-index-term" data-end-range="range_name"/>

term -> <a class="role-index-term" term_attributes>term_content</a>

term_attributes -> [ data-sort-as="text" ]? 
                   [ data-start-range="range_name" ]?

term_content -> rich_text term_childs

term_childs -> [ sub_term ]? | [ see ]* | [ see_also ]*

sub_term -> <span class="role-term" term_attributes>term_content</span>

see -> <span class="role-see">see_content</span>

see_also -> <span class="role-see-also">see_content</span>

see_content -> rich_text see_child

see_child -> [ <span class="role-term">rich_text see_child</span> ]?

In the above grammar:

• "Rich text" means the mix of text and phrase elements (b, i, em, etc) allowed in a and span elements.
• Though the grammar allows <span class="role-term"> to be nested to an arbitrary depth, a <a class="role-index-term"> may contain only up two nested <span class="role-term">, corresponding respectively to the secondary word and tertiary word of an index term. The same limit applies to <span class="role-see"> and to <span class="role-see-also">.

Examples:

• Simplest index term containing just a phrase:

  <a class="role-index-term">Dog, man's best friend</a>

• “Sort-as” example:

  1 2	<a class="role-index-term" data-sort-as="percent">%</a>

• Index terms having primary, secondary and tertiary terms:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

  <a class="role-index-term"><b>Pet</b> <span class="role-term">Cat</span> </a> ... <a class="role-index-term"><b>Pet</b> <span class="role-term">Cat <span class="role-term">Siamese</span> </span> </a> ... <a class="role-index-term"><b>Pet</b> <span class="role-term">Cat <span class="role-term">Burmese</span> </span> </a>

• Start of the "dogs" range:

  1 2 3

  <a class="role-index-term"><b>Pet</b> <span class="role-term" data-start-range="dogs">Dog</span> </a>

• End of the above "dogs" range. The end of a range must be found after the corresponding start of range in the same input HTML page or in a different input HTML page:

  <a class="role-index-term" data-end-range="dogs"></a>

  Notice that an end of range index term does not contain text nor any child element. It just has a "data-end-range" attribute.

• “See” example:

  1 2 3 4 5

  <a class="role-index-term"><i lang="la">Felis catus</i> <span class="role-see">Pet <span class="role-term">Cat</span> </span> </a>

• “See also” example:

  1 2 3 4 5 6

  <a class="role-index-term"><i lang="la">Canis lupus</i> <span class="role-see-also">Dog, man's best friend</span> <span class="role-see-also">Pet <span class="role-term">Dog</span> </span> </a>

7.1. Element appendices

Specifies the group of appendices of the ebook.

Content model

(head? , body? , related* , appendix+)

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain appendices: book.

Children

The following elements occur in appendices: appendix, body, head, related.

Example

1
2
3
4
5
6

<appendices pagename="Appendixes">
  <appendix href="pages/known_problems.html"/>
  <appendix href="pages/error_list.html">
    <section href="pages/report_error.html"/>
  </chapter>
</part>

7.2. Element appendix

Specifies an appendix of the ebook.

Content model

(head? , body? , related* , section*)

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain appendix: appendices, book.

Children

The following elements occur in appendix: body, head, related, section.

Example

1
2
3
4
5
6

<appendices pagename="Appendixes">
  <appendix href="pages/known_problems.html"/>
  <appendix href="pages/error_list.html">
    <section href="pages/report_error.html"/>
  </chapter>
</part>

7.3. Element backmatter

Specifies the back matter of the ebook.

Content model

(toc | index | lot | lof | loe | 
 lox | section)+

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain backmatter: book.

Children

The following elements occur in backmatter: index, loe, lof, lot, lox, section, toc.

Example

1
2
3
4

<backmatter>
  <section href="glossary.html"/>
  <index/>
</backmatter>

7.4. Element body

Specifies the content of a book division (part, chapter, section, etc).

When the parent of body is element book then body specifies the content of the “title page” of the book.

It's possible for a book division to have both an href attribute and a body child element. In such case, the content “pulled” using the href attribute is inserted before the content specified by the body child element.

Content model

content+

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain body: appendices, appendix, book, chapter, part, section.

Children

The following elements occur in body: content.

Example

1
2
3
4
5
6
7
8
9

<chapter>
  <head>
    <title>Using Widget</title>
  </head>
  <body>
    <content href="using1.html"/>
    <content href="using2.html"/>
  </body>
</chapter>

7.5. Element book

Specifies a complete ebook.

Content model

(headcommon? , 
 head? , 
 body? , 
 related* , 
 frontmatter? , 
 ((part+ , appendices?) | 
  (chapter+ , appendix*)) , 
 backmatter?)

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

adjustuserheadings

If set to true, change the level of user-specified headings (h1, h2, h3, etc) to be consistent with the level of automatically generated headings. If set to false, do not change any user-specified headings. Example:

1 2 3 4

<chapter href="ch01.html" pagename="first_chapter"> <section href="s01.html" pagename="first_section"> <section href="s01_01.html" pagename="nested_section"> ...

where input HTML file "s01_01.html" starts with a user-specified h1.

With adjustuserheadings="false", output HTML file "nested_section.html" contains:

1 2 3 4 5

<section class="role-section2> <h3 class="role-section2-title">Title of the section copied from "s01_01.html"<h3> <h1>User-specified heading found in "s01_01.html"</h1> ...

With adjustuserheadings="true", output HTML file "nested_section.html" contains:

1 2 3 4 5

<section class="role-section2> <h3 class="role-section2-title">Title of the section copied from "s01_01.html"<h3> <h4>User-specified heading found in "s01_01.html"</h4> ...

Note that adjustuserheadings="true" has no effect on headings having a class attribute. A heading having a user-specified class attribute is understood by XMLmind Ebook Compiler as being “not an ordinary heading which could be modified”.

§ Exceptions

Value "true" of attribute adjustuserheadings may be followed by "!" and a list of exceptions. An exception is either the local name of an HTML element (e.g. article, aside) or the local name of an HTML element followed by a dot and a value[21] of the class attribute (e.g. blockquote.role-warning, blockquote.role-*). When this is the case, the level of user-specified headings is not changed inside specified elements.

Note that the default value of attribute adjustuserheadings is "true!article" and not simply "true" because article elements are considered to be independent, self-contained content.

appendicestocdepth

If set to an integer larger than 0, instructs ebookc to automatically generate a Table of Contents (TOC) having specified depth at the beginning of the appendices division of the book.

appendixnumber

Specifies the format of the number automatically added to the title of an appendix. See Number format.

appendixtocdepth

If set to an integer larger than 0, instructs ebookc to automatically generate a Table of Contents (TOC) having specified depth at the beginning of each appendix of the book.

booklistlabels

Specifies the kind of numbered book divisions (part, chapter, appendix, section) and numbered figure objects (figure, table, equation, example) for which to add labels. This option applies to book list entries (toc, lof, lot, loe, lox).

§ What is a label?

A label is a localized message containing the type of the book division or figure object. For example, with chapternumber="%1", labelseparator=") ", booklistlabels="none", a TOC entry for a chapter looks like: "1) Introduction". With booklistlabels="chapter" (or booklistlabels="all"), this TOC entry looks like: "Chapter 1) Introduction".

Note that labels are added only to numbered book divisions or figure objects. For example, with chapternumber="%1", booklistlabels="", a TOC entry for a chapter will look like: "Introduction".

chapternumber

Specifies the format of the number automatically added to the title of a chapter. See Number format.

chaptertocdepth

If set to an integer larger than 0, instructs ebookc to automatically generate a Table of Contents (TOC) having specified depth at the beginning of each chapter of the book.

equationnumber

Specifies the format of the number automatically added to the caption of an equation. See Number format.

examplenumber

Specifies the format of the number automatically added to the caption of an example. See Number format.

figurenumber

Specifies the format of the number automatically added to the caption of an figure. See Number format.

footnotenumber

Specifies the format of the number automatically added to footnotes (<span class="role-footnote"> or <div class="role-footnote">) and footnote callouts (<a class="role-footnote-ref">).

includebasestylesheet

If set to "true", include ebookc_install_dir/xsl/common/resources/base.css in all the output HTML pages.

Using the base.css stock CSS stylesheet is the simplest, easiest, mean to create a nicely formatted book. More information about this attribute in Leveraging base.css, the stock CSS stylesheet.

When includebasestylesheet="true", base.css is included before the other CSS stylesheets referenced in the headcommon (if any).

If you want to control where base.css is included, do not set includebasestylesheet to "true", instead add a headcommon similar to the one in the following example:

<headcommon>
  <html:link href="corporate_styles.css" rel="stylesheet"
             type="text/css"/>
  <html:link href="ebookc-home:xsl/common/resources/base.css"
             rel="stylesheet resource" type="text/css"/>
</headcommon>

The "ebookc-home:" prefix works because stock XML catalog ebookc_install_dir/schema/catalog.xml contains:
<rewriteURI uriStartString="ebookc-home:" rewritePrefix="../"/>.

headoverridedefault

Specifies the default value of attribute override of element head.

labelseparator

Specifies the string which is appended to the label automatically generated at the beginning of the title of a book division (part, chapter, appendix, section) or figure object (figure, table, equation, example). Example: with labelseparator=") ", the output HTML element generated for the following chapter is:

<chapter href="ch01.html">

is:

1 2 3 4 5

<section class="role-chapter> <h1 class="role-chapter-title"> <span class="role-label">Chapter <span class="role-number">1</span>) </span> Title of the chapter copied from "ch01.html"<h1>

partnumber

Specifies the format of the number automatically added to the title of a part of the book. See Number format.

parttocdepth

If set to an integer larger than 0, instructs ebookc to automatically generate a Table of Contents (TOC) having specified depth at the beginning of each part of the book.

preventlonelyheading

If set to true, prevent an output HTML page from containing only a title. Example:

1 2 3 4 5 6

<chapter pagename="chapter1"> <head> <title>First chapter</title> </head> <section href="s01.html"/> ...

With preventlonelyheading="false", output HTML page "output_directory/chapter1.html" contains just the title of the chapter "First chapter", which may be surprising for the reader of the book.

With preventlonelyheading="true", output HTML page "output_directory/chapter1.html" contains the title of the chapter "First chapter" and also the content of input HTML page "s01.html"[22].

section1number

Specifies the format of the number automatically added to the title of a top level section. See Number format.

section2number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 2 (subsection of a top level section). See Number format.

section3number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 3. See Number format.

section4number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 4. See Number format.

section5number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 5. See Number format.

section6number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 6. See Number format.

section7number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 7. See Number format.

section8number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 8. See Number format.

section9number

Specifies the format of the number automatically added to the title of a section having a nesting level equal to 9. See Number format.

tablenumber

Specifies the format of the number automatically added to the caption of an table. See Number format.

titlelabels

Specifies the kind of numbered book divisions (part, chapter, appendix, section) and numbered figure objects (figure, table, equation, example) for which to add labels. This option applies to titles or captions.

For example, with chapternumber="%1", labelseparator=") ", titlelabels="none", the title of a chapter looks like: "1) Introduction". With titlelabels="chapter" (or titlelabels="all"), this title looks like: "Chapter 1) Introduction".

tocdepth

Specifies the depth of the main Table of Contents (TOC) (see toc element).

xml:lang

Specifies the main language of the book. This language is used to automatically generate some titles (e.g. "Table of Contents", "List of Figures") and also to sort index entries.

Unlike lang, which is a XHTML5 global attribute, xml:lang is not copied to the output HTML element corresponding to the book element.

However, explicitly setting attribute xml:lang on the book element is a convenient way to ensure that all the output HTML pages have a lang attribute.

xreflabels

Specifies the kind of numbered book divisions (part, chapter, appendix, section) and numbered figure objects (figure, table, equation, example) for which to add labels. This option applies to automatically generated link text.

For example, with chapternumber="%1", labelseparator=") ", xreflabels="none", the text automatically generated for empty link to chapter <a href="intro.html"/> looks like: "1) Introduction". With xreflabels="chapter" (or xreflabels="all"), this text looks like: "Chapter 1) Introduction".

With xreflabels="chapter-number", this text looks like: "Chapter 1", that is, no chapter title, just the label without any label separator. Note that this "-number" suffix is supported only by xreflabels.

Children

The following elements occur in book: appendices, appendix, backmatter, body, chapter, frontmatter, head, headcommon, part, related.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<book appendixtocdepth="100" chaptertocdepth="100"
      section7number="" section8number="" section9number=""
      labelseparator=" "
      booklistlabels="chapter appendix"
      xreflabels="chapter appendix section
                  figure-number table-number equation-number example-number"
      xml:lang="en-US"
      xmlns="http://www.xmlmind.com/schema/ebook"
      xmlns:html="http://www.w3.org/1999/xhtml">
  <head>
    <title>Widget User Guide</title>
    <html:meta content="John Smith" name="author"/>
    <html:meta content="2017-08-25" name="dc.date"/>
  </head>
  ...
</book>

7.6. Element chapter

Specifies a chapter of the ebook.

Content model

(head? , body? , related* , section*)

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain chapter: book, part.

Children

The following elements occur in chapter: body, head, related, section.

Example

1
2
3
4
5
6

<part>
  <chapter href="pages/install.html">
    <section href="pages/requirements.html" samepage="true"/>
  </chapter>
  <chapter href="pages/quick_start.html"/>
</part>

7.7. Element content

Instructs XMLmind Ebook Compiler to copy to the output HTML page all the elements found in the html:body of the input HTML page pointed to by the href attribute.

Content model

EMPTY

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain content: body.

Example

1
2
3
4
5
6
7
8
9

<chapter>
  <head>
    <title>Using Widget</title>
  </head>
  <body>
    <content href="using1.html"/>
    <content href="using2.html"/>
  </body>
</chapter>

7.8. Element frontmatter

Specifies the front matter of the ebook.

Content model

(toc | index | lot | lof | loe | 
 lox | section)+

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain frontmatter: book.

Children

The following elements occur in frontmatter: index, loe, lof, lot, lox, section, toc.

Example

1
2
3
4
5
6
7
8

<frontmatter>
  <toc/>
  <lof/>
  <lot/>
  <lox/>
  <loe/>
  <section href="intro.html"/>
</frontmatter>

7.9. Element head

Specifies the content of the html:head element of an output HTML page.

By default, this html:head element is simply a copy of the html:head element found in the content “pulled” using the href attribute of a book division. But when a head child element of a book division is specified,

1. Its title child element is used to specify the html:title of the output HTML page.
2. All its other child elements and also all its XHTML5 global attributes are copied to the html:head of the output HTML page.

Content model

(title? , 
 (html:base | html:link | html:meta | html:script | html:style | 
  html:template)*)

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

override

When set to true, the child elements and XHTML5 global attributes found in the head element completely replace the child elements and XHTML5 global attributes found in the html:head element of an input HTML page.

When set to false, the child elements and XHTML5 global attributes found in the head element are merged with the child elements and XHTML5 global attributes found in the html:head element of an input HTML page.

Parents

The following elements contain head: appendices, appendix, book, chapter, part, section.

Children

The following elements occur in head: html:base, html:link, html:meta, html:script, html:style, html:template, title.

Example

Element head is most often used to give a “rich” title to a book division.

1
2
3
4
5
6
7
8
9
10
11
12
13

<appendix href="ssh_key.html">
  <head>
    <title>Generating Your <html:b>SSH</html:b> Public Key</title>

    <html:style>
.error {
    font-weight: bold;
    font-style: italic;
    color: #800000;
}
    </html:style>
  </head>
</appendix>

7.10. Element headcommon

Specifies some common content for the html:head elements of all the output HTML pages.

Note that the XHTML5 global attributes found on element headcommon are also copied to the html:head elements of all the output HTML pages.

Content model

(html:base | html:link | html:meta | html:script | html:style | 
 html:template)*

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain headcommon: book.

Children

The following elements occur in headcommon: html:base, html:link, html:meta, html:script, html:style, html:template.

Example

Element headcommon is typically used to give a common CSS stylesheet to all the output HTML pages.

1
2
3
4
5
6
7

<book>
  <headcommon>
    <html:link href="../resources/styles.css" rel="stylesheet"
               type="text/css"/>
  </headcommon>
  ...
</book>

7.11. Element index

Instructs XMLmind Ebook Compiler to automatically generate an index.

• The language used to automatically sort generated index entries is taken from the xml:lang attribute of the book element.
• An index term is a a element without an href attribute having class attribute containing "role-index-term". See Section 6.8. Index terms.

Content model

EMPTY

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain toc: backmatter, frontmatter.

Example

1
2
3
4

<backmatter>
  <section href="glossary.html"/>
  <index/>
</backmatter>

7.12. Element loe

Instructs XMLmind Ebook Compiler to automatically generate a List of Equations (LOE).

An equation listed in the LOE is a html:figure element having a html:figcaption and a class attribute containing "role-equation". See Section 6.4. Equations.

Content model

EMPTY

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain loe: backmatter, frontmatter.

Example

1
2
3
4
5
6
7
8

<frontmatter>
  <toc/>
  <lof/>
  <lot/>
  <lox/>
  <loe/>
  <section href="intro.html"/>
</frontmatter>

7.13. Element lof

Instructs XMLmind Ebook Compiler to automatically generate a List of Figures (LOF).

A plain figure listed in the LOF is a html:figure having a html:figcaption and no class attribute or a class attribute not containing "role-equation" or "role-example".

Content model

EMPTY

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain lof: backmatter, frontmatter.

Example

1
2
3
4
5
6
7
8

<frontmatter>
  <toc/>
  <lof/>
  <lot/>
  <lox/>
  <loe/>
  <section href="intro.html"/>
</frontmatter>

7.14. Element lot

Instructs XMLmind Ebook Compiler to automatically generate a List of Tables (LOT).

A table listed in the LOT is a html:table having a html:caption.

Content model

EMPTY

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain lot: backmatter, frontmatter.

Example

1
2
3
4
5
6
7
8

<frontmatter>
  <toc/>
  <lof/>
  <lot/>
  <lox/>
  <loe/>
  <section href="intro.html"/>
</frontmatter>

7.15. Element lox

Instructs XMLmind Ebook Compiler to automatically generate a List of Examples (LOX).

An example listed in the LOX is a html:figure element having a html:figcaption and a class attribute containing "role-example". See Section 6.3. Examples.

Content model

EMPTY

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain lox: backmatter, frontmatter.

Example

1
2
3
4
5
6
7
8

<frontmatter>
  <toc/>
  <lof/>
  <lot/>
  <lox/>
  <loe/>
  <section href="intro.html"/>
</frontmatter>

7.16. Element part

Specifies a part —a group of chapters— of the ebook.

Content model

(head? , body? , related* , chapter+)

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain part: book.

Children

The following elements occur in part: body, chapter, head, related.

Example

1
2
3
4
5
6

<part>
  <chapter href="pages/install.html">
    <section href="pages/requirements.html" samepage="true"/>
  </chapter>
  <chapter href="pages/quick_start.html"/>
</part>

7.17. Element related

Instructs XMLmind Ebook Compiler to generate a list of links.

The targets of these links are the book divisions (part, chapter, section, etc) having an xml:id attribute referenced in the ids attribute of the related element.

The default title of this list of links is "Related information". A different title (e.g. "See also") may be specified in attribute relation.

Content model

EMPTY

Attributes

ids

Specifies the IDs of the related book divisions (part, chapter, section, etc). Redundant IDs found in this list are ignored.

relation

Specifies the title of the automatically generated list of links. By default, it's "Related information" translated to the language of the parent element of the automatically generated list of links.

Parents

The following elements contain related: appendices, appendix, book, chapter, part, section.

Example

1
2
3
4
5
6
7

<chapter href="ch01.html" xml:id="ch01">
  <related ids="ch01 ch02 ch03"/>
</chapter>
<chapter href="ch02.html" xml:id="ch02">
  <related ids="ch01 ch02 ch03"/>
</chapter>
...

7.18. Element section

Specifies a section of the ebook.

Content model

(head? , body? , related* , section*)

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain section: appendix, backmatter, chapter, frontmatter, section.

Children

The following elements occur in section: body, head, related, section.

Example

1
2
3
4
5
6

<part>
  <chapter href="pages/install.html">
    <section href="pages/requirements.html" samepage="true"/>
  </chapter>
  <chapter href="pages/quick_start.html"/>
</part>

7.19. Element title

Specifies the “rich” title of a book division (part, chapter, section, etc).

Content model

Element title can contain text and the same XHTML5 child elements as an html:p element (that is,phrasing content: html:b, html:img, etc) in any order and in any number.

Attributes

Other attributes: XHTML5 global attributes, including any attribute having a name starting with "data-".

Parents

The following elements contain title: head.

Children

The following elements occur in title: the same XHTML5 child elements as an html:p element.

Example

1
2
3
4
5

<appendix href="ssh_key.html">
  <head>
    <title>Generating Your <html:b>SSH</html:b> Public Key</title>
  </head>
</appendix>

7.20. Element toc

Instructs XMLmind Ebook Compiler to automatically generate a Table of Contents (TOC).

Content model

EMPTY

Attributes

Other attributes: any attribute having a name starting with "data-".

Parents

The following elements contain toc: backmatter, frontmatter.

Example

1
2
3
4
5
6
7
8

<frontmatter>
  <toc/>
  <lof/>
  <lot/>
  <lox/>
  <loe/>
  <section href="intro.html"/>
</frontmatter>

7.21. Common attributes

href

Specifies the location of an input HTML file. This file must contain valid XHTML5 (more information in Section 6.1. Valid XHTML5). The specified URL may not have a fragment identifier (e.g. something like href="ch09.html#conclusion" is not supported).

pagename

Specifies the base name without any extension of an output HTML file. By default, this name is the same as the name of the corresponding input HTML file. Example:

<chapter href="intro.html" pagename="introduction"/>

By default, without attribute pagename, the page generated for the above chapter would be output_directory/intro.html.

After setting pagename to "introduction", the page generated for the above chapter is output_directory/introduction.html.

samepage

Specifies that the book division (e.g. a section) is to be generated in the same output HTML file as its parent book division (e.g. a chapter). By default, all book divisions are generated by ebookc in their own HTML files. Example:

1 2 3 4

<chapter href="ch1.html"> <section href="ch1/s1.html" samepage="true"/> <section href="ch1/s2.html"/> </chapter>

Attribute samepage="true" instructs ebookc to generate the content of the chapter and the content of the first section in the same HTML file. The second section having an implied samepage="false" is created in its own HTML file.

Note that something like:

1 2 3 4

<chapter href="ch1.html"> <section href="ch1/s1.html"/> <section href="ch1/s2.html" samepage="true"/> </chapter>

is an error because there is no way for ebookc to generate two sibling sections in the same output HTML file.

xml:base

Specifies a base URL which used to resolve the relative URLs found in the ebook specification.

xml:lang

Ignored for any element other than book, for which it specifies the main language of the book.

xml:id

Specifies the unique ID of an element of the ebook specification. Specifying an xml:id attribute is useful in the following cases:

• It is required for a book division to be referenced in a related element. Example:

  1 2 3

  <chapter href="ch1.html" xml:id="ch01"> <related ids="ch01 ch02 ch03" xml:id="rel1"/> </chapter>

• It allows the inclusion of ebook elements using XInclude. In the preceding example, related element "rel1" is defined in first chapter. In the following example, a copy of related element "rel1" is included in the second chapter:

  1 2 3 4

  <chapter href="ch2.html" xml:id="ch02"> <xi:include href="" xpointer="rel1" set-xml-id="" xmlns:xi="http://www.w3.org/2001/XInclude"/> </chapter>

• It may be used to control the IDs generated in the output HTML pages. Example:

  1 2 3

  <chapter href="ch3.html" xml:id="going_further"> <section href="ch3/s1.html" xml:id="requirements" samepage="true"/> </chapter>

  • The html element of the output page containing the chapter will have id="going_further". All the elements “pulled” from "ch3.html" will have their IDs prefixed with "going_further__".
  • The section element containing the section will have id="requirements". All the elements “pulled” from "ch3/s1.html" will have their IDs prefixed with "requirements__".
• Referencing the value of an xml:id attribute in proprietary attribute data-xml-id-ref may be used to create links to locations that do not exist in the input HTML pages, but which will be created in the output HTML pages. Example:

  1 2 3 4 5

  <chapter xml:id="ch04"> <head><title>...</title></head> <section href="ch4/s1.html"/> <section href="ch4/s2.html"/> </chapter>

  In input HTML page "ch4/s2.html", you may refer to the first section of the chapter by writing <a href="s1.html"/>. But how to refer to the chapter itself? Notice that this chapter has no input HTML page to refer to.

  The solution to this problem is to add proprietary attribute data-xml-id-ref to an a element. For the above example, it's <a data-xml-id-ref="ch04"/>.

  Note that writing <a href="s1.html" data-xml-id-ref="ch04"/> is an even better option because href="s1.html" is used as a fallback link target in case xml:id="ch04" is not defined in the ebook specification.

Any XHTML5 global attribute, including any attribute having a name starting with "data-"

These attributes (e.g. class, dir, lang, onclick, style) are copied to the output HTML element corresponding to the book division. Example: the output HTML element corresponding to the following appendix:

<appendix href="a2.html" samepage="true" class="disclaimer" lang="fr-FR"/>

is:

<html:section class="role-appendix disclaimer" lang="fr-FR"/>

Specifying an id attribute for a book division is likely to cause broken links in the output HTML files.

10.1. Parameters of the XSLT stylesheets used to convert an ebook specification to EPUB

10.2. Parameters of the XSLT stylesheets used to convert an ebook specification to Web Help

Parameters starting with "wh-" are pseudo-parameters. They may or may not be passed to the XSLT stylesheets, but the important thing to remember is that they are also interpreted by ebookc itself. Consequently you cannot specify them in an XSLT stylesheet which customizes the stock ones.

body {
    ...
    --navigation-width: 33%;
    ...
} 

#wh-navigation {
    ...
    width: var(--navigation-width); 
    ...
}

-p wh---navigation-font-family inherit¬
-p wh---navigation-font-size inherit¬
-p wh---navigation-color inherit¬
-p wh---navigation-background-color inherit

-p wh-user-header¬
wh_resources/header.html
-p wh-user-footer¬
wh_resources/footer.html
-p wh-user-css¬
wh_resources/header_footer.css
-p wh-user-resources¬
wh_resources/header_footer_files

-p wh-user-header¬
wh_resources/header.html
-p wh-user-footer¬
wh_resources/footer.html
-p wh-user-css¬
wh_resources/header_footer.css
-p wh-user-resources¬
wh_resources/header_footer_files