⁠Chapter 4. Creating a document

This chapter describes creating books and articles: the main configuration files, example document files, and how to build a document.

Use the $ publican create command to create a new document, including all the necessary files for the document.

The $ publican create command accepts several options, detailed in this chapter. When an option can accept a value, separate the option from the value with a space or an equals sign; for example, publican create --name New_Book or publican create --name=New_Book.

--help: print a list of all $ publican create command options.
--name Doc_Name: set Doc_Name as the name of the book or article. This variable must not contain any spaces. For example, the command $ create_book --name Test_Book creates a book named Test_Book with all the necessary files to build the book, and sets the BOOKID in the Test_Book.ent file.
--lang Language_Code: set Language_Code as the language code of the language in which the book or article will be authored. If you do not specify a language code, Publican defaults to en-US (American English). The --lang option sets the xml_lang in the publican.cfg file and creates a directory with this name in the document directory. When initially created, this directory contains some boilerplate XML files. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters and Appendix G, Language codes for more detail on language codes.
--version version: set version as the version number of the product that the book describes. For example, for Red Hat Enterprise Linux 5.1 you would use 5.1. The default version is 0.1. The --version option sets the <productnumber> tag in the Book_Info.xml or Article_Info.xml file. For more information refer to Section 4.1.2, “Book_Info.xml”.
--edition edition: set edition as the edition number of the book. This number indicates to users when a new edition of the book is released. The initial general availability (GA) release of the book should be edition 1.0. The default value is 0. The --edition option sets the <edition> tag in the Book_Info.xml or Article_Info.xml file. For more information refer to Section 4.1.2, “Book_Info.xml”.
--product Product_Name: set Product_Name as the name of the product that the book describes. This variable must not contain any spaces. For example, set this to Fedora for core Fedora documentation, and the name of the product for other products, for example, Fedora_Directory_Server. The default value is Documentation. The --product option sets the <product name> tag in the Book_Info.xml file or Article_Info.xml file and the PRODUCT entity in the Doc_Name.ent file.
--type Article --name Article_Name: create an article instead of a book. Replace Article_Name with the article name. This variable must not contain any spaces. The --type option sets the type in the publican.cfg file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters.
--type Set --name Set_Name: create a set of documents instead of a book. Replace Set_Name with the set name. This variable must not contain any spaces. The --type option sets the type in the publican.cfg file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters and to Chapter 6, Using sets for details on using sets.
--brand brand: set brand as the brand to use to style the output of this document, for example, RedHat, fedora, JBoss, oVirt, or GIMP. The default value is common, a default brand shipped with Publican. The --brand option sets the brand parameter in the publican.cfg file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters. This option requires the appropriate Publican brand package to be installed. For example, to build Red Hat branded books, you must install the publican-redhat package. Refer to Section 5.1, “Installing a brand” for instructions on installing brand packages for Publican. If you do not specify a brand, Publican uses its built-in, default brand. Refer to Chapter 5, Branding for more information.

Before running the $ publican create command, use the $ cd command to change into the directory where you want the book to be created. For example, to create a book named Test_Book in the my_books/ directory, run the following commands:

$ cd my_books/ 
$ publican create --name Test_Book

To see the results of this command on a computer with a Linux operating system, run the following:

$ ls

The output should be similar to the following:

Test_Book/

To see the contents of the new Test_Book/ directory on a computer with a Linux operating system, run the following:

$ cd Test_Book/
$ ls

The output should be similar to the following:

en-US/ publican.cfg

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

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

# Config::Simple 4.59
# Wed Jul 18 13:00:40 2012

xml_lang: "en-US"
type: Book
brand: common

⁠

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 Chapter 5, Branding 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 Section 4.9.1, “Conditional tagging and translation” 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 Section 6.2, “Distributed sets” 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 Section 4.8.2, “The $ publican package command” and Section 5.4, “Packaging a brand” 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.

⁠

Example 4.1. 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 Section 4.9, “Conditional tagging” for more information.

Root nodes and conditional tagging

If the root node of an XML file is excluded with a conditional, your document will not build, because empty files are not valid XML. For example, if Installation_and_configuration_on_Fedora.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_Fedora" condition="Fedora">
<title>Installation and configuration on Fedora</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: Ubuntu set in the publican.cfg file.

To exclude this chapter, add a condition to the <xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration_on_Fedora.xml.

xrefs and conditional tagging

If an <xref> points to content not included in the build due to conditional tagging, the build will fail. For example, with $ condition: upstream set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection"> pointing to <section id="betasection" condition="beta">.

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 Section 4.8, “Packaging a document”.

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 Section 4.8.1.3, “Desktop menu entries for documents”.

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.

Note

This parameter is only permitted in a brand.

dtd_uri

Override URI for DocType. Must be a complete string.

Note

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.

Note

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.

⁠

Example 4.2. 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 Section 4.6, “Translating a document”, and to Appendix G, Language codes.

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 Section 4.8, “Packaging a document”.

max_image_width

specifies the maximum width allowable for images in the document in pixels. By default, Publican scales down any images wider than 444 pixels so that they fit within this limit. Keeping images no wider than 444 pixels ensures that they present no wider than the right-hand margin of the text in HTML output and that they fit within the pages of PDF output. Refer to Section 4.2, “Adding images” for more information on using images.

Important — 444 pixels is the maximum safe width

Do not use the max_image_width parameter if your images contain important information. Images wider than 444 pixels presented at their full size might lead to poorly presented HTML and to PDF output that it is unusable because the images have run off the page and are incomplete.

Conversely, images wider than 444 pixels that are scaled down in a web browser to fit the HTML container or in a PDF viewer to for a page lose quality.

To safeguard the quality of your images, crop them or scale them so that they are no wider than 444 pixels before you include them in a document.

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 Section 4.8.1.3, “Desktop menu entries for documents”.

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 Section 4.8, “Packaging a document” and Section 5.4, “Packaging a brand”.

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 Section 6.2, “Distributed sets”.

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 Section 6.2, “Distributed sets”.

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 Section 4.8, “Packaging a document”.

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

⁠

Example 4.3. 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 Section 4.8, “Packaging a document”.

web_formats

a comma-separated list of formats to include in the web RPM package. Refer to Section 4.8.2, “The $ publican package command”.

web_home

specifies that the document is the home page of a documentation website, not a standard document. Refer to Chapter 7, Building a website with Publican.

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 Chapter 7, Building a website with Publican.

web_obsoletes

