# Files in the book directory

If you run the command $ `publican create --name Test_Book --lang en-US`, Publican creates a directory structure and required files, similar to the following:

- `publican.cfg`

- `en-US` (directory)

  - `Test_Book.xml`

  - `Test_Book.ent`

  - `Revision_History.xml`

  - `Preface.xml`

  - `Chapter.xml`

  - `Book_Info.xml`

  - `Author_Group.xml`

  - `images` (directory)

    - `icon.svg`

## The publican.cfg file

### Note — Customizing output

If you maintain multiple versions of a document, you can create a configuration file for each version. When building or packaging the document, you can use the `--config` to specify a configuration file other than the `publican.cfg` file and therefore a different set of parameters to use in a particular build. For example:

    $ publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg

The `publican.cfg` file configures build options, and is located in the root of the book directory. The following is an example `publican.cfg` file, with a description of `publican.cfg` parameters following afterwards:

### Default parameters

`xml_lang`

  specifies the language of the source XML files, for example, `en-US`, as set by the `--lang` option for $ `publican create`.

`type`

  specifies the type of document — a DocBook `<article>`, DocBook `<book>`, or DocBook `<set>`, as set by the `--type` option for $ `publican create`.

`brand`

  sets the brand of the document, for example, `RedHat`, `fedora`, `JBoss`, `oVirt` or `GIMP` , as set by the `--brand` option for $ `publican create`. If you do not specify a brand, Publican uses its default brand. Refer to for more information.

### Advanced parameters

`arch`

  filters output by computer architecture. For example, if you set `arch: x86_64` in the `publican.cfg` file, Publican will only include XML elements tagged with the equivalent attribute, such as `<para arch="x86_64">`.

  ### Use with caution

  As with conditional tagging more generally, `arch` can cause great difficulties when translating documents. Refer to for an explanation of the issues.

  ### arch set for root nodes

  If the root node of an XML file is excluded by the `arch` attribute, your document will not build, because empty files are not valid XML. For example, if `Installation_and_configuration-PPC.xml` contains a single chapter:

      <?xml version='1.0' encoding='utf-8' ?>
      <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
      ]>
      <chapter id="chap-Installation_and_configuration_on_PowerPC" arch="PowerPC">
      <title>Installation and configuration on PowerPC</title>

      [text of chapter]

      </chapter>

  and this chapter is included in `User_Guide.xml` with an `<xi:include>` tag, the document will not build with $ `condition: x86` set in the `publican.cfg` file.

  To exclude this chapter, add the `arch` attribute to the `<xi:include>` tag in `User_Guide.xml`, not to the `<chapter>` tag in `Installation_and_configuration-PPC.xml`.

  ### xrefs and the arch attribute

  If an `<xref>` points to content not included in the build due to the `arch` attribute, the build will fail. For example, with `arch: x86` set in the `publican.cfg` file, $ `publican build --formats=pdf --langs=en-US` will fail if the book has the tag `<xref linkend="Itanium_installation">` pointing to `<section id="Itanium_installation" arch="IA64">`.

`books`

  specifies a space-separated list of books used in a remote set. Refer to for more information on distributed sets.

`brew_dist`

  specifies the build target to use for building the desktop RPM package in Brew, Red Hat's internal build system. This parameter defaults to `docs-5E`. Refer to and for more information on building RPM packages.

`bridgehead_in_toc`

  specifies whether the contents of `<bridgehead>` elements (free-floating titles) should be included among other titles (such as section titles and chapter titles) in tables of contents. To enable this feature, set `bridgehead_in_toc: 1`. Otherwise, the parameter defaults to `0`, and `<bridgehead>`s are not included in tables of contents.

`chunk_first`

  controls whether the first section should appear on a new page when rendered in HTML. To make the first section appear on a new HTML page, set this parameter to `chunk_first: 1`. Otherwise, the parameter defaults to `0`, and the first section appears on the same page of its chapter.

