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.
--helppublican create command options.
--name Doc_Namecreate_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_Codeen-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 F, Language codes for more detail on language codes.
--version version5.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 edition1.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_NameFedora 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 brandRedHat, 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
lsTest_Book/Test_Book/ directory on a computer with a Linux operating system, run the following:
cd Test_Book/ls
en-US/ publican.cfgpublican 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.cfgpublican.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_langen-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.
brandRedHat, 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
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">.
booksbrew_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 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.
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
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 ‘.’).
generate_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 4.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 F, Language codes.
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.
show_unknown1, so Publican reports unknown tags. Set this value to 0 to hide this output. Publican ignores this parameter in strict mode.
sort_ordersrc_urlSource: field in the header of an RPM spec file. Refer to Section 4.8, “Packaging a document”.
strictstrict parameter is set of 0, which disables strict mode. To enable strict mode, set this parameter to 1 Strict mode is not currently enforced.
tmp_dirtmp, which creates a directory named tmp inside the directory that holds your article or book.
tmpl_path/usr/share/publican/templates.
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 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_distdocs-5E, representing documentation packages for Red Hat Enterprise Linux 5. Refer to Section 4.8, “Packaging a document”.
web_formatspublican 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_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.
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-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>Publican</productname> <productnumber>3.0</productnumber> <abstract> <para> This book will help you install <application>Publican</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 Publican</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/extrascp ~/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/filesfiles:
cp arbitrary_files en-US/filespublican 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_titlepublican 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_productpublican rename --product PendantFarm<productname> tag in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file.
--version new_versionpublican 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 update_potpot. 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. If Publican has created PO files for this language previously, Publican updates the existing PO files to reflect any changes in the POT files since the PO files were last updated. You can update existing PO files in every subdirectory with the --langs=all option:
$ publican update_po --langs=allRemove 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 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.
Important — set Project-Id-Version for packaging
Project-Id-Version parameter in the Article_Info.po or Book_Info.po file. For example, release 3 of a book in Japanese would have the following set at the start of the ja-JP/Book_Info.po file:
"Project-Id-Version: 3\n"
$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.
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.cfgYEAR 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_Bookpublican build --formats=test --langs=en-USpublican build --formats=formats --langs=languageshtml,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
htmlchunk_first and chunk_section depth parameters in the publican.cfg file to control how Publican chunks sections in this format.
html-singlehtml-desktopmanpdftesttxtepubeclipseid, name, and provider-name parameters with Publican's ec_id, ec_name, and ec_provider parameters.
publican build commands:
publican build --helppublican 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=languagesDoc_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=languagesDoc_Name/tmp/language/html-single/ directory.
publican build --formats=pdf --langs=languagesDoc_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
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 commandpublican package --lang=Language_Code command to package documents for distribution in the language that you specify with the --lang option. Refer to Appendix F, 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_sightedversion in the publican.cfg file) in the package name.
Omitting the software version number
--binarypublican 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 usagepublican package --lang=cs-CZpublican package --desktop --lang=cs-CZpublican package --binary --lang=cs-CZpublican package --desktop --binary --lang=cs-CZpublican package --desktop --short_sighted --lang=cs-CZcondition. 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.