Product SiteDocumentation Site

⁠Appendix C. publican.cfg parameters

Every book, article, document set, or brand has a publican.cfg file in its root directory. Parameters that can be set in the publican.cfg file are:
docname
the document name, set by the --name option.
version
the product version, set by the --version option.
xml_lang
the language of the source XML files, set by the --lang option.
edition
the edition number for this documentation, set by the --edition option.
type
the type of document — a DocBook <article>, DocBook <book>, or DocBook <set>, set by the --type option.
brand
the brand of the document, set by the --brand option.
product
the product to which this documentation applies, set by the --product option.
arch
the computer architecture for this document.
books
a space-separated list of books used in a remote set.
brew_dist
the build target to use for building the desktop RPM package in Brew. (Default: docs-5E)
bridgehead_in_toc
whether bridgeheads should be included in tables of contents. (Default: 0 — bridgeheads are not included in tables of contents).
chunk_first
whether the first section should appear on the same page as its parent when rendered in HTML. (Default: 0 — the first section starts a new HTML page).
chunk_section_depth
the point at which Publican no longer splits sub-subsections onto a new page when rendering HTML. (Default: 4)
classpath
the path to the jar files for FOP. (Default for Linux operating systems: /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
the path to the Publican installation. (Default for Linux operating systems: /usr/share/publican, default for Windows operating systems: %SystemDrive%/%ProgramFiles%/publican — most usually C:/Program Files/publican)
common_content
the path to the Publican's Common Content files. (Default for Linux operating systems: /usr/share/publican/Common_Content, default for Windows operating systems: %SystemDrive%/%ProgramFiles%/publican/Common_Content — most usually C:/Program Files/publican/Common_Content)
condition
conditions on which to prune XML before transformation.
confidential
marks a document as confidential. (Default: 0 — not confidential).
confidential_text
sets the text with which to mark a document as confidential. (Default: CONFIDENTIAL).
debug
whether Publican should display debugging messages as it works. (Default: 0 — suppress messages)
def_lang
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. (Default: en-US — American English)
doc_url
URL for the documentation team for this package. (Default: https://fedorahosted.org/publican)
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
the version of the DocBook XML Document Type Definition (DTD) on which this project is based. (Default: 4.5)
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
the ID for an Eclipse help plugin (Default: product.docname)
ec_name
the name of an Eclipse help plugin (Default: product docname)
ec_provider
the provider name for an Eclipse help plugin (Default: Publican-Publican version)
extras_dir
the directory Publican will process extra files from. (Default: extras)
generate_section_toc_level
the section depth at which Publican generates a table of contents. (Default: 0 — no tables of contents in sections)
ignored_translations
translations to ignore.
img_dir
the directory Publican will process images from. (Default: images)
info_file
override the default Info file. Use the full filename without the path.
license
the license this package uses. (Default: GNU Free Documentation License).
mainfile
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.
max_image_width
the maximum width allowable for images in the document, unless specifically overriden in the <imagedata> tag for a specific image. (Default: 444 — 444 pixels wide)

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.
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
the operating system for which to build packages.
prod_url
URL for the product to which this document applies. (Default: https://fedorahosted.org/publican)
release
the release number of this package. Defaults to the value of xml_lang, fetched from the title tag in xml_lang/TYPE_Info.xml or Project-Id-Version in lang/TYPE_Info.po.
repo
the repository from which to fetch remote books that form part of a distributed set.
rev_file
override the default Revision History file. Use the full filename without the path.
scm
the version control system used in the repository in that stores the remote books in a distributed set. (Default: SVN)
show_remarks
whether to display remarks in transformed output. (Default: 0 — hide remarks)
sort_order
override the default sort weighting for books in a Publican website. Defaults to 50.
src_url
URL at which to find tarballs of source files.
tmp_dir
the directory for Publican output. (Default: tmp)
--toc_path
path to the directory in which to create the top-level toc.html file (mandatory).
toc_section_depth
the depth of sections that Publican includes in the main table of contents. (Default: 2)
--tmpl_path
path to the template directory (by default, /usr/share/publican/templates).
web_brew_dist
the brew build target to use for the web RPM package. (Defaults to docs-5E)
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.

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.
web_obsoletes
packages that the web RPM package obsoletes.
web_product_label
overrides the product name as it appears on the menu of a Publican-managed website.
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.
wkhtmltopdf_opts
Extra options to pass to wkhtmltopdf. e.g. wkhtmltopdf_opts: "-O landscape -s A3"