7.20. Element toc7.21. Common attributes (49/59)Chapter 8. How it works

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