specifies packages that the web RPM obsoletes. Refer to Section 4.8, “Packaging a document”.

web_product_label

overrides the product name as it appears on the menu of a Publican-managed website. Refer to Chapter 7, Building a website with Publican.

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 Chapter 7, Building a website with Publican.

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 Chapter 7, Building a website with Publican.

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.

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

Packages other than RPM packages

This section discusses packaging documents for distribution through the RPM Package Manager. However, when you use the $ publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.

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.


<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
]>
<bookinfo conformance="121" id="book-Publican-Users_Guide-Users_Guide" lang="en-US">
	<title>Users' Guide</title>
	 <subtitle>Publishing books, articles, papers and multi-volume sets with DocBook XML</subtitle>
	 <productname>&PRODUCT;</productname>
	 <productnumber>&PRODUCTNUM;</productnumber>
	 <abstract>
		<para>
			This book will help you install <application>&PRODUCT;</application>. It also provides instructions for using Publican to create and publish DocBook XML-based books, articles and book sets. This guide assumes that you are already familiar with DocBook XML.
		</para>

	</abstract>
	 <keywordset>
		<keyword>publican</keyword>
		 <keyword>docbook</keyword>
		 <keyword>publishing</keyword>

	</keywordset>
	 <subjectset scheme="libraryofcongress">
		<subject>
			<subjectterm>Electronic Publishing</subjectterm>

		</subject>
		 <subject>
			<subjectterm>XML (Computer program language)</subjectterm>

		</subject>

	</subjectset>
	 <corpauthor>
		<inlinemediaobject>
			<imageobject>
				<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
			</imageobject>
			 <textobject>
				<phrase>Team &PRODUCT;</phrase>
			</textobject>

		</inlinemediaobject>

	</corpauthor>
	 <mediaobject role="cover">
		<imageobject remap="lrg" role="front-large">
			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
		</imageobject>
		 <imageobject remap="s" role="front">
			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
		</imageobject>
		 <imageobject remap="xs" role="front-small">
			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
		</imageobject>
		 <imageobject remap="cs" role="thumbnail">
			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
		</imageobject>

	</mediaobject>
	 <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	 <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

<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.
Permitted characters
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain upper- and lower-case un-accented letters, digits, and the hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
<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.
Permitted characters
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain upper- and lower-case un-accented letters, digits, and the hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
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 Section 4.1.1, “The publican.cfg file”.
<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.
Permitted characters
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain numbers and the period (‘0–9’ and ‘.’) if you plan to build packages with Publican.
<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.
Permitted characters
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain numbers and the period (‘0–9’ and ‘.’) if you plan to build packages with Publican.
<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.
Permitted characters
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain numbers (‘0–9’) if you plan to build packages with Publican.
<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.

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

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

<?xml version='1.0'?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<authorgroup>
	<corpauthor>FF0000 Headgear Documentation Group</corpauthor>
	<author>
		<firstname>Dude</firstname>
		<surname>McDude</surname>
		<affiliation>
			<orgname>My Org</orgname>
			<orgdiv>Best Div in the place</orgdiv>
		</affiliation>
		<email>dude.mcdude@myorg.org</email>
	</author>
</authorgroup>

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

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

<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="MYBOOK-Test">
	<title>Test</title>
	<para>
		This is a test paragraph
	</para>
	<section id="MYBOOK-Test-Section_1_Test">
		<title>Section 1 Test</title>
		<para>
			Test of a section
		</para>
	</section>
	
	<section id="MYBOOK-Test-Section_2_Test">
		<title>Section 2 Test</title>
		<para>
			Test of a section
		</para>
	</section>

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

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

⁠

Example 4.4. A DocBook book

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<book>
	<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<index />
</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.

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

<!ENTITY PRODUCT "MYPRODUCT">
<!ENTITY BOOKID "MYBOOK">
<!ENTITY YEAR "2008">
<!ENTITY HOLDER "YOUR NAME GOES HERE">

⁠4.1.6.1. Entities and translation

Use entities with extreme caution

Entities offer convenience but they should be used with extreme caution in documents that will be translated. Writing (for example) &FDS; instead of Fedora Directory Server saves the writer time but transformed entities do not appear in the portable object (PO) files that translators use. Complete translations of documents containing entities are, as a consequence, impossible.

Entities present special obstacles to translators and can preclude the production of high-quality translations. The very nature of an entity is that the word or phrase represented by the entity is rendered exactly the same way every time that it occurs in the document, in every language. This inflexibility means that the word or word group represented by the entity might be illegible or incomprehensible in the target language and that the word or word group represented by the entity cannot change when the grammatical rules of the target language require them to change. Furthermore, because entities are not transformed when XML is converted to PO, translators cannot select the correct words that surround the entity, as required by the grammatical rules of the target language.

If you define an entity — <!ENTITY LIFT "Liberty Installation and Formatting Tome"> — you can enter &LIFT; in your XML and it will appear as Liberty Installation and Formatting Tome every time the book is built as HTML, PDF or text.

Entities are not transformed when XML is converted to PO, however. Consequently, translators never see Liberty Installation and Formatting Tome. Instead they see &LIFT;, which they cannot translate.

Consider something as simple as the following English sentence fragment being translated into a related language: German.

As noted in the Liberty Installation and Formatting Tome, Chapter 3…

A translation of this might be as follows:

Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…

Because there is no text missing, the title can be translated into elegant German. Also, note the use of ‘dem’, the correct form of the definite article ('the') when referring to a Wälzer ('tome') in this grammatical context.

By contrast, if entities are used, the entry in the PO file says:

#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…"
msgstr ""

The translation of this would probably run thus:

#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…"
msgstr "Wie in <citetitle>&LIFT;</citetitle>, Kapitel 3, erwähnt…"

And the presentation would be thus:

Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…

This, of course, leaves the title in English, including words like 'Tome' and 'Formatting' that readers are unlikely to understand. Also, the translator is forced to omit the definite article ‘dem’, a more general construction that comes close to a hybrid of English and German that German speakers call Denglisch or Angleutsch. Many German speakers consider this approach incorrect and almost all consider it inelegant.

Equivalent problems emerge with a fragment such as this:

However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…

With no text hidden behind an entity, a German translation of this might be:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…

If an entity was used to save the writer time, the translator has to deal with this:

#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…"
msgstr ""

And the translation would be subtly but importantly different:

#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…"
msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle>&LIFT;</citetitle>, dass…"

