$
publican create
command to create a new document, including all the necessary files for the document.
$
publican create
command accepts several options, detailed in this chapter. When an option can accept a value, separate the option from the value with a space or an equals sign; for example, publican create --name New_Book
or publican create --name=New_Book
.
--help
$
publican create
command options.
--name Doc_Name
$
create_book --name Test_Book
creates a book named Test_Book
with all the necessary files to build the book, and sets the BOOKID
in the Test_Book.ent
file.
--lang Language_Code
en-US
(American English). The --lang
option sets the xml_lang
in the publican.cfg
file and creates a directory with this name in the document directory. When initially created, this directory contains some boilerplate XML files. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg
parameters and Appendix G, Language codes for more detail on language codes.
--version version
5.1
. The default version is 0.1
. The --version
option sets the <productnumber>
tag in the Book_Info.xml
or Article_Info.xml
file. For more information refer to Section 4.1.2, “Book_Info.xml”.
--edition edition
1.0
. The default value is 0
. The --edition
option sets the <edition>
tag in the Book_Info.xml
or Article_Info.xml
file. For more information refer to Section 4.1.2, “Book_Info.xml”.
--product Product_Name
Fedora
for core Fedora documentation, and the name of the product for other products, for example, Fedora_Directory_Server
. The default value is Documentation
. The --product
option sets the <product name>
tag in the Book_Info.xml
file or Article_Info.xml
file and the PRODUCT
entity in the Doc_Name.ent
file.
--type Article --name Article_Name
--type
option sets the type
in the publican.cfg
file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg
parameters.
--type Set --name Set_Name
--type
option sets the type
in the publican.cfg
file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg
parameters and to Chapter 6, Using sets for details on using sets.
--brand brand
RedHat
, fedora
, JBoss
, oVirt
, or GIMP
. The default value is common
, a default brand shipped with Publican. The --brand
option sets the brand
parameter in the publican.cfg
file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg
parameters. This option requires the appropriate Publican brand package to be installed. For example, to build Red Hat branded books, you must install the publican-redhat package. Refer to Section 5.1, “Installing a brand” for instructions on installing brand packages for Publican. If you do not specify a brand, Publican uses its built-in, default brand. Refer to Chapter 5, Branding for more information.
$
publican create
command, use the $
cd
command to change into the directory where you want the book to be created. For example, to create a book named Test_Book
in the my_books/
directory, run the following commands:
$
cd my_books/
$
publican create --name Test_Book
$
ls
Test_Book/
Test_Book/
directory on a computer with a Linux operating system, run the following:
$
cd Test_Book/
$
ls
en-US/ publican.cfg
$
publican create --name Test_Book --lang en-US
, Publican creates a directory structure and required files, similar to the following:
publican.cfg
en-US
(directory)
Test_Book.xml
Test_Book.ent
Revision_History.xml
Preface.xml
Chapter.xml
Book_Info.xml
Author_Group.xml
images
(directory)
icon.svg
Note — Customizing output
--config
to specify a configuration file other than the publican.cfg
file and therefore a different set of parameters to use in a particular build. For example:
$
publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
publican.cfg
file configures build options, and is located in the root of the book directory. The following is an example publican.cfg
file, with a description of publican.cfg
parameters following afterwards:
# Config::Simple 4.59 # Wed Jul 18 13:00:40 2012 xml_lang: "en-US" type: Book brand: common
Default parameters
xml_lang
en-US
, as set by the --lang
option for $
publican create
.
type
<article>
, DocBook <book>
, or DocBook <set>
, as set by the --type
option for $
publican create
.
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.
Advanced 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
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 4.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
Note
<edition>
tag was required by versions of Publican prior to 2.0, which used it to generate the version of a documentation package. This tag is now completely optional and does not affect packaging in any way.
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 4.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 4.3. Controlling the depth of sections in the main table of contents
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"
Help from the command line
$
publican help_config
command in the root directory of a book for a summary of these parameters.
Article_Info.xml
and Set_Info.xml
Book_Info.xml
file applies to Article_Info.xml
and Set_Info.xml
files too. However, for the sake of simplicity, the file is referred to as Book_Info.xml
throughout this section.
Packages other than RPM packages
$
publican package
command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package
on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
Book_Info.xml
file contains the key metadata concerning a book: the book's ID; title; subtitle; author and edition number. It also contains the name and version of the product that is documented, and an abstract.
Book_Info.xml
must have appropriate data within them, and that data must conform to the requirements of the RPM format. You can override the data in these tags by using equivalent fields in the publican.cfg
file, as discussed in this section.
publican.cfg
file, data from seven of the default tags in Book_Info.xml
is required to build books as RPMs. Most immediately, the file name of a book built as an RPM package is constructed as follows:
productname-title-productnumber-language-edition-pubsnumber.src.rpm
Book_Info.xml
— you specify language when you build the book. As well, the <subtitle>
and <abstract>
are used in the RPM spec file, to provide the Summary:
field in the header and the %description
field, respectively.
Book_Info.xml
file, for the Test_Book
book, is presented below. Details regarding this file, and what the RPM format requirements are for each tag, follow.
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent"> %BOOK_ENTITIES; ]> <bookinfo conformance="121" id="book-Publican-Users_Guide-Users_Guide" lang="en-US"> <title>Users' Guide</title> <subtitle>Publishing books, articles, papers and multi-volume sets with DocBook XML</subtitle> <productname>&PRODUCT;</productname> <productnumber>&PRODUCTNUM;</productnumber> <abstract> <para> This book will help you install <application>&PRODUCT;</application>. It also provides instructions for using Publican to create and publish DocBook XML-based books, articles and book sets. This guide assumes that you are already familiar with DocBook XML. </para> </abstract> <keywordset> <keyword>publican</keyword> <keyword>docbook</keyword> <keyword>publishing</keyword> </keywordset> <subjectset scheme="libraryofcongress"> <subject> <subjectterm>Electronic Publishing</subjectterm> </subject> <subject> <subjectterm>XML (Computer program language)</subjectterm> </subject> </subjectset> <corpauthor> <inlinemediaobject> <imageobject> <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> </imageobject> <textobject> <phrase>Team &PRODUCT;</phrase> </textobject> </inlinemediaobject> </corpauthor> <mediaobject role="cover"> <imageobject remap="lrg" role="front-large"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="s" role="front"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="xs" role="front-small"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="cs" role="thumbnail"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> </mediaobject> <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo>
<bookinfo id="book_id">
, <articleinfo id="article_id">
, <setinfo id="set_id">
$
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>
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.
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.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 hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
<title>title</title>
<title>Server Configuration Guide</title>
). 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.
docname
parameter in the publican.cfg
file to set a name for the document in ASCII characters. When you build the document, the title appears as you set it with the <title>
tag, but when you package the document, the value that you used in the docname
parameter is used in the file name of the RPM package.
Permitted characters
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 hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
<title>
tag to find the file that contains the root XML node: <article>
, <book>
, or <set>
. For example, if you set the title to <title>Server Configuration Guide</title>
, Publican expects the root XML node to be in a file named Server_Configuration_Guide.xml
and the document entities to be in a file named Server_Configuration_Guide.ent
. To use a different name for these files, set the mainfile
parameter in the document configuration file (by default, publican.cfg
). Refer to Section 4.1.1, “The publican.cfg file”.
<subtitle>subtitle</subtitle>
Summary
in the RPM spec file. The rpm -qi
command returns the contents of several spec file fields, including the Summary
field.
<productnumber>productnumber</productnumber>
$
publican create --name Doc_Name --version version
command correctly configures the product number.
version
variable in the publican.cfg
file if the product version is anything other than a number.
Permitted characters
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>
$
publican package
command.
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
.
$
publican create --name Doc_Name --edition x.y
command correctly configures the edition.
edition
variable in the publican.cfg
file if the edition of your document is identified by anything other than a number.
Permitted characters
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>
$
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
.
release
variable in the publican.cfg
file if the release number of your document contains anything other than whole numbers.
Permitted characters
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>
Description
field of the RPM's spec file. This makes the abstract for a package available via the rpm -qi
command.
Book_Info.xml
file of a document, to support specific features in various output formats:
<keywordset>
, <keyword>
<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>
<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.
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">
<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>
images
subdirectory.
Book_Info.xml
used by Publican includes an <edition>
tag.
Book_Info.xml
also includes the <pubsnumber>
tag. Any data placed within this tag changes the release number of RPM-packaged books.
<productnumber>
tag also found in Book_Info.xml
: <productnumber>
denotes the version number of the product being documented or otherwise written about.
<pubsnumber>
tag, not the <edition>
tag. It functions as a near-equivalent to the impression or printing number of traditional publishing.
Author_Group.xml
is not required but is the standard place to record author, editor, artist and other credit details. The following is an example Author_Group.xml
file:
<?xml version='1.0'?> <!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <authorgroup> <corpauthor>FF0000 Headgear Documentation Group</corpauthor> <author> <firstname>Dude</firstname> <surname>McDude</surname> <affiliation> <orgname>My Org</orgname> <orgdiv>Best Div in the place</orgdiv> </affiliation> <email>dude.mcdude@myorg.org</email> </author> </authorgroup>
Author_Group.xml
does not have to contain all of the above information: include as much or as little as required.
Articles and chapters
--type=article
option with $
publican create
, Publican does not create a Chapter.xml
file. Use sections to organize content within articles.
Chapter.xml
file is a template for creating chapter files. Chapter files contain the content that make up a book. The following is a chapter template (Chapter.xml
) that is created by the $
publican create
command. Note the DOCTYPE
is set to chapter
:
<?xml version='1.0'?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="MYBOOK-Test"> <title>Test</title> <para> This is a test paragraph </para> <section id="MYBOOK-Test-Section_1_Test"> <title>Section 1 Test</title> <para> Test of a section </para> </section> <section id="MYBOOK-Test-Section_2_Test"> <title>Section 2 Test</title> <para> Test of a section </para> </section> </chapter>
Section 1 Test
and Section 2 Test
. Refer to http://docbook.org/tdg/en/html/chapter.html for further information about chapters.
Note
Installation.xml
, whereas a chapter on setting up a piece of software would be better called Setup.xml
or Configuration.xml
.
Doc_Name.xml
file contains xi:include
directives to include the other necessary XML files for the document, including chapters or sections contained in other XML files. For example, a book's Doc_Name.xml
file brings together chapters that are contained in separate XML files.
Doc_Name.xml
file that describes a DocBook book — note the DOCTYPE
is set to book
.
Example 4.4. A DocBook book
<?xml version='1.0'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <book> <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <index /> </book>
Book_Info.xml
, Preface.xml
, Chapter.xml
, and Appendix.xml
XML files.
Important
Book_Info.xml
will precede Preface.xml
which will precede Chapter.xml
, and so on.
Doc_Name.xml
file is not limited to using xi:include
directives. You can create documents with a single XML file. The following is an example of a book created using a single XML file:
<book> <chapter> <title>Chapter 1</title> <para> A paragraph in Chapter 1. </para> <section id="section1"> <title>Chapter 1 Section 1</title> <para> A paragraph in Section 1. </para> </section> <section id="section2"> <title>Chapter 1 Section 2</title> <para> A paragraph in Section 2. </para> </section> </chapter> <chapter> <title>Chapter 2</title> <para> A paragraph in Chapter 2. </para> </chapter> </book>
Doc_Name.ent
file is used to define local entities. The YEAR
and HOLDER
entities are used for copyright information. By default, Publican sets YEAR
to the current year, and inserts a message into HOLDER
to remind you to specify the copyright holder for the document. If the YEAR
and HOLDER
entities are missing altogether, the document will not build.
BOOKID
to specify how readers should refer to a document when they submit feedback about it.
<!ENTITY PRODUCT "MYPRODUCT"> <!ENTITY BOOKID "MYBOOK"> <!ENTITY YEAR "2008"> <!ENTITY HOLDER "YOUR NAME GOES HERE">
Use entities with extreme caution
&FDS;
instead of Fedora Directory Server saves the writer time but transformed entities do not appear in the portable object (PO) files that translators use. Complete translations of documents containing entities are, as a consequence, impossible.
<!ENTITY LIFT "Liberty Installation and Formatting Tome">
— you can enter &LIFT;
in your XML and it will appear as Liberty Installation and Formatting Tome
every time the book is built as HTML, PDF or text.
Liberty Installation and Formatting Tome
. Instead they see &LIFT;
, which they cannot translate.
As noted in the Liberty Installation and Formatting Tome, Chapter 3…
Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr ""
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr "Wie in <citetitle>&LIFT;</citetitle>, Kapitel 3, erwähnt…"
Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…
However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr ""
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle>&LIFT;</citetitle>, dass…"
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…
&PRODUCT;
. The advantage of this approach is that by simply changing this value in the Doc_Name.ent
file, you could easily adjust the book to document (for example) Red Hat Enterprise Linux, Fedora, or CentOS. However, while the proper noun Fedora
never varies in English, it has multiple forms in other languages. For example, in Czech the name Fedora
has six different forms, depending on one of seven ways in which you can use it in a sentence:
Table 4.1. 'Fedora' in Czech
Case | Usage | Form |
---|---|---|
Nominative | the subject of a sentence | Fedora |
Genitive | indicates possession | Fedory |
Accusative | the direct object of a sentence | Fedoru |
Dative | the indirect object of a sentence | Fedoře |
Vocative | the subject of direct address | Fedoro |
Locative | relates to a location | Fedoře |
Instrumental | relates to a method | Fedorou |
me
and she
is not correct. Me
is the accusative form of the pronoun, but because it is the subject of the sentence, the pronoun should take the nominative form, I
. Similarly, she
is nominative case, but as the direct object of the sentence the pronoun should take its accusative form, her
.
Doc_Name.ent
file, entities might prove useful for version numbers of products. Beyond that, the use of entities is tantamount to a conscious effort to inhibit and reduce the quality of translations. Furthermore, readers of your document in a language that inflects nouns (whether for case, definiteness, or other reasons) will not know that the bad grammar is the result of XML entities that you set — they will probably assume that the translator is incompetent.
$
publican package
command searches for the first XML file in the document's XML directory containing a <revhistory>
tag. Publican then uses that file to build the RPM revision history.
images
subdirectory in the directory that holds your XML files. Use ./images/image-name
to insert images into a book. The following is an example that inserts the testimage.png
image:
<mediaobject> <imageobject> <imagedata fileref="./images/testimage.png" /> </imageobject> <textobject><phrase>alternate text goes here</phrase></textobject> </mediaobject>
<textobject>
so that your content remains accessible to people with visual impairments. In certain jurisdictions, you might have a legal responsibility to provide this accessibility — for example, if you or your organization must comply with Section 508 of the United States Rehabilitation Act of 1973.
[1]
images
subdirectories for each language directory. Make sure that the image file in the translated language has the same name as the image file in the original language. When you build the book in the translated language, Publican uses the file from the images/
subdirectory of the translated language instead of the file from the images/
subdirectory of the original language.
<imagedata>
tag. For example, to set an image width to 670 pixels:
<imagedata fileref=".images/image.png" width="670px">
Image file locations
images
subdirectory of your XML directory and corresponding images in the images
subdirectories of your translated languages. Images stored in other directories directories do not work.
PNG files in PDF documents
Add alpha channel
, the option might be labeled Add transparency
instead.
extras/
in your source language directory and use an <xi:include>
to pull the code file into the XML structure of your document. Publican does not parse any files that it finds in the extras/
directory as XML.
&
and <
. If you insert code samples directly into the XML of your document, you must escape these characters, either by marking them as CDATA
or by replacing them with entities (& and < respectively).
[2] If you place these files in the extras/
directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.
extras/
directory in your document, follow this procedure:
$
mkdir
en-US/extras
$
cp
~/samples/foo.c en-US/extras/.
xi:include
the sample file in your xml file
<programlisting> <xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting>
en-US/extras/foo.c
in your favorite editor without having to be concerned about how it will affect the XML.
<programlistingco> <areaspec> <area id="orbit-for-parameter" coords='4 75'/> <area id="orbit-for-magnitude" coords='12 75'/> </areaspec> <programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <calloutlist> <callout id="callout-for-parameter" arearefs="orbit-for-parameter"> <para> The <firstterm>standard gravitational parameter</firstterm> (μ) is a derived value, the product of Newton's gravitational constant (G) and the mass of the primary body. </para> </callout> <callout id="callout-for-magnitude" arearefs="orbit-for-magnitude"> <para> Since the mass of the orbiting body is many orders of magnitude smaller than the mass of the primary body, the mass of the orbiting body is ignored in this calculation. </para> </callout> </calloutlist> </programlistingco>
<area>
elements that define the position of the callouts that will appear on the code sample. The coords
attributes specify a line number and a column number separated by a space. In this example, callouts are applied to lines 4 and 12 of the code, lined up with each other in column 75. Although this approach means that you might have to adjust coords
attributes if you ever modify the code to which they apply, it avoids mixing XML <coords>
tags into the code itself.
files
in the language directory for the original language (e.g. en-US
) of the book (e.g. My_Book
).
My_Book
:
$
mkdir en-US/files
files
:
$
cp arbitrary_files en-US/files
$
publican rename
command makes it easy for you to rename a document to give it a new title, or to change the name or version of the product to which the document applies. The command accepts up to three options:
--name
new_title$
publican rename --name "Server Deployment Guide"
<title>
tag in the Article_Info.xml
, Book_Info.xml
, or Set_Info.xml
file, and sets a value for the mainfile
parameter in the publican.cfg
file so that Publican can still find the root XML node and the entities for the document.
$
publican rename
command does not change any file names. Therefore, the root XML node and the document entities are still located in files named after the original title of the document — Server_Configuration_Guide
in the previous example.
--product
new_product$
publican rename --product PendantFarm
<productname>
tag in the Article_Info.xml
, Book_Info.xml
, or Set_Info.xml
file.
--version
new_version$
publican rename --version 2.0
<productnumber>
tag in the Article_Info.xml
, Book_Info.xml
, or Set_Info.xml
file.
$
publican rename --name "Server Deployment Guide" --product PendantFarm --version 2.0
$
publican trans_drop
trans_drop/
. The trans_drop/
subdirectory contains a snapshot of the source files of the document. When the trans_drop/
directory is present in a documentation project, Publican uses its content as the basis for the commands documented later in this procedure.
$
publican update_pot
pot
. The pot
subdirectory holds a POT file for each XML file in the document. If Publican has created POT files for this document previously, Publican updates the existing POT files to reflect any changes in the XML since the POT files were last updated.
Remove unused XML files
$
publican print_unused
command to generate a list of XML files that are not used in your document.
$
publican update_po --langs=language_code
$
publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN
--langs=
option. This subdirectory holds a PO file for each POT file in pot
subdirectory, plus a Revision_History.xml
file that tracks the history of this particular translation. When created for the first time, the Revision_History.xml
file records the date on which the PO files for this translation were created, and the version of the source language XML (taken from the source language's Revision_History.xml
file) on which this translation is therefore based.
Revision_History.xml
file to record the date on which the PO files for this translation were refreshed, and the version of the source language XML on which the revision is based. You can update existing PO files in every subdirectory with the --langs=all
option:
$
publican update_po --langs=all
Remove unused POT files
pot
directory, whether the POT file is based on a corresponding XML file that is used in the document or not, or whether a corresponding XML file even exists. If you transform POT files for unused or deleted XML files into PO files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
publican add_revision
command to describe your changes or corrections. Publican updates the Revision_History.xml
file for you.
publican trans_drop
, publican update_pot
, and publican update_po
commands as described earlier in this procedure instead.
$
publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
$
publican package --lang=is-IS
--langs=all
option, but note that you must package each language individually. Refer to Section 4.7, “Building a document” for more information on building a document, and Section 4.8, “Packaging a document” on packaging a document.
$translation/Author_Group.xml
and add a valid DocBook authorgroup. The translator can add their details to this file and Publican will append it to $source_lang/Author_Group.xml
when the book is build. This allows authors to finalize the original text without needing to know who will translate the book.
<glossentry>
elements into a book's glossary; and <primary>
, <secondary>
, and <tertiary>
<indexterm>
elements into a book's index. Entries are sorted automatically, and although this system works well for languages written with an alphabet, abugida, or syllabic script, languages written with logograms sort less well.
sortas
attribute to the XML element. For example, to ensure that the Japanese word 暗号化 sorts correctly in an index, specify:
#. Tag: indexterm #, no-c-format msgid "<primary>encryption</primary>" msgstr "<primary sortas="あんごうか">暗号化</primary>"
#. Tag: glossentry #, no-c-format msgid "<glossterm>encryption</glossterm>" msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"
Note — Customizing output
publican.cfg
) allow you to control many aspects of the way in which a document is presented — refer to Section 4.1.1, “The publican.cfg file”.
--config
to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
$
publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
YEAR
and HOLDER
entities have been configured in the Doc_Name.ent
file, as described in Section 4.1.6, “Doc_Name.ent”.
Test_Book
and is located in the ~/books/
directory, run the following command:
$
cd ~/books/Test_Book
$
publican build --formats=test --langs=en-US
$
publican build --formats=formats --langs=languages
html,html-single,pdf
. Replace langs with a comma-separated list of the languages that you want to build; for example, en-US,sv-SE,uk-UA,ko-KR
.
Formats for the build
action
html
chunk_first
and chunk_section depth
parameters in the publican.cfg
file to control how Publican chunks sections in this format.
html-single
html-desktop
man
pdf
test
txt
epub
eclipse
id
, name
, and provider-name
parameters with Publican's ec_id
, ec_name
, and ec_provider
parameters.
$
publican build
commands:
$
publican build --help
$
publican build
options for building a book.
$
publican build --formats=test --langs=languages
--formats=test
before running any other $
publican build
command, and before checking a book back into a version-controlled repository from which other contributors might download it.
$
publican build --formats=html --langs=languages
Doc_Name/tmp/language/html/
directory. Each chapter and major section is placed in a separate HTML file. You can control the depth at which Publican places subsections into separate HTML files with the chunk-section-depth
parameter in the publican.cfg
— refer to Section 4.1.1, “The publican.cfg file”.
$
publican build --formats=html-single --langs=languages
Doc_Name/tmp/language/html-single/
directory.
$
publican build --formats=pdf --langs=languages
Doc_Name/tmp/language/pdf/
directory.
$
publican build --formats=html,html-single,pdf --langs=languages
<xref>
s) to sections of the document that do not yet exist. To skip validation, run $
publican build
with the --novalid
option. Cross-references to non-existent content appear in the built document as three question marks: ???
.
--novalid
option is highly suspect. Do not publish documentation that you have built with the --novalid
option.
Packages other than RPM packages
$
publican package
command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package
on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
Note — Customizing output
publican.cfg
) allow you to control many aspects of the way in which a document is presented and packaged — refer to Section 4.1.1, “The publican.cfg file”.
--config
to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
$
publican package --lang hi-IN --config community.cfg
/usr/share/doc/
, the location specified by the Filesystem Hierarchy Standard (FHS) for ‘Miscellaneous documentation’.
[3] The desktop RPM package also contains a desktop file, to be placed in /usr/share/applications/
. This file enables desktop environments to add the installed document to their menus for ease of reference by users. By default, the menu item appears under → on the GNOME desktop. To customize the placement of the menu item, create a documentation menu package to supply .directory
and .menu
files and set the dt_requires
and menu_category
parameters in the publican.cfg
file to require this package and supply the appropriate menu category. Refer to Section 4.8.1.3, “Desktop menu entries for documents”
web_formats
parameter. The value of this parameter overrides the default formats that Publican packages. For example, to publish the document only as single-page HTML, PDF, and text, set web_formats: "html-single,pdf,txt"
/var/www/html/
, a common document root for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.
.directory
) file that provides metadata about the new submenu.
.menu
) file that defines the position of the new submenu within the menu.
.directory
file for Publican-generated documentation is as follows:
[Desktop Entry]
Name
parameter, set to the name of the submenu that you want to place under the menu.
Name
parameter, in the format Name[language_code]
where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.
Comment
parameter, set to a description of the new submenu.
Comment
parameter, in the format Comment[language_code]
where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.
Type
parameter, set to Directory
.
Encoding
parameter, set to UTF-8
.
Example 4.5. Example .directory file
menu-example.directory
illustrates the structure of a desktop entry file.
[Desktop Entry] Name=Example Name[fr]=Exemple Name[it]=Esempio Comment=Example Documentation menu Comment[fr]=Exemple d'une menu de documentation Comment[it]=Esempio di un menù di documentazione Type=Directory Encoding=UTF-8
/usr/share/desktop-directories/
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
, that contains:
<Name>
element with the content Documentation
<Menu>
element that in turn contains:
<Name>
element with the content Documentation
(just like the root element)
<Directory>
element with its content the name of the desktop entry file you created, for example:
<Directory>menu-example.directory</Directory>
<Includes>
element with the content X-category_name
, where category_name is an identifier for the documents that will be grouped together under this menu entry. For example:
<Includes>X-Example-Docs</Includes>
Example 4.6. Example .menu file
menu-example.menu
illustrates the structure of a desktop menu file.
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"> <Menu> <Name>Documentation</Name> <Menu> <Name>Documentation</Name> <Menu> <Name>Example</Name> <Directory>menu-example.directory</Directory> <Include> <Category>X-Example-Docs</Category> </Include> </Menu> </Menu> </Menu>
/etc/xdg/menus/settings-merged/
menu_category
parameter in its publican.cfg
file to match the content of the <Includes>
element in the corresponding desktop menu file. For example, consider a desktop menu file that contains the element:
<Includes>X-Example-Docs</Includes>
publican.cfg
file should contain:
menu_category: X-Example-Docs
Important
__LANG__
with the current language. This allows menus to be customized on a per language basis.
menu_category: X-Example-Docs-__LANG__
defaults.cfg
file or overrides.cfg
file of a brand so that all documents built with that brand are grouped into this submenu automatically without you having to set the menu_category
parameter in each document.
dt_requires
parameter in the document's publican.cfg
file. For example, if you ship a desktop menu package named foodocs-menu, set:
dt_requires: foodocs-menu
defaults.cfg
file or overrides.cfg
file of a brand so that all documents built with that brand require the same desktop menu package.
$
publican package
command$
publican package --lang=Language_Code
command to package documents for distribution in the language that you specify with the --lang
option. Refer to Appendix G, Language codes for more information about language codes.
$
publican package
with no options other than the mandatory --lang
option, Publican produces a web SRPM package. The full range of options for publican package
is as follows:
--lang
languageIncomplete translations
ignored_translations
parameter in the document's publican.cfg
file. The package will be named appropriately for the language, but will contain documentation in the original language of the XML rather than a partial translation. When translation is complete, remove the ignored_translations
parameter, increase the release number in the Project-Id-Version
field in the Book_Info.po
file for that language, and generate the package again. When you distribute the revised package, it becomes available to replace the original untranslated package.
--config
filenamepublican.cfg
file.
--desktop
--brew
--scratch
--brew
and --desktop
options, specifies that an SRPM package should be built as a scratch build when sent to Brew. Scratch builds are used to verify that an SRPM package is structured correctly, without updating the package database to use the resulting package.
--short_sighted
version
in the publican.cfg
file) in the package name.
Omitting the software version number
--binary
$
publican package
command, Publican outputs completed SRPM packages to the document's tmp/rpm
directory, and completed binary RPM packages to the document's tmp/rpm/noarch
directory.
productname-title-productnumber-[web]-language-edition-pubsnumber. [.[build_target].noarch].file_extension
.
publican.cfg
) to supply the various parameters in the file name, and then information in the Book_Info.xml
file for any parameters missing from the configuration file. Refer to Section 4.1, “Files in the book directory” for details of the parameters used in these files. Additionally, note that:
-web-
between the product version and the language code.
.src.rpm
but binary RPM packages have the file extension .rpm
build_target.noarch
before the file extension, where build_target represents the operating system and version that the package is built for as set by the os_ver
parameter in the publican.cfg
file. The noarch
element specifies that the package can be installed on any system, regardless of the system architecture.
--short_sighted
option removes the -productnumber-
from the package name.
Project-Id-Version
parameter in the Article_Info.po
or Book_Info.po
file. This release number is specific to a particular language and bears no relationship to the release numbers of the same document in the original language or any other language.
$
publican package
command — Example usage$
publican package --lang=cs-CZ
$
publican package --desktop --lang=cs-CZ
$
publican package --binary --lang=cs-CZ
$
publican package --desktop --binary --lang=cs-CZ
$
publican package --desktop --short_sighted --lang=cs-CZ
$
condition
. For example, let's say the book How To Use Product Foo has an "upstream", "enterprise", and "beta" version:
<para condition="upstream"> <application>Foo</application> starts automatically when you boot the system. </para> <para condition="enterprise"> <application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>. </para> <para condition="beta"> <application>Foo</application> does not start automatically when you boot the system. </para> <para condition="beta,enterprise"> To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file. </para>
$
condition: version
parameter to the publican.cfg
file and run the $
publican build
command as normal. For example, if you add condition: upstream
to the publican.cfg
file of How To Use Product Foo and run:
$
publican build --formats=pdf --langs=en-US
condition="upstream"
and builds How To Use Product Foo in as a PDF file in American English.
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">
.
Use conditional tagging with great caution
#. Tag: para #, no-c-format msgid "<application>Foo</application> starts automatically when you boot the system." msgstr "" #. Tag: para #, no-c-format msgid "<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>." msgstr "" #. Tag: para #, no-c-format msgid "<application>Foo</application> does not start automatically when you boot the system." msgstr "" #. Tag: para #, no-c-format msgid "To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file." msgstr ""
publican.cfg
file and are aware of the valid conditions for your book, they cannot proofread their work. Without that knowledge, when translators proofread a document, they will wonder why they cannot find text that they know they translated and can find easily in the PO file. If you must use conditionals in your book, you must be prepared to provide a greater degree of support to your translators than you would otherwise provide.
upstream.cfg
file might contain the condition condition: upstream
and the enterprise.cfg
file might contain the condition condition: enterprise
. You could then specify the version of the document to build or package with the --config
; for example, $
publican package --lang en-US --config upstream.cfg
. Using two separate config files saves you from having to edit the one config file each time you build or package a document.
<subtitle>
tag in your Book_Info.xml
file. Place this additional text in <remark>
tags. For example:
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
show_remarks
to the publican.cfg
file and set it to '1':
show_remarks: 1
<remark>
tag and the show_remarks
setting in place, the pre-release nature of the software is displayed clearly and unmistakably. PDF builds display the remark on their cover and title pages. HTML builds (both single-page HTML and multiple-page HTML) display the remark near the beginning of index.html
.
Book_Info.xml
used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.
Important
<remark>
tag and its contents and remove or turn off show_remarks
when documentation is updated for use with the release version of the software.
status="draft"
attribute to the <article>
, <book>
or <set>
tag in your document's root node. For example:
<book status="draft">
<book>
tag in your Doc_Name.xml
file.
<article>
or <set>
tag in Doc_Name.xml
.
status="draft"
attribute causes each page of the document to show the draft watermark. This is by design.