$
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.