`chunk_section_depth`

  controls the section depth at which Publican no longer splits sub-subsections onto a new page when rendering HTML. By default, this value is set to `4`.

  ### Controlling the section depth with chunk_section_depth

  chunk_section_depth: 0

    no section split. All sections with their sub-sections appear on the same page of the chapter they belong. The page succession is chapter 1, chapter 2, chapter 3, …

  chunk_section_depth: 1

    the split is at "level 1" section. Each level section one with its sub-sections, appear on a new page. The page succession is chapter 1, 1.2, 1.3, 1.4 … chapter 2, 2.1, 2.2, 2.3 …

  chunk_section_depth: 2

    the split is at "level 2" section. The page succession is chapter 1, 1.2, 1.2.2, 1.2.3, 1.2.4 … 1.3, 1.3.2, 1.3.3 …

  chunk_section_depth: 3

    the split is at "level 3" section. The page succession is chapter 1, 1.2, 1.2.2, 1.2.2.2, 1.2.2.3, 1.2.2.4 … 1.3, 1.3.2, 1.3.2.2, 1.3.2.3 …

  chunk_section_depth: 4 (default)

    the split is at "level 4" section. The page succession is chapter 1, 1.2, 1.2.2, 1.2.2.2, 1.2.2.2.2, 1.2.2.2.3, 1.2.2.2.4 … 1.2.3, 1.2.3.2, 1.2.3.2.2, 1.2.3.2.3 …

`classpath`

  sets the path to the Java archive (jar) files for FOP. Publican relies on Apache FOP — a Java application — to render documents as PDF files. The default path for FOP's jar files on a computer with a Linux operating system is: `/usr``/share``/java``/ant``/ant-trax-1.7.0.jar:``/usr``/share``/java``/xmlgraphics-commons.jar:``/usr``/share``/java``/batik-all.jar:``/usr``/share``/java``/xml-commons-apis.jar:``/usr``/share``/java``/xml-commons-apis-ext.jar`

`common_config`

  sets the path to the Publican installation. The default location on a computer with a Linux operating system is `/usr/share/publican`. On a computer with a Windows operating system, the default location is `%SystemDrive%/%ProgramFiles%/publican` — most usually `C:/Program Files/publican`.

`common_content`

  sets the path to the Publican common content files. These files provide default formatting, plus some boilerplate text and generic graphics. The default location on a computer with a Linux operating system is `/usr/share/publican/Common_Content`. On a computer with a Windows operating system, the default location is `%SystemDrive%/%ProgramFiles%/publican/Common_Content` — most usually `C:/Program Files/publican/Common_Content`.

`condition`

  specifies conditions on which to prune XML before transformation. Refer to for more information.

`confidential`

  marks a document as confidential. When this parameter is set to `1`, Publican adds the text specified by the `confidential_text` parameter (by default, `CONFIDENTIAL`) to the foot of each HTML page and the head of every page in a PDF document. The default value is `0` (no header or footer).

`confidential_text`

  specifies the text to use when the `confidential` parameter is set to `1`. The default text is `CONFIDENTIAL`.

`debug`

  controls whether Publican should display debugging messages as it works. When set to its default of `0`, Publican does not display debugging messages. Change this value to `1` to view these messages.

`def_lang`

  sets the default language for a Publican-managed website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available. Refer to .

`doc_url`

  provides a URL for the documentation team for this package. In HTML output, Publican links to this URL at the top right of each page, through the `image_right.png` image in the `Common_Content/images` directory for the brand. This parameter defaults to `https://fedorahosted.org/publican`

`docname`

  specifies the document name. If set, this value overrides the content of the `<title>` tag in the `Book_Info.xml` file when you package a document. This value must contain only upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).

`dt_obsoletes`

  a package that a desktop package obsoletes.

`dt_requires`

  a package that the desktop package requires, for example, a documentation menu package. Refer to .

`dtdver`

  specifies the version of the DocBook XML Document Type Definition (DTD) on which this project is based. Publican defaults to version 4.5. The specification for DocBook XML DTD version 4.5 is available from `http://www.docbook.org/specs/docbook-4.5-spec.html`.

  ### A different DTD might slow your build

  When you install Publican, you also install a local copy of the DocBook XML DTD version 4.5 and accompanying Extensible Stylesheet Language (XSL). If you set a version of the DTD for which there is no local support, Publican must download the appropriate DTD and XSL from an online source every time that it builds the document. Building your document is delayed while this download takes place. The combined size of the required files is around 70 MB.

`dtd_type`

  Override Type for DocType. Must be a complete string.

  This parameter is only permitted in a brand.

`dtd_uri`

  Override URI for DocType. Must be a complete string.

  This parameter is only permitted in a brand.

