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 4, 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 3.6.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 5.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 3.5.2, “The publican package command” and Section 4.4, “Packaging a brand” for more information on building RPM packages.

catalogs

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

chunk_first

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

chunk_section_depth

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

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 3.6, “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 a prominent footer marked Confidential to each page. The default value is 0 (no footer).

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.

doc_url

provides a URL for the documentation team for this package. In multi-page 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 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 ‘ ’).

dt_obsoletes

specifies the desktop packages that this package obsoletes. Refer to Section 3.5, “Packaging a book”.

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.

edition

specifies the edition number for this document. If set, this value overrides the content of the <edition> tag in the Book_Info.xml file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).

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.

ignored_translations

specifies translations to ignore. If you build or package a book in a language specified 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 3.3, “Preparing a document for translation”.

license

specifies the license this package uses. By default, Publican selects the GNU Free Documentation License (GFDL). Refer to Section 3.5, “Packaging a book”.

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, the default value is .el5, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to Section 3.5, “Packaging a book” and Section 4.4, “Packaging a brand”.

prod_url

provides a URL for the product to which this document applies. In multi-page 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 5.2, “Distributed sets”.

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

show_remarks

controls whether to display remarks 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.

show_unknown

controls whether Publican reports unknown tags when processing XML. By default, this value is set to 1, so Publican reports unknown tags. Set this value to 0 to hide this output. Publican ignores this parameter in strict mode.

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 3.5, “Packaging a book”.

strict

sets Publican to use strict mode, which prevents the use of tags that are unusable for professional output and translation. By default, the strict parameter is set of 0, which disables strict mode. To enable strict mode, set this parameter to 1 Strict mode is no longer enforced.

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.

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

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 3.5, “Packaging a book”.

web_obsoletes

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

<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 underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’) if you plan to build packages with Publican.

<title>title</title>

Obviously enough, the title of the document (for example, Server Configuration Guide). 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.

Override this tag with the docname variable in the publican.cfg file if the title of your document 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 underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’) if you plan to build packages with Publican.

<subtitle>subtitle</subtitle>

Again, plainly enough, the subtitle tag contains a 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 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 changes the release number (the last digit) 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.

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