When presented to a reader, this would appear as follows:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…

Again, note the missing definite article (den in this grammatical context). This is inelegant but necessary since the translator can otherwise only guess which form of the definite article (den, die or das) to use, which would inevitably lead to error.

Finally, consider that although a particular word never changes its form in English, this is not necessarily true of other languages, even when the word is a proper noun such as the name of a product. In many languages, nouns change (inflect) their form according to their role in a sentence (their grammatical case). An XML entity set to represent an English noun or noun phrase therefore makes correct translation impossible in such languages.

For example, if you write a document that could apply to more than one product, you might be tempted to set an entity such as &PRODUCT;. The advantage of this approach is that by simply changing this value in the Doc_Name.ent file, you could easily adjust the book to document (for example) Red Hat Enterprise Linux, Fedora, or CentOS. However, while the proper noun Fedora never varies in English, it has multiple forms in other languages. For example, in Czech the name Fedora has six different forms, depending on one of seven ways in which you can use it in a sentence:

⁠

Table 4.1. 'Fedora' in Czech

Case	Usage	Form
Nominative	the subject of a sentence	Fedora
Genitive	indicates possession	Fedory
Accusative	the direct object of a sentence	Fedoru
Dative	the indirect object of a sentence	Fedoře
Vocative	the subject of direct address	Fedoro
Locative	relates to a location	Fedoře
Instrumental	relates to a method	Fedorou

For example:

Fedora je linuxová distribuce. — Fedora is a Linux distribution.
Inštalácia Fedory — Installation of Fedora
Stáhnout Fedoru — Get Fedora
Přispějte Fedoře — Contribute to Fedora
Ahoj, Fedoro! — Hello Fedora!
Ve Fedoře 10… — In Fedora 10…
S Fedorou získáváte nejnovější… — With Fedora, you get the latest…

A sentence that begins S Fedora získáváte nejnovější… remains comprehensible to Czech readers, but the result is not grammatically correct. The same effect can be simulated in English, because although English nouns lost their case endings during the Middle Ages, English pronouns are still inflected. The sentence, 'Me see she' is completely comprehensible to English speakers, but is not what they expect to read, because the form of the pronouns me and she is not correct. Me is the accusative form of the pronoun, but because it is the subject of the sentence, the pronoun should take the nominative form, I. Similarly, she is nominative case, but as the direct object of the sentence the pronoun should take its accusative form, her.

Nouns in most Slavic languages like Russian, Ukrainian, Czech, Polish, Serbian, and Croatian have seven different cases. Nouns in Finno–Ugaric languages such as Finnish, Hungarian, and Estonian have between fifteen and seventeen cases. Other languages alter nouns for other reasons. For example, Scandinavian languages inflect nouns to indicate definiteness — whether the noun refers to 'a thing' or 'the thing' — and some dialects of those languages inflect nouns both for definiteness and for grammatical case.

Now multiply such problems by the more than 40 languages that Publican currently supports. Other than the few non-translated strings that Publican specifies by default in the Doc_Name.ent file, entities might prove useful for version numbers of products. Beyond that, the use of entities is tantamount to a conscious effort to inhibit and reduce the quality of translations. Furthermore, readers of your document in a language that inflects nouns (whether for case, definiteness, or other reasons) will not know that the bad grammar is the result of XML entities that you set — they will probably assume that the translator is incompetent.

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

⁠4.2. Adding images

Store images in the images subdirectory in the directory that holds your XML files. Use ./images/image-name to insert images into a book. The following is an example that inserts the testimage.png image:

<mediaobject>
<imageobject>
	<imagedata fileref="./images/testimage.png" />
</imageobject>
<textobject><phrase>alternate text goes here</phrase></textobject>
</mediaobject>

Ensure that you supply a <textobject> so that your content remains accessible to people with visual impairments. In certain jurisdictions, you might have a legal responsibility to provide this accessibility — for example, if you or your organization must comply with Section 508 of the United States Rehabilitation Act of 1973. ⁠^[1]

If your book contains images that need to be localized — for example, screenshots of a user interface in a language other than the original language of your book — place these images in the images subdirectories for each language directory. Make sure that the image file in the translated language has the same name as the image file in the original language. When you build the book in the translated language, Publican uses the file from the images/ subdirectory of the translated language instead of the file from the images/ subdirectory of the original language.

Large images present poorly in HTML because they often go beyond the right margin of the text. Similarly, images wider than 444 pixels often go beyond the right margin of PDF pages and are cropped so that only the left side of the image is visible. Therefore, by default, Publican creates HTML and PDF output that instructs web browsers and PDF viewers to scale down any images larger than 444 pixels wide. Note, however, that images lose quality significantly when scaled in this way. For best results, scale or crop your images in image editing software so that they are no more than 444 pixels wide before you place them in a document.

To override Publican limiting the image width to 444 px, specify an image width in the <imagedata> tag. For example, to set an image width to 670 pixels:

<imagedata fileref=".images/image.png" width="670px">

If you override the default maximum image width, take care to review your output to ensure that quality standards are met.

Image file locations

Publican only uses images in the images subdirectory of your XML directory and corresponding images in the images subdirectories of your translated languages. Images stored in other directories directories do not work.

PNG files in PDF documents

Publican depends on an external application, FOP, to render documents as PDF files. At present, some versions of FOP contain a bug that alters the colors in certain images in PNG format. Specifically, 32-bit PNG images are rendered correctly, while 24-bit PNG images are not.

If you notice that Publican produces a PDF file that contains images with incorrect colors, convert the original PNG files to 32-bit PNG format by adding an alpha channel to the image and rebuild the book. If your chosen image manipulation software does not include an option specifically labeled Add alpha channel, the option might be labeled Add transparency instead.

⁠4.3. Adding code samples

If your book contains code samples, place them in a directory named extras/ in your source language directory and use an <xi:include> to pull the code file into the XML structure of your document. Publican does not parse any files that it finds in the extras/ directory as XML.

Certain characters are reserved in XML, in particular, & and <. If you insert code samples directly into the XML of your document, you must escape these characters, either by marking them as CDATA or by replacing them with entities (& and < respectively). ⁠^[2] If you place these files in the extras/ directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.

To include a code sample from the extras/ directory in your document, follow this procedure:

Create the extras directory
```
$ mkdir en-US/extras
```
Copy the code file to the extras directory
```
$ cp ~/samples/foo.c en-US/extras/.
```

xi:include the sample file in your xml file

