# 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 `bridgehead`s should be included in tables of contents. (Default: `0` — `bridgehead`s 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"`