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 [1] 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:

<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:

<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:

<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:

<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:

...
<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:

...
<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.

[1] Other than an input HTML page of course.