`ec_id`

  sets the ID for an Eclipse help plugin. Every Eclipse help plugin must have a unique ID, and these generally follow Java package naming conventions — refer to `http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html`. By default, Publican sets the ID to org.product.docname. The ID that you set here also determines the directory name for this plugin in the `plugin` directory.

`ec_name`

  sets the name of an Eclipse help plugin. This is the human-readable name visible in the help list in Eclipse. This name does not need to be unique or to follow a special convention. By default, Publican sets the name to product docname.

`ec_provider`

  sets the provider name for an Eclipse help plugin. This should be your name, or the name of your project or organization. This name is presented to users and does not need to be unique or follow a special convention. By default, Publican sets the provider name to Publican-Publican version.

`edition`

  specifies the edition number for this document.

  The `<edition>` tag was required by versions of Publican prior to 2.0, which used it to generate the version of a documentation package. This tag is now completely optional and does not affect packaging in any way.

`extras_dir`

  the directory Publican will process extra files from. (Default: `extras`)

`footer`

  specifies content that will be injected into the bottom of every page on the site.

`generate_section_toc_level`

  controls the section depth at which Publican will generate a table of contents. At the default value of `0`, Publican will generate tables of contents at the start of the document and in parts, chapters, and appendixes, but not in sections. If (for example) the value is set to `1`, tables of contents also appear in each "level 1" section, such as sections 1.1, 1.2, 2.1, and 2.2. If set to `2`, tables of contents also appear in "level 2" sections, such as sections 1.1.1, 1.1.2, and 1.2.1.

  ### Setting the section depth at which tables of contents appear

  generate_section_toc_level: 0 (default)

    Publican will generate tables of contents at the start of the document and in parts, chapters, and appendixes, but not in sections.

  generate_section_toc_level: 1

    Publican will generate tables of contents also at the start of each "level 1" section, such as sections 1.1, 1.2 … 2.1, 2.2 …

  generate_section_toc_level: 2

    Publican will generate tables of contents also at the start of each "level 2" section, such as as sections 1.1.1, 1.1.2. 1.1.3 … 1.2.1., 1.2.2, 1.2.3 …

`ignored_translations`

  specifies translations to ignore as comma-separated XML language codes; for example, `es-ES,it-IT`. If you build or package a book for a language filtered by this parameter, Publican ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to , and to .

`img_dir`

  the directory Publican will process images from. (Default: `images`)

`info_file`

  overrides the default Info file. Specifies where Publican looks for info fields. Use the full filename without the path.

`license`

  specifies the license this package uses. By default, Publican selects the GNU Free Documentation License (GFDL). Refer to .

`mainfile`

  specifies the name of the XML file in your document that contains the root XML node `<article>`, `<book>`, or `<set>`, and the name of the corresponding `.ent` file that contains the document's entities. For example, if you set `mainfile: master`, Publican looks for the root XML node in `master.xml` and the document entities in `master.ent`.

  If `mainfile` is not set, Publican looks for the root XML node in a file that matches the `<title>` of the document set in the `Article_Info.xml`, `Book_Info.xml`, or `Set_Info.xml` file, and looks for the document entities in a file with a corresponding name.

`menu_category`

  the desktop menu category (as defined by a corresponding `.menu` file) in which a document should appear when installed from a desktop RPM package. Refer to .

`os_ver`

  specifies the operating system for which to build packages. Publican appends the value that you provide here to the RPM packages that it builds. For example, `.fc15` for Fedora 15. The default value is `.el5`, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to and .

`prod_url`

  provides a URL for the product to which this document applies. In HTML output, Publican links to this URL at the top left of each page, through the `image_left.png` image in the `Common_Content/images` directory for the brand. This parameter defaults to `https://fedorahosted.org/publican`.

`product`

  specifies the product to which this documentation applies. If set, this value overrides the content of the `<productname>` tag in the `Book_Info.xml` file when you package a document. This value must include only contain upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).

`release`

  specifies the release number of this package. If set, this value overrides the value of `<pubsnumber>` in the `Book_Info.xml` file when you package a document. This value must include only digits (‘0’–‘9’).

`repo`

  specifies the repository from which to fetch remote books that form part of a distributed set. Refer to .

`rev_dir`

  override the default Revision History file direction. By default Publican assumes the Revision History is sorted in descending order, newest versions at teh top, if you wish to change this and have the oldest revisions at the top, then set this parameter to `asc` or `ascending`.