<programlisting>
<xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>

You can now edit en-US/extras/foo.c in your favorite editor without having to be concerned about how it will affect the XML.

The same approach works when you want to annotate your code with callouts. For example:

<programlistingco>
	<areaspec>
		<area id="orbit-for-parameter" coords='4 75'/>
		<area id="orbit-for-magnitude" coords='12 75'/>
	</areaspec>
	<programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for"
	xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
	<calloutlist>
		<callout id="callout-for-parameter" arearefs="orbit-for-parameter">
			<para>
				The <firstterm>standard gravitational parameter</firstterm>
				(μ) is a derived value, the product of Newton's gravitational 
				constant (G) and the mass of the primary body.
			</para>
		</callout>
		<callout id="callout-for-magnitude" arearefs="orbit-for-magnitude">
			<para>
				Since the mass of the orbiting body is many orders of magnitude 
				smaller than the mass of the primary body, the mass of the 
				orbiting body is ignored in this calculation.
			</para>
		</callout>
	</calloutlist>
</programlistingco>

Note the <area> elements that define the position of the callouts that will appear on the code sample. The coords attributes specify a line number and a column number separated by a space. In this example, callouts are applied to lines 4 and 12 of the code, lined up with each other in column 75. Although this approach means that you might have to adjust coords attributes if you ever modify the code to which they apply, it avoids mixing XML <coords> tags into the code itself.

⁠4.4. Adding files

Publican allows you to include arbitrary files together with your documents. These files are included in RPM packages that you build with Publican and are installed on users' systems alongside the document itself. For example, you might want to include multimedia files of tutorials that complement the document, or sample files of source code or other materials that allow users to work through the examples or tutorials in a document.

To ship arbitrary files with a document, create a directory named files in the language directory for the original language (e.g. en-US) of the book (e.g. My_Book).

In the directory My_Book:

$ mkdir en-US/files

Copy the files to the directory files:

$ cp arbitrary_files en-US/files

⁠4.5. Renaming a document

The $ publican rename command makes it easy for you to rename a document to give it a new title, or to change the name or version of the product to which the document applies. The command accepts up to three options:

--name new_title

changes the title of the document. For example, to rename a document from Server Configuration Guide to Server Deployment Guide, change into the document's root directory and run:

$ publican rename --name "Server Deployment Guide"

Specifically, the command changes the content of the <title> tag in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file, and sets a value for the mainfile parameter in the publican.cfg file so that Publican can still find the root XML node and the entities for the document.

Note that the $ publican rename command does not change any file names. Therefore, the root XML node and the document entities are still located in files named after the original title of the document — Server_Configuration_Guide in the previous example.

--product new_product

changes the name of the product to which the document applies. For example, if the product was previously named ForceRivet but is now called PendantFarm, change into the document's root directory and run:

$ publican rename --product PendantFarm

The command changes the content of the <productname> tag in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file.

--version new_version

changes the product version to which the document applies. For example, if the product version was previously 1.0 but is now 2.0 , change into the document's root directory and run:

$ publican rename --version 2.0

The command changes the content of the <productnumber> tag in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file.

You can combine any combination of these options into a single command. For example:

$ publican rename --name "Server Deployment Guide" --product PendantFarm --version 2.0

⁠4.6. Translating a document

Support for localization of documents was a key consideration in the design of Publican. The general translation workflow for documents developed in Publican is as follows:

