publican.cfg
parameterspublican.cfg
parameters
arch
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
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">
.
books
brand
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.
brew_dist
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
<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
chunk_first: 1
. Otherwise, the parameter defaults to 0
, and the first section appears on the same page of its chapter.
chunk_section_depth
4
.
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
.
condition
Root 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">
.
confidential
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
confidential
parameter is set to 1
. The default text is CONFIDENTIAL
.
debug
0
, Publican does not display debugging messages. Change this value to 1
to view these messages.
def_lang
doc_url
image_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_obsoletes
dt_requires
dtdver
A different DTD might slow your build
dtd_type
Note
dtd_uri
Note
ec_id
plugin
directory.
ec_name
ec_provider
edition
<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_dir
extras
)
footer
generate_section_toc_level
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 D.2. Setting the section depth at which tables of contents appear
ignored_translations
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
images
)
info_file
license
max_image_width
Important — 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_url
image_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’).
repo
rev_dir
asc
or ascending
.
rev_file
Revision_History.xml
.
scm
SVN
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_order
src_url
Source:
field in the header of an RPM spec file. Refer to Section 4.8, “Packaging a document”.
tmp_dir
tmp
, which creates a directory named tmp
inside the directory that holds your article or book.
tmpl_path
/usr/share/publican/templates
.
toc_js
toc.tmpl
is in. The template name must be must be of the form toc_type+.tmpl
toc_type
toc-$toc_type.tmpl
in /usr/share/publican/templates
. You can override this by setting an alternative path with tmpl_path
.
toc_section_depth
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 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_dist
docs-5E
, representing documentation packages for Red Hat Enterprise Linux 5. Refer to Section 4.8, “Packaging a document”.
web_formats
$
publican package
command”.
web_home
Important — 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_label
web_obsoletes
web_product_label
web_style
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
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
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
wkhtmltopdf_opts: "-O landscape -s A3"
xml_lang
en-US
, as set by the --lang
option for $
publican create
.