`rev_file`

  override the default Revision History file. Specifies where Publican looks for revision fields. Use the full filename without the path. When combined with the Publican action add_revision, it enables you to build a book without a `Revision_History.xml`.

`scm`

  specifies the version control (or source code management) system used in the repository in that stores the remote books in a distributed set. At present, Publican can use only Subversion (SVN), and therefore uses `SVN` as its default setting. Refer to .

`show_remarks`

  controls whether to display DocBook `<remark>`s in transformed output. By default, this value is set to `0`, which causes Publican to hide remarks. Set this value to `1` to display remarks. In Publican's `common` brand, displayed remarks are highlighted in magenta.

`sort_order`

  override the default sort weighting for books in a Publican website. Books are displayed on the website in descending sort order. For example, a book with sort order 10 appears before a book with sort order 5. By default, this value is set to 50.

`src_url`

  specifies the URL at which to find tarballs of source files. This parameter provides the `Source:` field in the header of an RPM spec file. Refer to .

`tmp_dir`

  specifies the directory for Publican output. By default, this is set to `tmp`, which creates a directory named `tmp` inside the directory that holds your article or book.

`tmpl_path`

  specifies the path to Publican templates. By default, this is set to `/usr/share/publican/templates`.

`toc_js`

  allows a site to override the template used when building the embedded toc using in web_style=1 sites. The template must be in the same directory that `toc.tmpl` is in. The template name must be must be of the form toc_type+.tmpl

`toc_type`

  specifies the name of a custom TOC template. By default, Publican looks for `toc-$toc_type.tmpl` in `/usr/share/publican/templates`. You can override this by setting an alternative path with `tmpl_path`.

`toc_section_depth`

  controls the depth of sections that Publican includes in the main table of contents. By default, this value is set to `2`. With the default setting, sections 1.1 and 1.1.1 will appear in the main table of contents, but section 1.1.1.1 will not. (Note that the first digit in these examples represents a chapter, not a section).

  ### Controlling the depth of sections in the main table of contents

  toc_section_depth: 0

    Publican will generate a main table of contents only for chapters.

  toc_section_depth: 1

    Publican will generate a main table of contents only for chapters and "level 1" sections, such as 1, 1.1, 1.2, 1.3 … 9, 9.1, 9.2 … but not for sections 1.1.1, 1.1.2 …

  toc_section_depth: 2 (default)

    Publican will generate tables of contents for chapters and "level 1 and "level 2" sections, such as 1, 1.1, 1.1.1, … 1,2, 1.2.1, 1.2.2 … but not for deeper sections x.x.x.x .

`version`

  specifies the version number of that product to which this document applies. If set, this value overrides the content of the `<productnumber>` tag in the `Book_Info.xml` file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).

`web_brew_dist`

  specifies the brew build target to use for building the web RPM packages. Brew is the internal build system used by Red Hat. By default, this value is set to `docs-5E`, representing documentation packages for Red Hat Enterprise Linux 5. Refer to .

`web_formats`

  a comma-separated list of formats to include in the web RPM package. Refer to .

`web_home`

  specifies that the document is the home page of a documentation website, not a standard document. Refer to .

  ### Important — `web_home` is deprecated

  In Publican 2.2, `web_home` is replaced by `web_type: home`. Support for `web_home` will be removed in a future version of Publican.

`web_name_label`

  overrides the book name as it appears on the menu of a Publican-managed website. Refer to .

`web_obsoletes`

  specifies packages that the web RPM obsoletes. Refer to .

`web_product_label`

  overrides the product name as it appears on the menu of a Publican-managed website. Refer to .

`web_style`

  sets the web style, which determines the layout and presentation of the website. Valid values are `1` and `2`. Style 1 features a navigation pane at the left side of the screen that provides access to all of the documents on the site. Style 2 offers a breadcrumb-like navigation system.

`web_type`

  specifies that the document is descriptive content for a Publican-managed website rather than product documentation. This content includes the home page of the website (`web_type: home`), product description pages (`web_type: product`), and version description pages (`web_type: version`). Refer to .

`web_version_label`

  overrides the version number as it appears on the menu of a Publican-managed website. Set this value to `UNUSED` for general documentation that does not apply to any particular version of a product. Refer to .

`wkhtmltopdf_opts`

  Extra options to pass to wkhtmltopdf. e.g. `wkhtmltopdf_opts: "-O landscape -s A3"`