Complete the XML of a document.
The XML for this version of the document should now be considered ‘frozen’. If your document is stored in a version-controlled repository, you should now move this version into a separate directory or branch. This allows writers to begin work on subsequent versions of the document in one branch, while providing a stable base for translation in another branch.
Optional but recommended: drop the document to translation. Run:
```
$ publican trans_drop
```
Publican creates a new subdirectory, named trans_drop/. The trans_drop/ subdirectory contains a snapshot of the source files of the document. When the trans_drop/ directory is present in a documentation project, Publican uses its content as the basis for the commands documented later in this procedure.
Generate portable object template (POT) files from the XML files:
```
$ publican update_pot
```
If this is the first time that POT files have been created for this document, Publican creates a new subdirectory, named pot. The pot subdirectory holds a POT file for each XML file in the document. If Publican has created POT files for this document previously, Publican updates the existing POT files to reflect any changes in the XML since the POT files were last updated.
Remove unused XML files
Publican generates a POT file for every XML file in the XML directory, whether the XML file is used in the document or not. If you transform unused XML files into POT files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
Use the $ publican print_unused command to generate a list of XML files that are not used in your document.
Generate portable object (PO) files from the POT files to begin translation into a particular language:
```
$ publican update_po --langs=language_code
```
where language_code is the code for the target language. Refer to Appendix G, Language codes for more information about language codes. You can provide multiple language codes, separated by commas, to generate PO files for more than one language at a time. For example:
```
$ publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN
```
If this is the first time that PO files have been created for a particular language, Publican creates a new subdirectory, named with the language code that you specified with the --langs= option. This subdirectory holds a PO file for each POT file in pot subdirectory, plus a Revision_History.xml file that tracks the history of this particular translation. When created for the first time, the Revision_History.xml file records the date on which the PO files for this translation were created, and the version of the source language XML (taken from the source language's Revision_History.xml file) on which this translation is therefore based.
If Publican has created PO files for this language previously, Publican updates the existing PO files to reflect any changes in the POT files since the PO files were last updated, and adds a new entry to the translation's Revision_History.xml file to record the date on which the PO files for this translation were refreshed, and the version of the source language XML on which the revision is based. You can update existing PO files in every subdirectory with the --langs=all option:
```
$ publican update_po --langs=all
```
Remove unused POT files
Publican generates a PO file for every POT file in the pot directory, whether the POT file is based on a corresponding XML file that is used in the document or not, or whether a corresponding XML file even exists. If you transform POT files for unused or deleted XML files into PO files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
When you generate PO files, Publican presents you with a warning for any POT files that do not have corresponding XML files, but will generate the PO file nevertheless. However, Publican will not warn you if a POT file exists for an XML file that is not used in the document.
Translate the strings contained in the PO files.
If you are updating a previously published translation of this revision in the source language, use Publican's publican add_revision command to describe your changes or corrections. Publican updates the Revision_History.xml file for you.
If the document has changed in its original language, use the publican trans_drop, publican update_pot, and publican update_po commands as described earlier in this procedure instead.
Build the document in the target language, for example:
```
$ publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
```
or package it in the target language, for example:
```
$ publican package --lang=is-IS
```
You can build the document in all languages for which you have translations with the --langs=all option, but note that you must package each language individually. Refer to Section 4.7, “Building a document” for more information on building a document, and Section 4.8, “Packaging a document” on packaging a document.

⁠4.6.1. Translation Author Group

Translation takes place after a book has been finalized. You do not need to know who will translate your book in order to give them credit. Create $translation/Author_Group.xml and add a valid DocBook authorgroup. The translator can add their details to this file and Publican will append it to $source_lang/Author_Group.xml when the book is build. This allows authors to finalize the original text without needing to know who will translate the book.

⁠4.6.2. Translating Indexes and Glossaries

DocBook automatically collates and sorts <glossentry> elements into a book's glossary; and <primary>, <secondary>, and <tertiary> <indexterm> elements into a book's index. Entries are sorted automatically, and although this system works well for languages written with an alphabet, abugida, or syllabic script, languages written with logograms sort less well.

To manually adjust the sort order of a glossary entry or index entry, manually add DocBook's sortas attribute to the XML element. For example, to ensure that the Japanese word 暗号化 sorts correctly in an index, specify:

#. Tag: indexterm
#, no-c-format
msgid "<primary>encryption</primary>"
msgstr "<primary sortas="あんごうか">暗号化</primary>"

Similarly, to ensure that the Japanese word 暗号化 sorts correctly in a glossary, specify:

#. Tag: glossentry
#, no-c-format
msgid "<glossterm>encryption</glossterm>"
msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"

⁠4.7. Building a document

Note — Customizing output

The parameters set in the document configuration file (by default, publican.cfg) allow you to control many aspects of the way in which a document is presented — refer to Section 4.1.1, “The publican.cfg file”.

If you maintain multiple versions of a document, you can create a configuration file for each version. When building the document, you can use the --config to specify which configuration file (and therefore which 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

To build a document:

Confirm the YEAR and HOLDER entities have been configured in the Doc_Name.ent file, as described in Section 4.1.6, “Doc_Name.ent”.
Change into the root directory of the document. For example, if the document is named Test_Book and is located in the ~/books/ directory, run the following command:
```
$ cd ~/books/Test_Book
```
Run a test for any errors that would stop the book from building in your chosen language, for example:
```
$ publican build --formats=test --langs=en-US
```
Run the following command to build the book:
```
$ publican build --formats=formats --langs=languages
```
Replace formats with a comma-separated list of the formats that you want to build; for example, html,html-single,pdf. Replace langs with a comma-separated list of the languages that you want to build; for example, en-US,sv-SE,uk-UA,ko-KR.

⁠

Formats for the build action

html: Publican outputs the document as in multiple HTML pages, with each chapter and major section on a separate page. Publican places an index at the start of the document, and places navigational elements on each page.
Use the chunk_first and chunk_section depth parameters in the publican.cfg file to control how Publican chunks sections in this format.
html-single: Publican outputs the document as a single HTML page with the table of contents near the top of the page.
html-desktop: Publican outputs the document as a single HTML page with the table of contents located in a separate pane on the left side of the document.
man: Publican outputs the document as a manual page ("man page") for use with Linux, UNIX, and similar operating systems.
pdf: Publican outputs the document as a PDF file.
test: Publican validates the XML structure of the book, but does not transform the XML into another format.
txt: Publican outputs the document as a single text file.
epub: Publican outputs the document as an e-book in EPUB format.
eclipse: Publican outputs the document as an Eclipse help plugin. Refer to Section 4.1.1, “The publican.cfg file” for details of specifying Eclipse's id, name, and provider-name parameters with Publican's ec_id, ec_name, and ec_provider parameters.

The following examples demonstrate commonly used $ publican build commands:

$ publican build --help: List available $ publican build options for building a book.
$ publican build --formats=test --langs=languages: Check that the book can be built correctly. Build --formats=test before running any other $ publican build command, and before checking a book back into a version-controlled repository from which other contributors might download it.
$ publican build --formats=html --langs=languages: Build the book in multi-page HTML format. The HTML output will be located in the Doc_Name/tmp/language/html/ directory. Each chapter and major section is placed in a separate HTML file. You can control the depth at which Publican places subsections into separate HTML files with the chunk-section-depth parameter in the publican.cfg — refer to Section 4.1.1, “The publican.cfg file”.
$ publican build --formats=html-single --langs=languages: Build the book in single-page HTML format. The output will be a single HTML file located in the Doc_Name/tmp/language/html-single/ directory.
$ publican build --formats=pdf --langs=languages: Build the book as a PDF file. Publican relies on an external application, FOP to render PDF. Therefore, building PDF might not be available on all systems, depending on the availability of FOP. The output will be a single PDF file located in the Doc_Name/tmp/language/pdf/ directory.
$ publican build --formats=html,html-single,pdf --langs=languages: Build the book in multi-page HTML, single-page HTML, and PDF formats.

⁠4.7.1. Building a document without validation

Publican validates your XML against the DocBook document type definition (DTD) before it builds the content. However, while a document is under development, you might sometimes want to skip validation while building, especially if the document contains cross-references (<xref>s) to sections of the document that do not yet exist. To skip validation, run $ publican build with the --novalid option. Cross-references to non-existent content appear in the built document as three question marks: ???.

Because the document has not been validated against the DTD, the quality of the output produced when you build with the --novalid option is highly suspect. Do not publish documentation that you have built with the --novalid option.

⁠4.8. Packaging a document

Packages other than RPM packages

Note — Customizing output

The parameters set in the document configuration file (by default, publican.cfg) allow you to control many aspects of the way in which a document is presented and packaged — refer to Section 4.1.1, “The publican.cfg file”.

If you maintain multiple versions of a document, you can create a configuration file for each version. When packaging the document, you can use the --config to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:

$ publican package --lang hi-IN --config community.cfg

Publican not only builds documentation, but it can package built content for distribution to individual workstations and to web servers as RPM packages. RPM packages are used to distribute software to computers with Linux operating systems that use the RPM Package Manager. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.

⁠4.8.1. Types of RPM packages

Publican can produce both source RPM packages (SRPM packages) and binary RPM packages. Furthermore, both SRPM packages and binary RPM packages can be configured to deploy to workstations or web servers.

⁠4.8.1.1. Source RPM packages and binary RPM packages

SRPM packages contain the source code used to generate software rather than the software itself. To use an SRPM package, a computer must compile the source code into software — or in this case, into documents. SRPM packages of Publican documents contain XML files and a spec file rather than finished documents in formats such as HTML and PDF. You cannot install documentation directly from SRPM packages with current versions of the RPM Package Manager.

Conversely, binary RPM packages contain software — or in this case, a document — that is ready to copy to a location in the computer's file system and use immediately. The contents of the binary RPM package do not need to be compiled by the computer onto which they are installed. Therefore, when installing documentation solely for local use the computer does not need to have Publican installed. Installing Publican-generated documentation on a webserver does requires Publican to be installed, but for reasons other than compiling the source code. Refer to Section 4.8.1.2, “Desktop packages and web packages” for a description of the differences between documentation installed for local use (desktop RPMs) and documentation installed to serve as web content (web RPMs).

⁠4.8.1.2. Desktop packages and web packages

Publican can package documents for reading on a computer workstation (a desktop RPM package) or to install on a web server and publish on the World Wide Web (a web RPM package). The desktop RPM package of a Publican document and the web RPM package of the same document differ in that the desktop RPM package installs documentation only for local use on a computer, while the web RPM installs documentation for local use, but also to be served to the World Wide Web.

Desktop (binary) RPM packages of Publican documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of /usr/share/doc/, the location specified by the Filesystem Hierarchy Standard (FHS) for ‘Miscellaneous documentation’. ⁠^[3] The desktop RPM package also contains a desktop file, to be placed in /usr/share/applications/. This file enables desktop environments to add the installed document to their menus for ease of reference by users. By default, the menu item appears under System → Documentation on the GNOME desktop. To customize the placement of the menu item, create a documentation menu package to supply .directory and .menu files and set the dt_requires and menu_category parameters in the publican.cfg file to require this package and supply the appropriate menu category. Refer to Section 4.8.1.3, “Desktop menu entries for documents”

By default, web RPM packages of Publican documents contain the documentation in single-page HTML, multi-page HTML, EPUB, and PDF formats. The formats included vary if:

you publish documentation in a language in which PDF output is not currently supported. Publican relies on FOP to generate PDF output. FOP does not presently support right-to-left text (for example, Arabic, Persian, or Hebrew). Furthermore, because FOP cannot presently specify fonts on a character-by-character basis, a lack of available fonts in Indic scripts that also include Latin glyphs prevents Publican from reliably generating PDF output in Indic languages. By default, Publican does not include PDF files in web RPM packages generated in Arabic, Persian, Hebrew, or any Indic language.
your book or your brand contains the web_formats parameter. The value of this parameter overrides the default formats that Publican packages. For example, to publish the document only as single-page HTML, PDF, and text, set web_formats: "html-single,pdf,txt"

Built content is installed in subdirectories of /var/www/html/, a common document root for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.

⁠4.8.1.3. Desktop menu entries for documents

By default, RPM packages of Publican documents for desktop use appear on the GNOME desktop under the System → Documentation menu. When users have large numbers of documents installed on their systems, this menu becomes very cluttered and difficult to navigate. Documentation for many different products and perhaps different languages becomes intermixed, adding to the confusion.

To group documentation for your product under a separate submenu within the GNOME System → Documentation menu, you must:

create and distribute a desktop menu package that creates the new submenu.
specify the menu category in the document, and optionally, have the documentation package require the desktop menu package.

Note that the Documentation menu does not group entries under a submenu until two or more documents are installed that belong on that submenu. The first document appears under System → Documentation.

⁠4.8.1.3.1. Creating an desktop menu package

A desktop menu package consists of:

a desktop entry (.directory) file that provides metadata about the new submenu.
a desktop menu (.menu) file that defines the position of the new submenu within the Documentation menu.

The structure for the .directory file for Publican-generated documentation is as follows:

the group header [Desktop Entry]
the Name parameter, set to the name of the submenu that you want to place under the Documentation menu.
optionally, localizations of the Name parameter, in the format Name[language_code] where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.
the Comment parameter, set to a description of the new submenu.
optionally, localizations of the Comment parameter, in the format Comment[language_code] where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.
the Type parameter, set to Directory.
the Encoding parameter, set to UTF-8.

⁠

Example 4.5. Example .directory file

The following file, menu-example.directory illustrates the structure of a desktop entry file.

[Desktop Entry]
Name=Example
Name[fr]=Exemple
Name[it]=Esempio
Comment=Example Documentation menu
Comment[fr]=Exemple d'une menu de documentation
Comment[it]=Esempio di un menù di documentazione
Type=Directory
Encoding=UTF-8

The desktop entry file is placed in /usr/share/desktop-directories/

For a full description of how desktop entries work, refer to the Desktop Entry Specification, available from http://standards.freedesktop.org/entry-spec/latest/

A desktop menu file is an XML file that contains:

a document type declaration for the freedesktop.org Desktop Menu Specification:

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">

a root element, <Menu>, that contains:
- a <Name> element with the content Documentation
- another <Menu> element that in turn contains:
  - a <Name> element with the content Documentation (just like the root element)
  - a <Directory> element with its content the name of the desktop entry file you created, for example:
    <Directory>menu-example.directory</Directory>
  - an <Includes> element with the content X-category_name, where category_name is an identifier for the documents that will be grouped together under this menu entry. For example:
    <Includes>X-Example-Docs</Includes>

⁠

Example 4.6. Example .menu file

The following file, menu-example.menu illustrates the structure of a desktop menu file.

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
	<Name>Documentation</Name>
	<Menu>
		<Name>Documentation</Name>
		<Menu>
			<Name>Example</Name>
			<Directory>menu-example.directory</Directory>
			<Include>
				<Category>X-Example-Docs</Category>
			</Include>
		</Menu>
	</Menu> 
</Menu>

The desktop menu file is placed in /etc/xdg/menus/settings-merged/

For a full description of how desktop menus work, refer to the Desktop Menu Specification, available from http://standards.freedesktop.org/desktop-menu-spec/latest/

⁠4.8.1.3.2. Setting a desktop menu category

To place a document in a submenu of System → Documentation, set the menu_category parameter in its publican.cfg file to match the content of the <Includes> element in the corresponding desktop menu file. For example, consider a desktop menu file that contains the element:

<Includes>X-Example-Docs</Includes>

To place a document in the submenu defined by this desktop menu file, the document's publican.cfg file should contain:

menu_category: X-Example-Docs

Important

Publican will process the string in menu_category and replace __LANG__ with the current language. This allows menus to be customized on a per language basis.

menu_category: X-Example-Docs-__LANG__

Note that you can include this parameter in the defaults.cfg file or overrides.cfg file of a brand so that all documents built with that brand are grouped into this submenu automatically without you having to set the menu_category parameter in each document.

If you ship the desktop menu and desktop entry files in an RPM package, you can make RPM packages of documentation require the desktop menu package. With this dependency set, the desktop menu package is installed automatically on users' systems when they install a documentation package, which ensures that the documentation appears under the submenu you have created for your project. Set the dependency with the dt_requires parameter in the document's publican.cfg file. For example, if you ship a desktop menu package named foodocs-menu, set:

dt_requires: foodocs-menu

Note that you can include this parameter in the defaults.cfg file or overrides.cfg file of a brand so that all documents built with that brand require the same desktop menu package.

⁠4.8.2. The `$` `publican package` command

Use the $ publican package --lang=Language_Code command to package documents for distribution in the language that you specify with the --lang option. Refer to Appendix G, Language codes for more information about language codes.

If you run $ publican package with no options other than the mandatory --lang option, Publican produces a web SRPM package. The full range of options for publican package is as follows:

--lang language: specifies the language in which to package the documentation.
Incomplete translations
If translation in a particular language is not complete by the scheduled release date, consider marking the language with the ignored_translations parameter in the document's publican.cfg file. The package will be named appropriately for the language, but will contain documentation in the original language of the XML rather than a partial translation. When translation is complete, remove the ignored_translations parameter, increase the release number in the Project-Id-Version field in the Book_Info.po file for that language, and generate the package again. When you distribute the revised package, it becomes available to replace the original untranslated package.
--config filename: specifies that Publican should use a configuration file other than the default publican.cfg file.
--desktop: specifies that Publican should create a desktop RPM package rather than a web RPM package.
--brew: specifies that Publican should push the completed package to Brew. Brew is the build system used internally by Red Hat; this option is meaningless outside Red Hat.
--scratch: when used together with the --brew and --desktop options, specifies that an SRPM package should be built as a scratch build when sent to Brew. Scratch builds are used to verify that an SRPM package is structured correctly, without updating the package database to use the resulting package.
--short_sighted: specifies that Publican should build the package without including the version number of the software (version in the publican.cfg file) in the package name.
Omitting the software version number
Much software documentation is version-specific. At best, the procedures described in the documentation for one version of a product might not help you to install, configure, or use a different version of the product. At worst, the procedures described in the documentation for one version might be misleading or even harmful when applied to a different version.
If you distribute documentation as RPM packages without version numbers in the package names, the RPM Package Manager on users' computers will automatically replace any existing documentation with the documentation for the latest version; users will not have access to documentation for more than one version of the software at a time. Be certain you want this outcome.
--binary: specifies that Publican should build the package as a binary RPM package.

After you run the $ publican package command, Publican outputs completed SRPM packages to the document's tmp/rpm directory, and completed binary RPM packages to the document's tmp/rpm/noarch directory.

By default, Publican documentation packages are named:

productname-title-productnumber-[web]-language-edition-pubsnumber. [.[build_target].noarch].file_extension.

Publican uses the information in the document's configuration file (by default, publican.cfg) to supply the various parameters in the file name, and then information in the Book_Info.xml file for any parameters missing from the configuration file. Refer to Section 4.1, “Files in the book directory” for details of the parameters used in these files. Additionally, note that:

web RPM packages include the element -web- between the product version and the language code.
SRPM packages have the file extension .src.rpm but binary RPM packages have the file extension .rpm
binary RPM packages include build_target.noarch before the file extension, where build_target represents the operating system and version that the package is built for as set by the os_ver parameter in the publican.cfg file. The noarch element specifies that the package can be installed on any system, regardless of the system architecture.
use of the --short_sighted option removes the -productnumber- from the package name.
packages of translated documents take their release numbers from the Project-Id-Version parameter in the Article_Info.po or Book_Info.po file. This release number is specific to a particular language and bears no relationship to the release numbers of the same document in the original language or any other language.

⁠4.8.2.1. The `$` `publican package` command — Example usage

The following examples illustrate some common options, illustrated with the Foomaster 9 Configuration Guide, edition 2, revision 6.

$ publican package --lang=cs-CZ: produces a web SRPM package named Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.src.rpm that contains XML source files in Czech, together with a spec file.
$ publican package --desktop --lang=cs-CZ: produces a desktop SRPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.src.rpm that contains XML source files in Czech, together with a spec file.
$ publican package --binary --lang=cs-CZ: produces both a web binary RPM package named Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.el5.noarch.rpm and a desktop binary RPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm that contain documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
$ publican package --desktop --binary --lang=cs-CZ: produces a desktop binary RPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm that contains documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
$ publican package --desktop --short_sighted --lang=cs-CZ: produces a desktop SRPM package named Foomaster-Configuration_Guide-cs-CZ-2-6.src.rpm that contains documentation in Czech. This package will replace any Configuration Guides for previous versions of Foomaster that exists on a system. Users cannot have access to both the Foomaster 8 Configuration Guide and the Foomaster 9 Configuration Guide.

⁠4.9. Conditional tagging

In some cases you may need to maintain multiple versions of a book; for example, a HOWTO guide for product FOO can have an upstream version and an enterprise version, with very subtle differences between them.

Publican makes it easy to manage differences between multiple versions of a book by allowing you to use a single source for all versions. Conditional tagging allows you to make sure that version-specific content only appears in the correct version; that is, you conditionalize the content.

To conditionalize content in a book, use the tag attribute $ condition. For example, let's say the book How To Use Product Foo has an "upstream", "enterprise", and "beta" version:

<para condition="upstream">
	<application>Foo</application> starts automatically when you boot the system.
</para>
	
<para condition="enterprise">
	<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>.
</para>	
	
<para condition="beta">
	<application>Foo</application> does not start automatically when you boot the system.
</para>
	
<para condition="beta,enterprise">
	To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file.
</para>

To build a specific version (and thereby capture all content conditionalized for that version), add the $ condition: version parameter to the publican.cfg file and run the $ publican build command as normal. For example, if you add condition: upstream to the publican.cfg file of How To Use Product Foo and run:

$ publican build --formats=pdf --langs=en-US

Publican filters out all tags with condition attributes other than condition="upstream" and builds How To Use Product Foo in as a PDF file in American English.

Root nodes and conditional tagging


<?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_Fedora" condition="Fedora">
<title>Installation and configuration on Fedora</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: Ubuntu set in the publican.cfg file.

To exclude this chapter, add a condition to the <xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration_on_Fedora.xml.

xrefs and conditional tagging

⁠4.9.1. Conditional tagging and translation

Use conditional tagging with great caution

Use conditional tagging only with great caution in books that you expect to be translated, as conditional tagging creates extra difficulties for translators.

Conditional tagging creates difficulty for translators in two ways: it obscures context in the portable object (PO) files through which translators work, and it makes proofreading more difficult for translators who are not deeply familiar with your book and all the conditions that you have set.

The PO files for the document contain the full set of tags from the XML files, regardless of any conditions set. When translators open the PO file for the example from How To Use Product Foo in Section 4.9, “Conditional tagging”, they see:

#. Tag: para
#, no-c-format
msgid "<application>Foo</application> starts automatically when you boot the system."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<application>Foo</application> does not start automatically when you boot the system."
msgstr ""

#. Tag: para
#, no-c-format
msgid "To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file."
msgstr ""

Because PO files include do not include attributes from tags, there is nothing obvious here to show translators that these paragraphs are alternatives to each other and that the writer does not intend that meaning should flow from one paragraph to the next.

In this example, the only paragraphs where the meaning flows logically from one to the next is between paragraphs three and four. Because both of these paragraphs appear in the book for the beta version of the product, they (hopefully) make sense together. Beyond that, the use of conditionals here requires translators to translate individual small chunks of content without the ability to follow the context from one paragraph to the next. When translators must work under these conditions, the quality of the translation will suffer, or the time required — and therefore the cost of translation — will increase.

Furthermore, unless the translators who work on your book know how to configure Publican's publican.cfg file and are aware of the valid conditions for your book, they cannot proofread their work. Without that knowledge, when translators proofread a document, they will wonder why they cannot find text that they know they translated and can find easily in the PO file. If you must use conditionals in your book, you must be prepared to provide a greater degree of support to your translators than you would otherwise provide.

As an alternative to conditionals, consider maintaining separate versions of your book in separate branches of a version-controlled repository. You can still share XML files and even PO files between the various branches as necessary, and some version control systems allow you to share changes readily among branches.

If you maintain two versions of a book in the same repository, we recommend using a separate config file for each version. For example, the upstream.cfg file might contain the condition condition: upstream and the enterprise.cfg file might contain the condition condition: enterprise. You could then specify the version of the document to build or package with the --config; for example, $ publican package --lang en-US --config upstream.cfg. Using two separate config files saves you from having to edit the one config file each time you build or package a document.

⁠4.10. Pre-release software and draft documentation

Completed documentation for pre-release software is not the same thing as draft documentation.

Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.

In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.

⁠4.10.1. Denoting pre-release software

Documentation for pre-release software, especially pre-release software being distributed to testers, customers and partners, should carry a clear mark denoting the beta-status of the software.

To create that mark do the following:

Add the software's pre-release version number, or equivalent state information, to the <subtitle> tag in your Book_Info.xml file. Place this additional text in <remark> tags. For example:
```
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
```
add show_remarks to the publican.cfg file and set it to '1':
```
show_remarks: 1
```

When you build your book with this <remark> tag and the show_remarks setting in place, the pre-release nature of the software is displayed clearly and unmistakably. PDF builds display the remark on their cover and title pages. HTML builds (both single-page HTML and multiple-page HTML) display the remark near the beginning of index.html.

Because this approach makes no changes to the information in Book_Info.xml used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.

Important

It is the writer's responsibility to remove the <remark> tag and its contents and remove or turn off show_remarks when documentation is updated for use with the release version of the software.

⁠4.10.2. Denoting draft documentation

Unfinished documentation made available to others for review should be labeled clearly as such.

To add the draft watermark to your documentation add the status="draft" attribute to the <article>, <book> or <set> tag in your document's root node. For example:
```
<book status="draft">
```

By default, your root node is the <book> tag in your Doc_Name.xml file.

If you are working on an article or set, the root node is the <article> or <set> tag in Doc_Name.xml.

Adding the status="draft" attribute causes each page of the document to show the draft watermark. This is by design.

Even if you change only a portion of a work before sending it out for review, marking every page as draft will encourage reviewers to report errors or typos they spot in passing. It will also ensure non-reviewers who encounter the work do not mistake a draft for a finished version.

⁠4.10.3. Denoting draft documentation of pre-release software

To denote unfinished documentation of pre-release software properly, do both previously noted procedures.

^[1] Refer to http://www.section508.gov/

^[2] Refer to section 2.4 "Character Data and Markup" in the XML 1.0 standard, available from http://www.w3.org/TR/2008/REC-xml-20081126/.

^[3] Refer to http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA

⁠Chapter 4. Creating a document

⁠4.1. Files in the book directory

⁠4.1.1. The publican.cfg file

⁠4.1.2. Book_Info.xml

⁠4.1.2.1. RPM packages, editions, impressions and versions

⁠4.1.3. Author_Group.xml

⁠4.1.4. Chapter.xml

⁠4.1.5. Doc_Name.xml

⁠4.1.6. Doc_Name.ent

⁠4.1.6.1. Entities and translation

⁠4.1.7. Revision_History.xml

⁠4.2. Adding images

⁠4.3. Adding code samples

⁠4.4. Adding files

⁠4.5. Renaming a document

⁠4.6. Translating a document

⁠4.6.1. Translation Author Group

⁠4.6.2. Translating Indexes and Glossaries

⁠4.7. Building a document

⁠4.7.1. Building a document without validation

⁠4.8. Packaging a document

⁠4.8.1. Types of RPM packages

⁠4.8.1.1. Source RPM packages and binary RPM packages

⁠4.8.1.2. Desktop packages and web packages

⁠4.8.1.3. Desktop menu entries for documents

⁠4.8.1.3.1. Creating an desktop menu package

⁠4.8.1.3.2. Setting a desktop menu category

⁠4.8.2. The $ publican package command

⁠4.8.2.1. The $ publican package command — Example usage

⁠4.9. Conditional tagging

⁠4.9.1. Conditional tagging and translation

⁠4.10. Pre-release software and draft documentation

⁠4.10.1. Denoting pre-release software

⁠4.10.2. Denoting draft documentation

⁠4.10.3. Denoting draft documentation of pre-release software

⁠4.8.2. The `$` `publican package` command

⁠4.8.2.1. The `$` `publican package` command — Example usage