publican.cfg parameterspublican.cfg parameters
archarch: 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
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
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>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: x86 set in the publican.cfg file.
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
<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">.
booksbrandRedHat, 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.
brew_distdocs-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<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_firstchunk_first: 1. Otherwise, the parameter defaults to 0, and the first section appears on the same page of its chapter.
chunk_section_depth4.
Example D.1. Controlling the section depth with chunk_section_depth
classpath/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/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/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.
conditionRoot nodes and conditional tagging
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>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: Ubuntu set in the publican.cfg file.
<xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration_on_Fedora.xml.
xrefs and conditional tagging
<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">.
confidential1, 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_textconfidential parameter is set to 1. The default text is CONFIDENTIAL.
debug0, Publican does not display debugging messages. Change this value to 1 to view these messages.
def_langdoc_urlimage_right.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican
docname<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_obsoletesdt_requiresdtdverA different DTD might slow your build
dtd_typeNote
dtd_uriNote
ec_idplugin directory.
ec_nameec_provideredition<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 ‘.’).
extras_dirextras)
footergenerate_section_toc_level0, 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 D.2. Setting the section depth at which tables of contents appear
ignored_translationses-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, “Preparing a document for translation”, and to Appendix G, Language codes.
img_dirimages)
info_filelicensemax_image_widthImportant — 444 pixels is the maximum safe width
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.
mainfile<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.
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.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.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_urlimage_left.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican.
product<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<pubsnumber> in the Book_Info.xml file when you package a document. This value must include only digits (‘0’–‘9’).
reporev_fileRevision_History.xml.
scmSVN as its default setting. Refer to Section 6.2, “Distributed sets”.
show_remarks<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_ordersrc_urlSource: field in the header of an RPM spec file. Refer to Section 4.8, “Packaging a document”.
tmp_dirtmp, which creates a directory named tmp inside the directory that holds your article or book.
tmpl_path/usr/share/publican/templates.
toc_jstoc.tmpl is in. The template name must be must be of the form toc_type+.tmpl
toc_typetoc-$toc_type.tmpl in /usr/share/publican/templates. You can override this by setting an alternative path with tmpl_path.
toc_section_depth2. 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 D.3. Controlling the depth of sections in the main table of contents
type<article>, DocBook <book>, or DocBook <set>, as set by the --type option for $ publican create.
version<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_distdocs-5E, representing documentation packages for Red Hat Enterprise Linux 5. Refer to Section 4.8, “Packaging a document”.
web_formats$ publican package command”.
web_homeImportant — web_home is deprecated
web_home is replaced by web_type: home. Support for web_home will be removed in a future version of Publican.
web_name_labelweb_obsoletesweb_product_labelweb_style1 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_typeweb_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_labelUNUSED for general documentation that does not apply to any particular version of a product. Refer to Chapter 7, Building a website with Publican.
wkhtmltopdf_optswkhtmltopdf_opts: "-O landscape -s A3"
xml_langen-US, as set by the --lang option for $ publican create.