### Help from the command line

Run the $ `publican help_config` command in the root directory of a book for a summary of these parameters.

## Book_Info.xml

### `Article_Info.xml` and `Set_Info.xml`

This description of the `Book_Info.xml` file applies to `Article_Info.xml` and `Set_Info.xml` files too. However, for the sake of simplicity, the file is referred to as `Book_Info.xml` throughout this section.

The `Book_Info.xml` file contains the key metadata concerning a book: the book's ID; title; subtitle; author and edition number. It also contains the name and version of the product that is documented, and an abstract.

Aside from constituting much of a book's front matter, this metadata is also used when building books as RPM packages. Usually, if you distribute a book as an RPM package, several of the tags included by default in `Book_Info.xml` must have appropriate data within them, and that data must conform to the requirements of the RPM format. You can override the data in these tags by using equivalent fields in the `publican.cfg` file, as discussed in this section.

Unless overridden in the `publican.cfg` file, data from seven of the default tags in `Book_Info.xml` is required to build books as RPMs. Most immediately, the file name of a book built as an RPM package is constructed as follows:

`productname-title-productnumber-language-edition-pubsnumber.src.rpm`

Everything but language above is pulled from `Book_Info.xml` — you specify language when you build the book. As well, the `<subtitle>` and `<abstract>` are used in the RPM spec file, to provide the `Summary:` field in the header and the `%description` field, respectively.

An example `Book_Info.xml` file, for the `Test_Book` book, is presented below. Details regarding this file, and what the RPM format requirements are for each tag, follow.

`<bookinfo id="book_id">`
`<articleinfo id="article_id">`
`<setinfo id="set_id">`

  The document ID is used internally and is not displayed to readers when the book is built. If you run the $ `publican clean_ids` command, any manually entered ID, including this one, changes to a Doc_Name-Title format, where Title is the title of the associated book, article, section, or chapter.

`<productname>productname</productname>`

  The name of the product or product stream to which the book, article, or set applies, for example: `Red Hat Enterprise Linux` or `JBoss Enterprise Application Platform`. When building a book as an RPM package, data in the `<productname>` tag is used as part of the file name of the package.

  Override this tag with the `product` variable in the `publican.cfg` file if the name of your product contains non-Latin characters, accented Latin characters, or punctuation marks other than the underscore.

`<title>title</title>`

  The title of the document (for example, `<title>Server Configuration Guide</title>`). The title appears under the product name in both HTML and PDF editions. A title is required to build an RPM package. When building a book as an RPM package the title is used as the part of the file name of the package.

  The names of RPM packages can only contain certain basic ASCII characters. If the title of your document contains non-Latin characters, accented Latin characters, or punctuation marks other than the underscore, use the `docname` parameter in the `publican.cfg` file to set a name for the document in ASCII characters. When you build the document, the title appears as you set it with the `<title>` tag, but when you package the document, the value that you used in the `docname` parameter is used in the file name of the RPM package.

  By default, Publican also uses the contents of the `<title>` tag to find the file that contains the root XML node: `<article>`, `<book>`, or `<set>`. For example, if you set the title to `<title>Server Configuration Guide</title>`, Publican expects the root XML node to be in a file named `Server_Configuration_Guide.xml` and the document entities to be in a file named `Server_Configuration_Guide.ent`. To use a different name for these files, set the `mainfile` parameter in the document configuration file (by default, `publican.cfg`). Refer to .

`<subtitle>subtitle</subtitle>`

  The book's subtitle: an alternative, and commonly explanatory title for the book (for example: Server Configuration Guide: Preparing Red Hat Enterprise Linux for Production Use). The subtitle appears under the title in both HTML and PDF editions. A subtitle is also required to make a book available as an RPM package. When building a book as an RPM package, the subtitle is used as the `Summary` in the RPM spec file. The `rpm -qi` command returns the contents of several spec file fields, including the `Summary` field.

`<productnumber>productnumber</productnumber>`

  The version number of the product the book covers, for example ‘5.2’ for Red Hat Enterprise Linux 5.2 and ‘4.3’ for JBoss EAP 4.3.

  Running the $ `publican create --name Doc_Name --version version` command correctly configures the product number.

  Override this tag with the `version` variable in the `publican.cfg` file if the product version is anything other than a number.

`<edition>edition</edition>`

  This is the edition number of the book. The first edition of the book should be 1.0 (unless you use 0.x for pre-release versions of a book). Subsequent editions should increment the 1.x to indicate to readers that the book is a new edition. The edition changes the version number in the file name when building a book with the $ `publican package` command.

  For example, setting the edition to `1.2` and building the book using the $ `publican package --binary --lang=en-US` command creates an RPM file named `productname-title-productnumber-en-US-1.2-0.src.rpm`.

  Running the $ `publican create --name Doc_Name --edition x.y` command correctly configures the edition.

  Override this tag with the `edition` variable in the `publican.cfg` file if the edition of your document is identified by anything other than a number.

`<pubsnumber>pubsnumber</pubsnumber>`

  The pubsnumber sets the release number (the last digit in the file name) when building a book with the $ `publican package` command. For example, setting the pubsnumber to `1` and building the book using the `publican package --binary --lang=en-US` command creates an RPM file named `productname-title-productnumber-en-US-edition-1.src.rpm`.

  Override this tag with the `release` variable in the `publican.cfg` file if the release number of your document contains anything other than whole numbers.

`<abstract><para>abstract</para></abstract>`

  A short overview and summary of the book's subject and purpose, traditionally no more than a paragraph long. The abstract appears before the table of contents in HTML editions and on the second page of PDF editions. When a book is built as an RPM package, the abstract sets the `Description` field of the RPM's spec file. This makes the abstract for a package available via the `rpm -qi` command.

You can add extra metadata to the `Book_Info.xml` file of a document, to support specific features in various output formats:

`<keywordset>`
`<keyword>`

  Terms tagged with `<keyword>` and placed within a `<keywordset>` are added to a `<meta name="keywords">` entry in the head of HTML files and to the `Keywords` field of the properties of a PDF document.

`<subjectset>`
`<subject>`

  Terms tagged with `<subject>` and placed within a `<subjectset>` are added to the `Subject` field of the properties of a PDF document and in the metadata of an ebook in EPUB format.

  Consider using a controlled vocabulary when defining the subject of your document, for example, the Library of Congress Subject Headings (LCSH). Identify the chosen vocabulary with the `scheme` attibute in the `<subjectset>` tag, for example, `<subjectset scheme="libraryofcongress">`. You can search for LCSH subject headings through the Library of Congress Authorities & Vocabularies page: `http://id.loc.gov/authorities/search/`.

`<mediaobject role="cover" id="epub_cover">`

  Use a `<mediaobject>` tag with the `role="cover"` and `id="epub_cover"` attributes to set cover art for an ebook in EPUB format. For example:

      <mediaobject role="cover" id="epub_cover">
      	<imageobject role="front-large" remap="lrg">
      		<imagedata width="600px" format="PNG" fileref="images/front_cover.png"/>
      	</imageobject>
      	<imageobject role="front" remap="s">
      		<imagedata format="PNG" fileref="images/front_cover.png"/>
      	</imageobject>
      	<imageobject role="front-small" remap="xs">
      		<imagedata format="PNG" fileref="images/front_cover.png"/>
      	</imageobject>
      	<imageobject role="thumbnail" remap="cs">
      		<imagedata format="PNG" fileref="images/front_cover_thumbnail.png"/>
      	</imageobject>
      </mediaobject>

  As with all the other images in your document, place the cover images in the `images` subdirectory.

### RPM packages, editions, impressions and versions

As noted above, the default `Book_Info.xml` used by Publican includes an `<edition>` tag.

If you distribute a book as an RPM package, the data placed within this tag sets the first two digits of the version number in the RPM file name.

So, an edition of '1.0' becomes a version of '1.0'.

`Book_Info.xml` also includes the `<pubsnumber>` tag. Any data placed within this tag changes the release number of RPM-packaged books.

A book with an edition of 1.0 and a pubsnumber of 5, would be version 1.0, release 5 (1.0-5).

The edition and pubsnumber are not tied to the `<productnumber>` tag also found in `Book_Info.xml`: `<productnumber>` denotes the version number of the product being documented or otherwise written about.

It is entirely possible to have a 2nd edition of a book pertaining to a particular version of a product.

In bibliography, two copies of a book are the same edition if they are printed using substantially the same type-set master plates or pages. ('Substantially' offers some allowance for typo corrections and other inconsequential changes.)

Book collectors routinely conflate 'first edition' with 'first print run', while bibliographers pay attention to the text commonly placed in the front matter of a book, which calls a 2nd print run off the same (or substantially the same) plates a '1st edition, 2nd impression' or '1st edition, 2nd printing'.

We recommend following bibliographic practice in this regard. When using Publican to re-publish a book from 'substantially the same XML', increment the `<pubsnumber>` tag, not the `<edition>` tag. It functions as a near-equivalent to the impression or printing number of traditional publishing.

As for changing the edition number, we recommend changing this in the same circumstances traditional publishers change the edition of a work: when it is revised and re-written significantly. What constitutes significant, and how much re-writing is needed to increment an edition number by a whole number and how much is needed to increment it by one-tenth of a whole number, is a matter of editorial discretion.

## Author_Group.xml

`Author_Group.xml` is not required but is the standard place to record author, editor, artist and other credit details. The following is an example `Author_Group.xml` file:

`Author_Group.xml` does not have to contain all of the above information: include as much or as little as required.

## Chapter.xml

### Articles and chapters

DocBook articles cannot contain chapters. If you use the `--type=article` option with $ `publican create`, Publican does not create a `Chapter.xml` file. Use sections to organize content within articles.

Refer to DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner available at `http://www.docbook.org/tdg/en/html/docbook.html` for details of the different ways that sets, books, articles, parts, chapters, and sections interact. In particular, note that articles can be stand-alone documents, or can be incorporated into books.

The `Chapter.xml` file is a template for creating chapter files. Chapter files contain the content that make up a book. The following is a chapter template (`Chapter.xml`) that is created by the $ `publican create` command. Note the `DOCTYPE` is set to `chapter`:

This chapter has two sections, `Section 1 Test` and `Section 2 Test`. Refer to `http://docbook.org/tdg/en/html/chapter.html` for further information about chapters.

### Note

The chapter file should be renamed to reflect the chapter subject. For example, a chapter on product installation could be named `Installation.xml`, whereas a chapter on setting up a piece of software would be better called `Setup.xml` or `Configuration.xml`.

## Doc_Name.xml

The `Doc_Name.xml` file contains `xi:include` directives to include the other necessary XML files for the document, including chapters or sections contained in other XML files. For example, a book's `Doc_Name.xml` file brings together chapters that are contained in separate XML files.

The following is an example `Doc_Name.xml` file that describes a DocBook book — note the `DOCTYPE` is set to `book`.

### A DocBook book

This example loads the `Book_Info.xml`, `Preface.xml`, `Chapter.xml`, and `Appendix.xml` XML files.

### Important

The order in which chapters are listed matters. When this example book is built, `Book_Info.xml` will precede `Preface.xml` which will precede `Chapter.xml`, and so on.

The `Doc_Name.xml` file is not limited to using `xi:include` directives. You can create documents with a single XML file. The following is an example of a book created using a single XML file:

    <book>

    <chapter>
    <title>Chapter 1</title>
    <para>
    	A paragraph in Chapter 1.
    </para>
    <section id="section1">
    <title>Chapter 1 Section 1</title>
    	<para>
    		A paragraph in Section 1.
    	</para>
    </section>
    <section id="section2">
    <title>Chapter 1 Section 2</title>
    	<para>
    		A paragraph in Section 2.
    	</para>
    </section>
    </chapter>

    <chapter>
    <title>Chapter 2</title>
    <para>
    	A paragraph in Chapter 2.
    </para>
    </chapter>

    </book>

This book contains two chapters. Chapter one contains two sections. Refer to `http://docbook.org/tdg/en/html/section.html` for further information about sections, and `http://docbook.org/tdg/en/html/book.html` for further information about books.

## Doc_Name.ent

The `Doc_Name.ent` file is used to define local entities. The `YEAR` and `HOLDER` entities are used for copyright information. By default, Publican sets `YEAR` to the current year, and inserts a message into `HOLDER` to remind you to specify the copyright holder for the document. If the `YEAR` and `HOLDER` entities are missing altogether, the document will not build.

Other entities might be required by the brand applied to your document. For example, the Publican brand for Fedora documents uses the entity `BOOKID` to specify how readers should refer to a document when they submit feedback about it.

## Revision_History.xml

The $ `publican package` command searches for the first XML file in the document's XML directory containing a `<revhistory>` tag. Publican then uses that file to build the RPM revision history.