[web] Update PUG
Rüdiger Landmann
rlandmann at fedoraproject.org
Wed Jul 7 01:26:07 UTC 2010
commit 710be17dbe286709a415b4106cbe5c8f43fd02a8
Author: Ruediger Landmann <r.landmann at redhat.com>
Date: Wed Jul 7 11:25:44 2010 +1000
Update PUG
fedoradocs.db | Bin 349184 -> 349184 bytes
public_html/Sitemap | 8 +-
...tributor_Documentation-1-Users_Guide-en-US.epub | Bin 340890 -> 353125 bytes
.../Users_Guide/Common_Content/css/common.css | 48 +-
.../Users_Guide/Common_Content/css/lang.css | 2 +
.../1/html-single/Users_Guide/index.html | 700 +++++++++++++-------
.../html/Users_Guide/Common_Content/css/common.css | 48 +-
.../1/html/Users_Guide/Common_Content/css/lang.css | 2 +
.../appe-Users_Guide-Command_summary.html | 40 +-
...s_Guide-Disallowed_elements_and_attributes.html | 12 +-
.../appe-Users_Guide-Language_codes.html | 36 +-
.../appe-Users_Guide-Revision_History.html | 2 +-
.../appe-Users_Guide-publican.cfg_parameters.html | 18 +-
.../Users_Guide/chap-Users_Guide-Branding.html | 90 ++--
.../chap-Users_Guide-Creating_a_document.html | 173 +++---
...hap-Users_Guide-Frequently_Asked_Questions.html | 89 ++--
.../chap-Users_Guide-Installing_Publican.html | 34 +-
.../chap-Users_Guide-Publican_commands.html | 32 +-
.../Users_Guide/chap-Users_Guide-Using_sets.html | 10 +-
.../1/html/Users_Guide/index.html | 6 +-
.../Users_Guide/pref-Users_Guide-Introduction.html | 9 +-
.../html/Users_Guide/pref-Users_Guide-Preface.html | 16 +-
.../html/Users_Guide/sect-Users_Guide-Website.html | 160 +++++
...ntributor_Documentation-1-Users_Guide-en-US.pdf | Bin 527623 -> 566103 bytes
24 files changed, 981 insertions(+), 554 deletions(-)
---
diff --git a/fedoradocs.db b/fedoradocs.db
index d95ec56..db52776 100644
Binary files a/fedoradocs.db and b/fedoradocs.db differ
diff --git a/public_html/Sitemap b/public_html/Sitemap
index 12d11c7..4eeba4e 100644
--- a/public_html/Sitemap
+++ b/public_html/Sitemap
@@ -2570,25 +2570,25 @@
</url>
<url>
<loc>http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/epub/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.epub</loc>
- <lastmod>2010-05-22</lastmod>
+ <lastmod>2010-07-07</lastmod>
<changefreq>monthly</changefreq>
<priority>0.8</priority>
</url>
<url>
<loc>http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/index.html</loc>
- <lastmod>2010-05-22</lastmod>
+ <lastmod>2010-07-07</lastmod>
<changefreq>monthly</changefreq>
<priority>0.8</priority>
</url>
<url>
<loc>http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/index.html</loc>
- <lastmod>2010-05-22</lastmod>
+ <lastmod>2010-07-07</lastmod>
<changefreq>monthly</changefreq>
<priority>0.8</priority>
</url>
<url>
<loc>http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/pdf/Users_Guide/Publican-1.6-Users_Guide-en-US.pdf</loc>
- <lastmod>2010-05-22</lastmod>
+ <lastmod>2010-07-07</lastmod>
<changefreq>monthly</changefreq>
<priority>0.8</priority>
</url>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/epub/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.epub b/public_html/en-US/Fedora_Contributor_Documentation/1/epub/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.epub
index 8753c6c..7d12221 100644
Binary files a/public_html/en-US/Fedora_Contributor_Documentation/1/epub/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.epub and b/public_html/en-US/Fedora_Contributor_Documentation/1/epub/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.epub differ
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/common.css b/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/common.css
index e1f4d9f..a196f22 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/common.css
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/common.css
@@ -50,7 +50,8 @@ body.desktop .book > .toc {
line-height:1.35em;
}
-.toc .chapter, .toc .appendix, .toc .glossary {
+.toc .glossary,
+.toc .chapter, .toc .appendix {
margin-top:1em;
}
@@ -59,7 +60,8 @@ body.desktop .book > .toc {
display:block;
}
-span.appendix, span.glossary {
+span.glossary,
+span.appendix {
display:block;
margin-top:0.5em;
}
@@ -346,7 +348,6 @@ a.version:focus, a.version:hover {
clear:both;
}
-
/*revision history*/
.revhistory {
display:block;
@@ -362,34 +363,24 @@ a.version:focus, a.version:hover {
}
.revhistory td {
- text-align:right;
+ text-align :left;
padding:0em;
border: none;
border-top: 1px solid #fff;
+ font-weight: bold;
}
-
-.revhistory tr td:first-child {
- text-align:left;
+.revhistory .simplelist td {
+ font-weight: normal;
}
-.revhistory tr td p, .revhistory tr td div.para {
- text-align:left;
- font-weight:bold;
- display:block;
- margin:0em;
- padding:0em;
- padding-bottom:0.7em;
- border-bottom:1px solid #eee;
+.revhistory .simplelist {
+ margin-bottom: 1.5em;
+ margin-left: 1em;
}
.revhistory table th {
- background-color:transparent;
- color:#336699;
- font-size:2em;
- padding: 1em 0em;
- border: none;
- border-bottom:1px solid #eee;
+ display: none;
}
@@ -901,6 +892,10 @@ th, td {
border: 1px solid #000;
}
+.simplelist th, .simplelist td {
+ border: none;
+}
+
table table td {
border-bottom:1px dotted #aaa;
background-color:white;
@@ -964,6 +959,10 @@ span.chapter {
margin-top:0.5em;
}
+table.simplelist td, .calloutlist table td {
+ border-style: none;
+}
+
/*Breadcrumbs*/
#breadcrumbs ul li.first:before {
content:" ";
@@ -1007,7 +1006,8 @@ span.chapter {
margin-bottom:1em;
}
-.glossary dt, .index dt {
+.glossary dt,
+.index dt {
color:#444;
padding-top:.5em;
}
@@ -1375,10 +1375,6 @@ pre {
border-radius: 15px;
}
-.term{
- color:#336699;
-}
-
.package, .citetitle {
font-style: italic;
}
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/lang.css b/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/lang.css
index e69de29..81c3115 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/lang.css
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/Common_Content/css/lang.css
@@ -0,0 +1,2 @@
+/* place holder */
+
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/index.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/index.html
index 1e1f7ed..ea3ceb9 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/index.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html-single/Users_Guide/index.html
@@ -1,18 +1,18 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Users Guide</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="description" content="This book will help you install Publican. 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." /><meta name="keywords" content="publican, docbook, publishing" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</if
rame></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><div xml:lang="en-US" class="book" title="Users Guide" lang="en-US"><div class="titlepage"><div><div class="producttitle"><span class="productname">Publican</span> <span class="productnumber">1.6</span></div><div><h1 id="id536678" class="title">Users Guide</h1></div><div><h2 class="subtitle">Publishing books, articles, papers and multi-volume sets with DocBook XML</h2></div><p class="edition">Edition 1.6</p><div><h3 class="corpauthor">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Users Guide</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="description" content="This book will help you install Publican. 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." /><meta name="keywords" content="publican, docbook, publishing" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</ifr
ame></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><div xml:lang="en-US" class="book" title="Users Guide" id="id419332" lang="en-US"><div class="titlepage"><div><div class="producttitle"><span class="productname">Publican</span> <span class="productnumber">2.0</span></div><div><h1 id="id419332" class="title">Users Guide</h1></div><div><h2 class="subtitle">Publishing books, articles, papers and multi-volume sets with DocBook XML</h2></div><p class="edition">Edition 1.0</p><div><h3 class="corpauthor">
<span class="inlinemediaobject"><object data="Common_Content/images/title_logo.svg" type="image/svg+xml"> Team Publican</object></span>
</h3></div><div><div xml:lang="en-US" class="authorgroup" lang="en-US"><div class="author"><h3 class="author"><span class="firstname">Don</span> <span class="surname">Domingo</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:ddomingo at redhat.com">ddomingo at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Brian</span> <span class="surname">Forté</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:bforte at redhat.com">bforte at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Rüdiger</span> <span class="surname">Landmann</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Serv
ices</span></div><code class="email"><a class="email" href="mailto:r.landmann at redhat.com">r.landmann at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Joshua</span> <span class="surname">Oakes</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:joakes at redhat.com">joakes at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Joshua</span> <span class="surname">Wulf</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:jwulf at redhat.com">jwulf at redhat.com</a></code></div><div class="editor"><h4 class="editedby">Edited by</h4><h3 class="editor"><span class="firstname">Brian</span> <span class="surname">Forté</span></h3><div class="affiliation"><s
pan class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:bforte at redhat.com">bforte at redhat.com</a></code></div><div class="editor"><h4 class="editedby">Edited by</h4><h3 class="editor"><span class="firstname">Rüdiger</span> <span class="surname">Landmann</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:r.landmann at redhat.com">r.landmann at redhat.com</a></code></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Jeff</span> <span class="surname">Fearn</span></h3><span class="contrib">Extensive review, rough drafts, persistent annoyances.</span> <div class="affiliation"><span class="shortaffil"> <span class="inlinemediaobject"><img src="images/logos/engops.png" alt="Red Hat, Engineering Operations Logo" /></span>
- <br /></span></div><code class="email"><a class="email" href="mailto:jfearn at redhat.com">jfearn at redhat.com</a></code></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Josef</span> <span class="surname">Hruška</span></h3><span class="contrib">Checking the Czech examples in Entities and translation</span> <div class="affiliation"><span class="orgname">Fedora</span> <span class="orgdiv">Localization Project</span></div></div></div></div><hr /><div><div id="id625026" class="legalnotice"><h1 class="legalnotice">Legal Notice</h1><div class="para">
+ <br /></span></div><code class="email"><a class="email" href="mailto:jfearn at redhat.com">jfearn at redhat.com</a></code></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Josef</span> <span class="surname">Hruška</span></h3><span class="contrib">Checking the Czech examples in Entities and translation</span> <div class="affiliation"><span class="orgname">Fedora</span> <span class="orgdiv">Localization Project</span></div></div></div></div><hr /><div><div id="id413835" class="legalnotice"><h1 class="legalnotice">Legal Notice</h1><div class="para">
Copyright <span class="trademark"></span>© 2009 Red Hat, Inc This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at <a href="http://www.gnu.org/licenses/fdl.txt">http://www.gnu.org/licenses/fdl.txt</a>).
</div></div></div><div><div class="abstract" title="Abstract"><h6>Abstract</h6><div class="para">
This book will help you install <span class="application"><strong>Publican</strong></span>. 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.
- </div></div></div></div><hr /></div><div class="toc"><dl><dt><span class="preface"><a href="#pref-Users_Guide-Preface">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#id597254">1. Document Conventions</a></span></dt><dd><dl><dt><span class="section"><a href="#id597231">1.1. Typographic Conventions</a></span></dt><dt><span class="section"><a href="#id723731">1.2. Pull-quote Conventions</a></span></dt><dt><span class="section"><a href="#id702097">1.3. Notes and Warnings</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Preface-We_Need_Feedback">2. We Need Feedback!</a></span></dt></dl></dd><dt><span class="preface"><a href="#pref-Users_Guide-Introduction">Introduction</a></span></dt><dt><span class="chapter"><a href="#chap-Users_Guide-Installing_Publican">1. Installing Publican</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux_operating_systems">1.1. Inst
alling Publican on Linux operating systems</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Fedora">1.1.1. Installing Publican on Fedora</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Red_Hat_Enterprise_Linux_5">1.1.2. Installing Publican on Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Ubuntu">1.1.3. Installing Publican on Ubuntu</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Debian">1.1.4. Installing Publican on Debian</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Windows_operating_systems">1.2. Installing Pu
blican on Windows operating systems</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Publican_commands">2. Publican commands</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Publican_commands-Command_options">2.1. Command options</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Publican_commands-Actions">2.2. Actions</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Creating_a_document">3. Creating a document</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a hre
f="#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Preparing_a_document_for_translation">3.3. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document">3.4. Building a
document</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.4.1. Building a document created with Publican 0</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book">3.5. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.5.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.5.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging">3.6. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.6.1. Conditional tagging and translation</a></span></dt></dl></dd><dt><span class="se
ction"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.7. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.7.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.7.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.7.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Branding">4. Branding</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</a></span></dt><dt><span class="se
ction"><a href="#sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. CO
PYING</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Using_sets">5. Using sets</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distrib
uted sets</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Frequently_Asked_Questions">6. Frequently Asked Questions</a></span></dt><dt><span class="appendix"><a href="#appe-Users_Guide-Disallowed_elements_and_attributes">A. Disallowed elements and attributes</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements">A.1. Disallowed elements</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes">A.2. Disallowed attributes</a></span></dt></dl></dd><dt><span class="appendix"><a href="#appe-Users_Guide-Command_summary">B. Command summary</a></span></dt><dt><span class="appendix"><a href="#appe-Users_Guide-publican.cfg_parameters">C. publican.cfg parameters</a></span></dt><dt><span class="appendix"><a href="#appe-Users_Guide-Language_codes">D. Language codes</a></span></dt><dt><span class="appendix"><a href="
#appe-Users_Guide-Revision_History">E. Revision History</a></span></dt></dl></div><div xml:lang="en-US" class="preface" title="Preface" id="pref-Users_Guide-Preface" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Preface</h1></div></div></div><div xml:lang="en-US" class="section" title="1. Document Conventions" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="id597254">1. Document Conventions</h2></div></div></div><div class="para">
+ </div></div></div></div><hr /></div><div class="toc"><dl><dt><span class="preface"><a href="#pref-Users_Guide-Preface">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#id447500">1. Document Conventions</a></span></dt><dd><dl><dt><span class="section"><a href="#id447474">1.1. Typographic Conventions</a></span></dt><dt><span class="section"><a href="#id538203">1.2. Pull-quote Conventions</a></span></dt><dt><span class="section"><a href="#id538162">1.3. Notes and Warnings</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Preface-We_Need_Feedback">2. We Need Feedback!</a></span></dt></dl></dd><dt><span class="preface"><a href="#pref-Users_Guide-Introduction">Introduction</a></span></dt><dt><span class="chapter"><a href="#chap-Users_Guide-Installing_Publican">1. Installing Publican</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux">1.1. Linux operating system
s</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Fedora">1.1.1. Fedora</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5">1.1.2. Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Ubuntu">1.1.3. Ubuntu</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Debian">1.1.4. Debian</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican-Windows_operating_systems">1.2. Windows operating systems</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Publican_commands">2. Publican commands</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Publican_commands-Command_options">2.1. Command options</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Publican_
commands-Actions">2.2. Actions</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Creating_a_document">3. Creating a document</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt
><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Adding_files">3.3. Adding files</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Preparing_a_document_for_translation">3.4. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document">3.5. Building a document</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.5.1. Building a document created with Publican 0</a></span></dt></dl></dd><dt><span class="section"><a href="#
sect-Users_Guide-Packaging_a_book">3.6. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.6.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.6.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging">3.7. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.7.1. Conditional tagging and translation</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.8. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre
_release_software">3.8.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.8.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.8.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Branding">4. Branding</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</a></span></dt><dd><dl><dt><span class="section"><a href=
"#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directo
ry-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Using_sets">5. Using sets</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</a></span></dt></dl></dd><dt><span class="chapter"><a href="#sect-Users_Guide-Website">6. Building a website with Publican</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Website-structure">6.1. The website structure</a></spa
n></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-cfg_and_db">6.1.1. Creating the website structure</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-home_page">6.2. The home page</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-documents">6.3. Installing, updating and removing documents</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-documents-manual">6.3.1. Installing, updating and removing documents manually</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-documents-rpm">6.3.2. Installing, updating and removing documents as RPM packages</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Website-automation">6.4. Automating publishing</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Users_Guide-Frequently_Asked_Questions">7. Frequen
tly Asked Questions</a></span></dt><dt><span class="appendix"><a href="#appe-Users_Guide-Disallowed_elements_and_attributes">A. Disallowed elements and attributes</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements">A.1. Disallowed elements</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes">A.2. Disallowed attributes</a></span></dt></dl></dd><dt><span class="appendix"><a href="#appe-Users_Guide-Command_summary">B. Command summary</a></span></dt><dt><span class="appendix"><a href="#appe-Users_Guide-publican.cfg_parameters">C. publican.cfg parameters</a></span></dt><dt><span class="appendix"><a href="#appe-Users_Guide-Language_codes">D. Language codes</a></span></dt><dt><span class="appendix"><a href="#appe-Users_Guide-Revision_History">E. Revision History</a></span></dt></dl></div><div xml:lang="en-US" class="preface" title=
"Preface" id="pref-Users_Guide-Preface" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Preface</h1></div></div></div><div xml:lang="en-US" class="section" title="1. Document Conventions" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="id447500">1. Document Conventions</h2></div></div></div><div class="para">
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
</div><div class="para">
In PDF and paper editions, this manual uses typefaces drawn from the <a href="https://fedorahosted.org/liberation-fonts/">Liberation Fonts</a> set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
- </div><div class="section" title="1.1. Typographic Conventions"><div class="titlepage"><div><div><h3 class="title" id="id597231">1.1. Typographic Conventions</h3></div></div></div><div class="para">
+ </div><div class="section" title="1.1. Typographic Conventions"><div class="titlepage"><div><div><h3 class="title" id="id447474">1.1. Typographic Conventions</h3></div></div></div><div class="para">
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
</div><div class="para">
<code class="literal">Mono-spaced Bold</code>
@@ -60,14 +60,12 @@
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Publican is a <em class="firstterm">DocBook</em> publishing system.
- </div></blockquote></div></div><div class="section" title="1.2. Pull-quote Conventions"><div class="titlepage"><div><div><h3 class="title" id="id723731">1.2. Pull-quote Conventions</h3></div></div></div><div class="para">
+ </div></blockquote></div></div><div class="section" title="1.2. Pull-quote Conventions"><div class="titlepage"><div><div><h3 class="title" id="id538203">1.2. Pull-quote Conventions</h3></div></div></div><div class="para">
Terminal output and source code listings are set off visually from the surrounding text.
</div><div class="para">
Output sent to a terminal is set in <code class="computeroutput">mono-spaced roman</code> and presented thus:
</div><pre class="screen">books Desktop documentation drafts mss photos stuff svn
-books_tests Desktop1 downloads images notes scripts svgs
-
-</pre><div class="para">
+books_tests Desktop1 downloads images notes scripts svgs</pre><div class="para">
Source-code listings are also set in <code class="computeroutput">mono-spaced roman</code> but add syntax highlighting as follows:
</div><pre class="programlisting">package org.<span class="perl_Function">jboss</span>.<span class="perl_Function">book</span>.<span class="perl_Function">jca</span>.<span class="perl_Function">ex1</span>;
@@ -87,9 +85,7 @@ books_tests Desktop1 downloads images notes scripts svgs
System.<span class="perl_Function">out</span>.<span class="perl_Function">println</span>(<span class="perl_String">"Echo.echo('Hello') = "</span> + echo.<span class="perl_Function">echo</span>(<span class="perl_String">"Hello"</span>));
}
-}
-
-</pre></div><div class="section" title="1.3. Notes and Warnings"><div class="titlepage"><div><div><h3 class="title" id="id702097">1.3. Notes and Warnings</h3></div></div></div><div class="para">
+}</pre></div><div class="section" title="1.3. Notes and Warnings"><div class="titlepage"><div><div><h3 class="title" id="id538162">1.3. Notes and Warnings</h3></div></div></div><div class="para">
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
</div><div class="note"><h2>Note</h2><div class="para">
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
@@ -97,16 +93,17 @@ books_tests Desktop1 downloads images notes scripts svgs
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' won't cause data loss but may cause irritation and frustration.
</div></div><div class="warning"><h2>Warning</h2><div class="para">
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
- </div></div></div></div><div class="section" title="2. We Need Feedback!" id="sect-Users_Guide-Preface-We_Need_Feedback"><div class="titlepage"><div><div><h2 class="title">2. We Need Feedback!</h2></div></div></div><a id="id685749" class="indexterm"></a><div class="para">
+ </div></div></div></div><div class="section" title="2. We Need Feedback!" id="sect-Users_Guide-Preface-We_Need_Feedback"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Preface-We_Need_Feedback">2. We Need Feedback!</h2></div></div></div><a id="id554705" class="indexterm"></a><div class="para">
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: <a href="https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&version=rawhide&component=publican">https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&version=rawhide&component=publican</a> against the product <span class="application"><strong>fedora</strong></span>. When submitting a bug report, be sure to mention the manual's identifier: <em class="citetitle">publican</em>
</div><div class="para">
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
- </div></div></div><div xml:lang="en-US" class="preface" title="Introduction" id="pref-Users_Guide-Introduction" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Introduction</h1></div></div></div><div class="para">
- <a id="id702239" class="indexterm"></a>
- <span class="application"><strong>Publican</strong></span> is a tool for publishing material authored in DocBook XML. This guide explains how to create and build books and articles using <span class="application"><strong>Publican</strong></span>. It is not a general DocBook XML tutorial; refer to <em class="citetitle">DocBook: The Definitive Guide</em> by Norman Walsh and Leonard Muellner, available at <a href="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</a> for more general help with DocBook XML.
+ </div></div></div><div xml:lang="en-US" class="preface" title="Introduction" id="pref-Users_Guide-Introduction" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Introduction</h1></div></div></div><a id="id451307" class="indexterm"></a><div class="para">
+ <a id="id461966" class="indexterm"></a>
+ <span class="application"><strong>Publican</strong></span> <a id="id494941" class="indexterm"></a>
+ is a tool for publishing material authored in DocBook XML. This guide explains how to create and build books and articles using <span class="application"><strong>Publican</strong></span>. It is not a general DocBook XML tutorial; refer to <em class="citetitle">DocBook: The Definitive Guide</em> by Norman Walsh and Leonard Muellner, available at <a href="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</a> for more general help with DocBook XML.
</div><div class="para">
<span class="application"><strong>Publican</strong></span> began life as an internal tool used by Red Hat's Documentation Group (now known as Engineering Content Services). On occasion, this legacy is visible.
- </div><div class="formalpara"><h5 class="formalpara">Design</h5>
+ </div><div class="formalpara" id="form-Users_Guide-Introduction-Design"><h5 class="formalpara">Design</h5>
<span class="application"><strong>Publican</strong></span> is a publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, <span class="application"><strong>Publican</strong></span> works to ensure your XML is up to publishable standard.
</div><div class="para">
The branding functionality allows you to create your own presentation rules and look, overriding many parts of the default style to meet your publishing needs. Choices executed in code, however, are not changeable.
@@ -116,21 +113,19 @@ books_tests Desktop1 downloads images notes scripts svgs
As publishing workflows grow, unrestrained entity definition leads to entity duplication and other practices that cause maintenance difficulties. Consolidating entity definitions in a single, predictable place alleviates these maintenance issues and helps the automation of the build process stay robust.
</div><div class="para">
Entities also present an essentially insurmountable obstacle to quality translation (refer to <a class="xref" href="#sect-Users_Guide-Entities_and_translation" title="3.1.6.1. Entities and translation">Section 3.1.6.1, “Entities and translation”</a>). Consequently, while we are not reducing the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> file's functionality, we are no longer considering requests to add functionality or features associated with entity use.
- </div></div><div xml:lang="en-US" class="chapter" title="Chapter 1. Installing Publican" id="chap-Users_Guide-Installing_Publican" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 1. Installing Publican</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux_operating_systems">1.1. Installing Publican on Linux operating systems</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Fedora">1.1.1. Installing Publican on Fedora</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Red_Hat_Enterprise_Linux_5">1.1.2. Installing Publican on Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Pu
blican_on_Ubuntu">1.1.3. Installing Publican on Ubuntu</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Debian">1.1.4. Installing Publican on Debian</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Windows_operating_systems">1.2. Installing Publican on Windows operating systems</a></span></dt></dl></div><div class="section" title="1.1. Installing Publican on Linux operating systems" id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux_operating_systems"><div class="titlepage"><div><div><h2 class="title">1.1. Installing Publican on Linux operating systems</h2></div></div></div><div class="important"><h2>Important — Availability in repositories</h2><div class="para">
+ </div></div><div xml:lang="en-US" class="chapter" title="Chapter 1. Installing Publican" id="chap-Users_Guide-Installing_Publican" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 1. Installing Publican</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux">1.1. Linux operating systems</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Fedora">1.1.1. Fedora</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5">1.1.2. Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Ubuntu">1.1.3. Ubuntu</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Linux_operating_systems-Debian">1.1.4. Debian</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-I
nstalling_Publican-Windows_operating_systems">1.2. Windows operating systems</a></span></dt></dl></div><div class="section" title="1.1. Linux operating systems" id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux">1.1. Linux operating systems</h2></div></div></div><div class="important"><h2>Important — Availability in repositories</h2><div class="para">
The procedures documented in this section assume that <span class="application"><strong>Publican</strong></span> and its various dependencies are available in repositories to which your system has access.
- </div></div><div class="section" title="1.1.1. Installing Publican on Fedora" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Fedora"><div class="titlepage"><div><div><h3 class="title">1.1.1. Installing Publican on Fedora</h3></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ </div></div><div class="section" title="1.1.1. Fedora" id="sect-Users_Guide-Linux_operating_systems-Fedora"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Fedora">1.1.1. Fedora</h3></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Open a terminal.
</div></li><li class="step" title="Step 2"><div class="para">
Change to the root user: <code class="command"> su - </code>
</div></li><li class="step" title="Step 3"><div class="para">
Run the following command to install the <span class="package">publican</span> package and the <span class="package">publican-doc</span> documentation package:
- </div><pre class="screen"><code class="command"> yum install publican publican-doc</code>
-</pre></li></ol></div><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican publican-doc</code></pre></li></ol></div><div class="para">
Several brand packages are available for use with <span class="application"><strong>Publican</strong></span>. Run the following command as the root user to install packages for building branded books:
- </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code></pre><div class="para">
Replace <em class="replaceable"><code>brand</code></em> with, for example, <code class="literal">redhat</code>, <code class="literal">fedora</code>, <code class="literal">jboss</code>, <code class="literal">ovirt</code>, or <code class="literal">gimp</code>. Refer to <a class="xref" href="#chap-Users_Guide-Branding" title="Chapter 4. Branding">Chapter 4, <i>Branding</i></a> for more information on branding.
- </div></div><div class="section" title="1.1.2. Installing Publican on Red Hat Enterprise Linux 5" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Red_Hat_Enterprise_Linux_5"><div class="titlepage"><div><div><h3 class="title">1.1.2. Installing Publican on Red Hat Enterprise Linux 5</h3></div></div></div><div class="important"><h2>Important — Unsupported software</h2><div class="para">
+ </div></div><div class="section" title="1.1.2. Red Hat Enterprise Linux 5" id="sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5">1.1.2. Red Hat Enterprise Linux 5</h3></div></div></div><div class="important"><h2>Important — Unsupported software</h2><div class="para">
<span class="application"><strong>Publican</strong></span> is not part of the Red Hat Enterprise Linux distribution. Therefore, Red Hat does not offer support for <span class="application"><strong>Publican</strong></span>.
</div></div><div class="important"><h2>Important — Dependencies available only internally to Red Hat</h2><div class="para">
Installing <span class="application"><strong>Publican</strong></span> on Red Hat Enterprise Linux 5 requires a number of dependencies that are presently available only in yum repositories that are internal to Red Hat.
@@ -140,20 +135,17 @@ books_tests Desktop1 downloads images notes scripts svgs
Change to the root user: <code class="command"> su - </code>
</div></li><li class="step" title="Step 3"><div class="para">
Run the following command to install the <span class="package">publican</span> package and the <span class="package">publican-doc</span> documentation package:
- </div><pre class="screen"><code class="command"> yum install publican publican-doc</code>
-</pre></li></ol></div><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican publican-doc</code></pre></li></ol></div><div class="para">
Several brand packages are available for use with <span class="application"><strong>Publican</strong></span>. Run the following command as the root user to install packages for building branded books:
- </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code></pre><div class="para">
Replace <em class="replaceable"><code>brand</code></em> with, for example, <code class="literal">redhat</code>, <code class="literal">fedora</code>, <code class="literal">jboss</code>, <code class="literal">ovirt</code>, or <code class="literal">gimp</code>. Refer to <a class="xref" href="#chap-Users_Guide-Branding" title="Chapter 4. Branding">Chapter 4, <i>Branding</i></a> for more information on branding.
- </div></div><div class="section" title="1.1.3. Installing Publican on Ubuntu" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Ubuntu"><div class="titlepage"><div><div><h3 class="title">1.1.3. Installing Publican on Ubuntu</h3></div></div></div><div class="important"><h2> Important — New in 10.4 "Lucid Lynx"</h2><div class="para">
+ </div></div><div class="section" title="1.1.3. Ubuntu" id="sect-Users_Guide-Linux_operating_systems-Ubuntu"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Ubuntu">1.1.3. Ubuntu</h3></div></div></div><div class="important"><h2> Important — New in 10.4 "Lucid Lynx"</h2><div class="para">
<span class="application"><strong>Publican</strong></span> is new in Ubuntu 10.4 "Lucid Lynx".
</div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Open a terminal.
</div></li><li class="step" title="Step 2"><div class="para">
Run the following command to install the <span class="package">publican</span> package:
- </div><pre class="screen"><code class="command">sudo apt-get install publican</code>
-</pre></li></ol></div></div><div class="section" title="1.1.4. Installing Publican on Debian" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Debian"><div class="titlepage"><div><div><h3 class="title">1.1.4. Installing Publican on Debian</h3></div></div></div><div class="warning"><h2> Warning — Complete this procedure </h2><div class="para">
+ </div><pre class="screen"><code class="command">sudo apt-get install publican</code></pre></li></ol></div></div><div class="section" title="1.1.4. Debian" id="sect-Users_Guide-Linux_operating_systems-Debian"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Debian">1.1.4. Debian</h3></div></div></div><div class="warning"><h2> Warning — Complete this procedure </h2><div class="para">
Complete every step of this procedure. If you do not undo the changes that you make to the <code class="filename">/etc/apt/sources.list</code> file as described, your system might become unstable.
</div></div><div class="para">
<span class="application"><strong>Publican</strong></span> is not available in the current stable version of Debian (version 5.0, "Lenny"), but is available in the current testing version ("Squeeze"). To install <span class="application"><strong>Publican</strong></span> on a computer that runs Debian, temporarily enable access to the <code class="literal">squeeze</code> repository. When you enable access to this repository, you allow your computer to install newer software and newer versions of existing software than what is available in the current stable version of Debian. However, not all of the software available in the testing repository has completed quality assurance testing yet. If you do not disable access to this repository after you install <span class="application"><strong>Publican</strong></span>, the next time that your system updates, it will replace software packages on your system with newer but possibly untested versions of those packages that it downlo
ads from the testing repository.
@@ -161,8 +153,7 @@ books_tests Desktop1 downloads images notes scripts svgs
Open a terminal.
</div></li><li class="step" title="Step 2"><div class="para">
Open your <code class="filename">/etc/apt/sources.list</code> file in a text editor. For example, to edit the file in <span class="application"><strong>gedit</strong></span> run:
- </div><pre class="screen"><code class="command">sudo gedit /etc/apt/sources.list</code>
-</pre></li><li class="step" title="Step 3"><div class="para">
+ </div><pre class="screen"><code class="command">sudo gedit /etc/apt/sources.list</code></pre></li><li class="step" title="Step 3"><div class="para">
Add the following line to the end of the file:
</div><pre class="programlisting">deb http://ftp.debian.org/debian/ squeeze main
@@ -170,17 +161,15 @@ books_tests Desktop1 downloads images notes scripts svgs
Save the file and close the text editor.
</div></li><li class="step" title="Step 5"><div class="para">
Run the following command to update the list of packages available to your computer:
- </div><pre class="screen"><code class="command">sudo apt-get update</code>
-</pre></li><li class="step" title="Step 6"><div class="para">
+ </div><pre class="screen"><code class="command">sudo apt-get update</code></pre></li><li class="step" title="Step 6"><div class="para">
Run the following command to install the <span class="package">publican</span> package:
- </div><pre class="screen"><code class="command">sudo apt-get install publican</code>
-</pre></li><li class="step" title="Step 7"><div class="para">
+ </div><pre class="screen"><code class="command">sudo apt-get install publican</code></pre></li><li class="step" title="Step 7"><div class="para">
Open your <code class="filename">/etc/apt/sources.list</code> file again, and delete the extra line that you added in this procedure.
</div></li></ol></div><div class="para">
Note that until the release of "Squeeze" as the stable version of Debian, you must manually enable and disable access to the testing repository as described in this procedure whenever a new version of <span class="application"><strong>Publican</strong></span> becomes available in the testing repository. You can find up-to-date information about the status of <span class="application"><strong>Publican</strong></span> for Debian at <a href="http://packages.debian.org/squeeze/publican">http://packages.debian.org/squeeze/publican</a>, including the version number of <span class="application"><strong>Publican</strong></span> available in the repository (1.0 at the time of writing).
</div><div class="para">
When "Squeeze" becomes the stable version of Debian, you will not need to enable or disable access to extra repositories to install <span class="application"><strong>Publican</strong></span> on systems that run that version of the operating system.
- </div></div></div><div class="section" title="1.2. Installing Publican on Windows operating systems" id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Windows_operating_systems"><div class="titlepage"><div><div><h2 class="title">1.2. Installing Publican on Windows operating systems</h2></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ </div></div></div><div class="section" title="1.2. Windows operating systems" id="sect-Users_Guide-Installing_Publican-Windows_operating_systems"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Installing_Publican-Windows_operating_systems">1.2. Windows operating systems</h2></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Download the Publican installer from <a href="https://fedorahosted.org/releases/p/u/publican/">https://fedorahosted.org/releases/p/u/publican/</a>.
</div></li><li class="step" title="Step 2"><div class="para">
Browse to the folder to which you downloaded <code class="filename">Publican-Installer-<em class="replaceable"><code>version</code></em>.exe</code>.
@@ -216,7 +205,7 @@ books_tests Desktop1 downloads images notes scripts svgs
Some <em class="replaceable"><code>command_options</code></em> affect the output of <em class="replaceable"><code>actions</code></em>, for example, whether <span class="application"><strong>Publican</strong></span> should use ANSI colors in its output.
</div></dd></dl></div>
- </div><div class="section" title="2.1. Command options" id="sect-Users_Guide-Publican_commands-Command_options"><div class="titlepage"><div><div><h2 class="title">2.1. Command options</h2></div></div></div><div class="para">
+ </div><div class="section" title="2.1. Command options" id="sect-Users_Guide-Publican_commands-Command_options"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Publican_commands-Command_options">2.1. Command options</h2></div></div></div><div class="para">
The options for the <code class="command">publican</code> command are:
<div class="variablelist"><dl><dt><span class="term"><code class="option">--help</code></span></dt><dd><div class="para">
This option displays a help message, a condensed version of the contents of this chapter.
@@ -234,10 +223,10 @@ books_tests Desktop1 downloads images notes scripts svgs
This option disables all logging.
</div></dd></dl></div>
- </div></div><div class="section" title="2.2. Actions" id="sect-Users_Guide-Publican_commands-Actions"><div class="titlepage"><div><div><h2 class="title">2.2. Actions</h2></div></div></div><div class="para">
+ </div></div><div class="section" title="2.2. Actions" id="sect-Users_Guide-Publican_commands-Actions"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Publican_commands-Actions">2.2. Actions</h2></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> can perform the following actions:
<div class="variablelist"><dl><dt><span class="term">build</span></dt><dd><div class="para">
- transforms XML to other formats (for example: PDF, single-page HTML, or multiple-page HTML). Refer to <a class="xref" href="#sect-Users_Guide-Building_a_document" title="3.4. Building a document">Section 3.4, “Building a document”</a> for more details and a description of the available options.
+ transforms XML to other formats (for example: PDF, single-page HTML, or multiple-page HTML). Refer to <a class="xref" href="#sect-Users_Guide-Building_a_document" title="3.5. Building a document">Section 3.5, “Building a document”</a> for more details and a description of the available options.
</div></dd><dt><span class="term">clean</span></dt><dd><div class="para">
removes all files and folders in the <code class="filename">tmp/</code> subdirectory. The <code class="filename">tmp/</code> subdirectory is created after running the <code class="command">publican build</code> command to build a document, such as <code class="command">publican build --formats=html --langs=en-US</code>.
</div></dd><dt><span class="term">clean_ids</span></dt><dd><div class="para">
@@ -246,37 +235,47 @@ books_tests Desktop1 downloads images notes scripts svgs
To make translation easier, <code class="command">make clean_ids</code> uses the first four characters of the tag as a prefix for the ID. Consequently, you must check out the latest versions of the XML source and translations before running this command.
</div><div class="para">
If you do not have the current versions of the PO files checked out before running <code class="command">make clean_ids</code>, the XML and PO files will no longer in synchrony with each other. In this case, all links in the PO files must be manually updated.
- </div></div></dd><dt><span class="term">cleanset</span></dt><dd><div class="para">
+ </div></div></dd><dt><span class="term">clean_set</span></dt><dd><div class="para">
removes local copies of remote books in a distributed set. Refer to <a class="xref" href="#sect-Users_Guide-Using_sets-Distributed_sets" title="5.2. Distributed sets">Section 5.2, “Distributed sets”</a> for details of using distributed sets.
</div></dd><dt><span class="term">create</span></dt><dd><div class="para">
creates a new book, article, or set. Refer to <a class="xref" href="#chap-Users_Guide-Creating_a_document" title="Chapter 3. Creating a document">Chapter 3, <i>Creating a document</i></a> for details of creating a book or article, and to <a class="xref" href="#chap-Users_Guide-Using_sets" title="Chapter 5. Using sets">Chapter 5, <i>Using sets</i></a> for details of using sets.
</div></dd><dt><span class="term">create_brand</span></dt><dd><div class="para">
creates a new brand. Refer to <a class="xref" href="#sect-Users_Guide-Creating_a_brand" title="4.2. Creating a brand">Section 4.2, “Creating a brand”</a> for details of creating a brand.
+ </div></dd><dt><span class="term">create_site</span></dt><dd><div class="para">
+ creates a documentation website. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
</div></dd><dt><span class="term">help_config</span></dt><dd><div class="para">
displays help text for the configuration file contained in each book or brand, <code class="filename">publican.cfg</code>. Refer to <a class="xref" href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a> for more detail.
- </div></dd><dt><span class="term">installbrand</span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">install_book</span></dt><dd><div class="para">
+ installs a document on a documentation website. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
+ </div></dd><dt><span class="term">install_brand</span></dt><dd><div class="para">
configures a brand for installation. Refer to <a class="xref" href="#sect-Users_Guide-Installing_a_brand" title="4.1. Installing a brand">Section 4.1, “Installing a brand”</a> for details of installing a brand.
</div></dd><dt><span class="term">lang_stats --lang=<em class="replaceable"><code>language_code</code></em></span></dt><dd><div class="para">
generates a translation report for the language specified by <em class="replaceable"><code>language_code</code></em>.
</div></dd><dt><span class="term">old2new</span></dt><dd><div class="para">
- creates a <code class="filename">publican.cfg</code> file based on the <code class="filename">Makefile</code> of a book, article, or set originally created with a developmental version of <span class="application"><strong>Publican</strong></span> (versions up to and including <span class="application"><strong>Publican 0.45</strong></span>). Refer to <a class="xref" href="#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0" title="3.4.1. Building a document created with Publican 0">Section 3.4.1, “Building a document created with Publican 0”</a> for more detail.
+ creates a <code class="filename">publican.cfg</code> file based on the <code class="filename">Makefile</code> of a book, article, or set originally created with a developmental version of <span class="application"><strong>Publican</strong></span> (versions up to and including <span class="application"><strong>Publican 0.45</strong></span>). Refer to <a class="xref" href="#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0" title="3.5.1. Building a document created with Publican 0">Section 3.5.1, “Building a document created with Publican 0”</a> for more detail.
</div></dd><dt><span class="term">package</span></dt><dd><div class="para">
- packages a book, article, set, or brand for shipping as an RPM package. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a> and <a class="xref" href="#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more detail.
+ packages a book, article, set, or brand for shipping as an RPM package. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a> and <a class="xref" href="#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more detail.
</div></dd><dt><span class="term">print_banned</span></dt><dd><div class="para">
prints a list of DocBook tags banned by <span class="application"><strong>Publican</strong></span>. Refer to <a class="xref" href="#appe-Users_Guide-Disallowed_elements_and_attributes" title="Appendix A. Disallowed elements and attributes">Appendix A, <i>Disallowed elements and attributes</i></a> for a discussion of banned tags.
</div></dd><dt><span class="term">print_known</span></dt><dd><div class="para">
prints a list of DocBook tags supported by <span class="application"><strong>Publican</strong></span>. <em class="firstterm">Supported</em> are those tags whose output has undergone at least cursory verification for quality when used in <span class="application"><strong>Publican</strong></span> — refer to <a class="xref" href="#appe-Users_Guide-Disallowed_elements_and_attributes" title="Appendix A. Disallowed elements and attributes">Appendix A, <i>Disallowed elements and attributes</i></a>.
- </div></dd><dt><span class="term">printtree</span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">print_tree</span></dt><dd><div class="para">
prints a tree of the XML files included with the <code class="sgmltag-element"><xi:include></code> tag in a book, article, or set.
</div></dd><dt><span class="term">print_unused</span></dt><dd><div class="para">
prints a list of the XML files <span class="emphasis"><em>not</em></span> included with the <code class="sgmltag-element"><xi:include></code> tag in a book, article, or set.
+ </div></dd><dt><span class="term">remove_book</span></dt><dd><div class="para">
+ removes a document from a documentation website. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
+ </div></dd><dt><span class="term">site_stats</span></dt><dd><div class="para">
+ generates a site report for a documentation website.
</div></dd><dt><span class="term">update_po</span></dt><dd><div class="para">
- updates the <em class="firstterm">portable object</em> (PO) files. Refer to <a class="xref" href="#sect-Users_Guide-Preparing_a_document_for_translation" title="3.3. Preparing a document for translation">Section 3.3, “Preparing a document for translation”</a> for more detail.
+ updates the <em class="firstterm">portable object</em> (PO) files. Refer to <a class="xref" href="#sect-Users_Guide-Preparing_a_document_for_translation" title="3.4. Preparing a document for translation">Section 3.4, “Preparing a document for translation”</a> for more detail.
</div></dd><dt><span class="term">update_pot</span></dt><dd><div class="para">
- updates the <em class="firstterm">portable object template</em> (POT) files. Refer to <a class="xref" href="#sect-Users_Guide-Preparing_a_document_for_translation" title="3.3. Preparing a document for translation">Section 3.3, “Preparing a document for translation”</a> for more detail.
+ updates the <em class="firstterm">portable object template</em> (POT) files. Refer to <a class="xref" href="#sect-Users_Guide-Preparing_a_document_for_translation" title="3.4. Preparing a document for translation">Section 3.4, “Preparing a document for translation”</a> for more detail.
+ </div></dd><dt><span class="term">update_site</span></dt><dd><div class="para">
+ updates the templated content of the documentation website. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
</div></dd></dl></div>
- </div></div></div><div xml:lang="en-US" class="chapter" title="Chapter 3. Creating a document" id="chap-Users_Guide-Creating_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Creating a document</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section
"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Preparing_a_document_for_translation">3.3. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document">3.4. Building a document</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.4.1. Building a document created with Publican 0</a></span></dt></dl></dd><dt><span class="section"><a hr
ef="#sect-Users_Guide-Packaging_a_book">3.5. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.5.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.5.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging">3.6. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.6.1. Conditional tagging and translation</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.7. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denotin
g_pre_release_software">3.7.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.7.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.7.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></div><div class="para">
+ </div></div></div><div xml:lang="en-US" class="chapter" title="Chapter 3. Creating a document" id="chap-Users_Guide-Creating_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Creating a document</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section
"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Adding_files">3.3. Adding files</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Preparing_a_document_for_translation">3.4. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document">3.5. Building a document</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.5.1.
Building a document created with Publican 0</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book">3.6. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.6.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.6.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging">3.7. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.7.1. Conditional tagging and translation</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.8. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><
span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.8.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.8.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.8.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></div><div class="para">
This chapter describes creating books and articles: the main configuration files, example document files, and how to build a document.
</div><div class="para">
Use the <code class="command">publican create</code> command to create a new document, including all the necessary files for the document.
@@ -303,14 +302,11 @@ books_tests Desktop1 downloads images notes scripts svgs
</div></dd></dl></div><div class="para">
Before running the <code class="command">publican create</code> command, use the <code class="command">cd</code> command to change into the directory where you want the book to be created. For example, to create a book named <code class="literal">Test_Book</code> in the <code class="filename">my_books/</code> directory, run the following commands:
</div><pre class="screen"><code class="command">cd my_books/</code>
-<code class="command">publican create --name Test_Book</code>
-</pre><div class="para">
+<code class="command">publican create --name Test_Book</code></pre><div class="para">
To see the results of this command on a computer with a Linux operating system, run the following:
- </div><pre class="screen"><code class="command">ls</code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">ls</code></pre><div class="para">
The output should be similar to the following:
- </div><pre class="screen"><code class="computeroutput">en-US publican.cfg</code>
-</pre><div xml:lang="en-US" class="section" title="3.1. Files in the book directory" id="sect-Users_Guide-Files_in_the_book_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.1. Files in the book directory</h2></div></div></div><div class="para">
+ </div><pre class="screen"><code class="computeroutput">en-US publican.cfg</code></pre><div xml:lang="en-US" class="section" title="3.1. Files in the book directory" id="sect-Users_Guide-Files_in_the_book_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</h2></div></div></div><div class="para">
If you run the command <code class="command">publican create --name Test_Book --lang en-US</code>, <span class="application"><strong>Publican</strong></span> creates a directory structure and required files, similar to the following:
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
<code class="filename">publican.cfg</code>
@@ -334,10 +330,9 @@ books_tests Desktop1 downloads images notes scripts svgs
<code class="filename">images</code> (directory)
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
<code class="filename">icon.svg</code>
- </div></li></ul></div></li></ul></div></li></ul></div><div class="section" title="3.1.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title">3.1.1. The publican.cfg file</h3></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
+ </div></li></ul></div></li></ul></div></li></ul></div><div class="section" title="3.1.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</h3></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
If you maintain multiple versions of a document, you can create a configuration file for each version. When building or packaging the document, you can use the <code class="option">--config</code> to specify a configuration file other than the <code class="filename">publican.cfg</code> file and therefore a different set of parameters to use in a particular build. For example:
- </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code>
-</pre></div><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code></pre></div><div class="para">
The <code class="filename">publican.cfg</code> file configures build options, and is located in the root of the book directory. The following is an example <code class="filename">publican.cfg</code> file, with a description of <code class="filename">publican.cfg</code> parameters following afterwards:
</div><pre class="programlisting"># Config::Simple 4.59
# Mon Sep 28 16:38:14 2009
@@ -348,6 +343,7 @@ brand: common
+
</pre><div class="variablelist" title="Default parameters" id="vari-Users_Guide-The_publican.cfg_file-Default_parameters"><h6>Default parameters</h6><dl><dt><span class="term"><em class="parameter"><code>xml_lang</code></em></span></dt><dd><div class="para">
specifies the language of the source XML files, for example, <code class="literal">en-US</code>, as set by the <code class="option">--lang</code> option for <code class="command">publican create</code>.
@@ -358,7 +354,7 @@ brand: common
</div></dd></dl></div><div class="variablelist" title="Advanced parameters" id="vari-Users_Guide-The_publican.cfg_file-Advanced_parameters"><h6>Advanced parameters</h6><dl><dt><span class="term"><em class="parameter"><code>arch</code></em></span></dt><dd><div class="para">
filters output by computer <em class="firstterm">architecture</em>. For example, if you set <code class="literal">arch: x86_64</code> in the <code class="filename">publican.cfg</code> file, <span class="application"><strong>Publican</strong></span> will only include XML elements tagged with the equivalent attribute, such as <code class="sgmltag-element"><para arch="x86_64"></code>.
</div><div class="warning"><h2>Use with caution</h2><div class="para">
- As with conditional tagging more generally, <code class="literal">arch</code> can cause great difficulties when translating documents. Refer to <a class="xref" href="#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation" title="3.6.1. Conditional tagging and translation">Section 3.6.1, “Conditional tagging and translation”</a> for an explanation of the issues.
+ As with conditional tagging more generally, <code class="literal">arch</code> can cause great difficulties when translating documents. Refer to <a class="xref" href="#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation" title="3.7.1. Conditional tagging and translation">Section 3.7.1, “Conditional tagging and translation”</a> for an explanation of the issues.
</div></div><div class="important"><h2>arch set for root nodes</h2><div class="para">
If the root node of an XML file is excluded by the <em class="parameter"><code>arch</code></em> attribute, your document will not build, because empty files are not valid XML. For example, if <code class="filename">Installation_and_configuration-PPC.xml</code> contains a single chapter:
</div><pre class="programlisting">
@@ -381,7 +377,7 @@ brand: common
</div></div></dd><dt><span class="term"><em class="parameter"><code>books</code></em></span></dt><dd><div class="para">
specifies a space-separated list of books used in a remote set. Refer to <a class="xref" href="#sect-Users_Guide-Using_sets-Distributed_sets" title="5.2. Distributed sets">Section 5.2, “Distributed sets”</a> for more information on distributed sets.
</div></dd><dt><span class="term"><em class="parameter"><code>brew_dist</code></em></span></dt><dd><div class="para">
- specifies the build target to use for building the desktop RPM package in <span class="application"><strong>Brew</strong></span>, Red Hat's internal build system. This parameter defaults to <code class="literal">docs-5E</code>. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a> and <a class="xref" href="#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more information on building RPM packages.
+ specifies the build target to use for building the desktop RPM package in <span class="application"><strong>Brew</strong></span>, Red Hat's internal build system. This parameter defaults to <code class="literal">docs-5E</code>. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a> and <a class="xref" href="#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more information on building RPM packages.
</div></dd><dt><span class="term"><em class="parameter"><code>chunk_first</code></em></span></dt><dd><div class="para">
controls whether the first section should appear on the same page as its parent when rendered in HTML. To make the first section appear on the same page as its parent, set this parameter to <code class="literal">chunk_first: 1</code>. Otherwise, the parameter defaults to <code class="literal">0</code>, and the first section starts a new HTML page.
</div></dd><dt><span class="term"><em class="parameter"><code>chunk_section_depth</code></em></span></dt><dd><div class="para">
@@ -393,7 +389,7 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>common_content</code></em></span></dt><dd><div class="para">
sets the path to the <span class="application"><strong>Publican</strong></span> <em class="firstterm">Common Content</em> files. These files provide default formatting, plus some boilerplate text and generic graphics. The default location on a computer with a Linux operating system is <code class="filename">/usr/share/publican/Common_Content</code>. On a computer with a Windows operating system, the default location is <code class="filename">%SystemDrive%/%ProgramFiles%/publican/Common_Content</code> — most usually <code class="filename">C:/Program Files/publican/Common_Content</code>.
</div></dd><dt><span class="term"><em class="parameter"><code>condition</code></em></span></dt><dd><div class="para">
- specifies conditions on which to prune XML before transformation. Refer to <a class="xref" href="#sect-Users_Guide-Conditional_tagging" title="3.6. Conditional tagging">Section 3.6, “Conditional tagging”</a> for more information.
+ specifies conditions on which to prune XML before transformation. Refer to <a class="xref" href="#sect-Users_Guide-Conditional_tagging" title="3.7. Conditional tagging">Section 3.7, “Conditional tagging”</a> for more information.
</div><div class="important"><h2>Root nodes and conditional tagging</h2><div class="para">
If the root node of an XML file is excluded with a conditional, your document will not build, because empty files are not valid XML. For example, if <code class="filename">Installation_and_configuration_on_Fedora.xml</code> contains a single chapter:
</div><pre class="programlisting">
@@ -418,19 +414,21 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>confidential_text</code></em></span></dt><dd><div class="para">
specifies the text to use when the <em class="parameter"><code>confidential</code></em> parameter is set to <code class="literal">1</code>. The default text is <code class="literal">CONFIDENTIAL</code>.
</div></dd><dt><span class="term"><em class="parameter"><code>cvs_branch</code></em></span></dt><dd><div class="para">
- the CVS branch into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a>.
+ the CVS branch into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>cvs_pck</code></em></span></dt><dd><div class="para">
- the CVS package into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a>.
+ the CVS package into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>cvs_root</code></em></span></dt><dd><div class="para">
- the CVS root into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a>.
+ the CVS root into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>debug</code></em></span></dt><dd><div class="para">
controls whether <span class="application"><strong>Publican</strong></span> should display debugging messages as it works. When set to its default of <code class="literal">0</code>, <span class="application"><strong>Publican</strong></span> does not display debugging messages. Change this value to <code class="literal">1</code> to view these messages.
+ </div></dd><dt><span class="term"><em class="parameter"><code>def_lang</code></em></span></dt><dd><div class="para">
+ sets the default language for a <span class="application"><strong>Publican</strong></span>-managed website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>doc_url</code></em></span></dt><dd><div class="para">
provides a URL for the documentation team for this package. In multi-page HTML output, <span class="application"><strong>Publican</strong></span> links to this URL at the top right of each page, through the <code class="filename">image_right.png</code> image in the <code class="filename">Common_Content/images</code> directory for the brand. This parameter defaults to <code class="literal">https://fedorahosted.org/publican</code>
</div></dd><dt><span class="term"><em class="parameter"><code>docname</code></em></span></dt><dd><div class="para">
specifies the document name. If set, this value overrides the content of the <code class="sgmltag-element"><title></code> tag in the <code class="filename">Book_Info.xml</code> 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 ‘ ’).
</div></dd><dt><span class="term"><em class="parameter"><code>dt_obsoletes</code></em></span></dt><dd><div class="para">
- specifies the desktop packages that this package obsoletes. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the desktop packages that this package obsoletes. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>dtdver</code></em></span></dt><dd><div class="para">
specifies the version of the DocBook XML <em class="firstterm">Document Type Definition</em> (DTD) on which this project is based. <span class="application"><strong>Publican</strong></span> defaults to version 4.5. The specification for DocBook XML DTD version 4.5 is available from <a href="http://www.docbook.org/specs/docbook-4.5-spec.html">http://www.docbook.org/specs/docbook-4.5-spec.html</a>.
</div><div class="important"><h2>A different DTD might slow your build</h2><div class="para">
@@ -446,9 +444,9 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>generate_section_toc_level</code></em></span></dt><dd><div class="para">
controls the section depth at which <span class="application"><strong>Publican</strong></span> will generate a table of contents. At the default value of <code class="literal">0</code>, <span class="application"><strong>Publican</strong></span> 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 <code class="literal">1</code>, 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 <code class="literal">2</code>, tables of contents also appear in "level 2" sections, such as sections 1.1.1, 1.1.2, and 1.2.1.
</div></dd><dt><span class="term"><em class="parameter"><code>ignored_translations</code></em></span></dt><dd><div class="para">
- specifies translations to ignore. If you build or package a book in a language specified by this parameter, <span class="application"><strong>Publican</strong></span> ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to <a class="xref" href="#sect-Users_Guide-Preparing_a_document_for_translation" title="3.3. Preparing a document for translation">Section 3.3, “Preparing a document for translation”</a>.
+ specifies translations to ignore. If you build or package a book in a language specified by this parameter, <span class="application"><strong>Publican</strong></span> ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to <a class="xref" href="#sect-Users_Guide-Preparing_a_document_for_translation" title="3.4. Preparing a document for translation">Section 3.4, “Preparing a document for translation”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>license</code></em></span></dt><dd><div class="para">
- specifies the license this package uses. By default, <span class="application"><strong>Publican</strong></span> selects the GNU Free Documentation License (GFDL). Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the license this package uses. By default, <span class="application"><strong>Publican</strong></span> selects the GNU Free Documentation License (GFDL). Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>max_image_width</code></em></span></dt><dd><div class="para">
specifies the maximum width allowable for images in the document in pixels. By default, <span class="application"><strong>Publican</strong></span> scales down any images wider than 444 pixels so that they fit within this limit. Keeping images no wider than 444 pixels ensures that they present no wider than the right-hand margin of the text in HTML output and that they fit within the pages of PDF output.
</div><div class="important"><h2>Important — 444 pixels is the maximum safe width</h2><div class="para">
@@ -458,7 +456,7 @@ brand: common
</div><div class="para">
To safeguard the quality of your images, crop or scale them so that they are no wider than 444 pixels before including them in a document.
</div></div></dd><dt><span class="term"><em class="parameter"><code>os_ver</code></em></span></dt><dd><div class="para">
- specifies the operating system for which to build packages. <span class="application"><strong>Publican</strong></span> appends the value that you provide here to the RPM packages that it builds. For example, the default value is <code class="literal">.el5</code>, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a> and <a class="xref" href="#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a>.
+ specifies the operating system for which to build packages. <span class="application"><strong>Publican</strong></span> appends the value that you provide here to the RPM packages that it builds. For example, the default value is <code class="literal">.el5</code>, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a> and <a class="xref" href="#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>prod_url</code></em></span></dt><dd><div class="para">
provides a URL for the product to which this document applies. In multi-page HTML output, <span class="application"><strong>Publican</strong></span> links to this URL at the top left of each page, through the <code class="filename">image_left.png</code> image in the <code class="filename">Common_Content/images</code> directory for the brand. This parameter defaults to <code class="literal">https://fedorahosted.org/publican</code>.
</div></dd><dt><span class="term"><em class="parameter"><code>product</code></em></span></dt><dd><div class="para">
@@ -474,9 +472,9 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>show_unknown</code></em></span></dt><dd><div class="para">
controls whether <span class="application"><strong>Publican</strong></span> reports unknown tags when processing XML. By default, this value is set to <code class="literal">1</code>, so <span class="application"><strong>Publican</strong></span> reports unknown tags. Set this value to <code class="literal">0</code> to hide this output. <span class="strikethrough strikethrough"><span class="application"><strong>Publican</strong></span> ignores this parameter in <em class="firstterm">strict mode</em>.</span>
</div></dd><dt><span class="term"><em class="parameter"><code>src_url</code></em></span></dt><dd><div class="para">
- specifies the URL at which to find tarballs of source files. This parameter provides the <code class="literal">Source:</code> field in the header of an RPM spec file. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the URL at which to find tarballs of source files. This parameter provides the <code class="literal">Source:</code> field in the header of an RPM spec file. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>strict</code></em></span></dt><dd><div class="para">
- <span class="strikethrough strikethrough">sets <span class="application"><strong>Publican</strong></span> to use <em class="firstterm">strict mode</em>, which prevents the use of tags that are unusable for professional output and translation. By default, the <code class="literal">strict</code> parameter is set of <code class="literal">0</code>, which disables strict mode. To enable strict mode, set this parameter to <code class="literal">1</code></span> Strict mode is no longer enforced.
+ <span class="strikethrough strikethrough">sets <span class="application"><strong>Publican</strong></span> to use <em class="firstterm">strict mode</em>, which prevents the use of tags that are unusable for professional output and translation. By default, the <code class="literal">strict</code> parameter is set of <code class="literal">0</code>, which disables strict mode. To enable strict mode, set this parameter to <code class="literal">1</code></span> Strict mode is not currently enforced.
</div></dd><dt><span class="term"><em class="parameter"><code>tmp_dir</code></em></span></dt><dd><div class="para">
specifies the directory for <span class="application"><strong>Publican</strong></span> output. By default, this is set to <code class="literal">tmp</code>, which creates a directory named <code class="filename">tmp</code> inside the directory that holds your article or book.
</div></dd><dt><span class="term"><em class="parameter"><code>toc_section_depth</code></em></span></dt><dd><div class="para">
@@ -484,12 +482,24 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>version</code></em></span></dt><dd><div class="para">
specifies the version number of that product to which this document applies. If set, this value overrides the content of the <code class="sgmltag-element"><productnumber></code> tag in the <code class="filename">Book_Info.xml</code> file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).
</div></dd><dt><span class="term"><em class="parameter"><code>web_brew_dist</code></em></span></dt><dd><div class="para">
- specifies the <span class="application"><strong>brew</strong></span> build target to use for building the web RPM packages. <span class="application"><strong>Brew</strong></span> is the internal build system used by Red Hat. By default, this value is set to <code class="literal">docs-5E</code>, representing documentation packages for Red Hat Enterprise Linux 5. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the <span class="application"><strong>brew</strong></span> build target to use for building the web RPM packages. <span class="application"><strong>Brew</strong></span> is the internal build system used by Red Hat. By default, this value is set to <code class="literal">docs-5E</code>, representing documentation packages for Red Hat Enterprise Linux 5. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_home</code></em></span></dt><dd><div class="para">
+ specifies that the document is the home page of a documentation website, not a standard document. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_host</code></em></span></dt><dd><div class="para">
+ specifies the host name of a documentation website, used for the Sitemap and searches. Be sure to specify the protocol and the full path to the document tree, for example: <code class="literal">http://www.example.com/docs/</code>. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_name_label</code></em></span></dt><dd><div class="para">
+ overrides the book name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
</div></dd><dt><span class="term"><em class="parameter"><code>web_obsoletes</code></em></span></dt><dd><div class="para">
- specifies packages that the web RPM obsoletes. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies packages that the web RPM obsoletes. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_product_label</code></em></span></dt><dd><div class="para">
+ overrides the product name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_search</code></em></span></dt><dd><div class="para">
+ overrides the default search form for a <span class="application"><strong>Publican</strong></span>-managed website. Defaults to a search on Google which is limited to a site search if <em class="parameter"><code>web_host</code></em> is set. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_version_label</code></em></span></dt><dd><div class="para">
+ overrides the version number as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website. Set this value to <code class="literal">UNUSED</code> for general documentation that does not apply to any particular version of a product. Refer to <a class="xref" href="#sect-Users_Guide-Website" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
</div></dd></dl></div><div class="note"><h2>Help from the command line</h2><div class="para">
Run the <code class="command">publican help_config</code> command in the root directory of a book for a summary of these parameters.
- </div></div></div><div class="section" title="3.1.2. Book_Info.xml" id="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml"><div class="titlepage"><div><div><h3 class="title">3.1.2. Book_Info.xml</h3></div></div></div><div class="note"><h2><code class="filename">Article_Info.xml</code> and <code class="filename">Set_Info.xml</code></h2><div class="para">
+ </div></div></div><div class="section" title="3.1.2. Book_Info.xml" id="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</h3></div></div></div><div class="note"><h2><code class="filename">Article_Info.xml</code> and <code class="filename">Set_Info.xml</code></h2><div class="para">
This description of the <code class="filename">Book_Info.xml</code> file applies to <code class="filename">Article_Info.xml</code> and <code class="filename">Set_Info.xml</code> files too. However, for the sake of simplicity, the file is referred to as <code class="filename">Book_Info.xml</code> throughout this section.
</div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
This section discusses packaging documents for distribution through the <span class="application"><strong>RPM Package Manager</strong></span>. However, when you use the <code class="command">publican package</code> command, <span class="application"><strong>Publican</strong></span> generates a tarball that you can use to build a package to distribute through different package manager software. If you run <code class="command">publican package</code> on a computer on which <span class="application"><strong>rpmbuild</strong></span> is not installed, <span class="application"><strong>Publican</strong></span> still generates the tarball, even though it cannot then generate an RPM package from that tarball.
@@ -511,12 +521,12 @@ brand: common
<span class="perl_Keyword"><title></span>Users Guide<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><subtitle></span>Publishing books, articles, papers and multi-volume sets with DocBook XML<span class="perl_Keyword"></subtitle></span>
<span class="perl_Keyword"><productname></span>Publican<span class="perl_Keyword"></productname></span>
- <span class="perl_Keyword"><productnumber></span>1.6<span class="perl_Keyword"></productnumber></span>
- <span class="perl_Keyword"><edition></span>1.6<span class="perl_Keyword"></edition></span>
- <span class="perl_Keyword"><pubsnumber></span>1<span class="perl_Keyword"></pubsnumber></span>
+ <span class="perl_Keyword"><productnumber></span>2.0<span class="perl_Keyword"></productnumber></span>
+ <span class="perl_Keyword"><edition></span>1.0<span class="perl_Keyword"></edition></span>
+ <span class="perl_Keyword"><pubsnumber></span>3<span class="perl_Keyword"></pubsnumber></span>
<span class="perl_Keyword"><abstract></span>
<span class="perl_Keyword"><para></span>
- This book will help you install <span class="perl_Keyword"><application></span>Publican<span class="perl_Keyword"></application></span>. 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 <span class="perl_DecVal">&D_B;</span> XML.
+ This book will help you install <span class="perl_Keyword"><application></span>Publican<span class="perl_Keyword"></application></span>. 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.
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></abstract></span>
@@ -569,6 +579,7 @@ brand: common
<span class="perl_Keyword"></bookinfo></span>
+
</pre><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><bookinfo id="<em class="replaceable"><code>book_id</code></em>"></code>, </span><span class="term"><code class="sgmltag-element"><articleinfo id="<em class="replaceable"><code>article_id</code></em>"></code>, </span><span class="term"><code class="sgmltag-element"><setinfo id="<em class="replaceable"><code>set_id</code></em>"></code></span></dt><dd><div class="para">
The document ID is used internally and is not displayed to readers when the book is built. If you run the <code class="command">publican clean_ids</code> command, any manually entered ID, including this one, changes to a <em class="replaceable"><code>Doc_Name-Title</code></em> format, where <em class="replaceable"><code>Title</code></em> is the title of the associated book, article, section, or chapter.
@@ -639,7 +650,7 @@ brand: common
</pre><div class="para">
As with all the other images in your document, place the cover images in the <code class="filename">images</code> subdirectory.
- </div></dd></dl></div><div class="section" title="3.1.2.1. RPM packages, editions, impressions and versions" id="sect-Users_Guide-Book_Info.xml-RPM_packages_editions_impressions_and_versions"><div class="titlepage"><div><div><h4 class="title">3.1.2.1. RPM packages, editions, impressions and versions</h4></div></div></div><div class="para">
+ </div></dd></dl></div><div class="section" title="3.1.2.1. RPM packages, editions, impressions and versions" id="sect-Users_Guide-Book_Info.xml-RPM_packages_editions_impressions_and_versions"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Book_Info.xml-RPM_packages_editions_impressions_and_versions">3.1.2.1. RPM packages, editions, impressions and versions</h4></div></div></div><div class="para">
As noted above, the default <code class="filename">Book_Info.xml</code> used by <span class="application"><strong>Publican</strong></span> includes an <em class="parameter"><code><edition></code></em> tag.
</div><div class="para">
If you distribute a book as an RPM package, the data placed within this tag sets 'the first two digits of the version number in the RPM file name.
@@ -661,7 +672,7 @@ brand: common
We recommend following bibliographic practice in this regard. When using <span class="application"><strong>Publican</strong></span> to re-publish a book from 'substantially the same XML', increment the <em class="parameter"><code><pubsnumber></code></em> tag, not the <em class="parameter"><code><edition></code></em> tag. It functions as a near-equivalent to the impression or printing number of traditional publishing.
</div><div class="para">
As for changing the edition number, we recommend changing this in the same circumstances traditional publishers change the edition of a work: when it is revised and re-written significantly. What constitutes significant, and how much re-writing is needed to increment an edition number by a whole number and how much is needed to increment it by one-tenth of a whole number, is a matter of editorial discretion.
- </div></div></div><div class="section" title="3.1.3. Author_Group.xml" id="sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml"><div class="titlepage"><div><div><h3 class="title">3.1.3. Author_Group.xml</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.1.3. Author_Group.xml" id="sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</h3></div></div></div><div class="para">
<code class="filename">Author_Group.xml</code> is not required but is the standard place to record author, editor, artist and other credit details. The following is an example <code class="filename">Author_Group.xml</code> file:
</div><pre class="programlisting"><span class="perl_Keyword"><?xml</span> version='1.0'<span class="perl_Keyword">?></span>
<span class="perl_DataType"><!DOCTYPE </span>authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" <span class="perl_DataType">[</span>
@@ -680,10 +691,11 @@ brand: common
<span class="perl_Keyword"></author></span>
<span class="perl_Keyword"></authorgroup></span>
+
</pre><div class="para">
<code class="filename">Author_Group.xml</code> does not have to contain all of the above information: include as much or as little as required.
- </div></div><div class="section" title="3.1.4. Chapter.xml" id="sect-Users_Guide-Files_in_the_book_directory-Chapter.xml"><div class="titlepage"><div><div><h3 class="title">3.1.4. Chapter.xml</h3></div></div></div><div class="important"><h2>Articles and chapters</h2><div class="para">
+ </div></div><div class="section" title="3.1.4. Chapter.xml" id="sect-Users_Guide-Files_in_the_book_directory-Chapter.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</h3></div></div></div><div class="important"><h2>Articles and chapters</h2><div class="para">
DocBook articles cannot contain chapters. If you use the <code class="option">--type=article</code> option with <code class="command">publican create</code>, <span class="application"><strong>Publican</strong></span> does not create a <code class="filename">Chapter.xml</code> file. Use sections to organize content within articles.
</div><div class="para">
Refer to <em class="citetitle">DocBook: The Definitive Guide</em> by Norman Walsh and Leonard Muellner available at <a href="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</a> for details of the different ways that sets, books, articles, parts, chapters, and sections interact. In particular, note that articles can be stand-alone documents, or can be incorporated into books.
@@ -715,12 +727,13 @@ brand: common
<span class="perl_Keyword"></chapter></span>
+
</pre><div class="para">
This chapter has two sections, <code class="filename">Section 1 Test</code> and <code class="filename">Section 2 Test</code>. Refer to <a href="http://docbook.org/tdg/en/html/chapter.html">http://docbook.org/tdg/en/html/chapter.html</a> for further information about chapters.
</div><div class="note"><h2>Note</h2><div class="para">
The chapter file should be renamed to reflect the chapter subject. For example, a chapter on product installation could be named <code class="filename">Installation.xml</code>, whereas a chapter on setting up a piece of software would be better called <code class="filename">Setup.xml</code> or <code class="filename">Configuration.xml</code>.
- </div></div></div><div class="section" title="3.1.5. Doc_Name.xml" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml"><div class="titlepage"><div><div><h3 class="title">3.1.5. Doc_Name.xml</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.1.5. Doc_Name.xml" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</h3></div></div></div><div class="para">
The <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.xml</code> file contains <code class="literal">xi:include</code> 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 <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.xml</code> file brings together chapters that are contained in separate XML files.
</div><div class="para">
The following is an example <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.xml</code> file that describes a DocBook book — note the <em class="parameter"><code>DOCTYPE</code></em> is set to <code class="literal">book</code>.
@@ -737,6 +750,7 @@ brand: common
<span class="perl_Keyword"></book></span>
+
</pre><div class="para">
This example loads the <code class="filename">Book_Info.xml</code>, <code class="filename">Preface.xml</code>, <code class="filename">Chapter.xml</code>, and <code class="filename">Appendix.xml</code> XML files.
@@ -776,7 +790,7 @@ brand: common
</pre><div class="para">
This book contains two chapters. Chapter one contains two sections. Refer to <a href="http://docbook.org/tdg/en/html/section.html">http://docbook.org/tdg/en/html/section.html</a> for further information about sections, and <a href="http://docbook.org/tdg/en/html/book.html">http://docbook.org/tdg/en/html/book.html</a> for further information about books.
- </div></div><div class="section" title="3.1.6. Doc_Name.ent" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent"><div class="titlepage"><div><div><h3 class="title">3.1.6. Doc_Name.ent</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="3.1.6. Doc_Name.ent" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</h3></div></div></div><div class="para">
The <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> file is used to define local entities. The <em class="parameter"><code>YEAR</code></em> and <em class="parameter"><code>HOLDER</code></em> entities are used for copyright information. By default, <span class="application"><strong>Publican</strong></span> sets <em class="parameter"><code>YEAR</code></em> to the current year, and inserts a message into <em class="parameter"><code>HOLDER</code></em> to remind you to specify the copyright holder for the document. If the <em class="parameter"><code>YEAR</code></em> and <em class="parameter"><code>HOLDER</code></em> entities are missing altogether, the document will not build.
</div><div class="para">
Other entities might be required by the <em class="firstterm">brand</em> applied to your document. For example, the <span class="application"><strong>Publican</strong></span> brand for Fedora documents uses the entity <code class="computeroutput">BOOKID</code> to specify how readers should refer to a document when they submit feedback about it.
@@ -786,8 +800,9 @@ brand: common
<!ENTITY HOLDER "YOUR NAME GOES HERE">
+
-</pre><div xml:lang="en-US" class="section" title="3.1.6.1. Entities and translation" id="sect-Users_Guide-Entities_and_translation" lang="en-US"><div class="titlepage"><div><div><h4 class="title">3.1.6.1. Entities and translation</h4></div></div></div><div class="warning"><h2>Use entities with extreme caution</h2><div class="para">
+</pre><div xml:lang="en-US" class="section" title="3.1.6.1. Entities and translation" id="sect-Users_Guide-Entities_and_translation" lang="en-US"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Entities_and_translation">3.1.6.1. Entities and translation</h4></div></div></div><div class="warning"><h2>Use entities with extreme caution</h2><div class="para">
Entities offer convenience but they should be used with extreme caution in documents that will be translated. Writing (for example) <code class="sgmltag-element">&FDS;</code> instead of <span class="application"><strong>Fedora Directory Server</strong></span> saves the writer time but transformed entities do not appear in the <em class="firstterm">portable object</em> (PO) files that translators use. Complete translations of documents containing entities are, as a consequence, impossible.
</div></div><div class="para">
Entities present special obstacles to translators and can preclude the production of high-quality translations. The very nature of an entity is that the word or phrase represented by the entity is rendered exactly the same way every time that it occurs in the document, in every language. This inflexibility means that the word or word group represented by the entity might be illegible or incomprehensible in the target language and that the word or word group represented by the entity cannot change when the grammatical rules of the target language require them to change. Furthermore, because entities are not transformed when XML is converted to PO, translators cannot select the correct words that surround the entity, as required by the grammatical rules of the target language.
@@ -861,7 +876,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Finally, consider that although a particular word never changes its form in English, this is not necessarily true of other languages, even when the word is a <em class="firstterm">proper noun</em> such as the name of a product. In many languages, nouns change (<em class="firstterm">inflect</em>) their form according to their role in a sentence (their grammatical <em class="firstterm">case</em>). An XML entity set to represent an English noun or noun phrase therefore makes correct translation impossible in such languages.
</div><div class="para">
For example, if you write a document that could apply to more than one product, you might be tempted to set an entity such as <code class="sgmltag-element">&PRODUCT;</code>. The advantage of this approach is that by simply changing this value in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> file, you could easily adjust the book to document (for example) Red Hat Enterprise Linux, Fedora, or CentOS. However, while the proper noun <em class="firstterm">Fedora</em> never varies in English, it has six different forms in Czech, depending on one of seven ways that you can use it in a sentence:
- </div><div class="table"><div class="table-contents"><table summary="'Fedora' in Czech" border="1"><colgroup><col align="left" width="33%" /><col align="left" width="33%" /><col align="left" width="33%" /></colgroup><thead><tr><th align="left">
+ </div><div class="table" title="Table 3.1. 'Fedora' in Czech" id="tabl-Users_Guide-Entities_and_translation-Fedora_in_Czech"><div class="table-contents"><table summary="'Fedora' in Czech" border="1"><colgroup><col align="left" width="33%" /><col align="left" width="33%" /><col align="left" width="33%" /></colgroup><thead><tr><th align="left">
Case
</th><th align="left">
Usage
@@ -931,9 +946,9 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Nouns in most Slavic languages like Russian, Ukrainian, Czech, Polish, Serbian, and Croatian have seven different cases. Nouns in Finno–Ugaric languages such as Finnish, Hungarian, and Estonian have between fifteen and seventeen cases. Other languages alter nouns for other reasons. For example, Scandinavian languages inflect nouns to indicate <em class="firstterm">definiteness</em> — whether the noun refers to '<span class="emphasis"><em>a</em></span> thing' or '<span class="emphasis"><em>the</em></span> thing' — and some dialects of those languages inflect nouns both for definiteness <span class="emphasis"><em>and</em></span> for grammatical case.
</div><div class="para">
Now multiply such problems by the more than 40 languages that <span class="application"><strong>Publican</strong></span> currently supports. Other than the few non-translated strings that <span class="application"><strong>Publican</strong></span> specifies by default in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> 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.
- </div></div></div><div class="section" title="3.1.7. Revision_History.xml" id="sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml"><div class="titlepage"><div><div><h3 class="title">3.1.7. Revision_History.xml</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.1.7. Revision_History.xml" id="sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</h3></div></div></div><div class="para">
The <code class="command">publican package</code> command searches for the first XML file in the document's XML directory containing a <code class="literal"><revhistory></code> tag. <span class="application"><strong>Publican</strong></span> then uses that file to build the RPM revision history.
- </div></div></div><div xml:lang="en-US" class="section" title="3.2. Adding images" id="sect-Users_Guide-Adding_images" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.2. Adding images</h2></div></div></div><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.2. Adding images" id="sect-Users_Guide-Adding_images" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Adding_images">3.2. Adding images</h2></div></div></div><div class="para">
Store images in the <code class="filename">images</code> subdirectory in the directory that holds your XML files. Use <code class="computeroutput">./images/<em class="replaceable"><code>image-name</code></em></code> to insert images into a book. The following is an example that inserts the <code class="filename">testimage.png</code> image:
</div><pre class="programlisting"><span class="perl_Keyword"><mediaobject></span>
<span class="perl_Keyword"><imageobject></span>
@@ -943,7 +958,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
<span class="perl_Keyword"></mediaobject></span>
</pre><div class="para">
- Ensure that you supply a <code class="sgmltag-element"><textobject></code> 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 <em class="citetitle">Rehabilitation Act of 1973</em>.<sup>[<a id="id720619" href="#ftn.id720619" class="footnote">1</a>]</sup>
+ Ensure that you supply a <code class="sgmltag-element"><textobject></code> 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 <em class="citetitle">Rehabilitation Act of 1973</em>.<sup>[<a id="id627973" href="#ftn.id627973" class="footnote">1</a>]</sup>
</div><div class="para">
If your book contains images that need to be localized — for example, screenshots of a user interface in a language other than the original language of your book — place these images in the <code class="filename">images</code> 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, <span class="application"><strong>Publican</strong></span> uses the file from the <code class="filename">images</code> subdirectory of the translated language instead of the file from the <code class="filename">images</code> subdirectory of the original language.
</div><div class="para">
@@ -954,16 +969,19 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
<span class="application"><strong>Publican</strong></span> depends on an external application, <span class="application"><strong>FOP</strong></span>, to render documents as PDF files. At present, some versions of <span class="application"><strong>FOP</strong></span> contain a bug that alters the colors in certain images in PNG format. Specifically, 32-bit PNG images are rendered correctly, while 24-bit PNG images are not.
</div><div class="para">
If you notice that <span class="application"><strong>Publican</strong></span> produces a PDF file that contains images with incorrect colors, convert the original PNG files to 32-bit PNG format by adding an <em class="firstterm">alpha channel</em> to the image and rebuild the book. If your chosen image manipulation software does not include an option specifically labeled <code class="literal">Add alpha channel</code>, the option might be labeled <code class="literal">Add transparency</code> instead.
- </div></div></div><div xml:lang="en-US" class="section" title="3.3. Preparing a document for translation" id="sect-Users_Guide-Preparing_a_document_for_translation" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.3. Preparing a document for translation</h2></div></div></div><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.3. Adding files" id="sect-Users_Guide-Adding_files" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Adding_files">3.3. Adding files</h2></div></div></div><div class="para">
+ <span class="application"><strong>Publican</strong></span> allows you to include arbitrary files together with your documents. These files are included in RPM packages that you build with <span class="application"><strong>Publican</strong></span> and are installed on users' systems alongside the document itself. For example, you might want to include multimedia files of tutorials that complement the document, or sample files of source code or other materials that allow users to work through the examples or tutorials in a document.
+ </div><div class="para">
+ To ship arbitrary files with a document, include them in a directory named <code class="filename">files</code> and include it in the language directory for the original language of the book, for example, <code class="filename">en-US/files/</code>.
+ </div></div><div xml:lang="en-US" class="section" title="3.4. Preparing a document for translation" id="sect-Users_Guide-Preparing_a_document_for_translation" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Preparing_a_document_for_translation">3.4. Preparing a document for translation</h2></div></div></div><div class="para">
Support for localization of documents was a key consideration in the design of <span class="application"><strong>Publican</strong></span>. The general translation workflow for documents developed in <span class="application"><strong>Publican</strong></span> is as follows:
- </div><div class="procedure"><ol class="1"><li class="step" title="Step 1" id="step1"><div class="para">
+ </div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Complete the XML of a document.
</div><div class="para">
The XML for this version of the document should now be considered ‘frozen’. If your document is stored in a version-controlled repository, you should now move this version into a separate directory or branch. This allows writers to begin work on subsequent versions of the document in one branch, while providing a stable base for translation in another branch.
</div></li><li class="step" title="Step 2"><div class="para">
Generate <em class="firstterm">portable object template</em> (POT) files from the XML files:
- </div><pre class="screen">$ <code class="command">publican update_pot</code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_pot</code></pre><div class="para">
If this is the first time that POT files have been created for this document, <span class="application"><strong>Publican</strong></span> creates a new subdirectory, named <code class="filename">pot</code>. The <code class="filename">pot</code> subdirectory holds a POT file for each XML file in the document. If <span class="application"><strong>Publican</strong></span> has created POT files for this document previously, <span class="application"><strong>Publican</strong></span> updates the existing POT files to reflect any changes in the XML since the POT files were last updated.
</div><div class="important"><h2>Remove unused XML files</h2><div class="para">
<span class="application"><strong>Publican</strong></span> generates a POT file for every XML file in the XML directory, whether the XML file is used in the document or not. If you transform unused XML files into POT files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
@@ -971,14 +989,11 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Use the <code class="command">publican print_unused</code> command to generate a list of XML files that are not used in your document.
</div></div></li><li class="step" title="Step 3"><div class="para">
Generate <em class="firstterm">portable object</em> (PO) files from the POT files to begin translation into a particular language:
- </div><pre class="screen">$ <code class="command">publican update_po --langs=<em class="replaceable"><code>language_code</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_po --langs=<em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
where <em class="replaceable"><code>language_code</code></em> is the code for the target language. Refer to <a class="xref" href="#appe-Users_Guide-Language_codes" title="Appendix D. Language codes">Appendix D, <i>Language codes</i></a> for more information about language codes. You can provide multiple language codes, separated by commas, to generate PO files for more than one language at a time. For example:
- </div><pre class="screen">$ <code class="command">publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN</code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN</code></pre><div class="para">
If this is the first time that PO files have been created for a particular language, <span class="application"><strong>Publican</strong></span> creates a new subdirectory, named with the language code that you specified with the <code class="option">--langs=</code> option. This subdirectory holds a PO file for each POT file in <code class="filename">pot</code> subdirectory. If <span class="application"><strong>Publican</strong></span> has created PO files for this language previously, <span class="application"><strong>Publican</strong></span> 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 <code class="option">--langs=all</code> option:
- </div><pre class="screen">$ <code class="command">publican update_po --langs=all</code>
-</pre><div class="important"><h2>Remove unused POT files</h2><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_po --langs=all</code></pre><div class="important"><h2>Remove unused POT files</h2><div class="para">
<span class="application"><strong>Publican</strong></span> generates a PO file for every POT file in the <code class="filename">pot</code> 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.
</div><div class="para">
When you generate PO files, <span class="application"><strong>Publican</strong></span> presents you with a warning for any POT files that do not have corresponding XML files, but will generate the PO file nevertheless. However, <span class="application"><strong>Publican</strong></span> will not warn you if a POT file exists for an XML file that is not used in the document.
@@ -986,31 +1001,25 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Translators translate the <em class="firstterm">strings</em> contained in the PO files.
</div></li><li class="step" title="Step 5"><div class="para">
Build the document in the target language, for example:
- </div><pre class="screen">$ <code class="command">publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO</code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO</code></pre><div class="para">
or package it in the target language, for example:
- </div><pre class="screen">$ <code class="command">publican package --lang=is-IS</code>
-</pre><div class="para">
- You can build the document in all languages for which you have translations with the <code class="option">--langs=all</code> option, but note that you must package each language individually. Refer to <a class="xref" href="#sect-Users_Guide-Building_a_document" title="3.4. Building a document">Section 3.4, “Building a document”</a> for more information on building a document, and <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a> on packaging a document.
- </div></li></ol></div></div><div xml:lang="en-US" class="section" title="3.4. Building a document" id="sect-Users_Guide-Building_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.4. Building a document</h2></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
+ </div><pre class="screen">$ <code class="command">publican package --lang=is-IS</code></pre><div class="para">
+ You can build the document in all languages for which you have translations with the <code class="option">--langs=all</code> option, but note that you must package each language individually. Refer to <a class="xref" href="#sect-Users_Guide-Building_a_document" title="3.5. Building a document">Section 3.5, “Building a document”</a> for more information on building a document, and <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a> on packaging a document.
+ </div></li></ol></div></div><div xml:lang="en-US" class="section" title="3.5. Building a document" id="sect-Users_Guide-Building_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Building_a_document">3.5. Building a document</h2></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
The parameters set in the document configuration file (by default, <code class="filename">publican.cfg</code>) allow you to control many aspects of the way in which a document is presented — refer to <a class="xref" href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a>.
</div><div class="para">
If you maintain multiple versions of a document, you can create a configuration file for each version. When building the document, you can use the <code class="option">--config</code> to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
- </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code>
-</pre></div><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code></pre></div><div class="para">
To build a document:
</div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Confirm the <em class="parameter"><code>YEAR</code></em> and <em class="parameter"><code>HOLDER</code></em> entities have been configured in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> file, as described in <a class="xref" href="#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent" title="3.1.6. Doc_Name.ent">Section 3.1.6, “Doc_Name.ent”</a>.
</div></li><li class="step" title="Step 2"><div class="para">
Change into the root directory of the document. For example, if the document was named <code class="literal">Test_Book</code> and was located in the <code class="filename">books/</code> directory, run the following command:
- </div><pre class="screen"><code class="command">cd books/Test_Book</code>
-</pre></li><li class="step" title="Step 3"><div class="para">
+ </div><pre class="screen"><code class="command">cd books/Test_Book</code></pre></li><li class="step" title="Step 3"><div class="para">
Run a test for any errors that would stop the book from building in your chosen language, for example:
- </div><pre class="screen"><code class="command">publican build --formats=test --langs=en-US</code>
-</pre></li><li class="step" title="Step 4"><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats=test --langs=en-US</code></pre></li><li class="step" title="Step 4"><div class="para">
Run the following command to build the book:
- </div><pre class="screen"><code class="command">publican build --formats=<em class="replaceable"><code>formats</code></em> --langs=<em class="replaceable"><code>languages</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats=<em class="replaceable"><code>formats</code></em> --langs=<em class="replaceable"><code>languages</code></em></code></pre><div class="para">
Replace <em class="replaceable"><code>formats</code></em> with a comma-separated list of the formats that you want to build, for example, <code class="literal">--formats=html,html-single,pdf</code>. Replace <em class="replaceable"><code>langs</code></em> with a comma-separated list of the languages that you want to build, for example, <code class="literal">--langs=en-US,sv-SE,uk-UA,ko-KR</code>.
</div></li></ol></div><div class="variablelist" title="Formats for the build action" id="vari-Users_Guide-Building_a_document-Formats_for_the_build_action"><h6>Formats for the <code class="command">build</code> action</h6><dl><dt><span class="term"><code class="option">html</code></span></dt><dd><div class="para">
<span class="application"><strong>Publican</strong></span> outputs the document as in multiple HTML pages, with each chapter and major section on a separate page. <span class="application"><strong>Publican</strong></span> places an index at the start of the document, and places navigational elements on each page.
@@ -1044,7 +1053,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Build the book as a PDF file. <span class="application"><strong>Publican</strong></span> relies on an external application, <span class="application"><strong>FOP</strong></span> to render PDF. Therefore, building PDF might not be available on all systems, depending on the availability of <span class="application"><strong>FOP</strong></span>. The output will be a single PDF file located in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>/tmp/<em class="replaceable"><code>language</code></em>/pdf/</code> directory.
</div></dd><dt><span class="term"><code class="command">publican build --formats=html,html-single,pdf --langs=<em class="replaceable"><code>languages</code></em></code></span></dt><dd><div class="para">
Build the book in multi-page HTML, single-page HTML, and PDF formats.
- </div></dd></dl></div><div class="section" title="3.4.1. Building a document created with Publican 0" id="sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0"><div class="titlepage"><div><div><h3 class="title">3.4.1. Building a document created with Publican 0</h3></div></div></div><div class="para">
+ </div></dd></dl></div><div class="section" title="3.5.1. Building a document created with Publican 0" id="sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.5.1. Building a document created with Publican 0</h3></div></div></div><div class="para">
Documents produced with early versions of <span class="application"><strong>Publican</strong></span> (versions up to and including 0.45) did not have a <code class="filename">publican.cfg</code> file; a similar set of parameters was defined in a <code class="filename">Makefile</code>. Before you build such a document in a current version of <span class="application"><strong>Publican</strong></span> (version 0.99 onwards), you must convert the <code class="filename">Makefile</code> into a <code class="filename">publican.cfg</code> file. <span class="application"><strong>Publican</strong></span> can do this conversion automatically:
</div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Change into the document directory, the one that holds the <code class="filename">Makefile</code>.
@@ -1052,28 +1061,27 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Run <code class="command">publican old2new</code>. <span class="application"><strong>Publican</strong></span> parses the <code class="filename">Makefile</code> and creates a <code class="filename">publican.cfg</code> file with equivalent parameters wherever available.
</div></li></ol></div><div class="para">
When you run <code class="command">publican old2new</code>, <span class="application"><strong>Publican</strong></span> does not alter or delete the original <code class="filename">Makefile</code>. A <code class="filename">Makefile</code> and a <code class="filename">publican.cfg</code> file can coexist in the same document.
- </div></div></div><div xml:lang="en-US" class="section" title="3.5. Packaging a book" id="sect-Users_Guide-Packaging_a_book" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.5. Packaging a book</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.6. Packaging a book" id="sect-Users_Guide-Packaging_a_book" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Packaging_a_book">3.6. Packaging a book</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
This section discusses packaging documents for distribution through the <span class="application"><strong>RPM Package Manager</strong></span>. However, when you use the <code class="command">publican package</code> command, <span class="application"><strong>Publican</strong></span> generates a tarball that you can use to build a package to distribute through different package manager software. If you run <code class="command">publican package</code> on a computer on which <span class="application"><strong>rpmbuild</strong></span> is not installed, <span class="application"><strong>Publican</strong></span> still generates the tarball, even though it cannot then generate an RPM package from that tarball.
</div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
The parameters set in the document configuration file (by default, <code class="filename">publican.cfg</code>) allow you to control many aspects of the way in which a document is presented and packaged — refer to <a class="xref" href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a>.
</div><div class="para">
If you maintain multiple versions of a document, you can create a configuration file for each version. When packaging the document, you can use the <code class="option">--config</code> to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
- </div><pre class="screen"><code class="command">publican package --lang hi-IN --config community.cfg</code>
-</pre></div><div class="para">
+ </div><pre class="screen"><code class="command">publican package --lang hi-IN --config community.cfg</code></pre></div><div class="para">
<span class="application"><strong>Publican</strong></span> not only builds documentation as HTML and PDF files, but it can package these files for distribution to individual workstations and to web servers as <em class="firstterm">RPM packages</em>. RPM packages are used to distribute software to computers with Linux operating systems that use the <span class="application"><strong>RPM Package Manager</strong></span>. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
- </div><div class="section" title="3.5.1. Types of RPM packages" id="sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages"><div class="titlepage"><div><div><h3 class="title">3.5.1. Types of RPM packages</h3></div></div></div><div class="para">
+ </div><div class="section" title="3.6.1. Types of RPM packages" id="sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.6.1. Types of RPM packages</h3></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> can produce both <em class="firstterm">source RPM packages</em> (<em class="firstterm">SRPM packages</em>) and <em class="firstterm">binary RPM packages</em>. Furthermore, both SRPM packages and binary RPM packages can be configured to deploy to workstations or web servers.
- </div><div class="section" title="3.5.1.1. Source RPM packages and binary RPM packages" id="sect-Users_Guide-Types_of_RPM_packages-Source_RPM_packages_and_binary_RPM_packages"><div class="titlepage"><div><div><h4 class="title">3.5.1.1. Source RPM packages and binary RPM packages</h4></div></div></div><div class="para">
+ </div><div class="section" title="3.6.1.1. Source RPM packages and binary RPM packages" id="sect-Users_Guide-Types_of_RPM_packages-Source_RPM_packages_and_binary_RPM_packages"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Types_of_RPM_packages-Source_RPM_packages_and_binary_RPM_packages">3.6.1.1. Source RPM packages and binary RPM packages</h4></div></div></div><div class="para">
An SRPM package contains the source code used to generate software rather than the software itself. To use an SRPM package, a computer must <em class="firstterm">compile</em> the source code into software — or in this case, into documents. SRPM packages of <span class="application"><strong>Publican</strong></span> documents contain XML files rather than finished documents. To install documentation from the SRPM package to a computer, the computer must have <span class="application"><strong>Publican</strong></span> installed on it. When you try to install the SRPM package on a computer that does not have <span class="application"><strong>Publican</strong></span> installed, the <span class="application"><strong>RPM Package Manager</strong></span> looks for <span class="application"><strong>Publican</strong></span> in the software repositories that are available to it. The <span class="application"><strong>RPM Package Manager</strong></span> installs <span class="applicat
ion"><strong>Publican</strong></span> first, so that it can build and install the document contained in the SRPM package. If the <span class="application"><strong>RPM Package Manager</strong></span> cannot find and install <span class="application"><strong>Publican</strong></span>, installation of the SRPM package will fail.
</div><div class="para">
Conversely, binary RPM packages contain software — or in this case, a document — that is ready to copy to a location in the computer's file system and use immediately. The contents of the binary RPM package do not need to be compiled by the computer onto which they are installed, and therefore, the computer does not need to have <span class="application"><strong>Publican</strong></span> installed.
- </div></div><div class="section" title="3.5.1.2. Desktop packages and web packages" id="sect-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages"><div class="titlepage"><div><div><h4 class="title">3.5.1.2. Desktop packages and web packages</h4></div></div></div><div class="para">
+ </div></div><div class="section" title="3.6.1.2. Desktop packages and web packages" id="sect-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages">3.6.1.2. Desktop packages and web packages</h4></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> can package documents for reading on a computer workstation (a <em class="firstterm">desktop RPM package</em>) or to install on a web server and publish on the world-wide web (a <em class="firstterm">web RPM package</em>). The desktop RPM package of a <span class="application"><strong>Publican</strong></span> document and the web RPM package of the same document differ in that the desktop RPM package installs documentation only for local use on a computer, while the web RPM installs documentation for local use, but also to be served to the World Wide Web.
</div><div class="para">
- Desktop RPM packages of <span class="application"><strong>Publican</strong></span> documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of <code class="filename">/usr/share/doc/</code>, the location specified by the <em class="citetitle">Filesystem Hierarchy Standard</em> (<em class="citetitle">FHS</em>) for ‘Miscellaneous documentation’.<sup>[<a id="id595292" href="#ftn.id595292" class="footnote">2</a>]</sup> The desktop RPM package also contains a <em class="firstterm">desktop file</em>, to be placed in <code class="filename">/usr/share/applications/</code>. This file enables <em class="firstterm">desktop environments</em> such as GNOME and KDE to add the installed document to their menus for ease of reference by users.
+ Desktop RPM packages of <span class="application"><strong>Publican</strong></span> documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of <code class="filename">/usr/share/doc/</code>, the location specified by the <em class="citetitle">Filesystem Hierarchy Standard</em> (<em class="citetitle">FHS</em>) for ‘Miscellaneous documentation’.<sup>[<a id="id503494" href="#ftn.id503494" class="footnote">2</a>]</sup> The desktop RPM package also contains a <em class="firstterm">desktop file</em>, to be placed in <code class="filename">/usr/share/applications/</code>. This file enables <em class="firstterm">desktop environments</em> such as GNOME and KDE to add the installed document to their menus for ease of reference by users.
</div><div class="para">
Web RPM packages of <span class="application"><strong>Publican</strong></span> documents contain the documentation in single-page HTML, multi-page HTML, and PDF formats. They are installed in a subdirectory of <code class="filename">/var/www/html/</code>, a common <em class="firstterm">document root</em> for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.
- </div></div></div><div class="section" title="3.5.2. The publican package command" id="sect-Users_Guide-Packaging_a_book-The_publican_package_command"><div class="titlepage"><div><div><h3 class="title">3.5.2. The <code class="command">publican package</code> command</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.6.2. The publican package command" id="sect-Users_Guide-Packaging_a_book-The_publican_package_command"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.6.2. The <code class="command">publican package</code> command</h3></div></div></div><div class="para">
Use the <code class="command">publican package --lang=<em class="replaceable"><code>Language_Code</code></em></code> command to package documents for distribution in the language that you specify with the <code class="option">--lang</code> option. Refer to <a class="xref" href="#appe-Users_Guide-Language_codes" title="Appendix D. Language codes">Appendix D, <i>Language codes</i></a> for more information about language codes.
</div><div class="para">
If you run <code class="command">publican package</code> with no options other than the mandatory <code class="option">--lang</code> option, <span class="application"><strong>Publican</strong></span> produces a web SRPM package. The full range of options for <code class="command">publican package</code> is as follows:
@@ -1113,7 +1121,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
use of the <code class="option">--short_sighted</code> option removes the <code class="literal">-<em class="replaceable"><code>productnumber</code></em>-</code> from the package name.
</div></li></ul></div>
- </div><div class="section" title="3.5.2.1. The publican package command — Example usage" id="sect-Users_Guide-The_publican_package_command-The_publican_package_command_Example_usage"><div class="titlepage"><div><div><h4 class="title">3.5.2.1. The <code class="command">publican package</code> command — Example usage</h4></div></div></div><div class="para">
+ </div><div class="section" title="3.6.2.1. The publican package command — Example usage" id="sect-Users_Guide-The_publican_package_command-The_publican_package_command_Example_usage"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-The_publican_package_command-The_publican_package_command_Example_usage">3.6.2.1. The <code class="command">publican package</code> command — Example usage</h4></div></div></div><div class="para">
The following examples illustrate some common options, illustrated with the <em class="citetitle">Foomaster 9 Configuration Guide</em>, edition 2, revision 6.
</div><div class="variablelist"><dl><dt><span class="term"><code class="command">publican package --lang=cs-CZ</code></span></dt><dd><div class="para">
produces a web SRPM package named <span class="package">Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.src.rpm</span> that contains documentation in Czech.
@@ -1125,7 +1133,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
produces a desktop binary RPM package named <span class="package">Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm</span> that contains documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
</div></dd><dt><span class="term"><code class="command">publican package --desktop --short_sighted --lang=cs-CZ</code></span></dt><dd><div class="para">
produces a desktop SRPM package named <span class="package">Foomaster-Configuration_Guide-cs-CZ-2-6.src.rpm</span> that contains documentation in Czech. This package will replace any Configuration Guides for previous versions of <span class="application"><strong>Foomaster</strong></span> that exists on a system. Users cannot have access to both the <em class="citetitle">Foomaster 8 Configuration Guide</em> and the <em class="citetitle">Foomaster 9 Configuration Guide</em>.
- </div></dd></dl></div></div></div></div><div xml:lang="en-US" class="section" title="3.6. Conditional tagging" id="sect-Users_Guide-Conditional_tagging" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.6. Conditional tagging</h2></div></div></div><div class="para">
+ </div></dd></dl></div></div></div></div><div xml:lang="en-US" class="section" title="3.7. Conditional tagging" id="sect-Users_Guide-Conditional_tagging" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Conditional_tagging">3.7. Conditional tagging</h2></div></div></div><div class="para">
In some cases you may need to maintain multiple versions of a book; for example, a HOWTO guide for product FOO can have an upstream version and an enterprise version, with very subtle differences between them.
</div><div class="para">
<span class="application"><strong>Publican</strong></span> makes it easy to manage differences between multiple versions of a book by allowing you to use a single source for all versions. <em class="firstterm">Conditional tagging</em> allows you to make sure that version-specific content only appears in the correct version; that is, you <em class="firstterm">conditionalize</em> the content.
@@ -1174,12 +1182,12 @@ publican build --formats=pdf --langs=en-US
To exclude this chapter, add a condition to the <code class="sgmltag-element"><xi:include></code> tag in <code class="filename">User_Guide.xml</code>, not to the <code class="sgmltag-element"><chapter></code> tag in <code class="filename">Installation_and_configuration_on_Fedora.xml</code>.
</div></div><div class="important"><h2>xrefs and conditional tagging</h2><div class="para">
If an <code class="sgmltag-element"><xref></code> points to content not included in the build due to conditional tagging, the build will fail. For example, with <code class="command">condition: upstream</code> set in the <code class="filename">publican.cfg</code> file, <code class="command">publican build --formats=pdf --langs=en-US</code> will fail if the book has the tag <code class="sgmltag-element"><xref linkend="betasection"></code> pointing to <code class="sgmltag-element"><section id="betasection" condition="beta"></code>.
- </div></div><div class="section" title="3.6.1. Conditional tagging and translation" id="sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation"><div class="titlepage"><div><div><h3 class="title">3.6.1. Conditional tagging and translation</h3></div></div></div><div class="warning"><h2>Use conditional tagging with great caution</h2><div class="para">
+ </div></div><div class="section" title="3.7.1. Conditional tagging and translation" id="sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.7.1. Conditional tagging and translation</h3></div></div></div><div class="warning"><h2>Use conditional tagging with great caution</h2><div class="para">
Use conditional tagging only with great caution in books that you expect to be translated, as conditional tagging creates extra difficulties for translators.
</div></div><div class="para">
Conditional tagging creates difficulty for translators in two ways: it obscures context in the <em class="firstterm">portable object</em> (PO) files through which translators work, and it makes proofreading more difficult for translators who are not deeply familiar with your book and all the conditions that you have set.
</div><div class="para">
- PO files do not include attributes from tags. When translators open the PO file for the example from <em class="citetitle">How To Use Product Foo</em> in <a class="xref" href="#sect-Users_Guide-Conditional_tagging" title="3.6. Conditional tagging">Section 3.6, “Conditional tagging”</a>, they see:
+ PO files do not include attributes from tags. When translators open the PO file for the example from <em class="citetitle">How To Use Product Foo</em> in <a class="xref" href="#sect-Users_Guide-Conditional_tagging" title="3.7. Conditional tagging">Section 3.7, “Conditional tagging”</a>, they see:
</div><pre class="programlisting">
#. Tag: para
#, no-c-format
@@ -1207,13 +1215,13 @@ msgstr ""
Furthermore, unless the translators who work on your book know how to configure <span class="application"><strong>Publican</strong></span>'s <code class="filename">publican.cfg</code> 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.
</div><div class="para">
As an alternative to conditionals, consider maintaining separate versions of your book in separate branches of a version-controlled repository. You can still share XML files and even PO files between the various branches as necessary, and some version control systems allow you to share changes readily among branches.
- </div></div></div><div xml:lang="en-US" class="section" title="3.7. Pre-release software and draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.7. Pre-release software and draft documentation</h2></div></div></div><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.8. Pre-release software and draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation">3.8. Pre-release software and draft documentation</h2></div></div></div><div class="para">
Completed documentation for pre-release software is not the same thing as draft documentation.
</div><div class="para">
Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.
</div><div class="para">
In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.
- </div><div class="section" title="3.7.1. Denoting pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software"><div class="titlepage"><div><div><h3 class="title">3.7.1. Denoting pre-release software</h3></div></div></div><div class="para">
+ </div><div class="section" title="3.8.1. Denoting pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.8.1. Denoting pre-release software</h3></div></div></div><div class="para">
Documentation for pre-release software, especially pre-release software being distributed to testers, customers and partners, should carry a clear mark denoting the beta-status of the software.
</div><div class="para">
To create that mark do the following:
@@ -1231,7 +1239,7 @@ msgstr ""
Because this approach makes no changes to the information in <code class="filename">Book_Info.xml</code> used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.
</div><div class="important"><h2>Important</h2><div class="para">
It is the writer's responsibility to remove the <code class="sgmltag-element"><remark></code> tag and its contents and remove or turn off <code class="varname">show_remarks</code> when documentation is updated for use with the release version of the software.
- </div></div></div><div class="section" title="3.7.2. Denoting draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation"><div class="titlepage"><div><div><h3 class="title">3.7.2. Denoting draft documentation</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.8.2. Denoting draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.8.2. Denoting draft documentation</h3></div></div></div><div class="para">
Unfinished documentation made available to others for review should be labeled clearly as such.
</div><div class="procedure"><ul><li class="step" title="Step 1"><div class="para">
To add the draft watermark to your documentation add the <strong class="userinput"><code>status="draft"</code></strong> attribute to the <code class="sgmltag-element"><article></code>, <code class="sgmltag-element"><book></code> or <code class="sgmltag-element"><set></code> tag in your document's root node. For example:
@@ -1245,15 +1253,15 @@ msgstr ""
Adding the <strong class="userinput"><code>status="draft"</code></strong> attribute causes each page of the document to show the draft watermark. This is by design.
</div><div class="para">
Even if you change only a portion of a work before sending it out for review, marking every page as draft will encourage reviewers to report errors or typos they spot in passing. It will also ensure non-reviewers who encounter the work do not mistake a draft for a finished version.
- </div></div><div class="section" title="3.7.3. Denoting draft documentation of pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software"><div class="titlepage"><div><div><h3 class="title">3.7.3. Denoting draft documentation of pre-release software</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="3.8.3. Denoting draft documentation of pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.8.3. Denoting draft documentation of pre-release software</h3></div></div></div><div class="para">
To denote unfinished documentation of pre-release software properly, do both previously noted procedures.
- </div></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id720619" href="#id720619" class="para">1</a>] </sup>
+ </div></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id627973" href="#id627973" class="para">1</a>] </sup>
Refer to <a href="http://www.section508.gov/">http://www.section508.gov/</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id595292" href="#id595292" class="para">2</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id503494" href="#id503494" class="para">2</a>] </sup>
Refer to <a href="http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA">http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA</a>
</p></div></div></div><div xml:lang="en-US" class="chapter" title="Chapter 4. Branding" id="chap-Users_Guide-Branding" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 4. Branding</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</a></span></dt><dt><span class="section"><a hr
ef="#sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Gui
de-Packaging_a_brand">4.4. Packaging a brand</a></span></dt></dl></div><div class="para">
<em class="firstterm">Brands</em> are collections of files that <span class="application"><strong>Publican</strong></span> uses to apply a consistent look and style to HTML and PDF output. They provide boilerplate text that appears at the beginning of documents, images such as logos, and stylistic elements such as color schemes. <span class="application"><strong>Publican</strong></span> ships with one brand, <code class="filename">common/</code>. Documentation projects can produce and distribute brands to their contributors, either as a package (for example, an RPM package) or as an archive (for example, a tarball or ZIP file).
- </div><div xml:lang="en-US" class="section" title="4.1. Installing a brand" id="sect-Users_Guide-Installing_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.1. Installing a brand</h2></div></div></div><div class="para">
+ </div><div xml:lang="en-US" class="section" title="4.1. Installing a brand" id="sect-Users_Guide-Installing_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</h2></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> brands for Fedora, Genome, and oVirt documents are available as RPM packages in Fedora. Similarly, Red Hat internally distributes RPM packages containing <span class="application"><strong>Publican</strong></span> brands for GIMP, JBoss, and Red Hat documents. Providing that you have access to the relevant repositories, you can install these brands on a computer that runs Red Hat Enterprise Linux or Fedora — or an operating system derived from either — with the command <code class="command">yum install publican-<em class="replaceable"><code>brand</code></em></code> or with a graphical package manager such as <span class="application"><strong>PackageKit</strong></span>.
</div><div class="para">
If you use <span class="application"><strong>Publican</strong></span> on an operating system that does not use RPM packages, your documentation project might provide its brand in another format. Whatever the format in which the brand is supplied, you must place the brand files in a subdirectory of the <span class="application"><strong>Publican</strong></span> Common Content directory. By default, this directory is located at <code class="filename">/usr/share/publican/Common_Content</code> on Linux operating systems and at <code class="filename">%SystemDrive%/%ProgramFiles%/Publican/Common_Content</code> on Windows operating systems — typically, <code class="filename">C:/Program Files/Publican/Common_Content</code>
@@ -1265,29 +1273,22 @@ msgstr ""
If the brand was supplied to you in an archive of some kind, for example, a tarball or ZIP file, unpack the brand into a new directory on your system.
</div></li><li class="step" title="Step 2"><div class="para">
Change into the directory in which you created or unpacked the brand:
- </div><pre class="screen"><code class="command">cd publican-<em class="replaceable"><code>brand</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">cd publican-<em class="replaceable"><code>brand</code></em></code></pre><div class="para">
where <em class="replaceable"><code>brand</code></em> is the name of the brand.
</div></li><li class="step" title="Step 3"><div class="para">
Build the brand:
- </div><pre class="screen"><code class="command">publican build --formats xml --langs all --publish</code>
-</pre></li><li class="step" title="Step 4"><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats xml --langs all --publish</code></pre></li><li class="step" title="Step 4"><div class="para">
Install the brand:
- </div><pre class="screen"><code class="command">sudo publican installbrand --path <em class="replaceable"><code>path</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">sudo publican install_brand --path <em class="replaceable"><code>path</code></em></code></pre><div class="para">
where <em class="replaceable"><code>path</code></em> is the path to the <span class="application"><strong>Publican</strong></span> Common Content files. For example, on a Linux system, run:
- </div><pre class="screen"><code class="command">sudo publican installbrand --path /usr/share/publican/Common_Content</code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">sudo publican install_brand --path /usr/share/publican/Common_Content</code></pre><div class="para">
or on a Windows system, run
- </div><pre class="screen"><code class="command">sudo publican installbrand --path "C:/Program Files/Publican/Common_Content"</code>
-</pre></li><li class="step" title="Step 5"><div class="para">
-
- </div></li><li class="step" title="Step 6"><div class="para">
-
- </div></li></ol></div><div class="table"><div class="table-contents"><table summary="Current Brands and their packages" border="1"><colgroup><col width="14%" /><col width="29%" /><col width="29%" /><col width="29%" /></colgroup><thead><tr><th>
+ </div><pre class="screen"><code class="command">publican install_brand --path "C:/Program Files/Publican/Common_Content"</code></pre></li></ol></div><div class="table" title="Table 4.1. Current Brands and their packages" id="tabl-Users_Guide-Installing_a_brand-Current_Brands_and_their_packages"><div class="table-contents"><table summary="Current Brands and their packages" border="1"><colgroup><col width="11%" /><col width="22%" /><col width="22%" /><col width="22%" /><col width="22%" /></colgroup><thead><tr><th>
Brand
</th><th>
- License
+ License of Common Content files
+ </th><th>
+ Default license for documents
</th><th>
Package
</th><th>
@@ -1295,6 +1296,8 @@ msgstr ""
</th></tr></thead><tbody><tr><td>
common
</td><td>
+ <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0</a>
+ </td><td>
<a href="http://www.gnu.org/licenses/fdl.html">GFDL Version 1.2</a>
</td><td>
publican
@@ -1305,13 +1308,17 @@ msgstr ""
</td><td>
<a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA 3.0</a>
</td><td>
+ <span>CC-BY-SA 3.0</span>
+ </td><td>
publican-redhat
</td><td>
</td></tr><tr><td>
Fedora
</td><td>
- <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA 3.0</a>
+ <span>CC-BY-SA 3.0</span>
+ </td><td>
+ <span>CC-BY-SA 3.0</span>
</td><td>
publican-fedora
</td><td>
@@ -1319,7 +1326,9 @@ msgstr ""
</td></tr><tr><td>
JBoss
</td><td>
- <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA 3.0</a>
+ <span>CC-BY-SA 3.0</span>
+ </td><td>
+ <span>CC-BY-SA 3.0</span>
</td><td>
publican-jboss
</td><td>
@@ -1329,6 +1338,8 @@ msgstr ""
</td><td>
<a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
</td><td>
+ <span>OPL 1.0</span>
+ </td><td>
publican-ovirt
</td><td>
No Options.
@@ -1337,31 +1348,34 @@ msgstr ""
</td><td>
<a href="http://www.gnu.org/licenses/fdl.html">GFDL Version 1.2</a>
</td><td>
+ <span>GFDL Version 1.2</span>
+ </td><td>
publican-gimp
</td><td>
- GPL compatible license. No options.
+ Matches the license for existing GIMP documentation.
</td></tr><tr><td>
Genome
</td><td>
- <a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
+ <span>OPL 1.0</span>
+ </td><td>
+ <span>OPL 1.0</span>
</td><td>
publican-genome
</td><td>
No Options.
- </td></tr></tbody></table></div><h6>Table 4.1. Current Brands and their packages</h6></div><br class="table-break" /></div><div xml:lang="en-US" class="section" title="4.2. Creating a brand" id="sect-Users_Guide-Creating_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.2. Creating a brand</h2></div></div></div><div class="para">
+ </td></tr></tbody></table></div><h6>Table 4.1. Current Brands and their packages</h6></div><br class="table-break" /><div class="para">
+ Note the difference in licensing between the common content files provided in the common brand (CC0) and the default license set for books generated with the common brand (GFDL). The CC0 license allows you to redistribute and relicense the files that make up the common brand (including the CSS and image files) to suit your project. <span class="application"><strong>Publican</strong></span> suggests the GFDL for documentation by default because <span class="application"><strong>Publican</strong></span> is developed primarily to build documentation for software. The GFDL is compatible with the GPL, which is the most commonly used license for open-source software.
+ </div></div><div xml:lang="en-US" class="section" title="4.2. Creating a brand" id="sect-Users_Guide-Creating_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</h2></div></div></div><div class="para">
Use the <code class="command">create_brand</code> action to create a new brand. When you create a new brand, you must give it a name and specify the original language for the brand's XML files. The <code class="option">--name</code> option provides the name, and the <code class="option">--lang</code> option specifies the language. The complete command is therefore:
- </div><pre class="screen"><code class="command">publican create_brand --name=<em class="replaceable"><code>brand</code></em> --lang=<em class="replaceable"><code>language_code</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">publican create_brand --name=<em class="replaceable"><code>brand</code></em> --lang=<em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
<span class="application"><strong>Publican</strong></span> creates a new subdirectory named <code class="filename">publican-<em class="replaceable"><code>brand</code></em></code>, where <em class="replaceable"><code>brand</code></em> is the brand that you specified with the <code class="option">--name</code> option.
</div><div class="para">
For example, to create a brand called <code class="literal">Acme</code>, which will have its Common Content XML files written originally in American English, run:
- </div><pre class="screen"><code class="command">publican create_brand --name=Acme --lang=en-US</code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">publican create_brand --name=Acme --lang=en-US</code></pre><div class="para">
<span class="application"><strong>Publican</strong></span> creates the brand in a subdirectory named <code class="filename">publican-Acme</code>.
</div><div class="para">
To configure your new brand, search for the word <code class="literal">SETUP</code> in the default files that <span class="application"><strong>Publican</strong></span> creates and edit the files to provide the missing details. On Linux operating systems, you can search for the word <code class="literal">SETUP</code> in these files with the command:
- </div><pre class="screen"><code class="command">grep -r 'SETUP' *</code>
-</pre></div><div xml:lang="en-US" class="section" title="4.3. Files in the brand directory" id="sect-Users_Guide-Files_in_the_brand_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.3. Files in the brand directory</h2></div></div></div><div class="para">
+ </div><pre class="screen"><code class="command">grep -r 'SETUP' *</code></pre></div><div xml:lang="en-US" class="section" title="4.3. Files in the brand directory" id="sect-Users_Guide-Files_in_the_brand_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</h2></div></div></div><div class="para">
Running the <code class="command">publican create_brand --name=<em class="replaceable"><code>brand</code></em> --lang=<em class="replaceable"><code>language_code</code></em></code> command creates a directory structure and the required files. The brand directory initially contains:
<div class="itemizedlist"><ul><li class="listitem"><div class="para">
<code class="filename">COPYING</code>
@@ -1389,7 +1403,7 @@ msgstr ""
the <code class="filename">images</code> subdirectory, which contains 43 images in both raster (PNG) and vector (SVG) formats.
</div></li></ul></div></li></ul></div>
- </div><div class="section" title="4.3.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title">4.3.1. The publican.cfg file</h3></div></div></div><div class="para">
+ </div><div class="section" title="4.3.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</h3></div></div></div><div class="para">
The <code class="filename">publican.cfg</code> file in a brand serves a similar purpose to the <code class="filename">publican.cfg</code> file in a document — it configures a number of basic options that define your brand.
</div><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>version</code></em></span></dt><dd><div class="para">
specifies the version number for the brand. When you create the brand with <code class="command">publican create_brand</code>, the version number is set to <code class="literal">1.0</code>. Update the version number here in the brand <code class="filename">publican.cfg</code> file and in the brand <code class="filename">publican.spec</code> file when you prepare a new version of the brand.
@@ -1403,7 +1417,7 @@ msgstr ""
when set to <code class="literal">type=brand</code>, this parameter identifies the contents of this directory as a brand, rather than a book, article, or set.
</div></dd><dt><span class="term"><em class="parameter"><code>brand</code></em></span></dt><dd><div class="para">
specifies the name of the brand, as set by the <code class="option">--name</code> option for <code class="command">publican create_brand</code>.
- </div></dd></dl></div></div><div class="section" title="4.3.2. The defaults.cfg file and overrides.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file"><div class="titlepage"><div><div><h3 class="title">4.3.2. The defaults.cfg file and overrides.cfg file</h3></div></div></div><div class="para">
+ </div></dd></dl></div></div><div class="section" title="4.3.2. The defaults.cfg file and overrides.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</h3></div></div></div><div class="para">
Every document built in <span class="application"><strong>Publican</strong></span> has a <code class="filename">publican.cfg</code> file in its root directory, which configures build options for the document. Refer to <a class="xref" href="#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a> for a full description of these options. The <code class="filename">defaults.cfg</code> file and <code class="filename">overrides.cfg</code> file in a brand supply default values for any of the parameters that you can otherwise set with a document's <code class="filename">publican.cfg</code> file.
</div><div class="para">
When you build a document with a particular brand, <span class="application"><strong>Publican</strong></span> first applies the values in the brand's <code class="filename">defaults.cfg</code> file before it applies the values in the document's <code class="filename">publican.cfg</code> file. Values in the document's <code class="filename">publican.cfg</code> file therefore override those in the brand's <code class="filename">defaults.cfg</code> file.
@@ -1411,25 +1425,25 @@ msgstr ""
<span class="application"><strong>Publican</strong></span> next applies the values in the brand's <code class="filename">overrides.cfg</code> file, which therefore override any values in the brand's <code class="filename">defaults.cfg</code> file and the document's <code class="filename">publican.cfg</code> file.
</div><div class="para">
Use the <code class="filename">defaults.cfg</code> file to set values that you routinely apply to your brand but want to allow writers to change in particular books; use the <code class="filename">overrides.cfg</code> file for values that you do not want to allow writers to change.
- </div></div><div class="section" title="4.3.3. publican-brand.spec file" id="sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file"><div class="titlepage"><div><div><h3 class="title">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.3. publican-brand.spec file" id="sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</h3></div></div></div><div class="para">
Some Linux operating systems use the <span class="application"><strong>RPM Package Manager</strong></span> to distribute software, in the form of <em class="firstterm">RPM packages</em>. In general terms, an RPM package contains software files compressed into an archive, accompanied by a <em class="firstterm">spec file</em> that tells the <span class="application"><strong>RPM Package Manager</strong></span> how and where to install those files.
</div><div class="para">
When you create a brand, <span class="application"><strong>Publican</strong></span> generates the outline of an RPM spec file for the brand. The automatically generated spec file provides you with a starting point from which to create an RPM package to distribute your brand. Refer to <a class="xref" href="#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> to learn how to configure the spec file and use it to produce an RPM package.
- </div></div><div class="section" title="4.3.4. README" id="sect-Users_Guide-Files_in_the_brand_directory-README"><div class="titlepage"><div><div><h3 class="title">4.3.4. README</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.4. README" id="sect-Users_Guide-Files_in_the_brand_directory-README"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</h3></div></div></div><div class="para">
The <code class="filename">README</code> file in an SRPM package includes a brief description of the package.
- </div></div><div class="section" title="4.3.5. COPYING" id="sect-Users_Guide-Files_in_the_brand_directory-COPYING"><div class="titlepage"><div><div><h3 class="title">4.3.5. COPYING</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.5. COPYING" id="sect-Users_Guide-Files_in_the_brand_directory-COPYING"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</h3></div></div></div><div class="para">
The <code class="filename">COPYING</code> file in an SRPM package contains details of the copyright license for the package.
- </div></div><div class="section" title="4.3.6. Common Content for the brand" id="sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand"><div class="titlepage"><div><div><h3 class="title">4.3.6. Common Content for the brand</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.6. Common Content for the brand" id="sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</h3></div></div></div><div class="para">
Inside the brand directory is a subdirectory named after the default XML language for brand, as set with the <code class="option">--lang</code> option when you created the brand. This subdirectory contains XML and image files that override the default Common Content provided with <span class="application"><strong>Publican</strong></span>. Customizing these files provides your brand with its distinctive appearance, including its color scheme and logos.
- </div><div class="section" title="4.3.6.1. Feedback.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Feedback.xml"><div class="titlepage"><div><div><h4 class="title">4.3.6.1. <code class="filename">Feedback.xml</code></h4></div></div></div><div class="para">
+ </div><div class="section" title="4.3.6.1. Feedback.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Feedback.xml"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Common_Content_for_the_brand-Feedback.xml">4.3.6.1. <code class="filename">Feedback.xml</code></h4></div></div></div><div class="para">
The <code class="filename">Feedback.xml</code> file is included by default in the preface of every book produced in <span class="application"><strong>Publican</strong></span>. It invites readers to leave feedback about the document. Customize this file with the contact details of your project. If your project uses a bug tracking system such as <span class="application"><strong>Bugzilla</strong></span>, <span class="application"><strong>JIRA</strong></span>, or <span class="application"><strong>Trac</strong></span>, you could include this information here.
- </div></div><div class="section" title="4.3.6.2. Legal_Notice.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Legal_Notice.xml"><div class="titlepage"><div><div><h4 class="title">4.3.6.2. <code class="filename">Legal_Notice.xml</code></h4></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.6.2. Legal_Notice.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Legal_Notice.xml"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Common_Content_for_the_brand-Legal_Notice.xml">4.3.6.2. <code class="filename">Legal_Notice.xml</code></h4></div></div></div><div class="para">
The <code class="filename">Legal_Notice.xml</code> file contains the legal notice that appears at the beginning of every document produced by <span class="application"><strong>Publican</strong></span>. Insert the details of your chosen copyright license into this file. Typically, this might include the name of the license, a short summary of the license, and a link to the full details of the license.
- </div></div></div><div class="section" title="4.3.7. The css subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory"><div class="titlepage"><div><div><h3 class="title">4.3.7. The <code class="filename">css</code> subdirectory</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="4.3.7. The css subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</h3></div></div></div><div class="para">
The <code class="filename">css</code> subdirectory contains a single file: <code class="filename">overrides.css</code>.
- </div><div class="section" title="4.3.7.1. overrides.css" id="sect-Users_Guide-The_css_subdirectory-overrides.css"><div class="titlepage"><div><div><h4 class="title">4.3.7.1. overrides.css</h4></div></div></div><div class="para">
+ </div><div class="section" title="4.3.7.1. overrides.css" id="sect-Users_Guide-The_css_subdirectory-overrides.css"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-The_css_subdirectory-overrides.css">4.3.7.1. overrides.css</h4></div></div></div><div class="para">
The <code class="filename">overrides.css</code> file sets the visual style for your brand. Values in this file override those in <span class="application"><strong>Publican</strong></span>'s <code class="filename">Common_Content/common/<em class="replaceable"><code>xml_lang</code></em>/css/common.css</code> file.
- </div></div></div><div class="section" title="4.3.8. The images subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory"><div class="titlepage"><div><div><h3 class="title">4.3.8. The <code class="filename">images</code> subdirectory</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="4.3.8. The images subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</h3></div></div></div><div class="para">
The <code class="filename">images</code> subdirectory contains 43 images in both <em class="firstterm">portable network graphics</em> (PNG) and <em class="firstterm">scalable vector graphics</em> (SVG) format. These images are placeholders for various navigation icons, admonition graphics, and brand logos. They include:
</div><div class="variablelist"><dl><dt><span class="term"><code class="filename">image_left</code></span></dt><dd><div class="para">
is a logo for the product to which this document applies. It appears at the top left corner of HTML pages, where it contains a hyperlink to a web page for the product, as defined by <em class="parameter"><code>prod_url</code></em> in the <code class="filename">publican.cfg</code> file for the document. Consider setting <em class="parameter"><code>prod_url</code></em> in the brand's <code class="filename">defaults.cfg</code> or <code class="filename">overrides.cfg</code> file.
@@ -1446,8 +1460,8 @@ msgstr ""
</div></dd><dt><span class="term"><code class="filename">h1-bg</code></span></dt><dd><div class="para">
is a background for the heading that contains the name of your product, as it appears at the very beginning of a HTML document.
</div></dd><dt><span class="term"><code class="filename">watermark_draft</code></span></dt><dd><div class="para">
- is a watermark that appears on pages of draft documentation. Refer to <a class="xref" href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation" title="3.7.2. Denoting draft documentation">Section 3.7.2, “Denoting draft documentation”</a>.
- </div></dd></dl></div></div></div><div xml:lang="en-US" class="section" title="4.4. Packaging a brand" id="sect-Users_Guide-Packaging_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.4. Packaging a brand</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
+ is a watermark that appears on pages of draft documentation. Refer to <a class="xref" href="#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation" title="3.8.2. Denoting draft documentation">Section 3.8.2, “Denoting draft documentation”</a>.
+ </div></dd></dl></div></div></div><div xml:lang="en-US" class="section" title="4.4. Packaging a brand" id="sect-Users_Guide-Packaging_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
This section discusses packaging documents for distribution through the <span class="application"><strong>RPM Package Manager</strong></span>. However, when you use the <code class="command">publican package</code> command, <span class="application"><strong>Publican</strong></span> generates a tarball that you can use to build a package to distribute through different package manager software. If you run <code class="command">publican package</code> on a computer on which <span class="application"><strong>rpmbuild</strong></span> is not installed, <span class="application"><strong>Publican</strong></span> still generates the tarball, even though it cannot then generate an RPM package from that tarball.
</div></div><div class="para">
After you create a brand (as described in <a class="xref" href="#sect-Users_Guide-Creating_a_brand" title="4.2. Creating a brand">Section 4.2, “Creating a brand”</a>), <span class="application"><strong>Publican</strong></span> can help you to distribute the brand to members of your documentation project as <em class="firstterm">RPM packages</em>. RPM packages are used to distribute software to computers with Linux operating systems that use the <span class="application"><strong>RPM Package Manager</strong></span>. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
@@ -1466,7 +1480,7 @@ msgstr ""
</div></dd><dt><span class="term"><code class="option">--scratch</code></span></dt><dd><div class="para">
when used together with the <code class="option">--brew</code> option, specifies that a SRPM package should be built as a <em class="firstterm">scratch build</em> when sent to <span class="application"><strong>Brew</strong></span>. Scratch builds are used to verify that a SRPM package is structured correctly, without updating the package database to use the resulting package.
</div></dd></dl></div><div class="para">
- The <code class="option">--lang</code>, <code class="option">--desktop</code> and <code class="option">--short_sighted</code> options that apply when you package books (described in <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>) are meaningless when you package brands. In particular, note that although the <code class="option">--lang</code> option is mandatory when you package a book, you do not need to use it when you package a brand.
+ The <code class="option">--lang</code>, <code class="option">--desktop</code> and <code class="option">--short_sighted</code> options that apply when you package books (described in <a class="xref" href="#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>) are meaningless when you package brands. In particular, note that although the <code class="option">--lang</code> option is mandatory when you package a book, you do not need to use it when you package a brand.
</div><div class="para">
By default, <span class="application"><strong>Publican</strong></span> brand packages are named <code class="filename">publican-<em class="replaceable"><code>brand</code></em>-<em class="replaceable"><code>version</code></em>-<em class="replaceable"><code>release</code></em>.<em class="replaceable"><code>[build_target]</code></em>.[noarch].<em class="replaceable"><code>file_extension</code></em></code>. <span class="application"><strong>Publican</strong></span> uses the information in the <code class="filename">publican.cfg</code> file to supply the various parameters in the file name. Refer to <a class="xref" href="#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file" title="4.3.1. The publican.cfg file">Section 4.3.1, “The publican.cfg file”</a> for details of configuring this file. Additionally:
<div class="itemizedlist"><ul><li class="listitem"><div class="para">
@@ -1477,7 +1491,7 @@ msgstr ""
</div></div></div><div xml:lang="en-US" class="chapter" title="Chapter 5. Using sets" id="chap-Users_Guide-Using_sets" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 5. Using sets</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</a></span></dt></dl></div><div class="para">
A <em class="firstterm">set</em> is a collection of books, published as a single output. The <em class="citetitle">Services Plan</em> for example is a set comprised of many books such as the <em class="citetitle">Developer Guide</em>, <em class="citetitle">Engineering Content Services Guide</em> and the <em class="citetitle">Engineering Operations Guide</em> to name just a few. The <code class="command">create_book</code> command creates a template for a set by setting the <em class="parameter"><code>type</code></em> parameter to <code class="literal">Set</code>. There are two types of sets, <em class="firstterm">stand-alone sets</em> and <em class="firstterm">distributed sets</em>.
- </div><div class="section" title="5.1. Stand-alone sets" id="sect-Users_Guide-Using_sets-Stand_alone_sets"><div class="titlepage"><div><div><h2 class="title">5.1. Stand-alone sets</h2></div></div></div><div class="para">
+ </div><div class="section" title="5.1. Stand-alone sets" id="sect-Users_Guide-Using_sets-Stand_alone_sets"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</h2></div></div></div><div class="para">
A stand-alone set contains the XML files for each book, all of which are located inside the directory of the set.
</div><div class="para">
The procedure that follows will guide you through the process of creating a stand-alone set named <em class="citetitle">My Set</em> located in a directory called <code class="filename">books/My_Set/</code>. The set will contain <em class="citetitle">Book A</em> and <em class="citetitle">Book B</em> both of which will be manually created inside the <code class="filename">books/My_Set/en-US</code> directory.
@@ -1519,10 +1533,11 @@ mkdir Book_A Book_B
<span class="perl_Keyword"><xi:include</span><span class="perl_Others"> href=</span><span class="perl_String">"Revision_History.xml"</span><span class="perl_Others"> xmlns:xi=</span><span class="perl_String">"http://www.w3.org/2001/XInclude"</span> <span class="perl_Keyword">/></span>
<span class="perl_Keyword"></set></span>
+
</pre></li><li class="step" title="Step 6"><div class="para">
Test your set by running the <code class="command">publican build --formats=test langs=en-US</code> command.
- </div></li></ol></div></div><div class="section" title="5.2. Distributed sets" id="sect-Users_Guide-Using_sets-Distributed_sets"><div class="titlepage"><div><div><h2 class="title">5.2. Distributed sets</h2></div></div></div><div class="para">
+ </div></li></ol></div></div><div class="section" title="5.2. Distributed sets" id="sect-Users_Guide-Using_sets-Distributed_sets"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</h2></div></div></div><div class="para">
A <em class="firstterm">distributed set</em> contains books that are located in a version-controlled repository. Although several version control systems exist, this version of <span class="application"><strong>Publican</strong></span> supports only one: <span class="application"><strong>Subversion</strong></span> (<span class="application"><strong>SVN</strong></span>). By setting the repository location and titles of the included books in the <code class="filename">publican.cfg</code> file, each book can be exported to build the entire set. The procedure that follows will guide you through the process of creating a set named <em class="citetitle">My Set</em> containing <em class="citetitle">Book A</em> and <em class="citetitle">Book B</em>.
</div><div class="important"><h2>Important</h2><div class="para">
The following procedure assumes that <em class="citetitle">Book A</em> and <em class="citetitle">Book B</em> already exist and are available in your <span class="application"><strong>SVN</strong></span> repository. Currently <span class="application"><strong>Publican</strong></span> only supports <span class="application"><strong>SVN</strong></span>.
@@ -1551,82 +1566,238 @@ scm = SVN
<span class="perl_Keyword"><xi:include</span><span class="perl_Others"> href=</span><span class="perl_String">"Revision_History.xml"</span><span class="perl_Others"> xmlns:xi=</span><span class="perl_String">"http://www.w3.org/2001/XInclude"</span> <span class="perl_Keyword">/></span>
<span class="perl_Keyword"></set></span>
+
</pre></li><li class="step" title="Step 4"><div class="para">
Test your set by running the <code class="command">publican build --formats=test --langs=en-US</code> command.
</div><div class="important"><h2>Important</h2><div class="para">
When building a set, the <code class="command">publican clean_ids</code> command will be run over each book because of the constraint that IDs must be unique across all books. Be careful of creating IDs that rely on content that may not be available when building books independently of the set.
- </div></div></li></ol></div></div></div><div xml:lang="en-US" class="chapter" title="Chapter 6. Frequently Asked Questions" id="chap-Users_Guide-Frequently_Asked_Questions" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 6. Frequently Asked Questions</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><dl><dt>Q: <a href="#id720356">
+ </div></div></li></ol></div></div></div><div xml:lang="en-US" class="chapter" title="Chapter 6. Building a website with Publican" id="sect-Users_Guide-Website" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 6. Building a website with Publican</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#sect-Users_Guide-Website-structure">6.1. The website structure</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-cfg_and_db">6.1.1. Creating the website structure</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-home_page">6.2. The home page</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-documents">6.3. Installing, updating and removing documents</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-documents-manual">6.3.1. Installing, updating and removing d
ocuments manually</a></span></dt><dt><span class="section"><a href="#sect-Users_Guide-Website-structure-documents-rpm">6.3.2. Installing, updating and removing documents as RPM packages</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Users_Guide-Website-automation">6.4. Automating publishing</a></span></dt></dl></div><div class="para">
+ <span class="application"><strong>Publican</strong></span> not only builds documents for publication but can build and manage a documentation website as well. For a suite of documents that you maintain by yourself, you can use <span class="application"><strong>Publican</strong></span> to build a site on your local system; you can then upload the site to a webserver by whatever means you choose. This approach does not scale well, however, so for team-based documentation projects, <span class="application"><strong>Publican</strong></span> can generate RPM packages of documentation to install on the webserver.
+ </div><div class="para">
+ The websites that <span class="application"><strong>Publican</strong></span> creates consist of three parts: the website structure, a home page, and the documents published on the site.
+ </div><div class="section" title="6.1. The website structure" id="sect-Users_Guide-Website-structure"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-structure">6.1. The website structure</h2></div></div></div><div class="para">
+ The website structure itself consists of:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ a configuration file.
+ </div></li><li class="listitem"><div class="para">
+ an SQLite database file.
+ </div></li><li class="listitem"><div class="para">
+ a subdirectory for the published documents, which contains:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="filename">index.html</code> — an index page with no content that redirects to localized versions of a home page for the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">interactive.css</code> — a CSS stylesheet that contains styles for the navigation menu, map, and site statistics page.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">Sitemap</code> — an XML Sitemap to assist search engines to crawl the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">toc.html</code> — a static map of the documents on the site, to assist visitors to the site who do not have JavaScript enabled on their browsers.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">toc.js</code> — a JavaScript script that directs visitors to localized content based on the locale set in their browser and controls the presentation of the navigation menu.
+ </div></li><li class="listitem"><div class="para">
+ subdirectories for each language in which you publish. Initially, this contains: <code class="filename">Site_Statistics.html</code>
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="filename">Site_Statistics.html</code> — an overview of the documentation installed on the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">Site_Tech.html</code> — an overview of the technology used to build the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">toc.html</code> — the table of contents for that language, initially empty.
+ </div></li></ul></div></li></ul></div></li></ul></div><div class="section" title="6.1.1. Creating the website structure" id="sect-Users_Guide-Website-structure-cfg_and_db"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Website-structure-cfg_and_db">6.1.1. Creating the website structure</h3></div></div></div><div class="para">
+ To build the website structure:
+ </div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ Create a new directory and change into it. For example, on a Linux system, run:
+ </div><pre class="screen"><code class="command">mkdir ~/docsite</code>
+<code class="command">cd ~/docsite</code></pre></li><li class="step" title="Step 2"><div class="para">
+ Run <code class="command">publican create_site</code>, specifying the following parameters:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="option">--site_config</code> — the name of the configuration file for your site, with the filename extension <code class="filename">.cfg</code>
+ </div></li><li class="listitem"><div class="para">
+ <code class="option">--db_file</code> — the name of the SQLite database file for your site, with the filename extension <code class="filename">.db</code>
+ </div></li><li class="listitem"><div class="para">
+ <code class="option">--toc_path</code> — the path to the directory in which you will place your documents
+ </div></li></ul></div><div class="para">
+ On a computer with an operating system other than Linux, also set:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="option">--temp_path</code> — the path to the <code class="filename">templates/</code> directory of your <span class="application"><strong>Publican</strong></span> installation. On computers with Windows operating systems, this is typically <code class="filename"><em class="replaceable"><code>%SystemDrive%</code></em>\<em class="replaceable"><code>%ProgramFiles%</code></em>\Publican\templates</code>.
+ </div></li></ul></div><div class="para">
+ For example:
+ </div><pre class="screen"><code class="command">publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs</code></pre><div class="para">
+ Typically, you might give names to the site configuration file and database file that help you to recognize the site to which they belong. For example, for the <span class="application"><strong>FooMaster</strong></span> documentation site, you might call these files <code class="filename">foomaster.cfg</code> and <code class="filename">foomaster.db</code>.
+ </div><div class="para">
+ If you plan to install documentation on the webserver with <span class="application"><strong>Publican</strong></span>-generated RPM packages, set <em class="parameter"><code>--toc_path</code></em> to <code class="literal">/var/www/html/docs</code>. If you plan to build the site manually and upload it to the webserver, you can set <em class="parameter"><code>--toc_path</code></em> to whatever you choose.
+ </div></li><li class="step" title="Step 3"><div class="para">
+ If you plan to install <span class="application"><strong>Publican</strong></span>-generated RPM packages of documents on the site, transfer the site structure to the <code class="filename">/var/www/</code> directory of your webserver now by whatever process you usually use, for example <span class="application"><strong>scp</strong></span>, <span class="application"><strong>rsync</strong></span>, or an FTP client. If you plan to build the site manually, you can wait until you finish building the site and then upload the complete site.
+ </div></li></ol></div><div class="para">
+ To make <span class="application"><strong>Publican</strong></span> refresh the site structure at any time, run:
+ </div><pre class="screen"><code class="command">publican update_site --site_config <em class="replaceable"><code>path_to_site_configuration_file</code></em>.cfg</code></pre></div></div><div class="section" title="6.2. The home page" id="sect-Users_Guide-Website-structure-home_page"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-structure-home_page">6.2. The home page</h2></div></div></div><div class="para">
+ The <span class="application"><strong>Publican</strong></span>-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook <code class="sgmltag-element"><article></code> with an extra <em class="parameter"><code>web_home</code></em> parameter in its <code class="filename">publican.cfg</code> file. To create the home page:
+ </div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ Change into a convenient directory and run the following <code class="command">publican create</code> command:
+ </div><pre class="screen"><code class="command">publican create --type Article --name <em class="replaceable"><code>page_name</code></em></code></pre><div class="para">
+ For example:
+ </div><pre class="screen"><code class="command">publican create --type Article --name Home_Page</code></pre></li><li class="step" title="Step 2"><div class="para">
+ Change into the article directory. For example:
+ </div><pre class="screen"><code class="command">cd Home_Page</code></pre></li><li class="step" title="Step 3"><div class="para">
+ Edit the <code class="filename">Article_Info.xml</code> file to configure the product name and version number. As with other documents created with <span class="application"><strong>Publican</strong></span>, the product name and product version number appear in a banner at the top of the page when built as HTML. Unless the entire site documents only a single version of a product, you might want to suppress the version number. If so, make the <code class="sgmltag-element"><productnumber></code> tag empty, thus:
+ </div><pre class="programlisting"><productnumber></productnumber></pre><div class="para">
+ You might also want to remove or re-order some of the typical content of a DocBook article as rendered by <span class="application"><strong>Publican</strong></span>, such as the <code class="sgmltag-element"><abstract></code>, <code class="sgmltag-element"><corpauthor></code>, and the transcluded <code class="sgmltag-element"><authorgroup></code> and <code class="sgmltag-element"><legalnotice></code>.
+ </div><div class="para">
+ Alternatively, edit the root XML file of your home page to remove the <code class="sgmltag-element"><xi:include></code> that links to <code class="filename">Article_Info.xml</code>. <span class="application"><strong>Publican</strong></span> still uses the information in <code class="filename">Article_Info.xml</code> for packaging, but does not include it on the page itself.
+ </div></li><li class="step" title="Step 4"><div class="para">
+ Edit the <code class="filename">publican.cfg</code> file to add the <em class="parameter"><code>web_home</code></em> parameter and set it to <code class="literal">1</code> (enabled):
+ </div><pre class="programlisting">web_home: 1</pre><div class="para">
+ The <em class="parameter"><code>web_home</code></em> parameter instructs <span class="application"><strong>Publican</strong></span> to process this document differently from product documentation. This is the only mandatory change to the <code class="filename">publican.cfg</code> file. The rest of this step describes other parameters that might be useful but which are not required.
+ </div><div class="para">
+ To style your home page to match your documents, add:
+ </div><pre class="programlisting">brand: <em class="replaceable"><code>name_of_brand</code></em></pre><div class="para">
+ If you emptied the <code class="sgmltag-element"><productnumber></code> tag in the <code class="filename">Article_Info.xml</code> file, set:
+ </div><pre class="programlisting">version: 0.1</pre><div class="para">
+ If the <code class="sgmltag-element"><title></code> or the <code class="sgmltag-element"><product></code> that you set in the <code class="filename">Article_Info</code> file included anything other than basic, unaccented Latin characters, set the <em class="parameter"><code>docname</code></em> and <em class="parameter"><code>product</code></em> as necessary.
+ </div><div class="para">
+ <span class="application"><strong>Publican</strong></span> creates a separate, translatable navigation menu for each language in which you publish documentation. However, a document is not available in a particular language, <span class="application"><strong>Publican</strong></span> links visitors to the translated version of that document. To specify the default, untranslated language for the site, set <em class="parameter"><code>def_lang</code></em> with a language code. For example:
+ </div><pre class="programlisting">def_lang: fr-FR</pre><div class="para">
+ With <em class="parameter"><code>def_lang</code></em> set to <code class="literal">fr-FR</code>, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.
+ </div><div class="para">
+ The navigation menu also includes a search box that submits a query to Google. To constrain the results to only hits on your site, set the <em class="parameter"><code>web_host</code></em> parameter. For example, to limit the Google results to only pages on your website at <code class="literal">http://docs.example.com</code>, set:
+ </div><pre class="programlisting">web_host: http://docs.example.com</pre><div class="para">
+ <span class="application"><strong>Publican</strong></span> also uses the value set for <em class="parameter"><code>web_host</code></em> to construct the URLs in the XML <code class="filename">Sitemap</code> that it creates for search engine crawlers. Therefore, when you set this parameter, make sure you use the full URL, including the protocol (for example, <code class="literal">http://</code>).
+ </div><div class="para">
+ If you prefer to use a search engine other than Google, or want to customize the search, use the <em class="parameter"><code>web_search</code></em> parameter to specify the entire content of a HTML <code class="sgmltag-element"><form></code>. For example, to construct a Yahoo! search limited to <code class="literal">docs.example.com</code>, set:
+ </div><pre class="programlisting">web_search: '<span class="perl_Keyword"><form</span><span class="perl_Others"> target=</span><span class="perl_String">"_top"</span><span class="perl_Others"> method=</span><span class="perl_String">"get"</span><span class="perl_Others"> action=</span><span class="perl_String">"http://search.yahoo.com/search"</span><span class="perl_Keyword">></span> <span class="perl_Keyword"><div</span><span class="perl_Others"> class=</span><span class="perl_String">"search"</span><span class="perl_Keyword">></span> <span class="perl_Keyword"><input</span><span class="perl_Others"> type=</span><span class="perl_String">"text"</span><span class="perl_Others"> name=</span><span class="perl_String">"p"</span><span class="perl_Others"> value=</span><span class="perl_String">""</span> <span class="perl_Keyword">/></span> <span class="perl_Keyword"><input</span><span class="perl_Others"> type=</span><span class="perl_String">"hidden"</s
pan><span class="perl_Others"> name=</span><span class="perl_String">"vs"</span><span class="perl_Others"> value=</span><span class="perl_String">"docs.example.com"</span> <span class="perl_Keyword">/></span> <span class="perl_Keyword"><input</span><span class="perl_Others"> type=</span><span class="perl_String">"submit"</span><span class="perl_Others"> value=</span><span class="perl_String">"###Search###"</span> <span class="perl_Keyword">/></span> <span class="perl_Keyword"></div></span> <span class="perl_Keyword"></form></span>'</pre><div class="para">
+ Refer to the documentation of your chosen search engine for details of how to construct custom searches.
+ </div><div class="para">
+ If you set <code class="literal">value="###Search###"</code> on the code for a submit button, <span class="application"><strong>Publican</strong></span> uses the word <code class="literal">Search</code> on the button, localized into any language that <span class="application"><strong>Publican</strong></span> supports.
+ </div><div class="important"><h2>Important — Publican does not validate the web_search parameter</h2><div class="para">
+ <span class="application"><strong>Publican</strong></span> does not validate the <em class="parameter"><code>web_search</code></em> parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.
+ </div></div></li><li class="step" title="Step 5"><div class="para">
+ Edit the content of the <code class="filename"><em class="replaceable"><code>page_name</code></em>.xml</code> file (for example, <code class="filename">Home_Page.xml</code>) as you would any other DocBook document.
+ </div><div class="para">
+ If you remove the <code class="sgmltag-element"><xi:include></code> that links to <code class="filename">Article_Info.xml</code>, specify a title for your page in the following format:
+ </div><pre class="programlisting"><span class="perl_Keyword"><title</span><span class="perl_Others"> role=</span><span class="perl_String">"producttitle"</span><span class="perl_Keyword">></span>FooMaster Documentation<span class="perl_Keyword"></title></span></pre></li><li class="step" title="Step 6"><div class="para">
+ If you publish documentation in more than one language, create a set of POT files and a set of PO files for each language with the <code class="command">publican update_pot</code> and <code class="command">publican update_po</code> commands.
+ </div></li><li class="step" title="Step 7"><div class="para">
+ To customize the logo at the top of the navigation menu that provides a link back to the home page, create a PNG image 300 px × 100 px and name it <code class="filename">web_home.png</code>. Place this image in the <code class="filename">images/</code> directory in the document's XML directory, for example <code class="filename">en-US/images/</code>.
+ </div></li><li class="step" title="Step 8"><div class="para">
+ If you are building your website manually, build the home page in single-page HTML format with the <code class="option">--embedtoc</code> option and install it in your website structure. For example:
+ </div><pre class="screen"><code class="command">publican build --publish --formats html-single --embedtoc</code>
+<code class="command">publican install_book --site_config ~/docsite/foomaster.cfg</code></pre><div class="para">
+ Alternatively, to build RPM packages to install on your webserver, run the following command for each language in which you publish documentation:
+ </div><pre class="screen"><code class="command">publican package --binary --lang <em class="replaceable"><code>language_code</code></em></code></pre></li></ol></div></div><div class="section" title="6.3. Installing, updating and removing documents" id="sect-Users_Guide-Website-structure-documents"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-structure-documents">6.3. Installing, updating and removing documents</h2></div></div></div><div class="section" title="6.3.1. Installing, updating and removing documents manually" id="sect-Users_Guide-Website-structure-documents-manual"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Website-structure-documents-manual">6.3.1. Installing, updating and removing documents manually</h3></div></div></div><div class="para">
+ To install a document on a website that you are building manually, change into the directory that contains the source for the document and run:
+ </div><pre class="screen"><code class="command">publican build --embedtoc --formats=<em class="replaceable"><code>list_of_formats</code></em> --langs=<em class="replaceable"><code>language_codes</code></em> --publish</code>
+<code class="command">publican install_book --site_config <em class="replaceable"><code>path_to_site_configuration_file</code></em>.cfg --lang <em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
+ Note that you can run a single <code class="command">publican build</code> command for all languages that you want to publish, but must run a separate <code class="command">publican install_book</code> for each language. You must include <code class="literal">html</code> as one of the formats in the <code class="command">publican build</code>; optionally, include any or all of the following formats in a comma-separated list: <code class="literal">html-single</code>, <code class="literal">pdf</code>, and <code class="literal">epub</code>.
+ </div><div class="para">
+ To update a document, change into the directory that contains the updated source for the document and run the same commands as if you were installing the document for the first time. <span class="application"><strong>Publican</strong></span> replaces the old version with the new version.
+ </div><div class="para">
+ To remove a document, change into the directory that contains the source for the document and run:
+ </div><pre class="screen"><code class="command">publican remove_book --site_config <em class="replaceable"><code>path_to_site_configuration_file</code></em>.cfg --lang <em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
+ When you have installed the documents, the website is ready to upload to your webserver by whatever process you usually use, for example <span class="application"><strong>scp</strong></span>, <span class="application"><strong>rsync</strong></span>, or an FTP client.
+ </div></div><div class="section" title="6.3.2. Installing, updating and removing documents as RPM packages" id="sect-Users_Guide-Website-structure-documents-rpm"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Website-structure-documents-rpm">6.3.2. Installing, updating and removing documents as RPM packages</h3></div></div></div><div class="para">
+ To use an RPM package to install a document on a website, change into the directory that contains the source for the document and run:
+ </div><pre class="screen"><code class="command">publican package --binary --lang <em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
+ <span class="application"><strong>Publican</strong></span> builds an RPM package and places it in the <code class="filename">/tmp/rpms/noarch/</code> directory of the document. Note that by default, <span class="application"><strong>Publican</strong></span> generates an RPM package to install on a Red Hat Enterprise Linux 5 server. To build an RPM package to install on a server that runs a different operating system, set the <em class="parameter"><code>os_var</code></em> parameter in the <code class="filename">publican.cfg</code> file.
+ </div><div class="para">
+ Either upload the document packages to the webserver and install them with the <code class="command">rpm -i</code> or <code class="command">yum localinstall</code> command, or place the packages in a repository and configure the webserver to install from that repository when you run <code class="command">yum install</code>.
+ </div><div class="para">
+ To update a document, build a new package with a higher <code class="sgmltag-element"><edition></code> number or <code class="sgmltag-element"><pubsnumber></code> in the <code class="filename">Book_Info.xml</code> or <code class="filename">Article_Info.xml</code>. <span class="application"><strong>Publican</strong></span> uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, <span class="application"><strong>yum</strong></span> can replace the old version with the new when you run <code class="command">yum localinstall</code> for a local package, or <code class="command">yum update</code> for a package fetched from a repository.
+ </div><div class="para">
+ Remove a document from the webserver with the <code class="command">rpm -e</code> or <code class="command">yum erase</code> command.
+ </div></div></div><div class="section" title="6.4. Automating publishing" id="sect-Users_Guide-Website-automation"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-automation">6.4. Automating publishing</h2></div></div></div><div class="para">
+ Because <span class="application"><strong>Publican</strong></span> can generate RPM packages, you can use <span class="application"><strong>Publican</strong></span> together with an RPM build system like <span class="application"><strong>Koji</strong></span> to automate your publishing process. When a document is ready for publication, the writer or translator runs the following command:
+ </div><pre class="screen"><code class="command">publican package --cvs</code></pre><div class="para">
+ <span class="application"><strong>Publican</strong></span> then carries out the following actions:
+ </div><div class="orderedlist"><ol><li class="listitem"><div class="para">
+ generates an SRPM
+ </div></li><li class="listitem"><div class="para">
+ imports the SRPM into the CVS root for the <span class="application"><strong>Koji</strong></span> instance specified in the document's <code class="filename">publican.cfg</code> file
+ </div></li><li class="listitem"><div class="para">
+ runs <code class="command">cvs up</code>
+ </div></li><li class="listitem"><div class="para">
+ runs <code class="command">make build</code>
+ </div></li></ol></div><div class="para">
+ If your webserver periodically checks for updated packages in the repository in which <span class="application"><strong>Koji</strong></span> places built packages, the webserver can automatically install updated versions of your documents.
+ </div><div class="para">
+ You might also implement a system of tags where a writer or translator could run <code class="command">koji tag-pkg</code> to apply a tag that tells the webserver to publish the document only on a staging site for proofreading and review; or a different tag that tells the webserver to publish the document publicly.
+ </div><div class="para">
+ To prepare a document for building in a <span class="application"><strong>Koji</strong></span> instance, edit the <code class="filename">publican.cfg</code> file to specify:
+ </div><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>cvs_branch</code></em></span></dt><dd><div class="para">
+ the name of the <em class="firstterm">branch</em> for the package; typically, a particular software version.
+ </div></dd><dt><span class="term"><em class="parameter"><code>cvs_pkg</code></em></span></dt><dd><div class="para">
+ the name of the package in CVS. <span class="application"><strong>Publican</strong></span> defaults to: <code class="literal"><em class="replaceable"><code>product</code></em>-<em class="replaceable"><code>title</code></em>-<em class="replaceable"><code>product_version</code></em>-web-<em class="replaceable"><code>language</code></em>-<em class="replaceable"><code>edition</code></em>-<em class="replaceable"><code>pubsnumber</code></em></code>
+ </div></dd><dt><span class="term"><em class="parameter"><code>cvs_root</code></em></span></dt><dd><div class="para">
+ the CVS root into which to import the SRPM. For example, the CVS root for the Fedora Project's <span class="application"><strong>Koji</strong></span> instance is <code class="literal">:ext:USERNAME at cvs.fedoraproject.org:/cvs/pkgs</code>
+ </div></dd></dl></div><div class="para">
+ For more information about <span class="application"><strong>Koji</strong></span>, visit <a href="https://fedorahosted.org/koji/wiki">https://fedorahosted.org/koji/wiki</a>.
+ </div></div></div><div xml:lang="en-US" class="chapter" title="Chapter 7. Frequently Asked Questions" id="chap-Users_Guide-Frequently_Asked_Questions" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 7. Frequently Asked Questions</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><dl><dt>Q: <a href="#id547478">
How do I add a language to my book?
- </a></dt><dt>Q: <a href="#id595686">
+ </a></dt><dt>Q: <a href="#id487213">
What if I do not want to use the country code? For example, can I run publican update_po --langs=es,de,fr?
- </a></dt><dt>Q: <a href="#id628015">
+ </a></dt><dt>Q: <a href="#id582996">
How do I update all po files?
- </a></dt><dt>Q: <a href="#id727152">
+ </a></dt><dt>Q: <a href="#id627932">
Where can I get a complete list of Publican's build options?
- </a></dt><dt>Q: <a href="#id715481">
+ </a></dt><dt>Q: <a href="#id494894">
Where can I get a complete list of parameters that can be set in the publican.cfg?
- </a></dt><dt>Q: <a href="#id599753">
+ </a></dt><dt>Q: <a href="#id472821">
Where are the Publican common files located?
- </a></dt><dt>Q: <a href="#id599788">
+ </a></dt><dt>Q: <a href="#id572285">
I have extensive code samples for my book, how can I include them without having to XML escape everything?
- </a></dt><dt>Q: <a href="#id623294">
+ </a></dt><dt>Q: <a href="#id463915">
Is it possible to include arbitrary files in tarballs and RPM packages?
- </a></dt><dt>Q: <a href="#id623341">
+ </a></dt><dt>Q: <a href="#id578380">
Why does Publican give me warnings about unknown tags?
- </a></dt><dt>Q: <a href="#id619780">
- Which brands enable strict mode? Strict mode is no longer enforced.
- </a></dt><dt>Q: <a href="#id619811">
+ </a></dt><dt>Q: <a href="#id578406">
+ Which brands enable strict mode? Strict mode is not currently enforced.
+ </a></dt><dt>Q: <a href="#id578436">
I get an error saying Batik is not in the classpath but Batik is installed! What is wrong?
- </a></dt><dt>Q: <a href="#id689828">
+ </a></dt><dt>Q: <a href="#id575562">
I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?
- </a></dt><dt>Q: <a href="#id689865">
+ </a></dt><dt>Q: <a href="#id575598">
Previous versions of Publican removed empty <para> tags. Does Publican still do this?
- </a></dt><dt>Q: <a href="#id630454">
+ </a></dt><dt>Q: <a href="#id578678">
What happened to the spell check?
- </a></dt><dt>Q: <a href="#id630479">
+ </a></dt><dt>Q: <a href="#id578702">
Why don't <segmentedlist>s work when I build PDFs?
- </a></dt><dt>Q: <a href="#id732415">
+ </a></dt><dt>Q: <a href="#id578742">
What happened to the colors in my images in this PDF?
- </a></dt><dt>Q: <a href="#id732440">
+ </a></dt><dt>Q: <a href="#id552475">
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
- </a></dt><dt>Q: <a href="#id741102">
+ </a></dt><dt>Q: <a href="#id552550">
Why does Jeff call Isaac ‘Ivan’?
- </a></dt></dl><div class="qandaset"><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </a></dt></dl><div class="qandaset"><div id="id547478" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
How do I add a language to my book?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run <code class="command">publican update_po --langs=<em class="replaceable"><code>language</code></em></code>, where <em class="replaceable"><code>language</code></em> is the code for the new language that you want to add. You can add more than one language at a time, with the language codes separated by commas. For example, <code class="command">publican update_po --langs=ja-JP</code> creates the Japanese language directory and Japanese PO files, and <code class="command">publican update_po --langs=ja-JP,ko-KR</code> creates directories and PO files for both Japanese and Korean.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id487213" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
What if I do not want to use the country code? For example, can I run <code class="command">publican update_po --langs=es,de,fr</code>?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Yes — this command works. However, if you omit the country code, the output might be unpredictable when <span class="application"><strong>Publican</strong></span> or a brand has definitions for more than one regional variety of a language — for example, <code class="literal">zh-CN</code> (Simplified Chinese as used in the People's Republic of China) and <code class="literal">zh-TW</code> (Traditional Chinese as used in the Republic of China, on Taiwan). Even when only one variety is currently defined, it is always safest to include the country code so that, for example, a future update of <span class="application"><strong>Publican</strong></span> does not suddenly cause your German (<code class="literal">de-DE</code>) documents to switch to Schweizerdeutsch (Swiss German, <code class="literal">de-CH</code>) Common Content and headings.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id582996" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
How do I update all po files?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run the <code class="command">publican update_po --langs=all</code> command.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id627932" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Where can I get a complete list of <span class="application"><strong>Publican</strong></span>'s build options?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run the <code class="command">publican build --help</code> command.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id494894" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Where can I get a complete list of parameters that can be set in the <code class="filename">publican.cfg</code>?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run the <code class="command">publican help_config</code> command in a directory that holds any <span class="application"><strong>Publican</strong></span> document.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id472821" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Where are the <span class="application"><strong>Publican</strong></span> common files located?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
By default, they are in <code class="filename">/usr/share/publican/</code> on Linux operating systems and in <code class="filename">%SystemDrive%/%ProgramFiles%/publican/Common_Content</code> on Windows operating systems — typically, <code class="filename">C:/Program Files/publican/Common_Content</code>.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id572285" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
I have extensive code samples for my book, how can I include them without having to XML escape everything?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
The best way to do this is to create a directory named <code class="filename">extras</code> in your source language directory and use an <code class="sgmltag-element">xi:include</code> to pull in the code file.
- </div><div class="procedure"><h6>Procedure 6.1. Including code samples</h6><ol class="1"><li class="step" title="Step 1"><div class="para">
+ </div><div class="procedure"><h6>Procedure 7.1. Including code samples</h6><ol class="1"><li class="step" title="Step 1"><div class="para">
Create the extras directory
- </div><pre class="screen"><code class="command">mkdir <code class="filename">en-US/extras</code></code>
-</pre></li><li class="step" title="Step 2"><div class="para">
+ </div><pre class="screen"><code class="command">mkdir <code class="filename">en-US/extras</code></code></pre></li><li class="step" title="Step 2"><div class="para">
Copy the code file to the extras directory
- </div><pre class="screen"><code class="command">cp <code class="filename">~/samples/foo.c en-US/extras/.</code></code>
-</pre></li><li class="step" title="Step 3"><div class="para">
+ </div><pre class="screen"><code class="command">cp <code class="filename">~/samples/foo.c en-US/extras/.</code></code></pre></li><li class="step" title="Step 3"><div class="para">
<code class="sgmltag-element">xi:include</code> the sample file in your xml file
</div><pre class="programlisting"><span class="perl_Keyword"><programlisting></span>
<span class="perl_Keyword"><xi:include</span><span class="perl_Others"> parse=</span><span class="perl_String">"text"</span><span class="perl_Others"> href=</span><span class="perl_String">"extras/foo.c"</span><span class="perl_Others"> xmlns:xi=</span><span class="perl_String">"http://www.w3.org/2001/XInclude"</span> <span class="perl_Keyword">/></span>
@@ -1634,21 +1805,21 @@ scm = SVN
</pre></li><li class="step" title="Step 4"><div class="para">
You can now edit <code class="filename">en-US/extras/foo.c</code> in your favorite editor without having to be concerned about how it will affect the XML.
- </div></li></ol></div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></li></ol></div></div></div></div><div id="id463915" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Is it possible to include arbitrary files in tarballs and RPM packages?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Yes. If you make a directory named <code class="filename">files</code> in your source language directory it will be included in any tarballs or SRPM packages that <span class="application"><strong>Publican</strong></span> creates.
</div><div class="important"><h2>Important</h2><div class="para">
The <code class="filename">files</code> directory will not be available during the validation process so you can not <code class="sgmltag-element">xi:include</code> or otherwise embed any files in this directory in your XML.
- </div></div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div></div><div id="id578380" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Why does <span class="application"><strong>Publican</strong></span> give me warnings about unknown tags?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
This warning informs you that you are using a tag whose output has not been tested for attractiveness, XHTML 1.0 Strict compliance, or Section 508 (Accessibility) compliance.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
- <span class="strikethrough strikethrough">Which brands enable strict mode?</span> Strict mode is no longer enforced.
+ </div></div></div></div><div id="id578406" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ <span class="strikethrough strikethrough">Which brands enable strict mode?</span> Strict mode is not currently enforced.
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
<span class="strikethrough strikethrough">Currently the Red Hat and JBoss brands enable strict mode.</span>
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id578436" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
I get an error saying <span class="application"><strong>Batik</strong></span> is not in the classpath but <span class="application"><strong>Batik</strong></span> is installed! What is wrong?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
We believe this is due to classpath issues caused by having different JRE and JDK versions installed. Sometimes this can be fixed by upgrading your JDK to the same version of your JRE.
@@ -1656,37 +1827,36 @@ scm = SVN
Sometimes this issue can be revealed by running <code class="command">alternatives --config java</code> and <code class="command">alternatives --config javac</code>, if the versions are different then selecting the same version in both can fix this problem.
</div><div class="para">
Some Java installs do not set-up the <code class="command">alternatives</code> environment correctly, no fix has been determined for this situation.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id575562" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
I get an error <code class="computeroutput">Exception in thread "main" java.lang.OutOfMemoryError: Java heap space</code> when trying to build PDF. What is wrong?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to <span class="application"><strong>FOP</strong></span>. Before running <code class="command">make </code> run <code class="command">echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc</code>. This sets the initial heap space to 50 MB and allows it to grow to a maximum of 700 MB.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id575598" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Previous versions of <span class="application"><strong>Publican</strong></span> removed empty <code class="sgmltag-element"><para></code> tags. Does <span class="application"><strong>Publican</strong></span> still do this?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
No. <span class="application"><strong>Publican</strong></span> previously removed empty <code class="sgmltag-element"><para></code> tags while it transformed XML because empty <code class="sgmltag-element"><para></code> tags broke earlier translation toolchains used within Red Hat and the Fedora Project. Empty <code class="sgmltag-element"><para></code> tags are valid DocBook XML, and <span class="application"><strong>Publican</strong></span> no longer removes them.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id578678" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
What happened to the spell check?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Early versions of <span class="application"><strong>Publican</strong></span> (up to and including 0.45) ran a spell check while transforming a document's XML. Due to negative feedback from users, this feature was dropped.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id578702" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Why don't <code class="sgmltag-element"><segmentedlist></code>s work when I build PDFs?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Check the number of columns in your <code class="sgmltag-element"><segmentedlist></code>s. When <code class="sgmltag-element"><segmentedlist></code>s are formatted as tables, the DocBook XSL limits the number of columns to two, and <span class="application"><strong>Publican</strong></span> formats <code class="sgmltag-element"><segmentedlist></code>s as tables.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id578742" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
What happened to the colors in my images in this PDF?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
This is the result of a bug in <span class="application"><strong>FOP</strong></span> that distorts colors in 24-bit PNG images. Convert your images to 32-bit PNG images to work around the problem.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id552475" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Code highlighting in <span class="application"><strong>Publican</strong></span> is generated with the <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> Perl module. If you specify a language in a <code class="sgmltag-element"><programlisting></code> tag that <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> does not recognize, you receive an error when you build your book. The first lines of the error message are similar to:
</div><pre class="screen"><code class="computeroutput">undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pm line 615.</code>
-<code class="computeroutput">cannot create plugin for language 'JAVA'</code>
-</pre><div class="para">
+<code class="computeroutput">cannot create plugin for language 'JAVA'</code></pre><div class="para">
Note that <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> is very strict about names of languages and is case sensitive. Therefore, <code class="sgmltag-element"><programlisting language="Java"></code> works, but <code class="sgmltag-element"><programlisting language="java"></code> and <code class="sgmltag-element"><programlisting language="JAVA"></code> do not. The error message that you receive identifies the problematic language attribute.
</div><div class="para">
Refer to <a href="http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS">http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS</a> for the full list of languages that <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> supports, including their expected capitalization and punctuation.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id552550" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Why does Jeff call Isaac ‘Ivan’?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Because Jeff's memory is pants!
@@ -1700,7 +1870,7 @@ scm = SVN
Finally, a small group of elements and attributes are <em class="firstterm">disallowed</em>. These elements and attributes are set out below, each accompanied by rationale explaining why it is disallowed.
</div><div class="para">
Use the command <code class="command">publican print_known</code> to print a list of tags that <span class="application"><strong>Publican</strong></span> supports, and the command <code class="command">publican print_banned</code> to print a list of tags that are banned in <span class="application"><strong>Publican</strong></span>.
- </div><div class="section" title="A.1. Disallowed elements" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements"><div class="titlepage"><div><div><h2 class="title">A.1. Disallowed elements</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><caution></code>, </span><span class="term"><code class="sgmltag-element"><tip></code></span></dt><dd><div class="para">
+ </div><div class="section" title="A.1. Disallowed elements" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements">A.1. Disallowed elements</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><caution></code>, </span><span class="term"><code class="sgmltag-element"><tip></code></span></dt><dd><div class="para">
DocBook XML supports five <em class="firstterm">admonitions</em> of varying severity: <code class="sgmltag-element"><tip></code>, <code class="sgmltag-element"><note></code>, <code class="sgmltag-element"><important></code>, <code class="sgmltag-element"><caution></code>, and <code class="sgmltag-element"><warning></code>. Taken together, these represent a very fine-grained set of distinctions. It is unlikely that these fine distinctions can be applied consistently within a document, especially when more than one person writes or maintains the document. Moreover, this level of granularity is meaningless to readers. By design, <span class="application"><strong>Publican</strong></span> disallows the <code class="sgmltag-element"><tip></code> and <code class="sgmltag-element"><caution></code> elements, these elements being the two most redundant in the set.
</div><div class="para">
Use <code class="sgmltag-element"><note></code> instead of <code class="sgmltag-element"><tip></code>, and use either <code class="sgmltag-element"><important></code> or <code class="sgmltag-element"><warning></code> instead of <code class="sgmltag-element"><caution></code>. Some criteria by which you might select a suitable level of severity are presented in the ‘Document Conventions’ section of the preface of books produced with <span class="application"><strong>Publican</strong></span>'s default brand.
@@ -1731,14 +1901,14 @@ scm = SVN
</div></dd></dl></div><div class="para">
In a translated language that does not share the same writing system with the original language in which the XML was written, the result is even more nonsensical.
</div></dd><dt><span class="term"><code class="sgmltag-element"><inlinegraphic></code></span></dt><dd><div class="para">
- This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This tag therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this tag will not satisfy those requirements. Section 508 of the <em class="citetitle">Rehabilitation Act of 1973</em><sup>[<a id="id617107" href="#ftn.id617107" class="footnote">3</a>]</sup> is an example of such a requirement for federal agencies in the United States.
+ This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This tag therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this tag will not satisfy those requirements. Section 508 of the <em class="citetitle">Rehabilitation Act of 1973</em><sup>[<a id="id469437" href="#ftn.id469437" class="footnote">3</a>]</sup> is an example of such a requirement for federal agencies in the United States.
</div><div class="para">
Note that <code class="sgmltag-element"><inlinegraphic></code> is not valid in DocBook version 5.
</div></dd><dt><span class="term"><code class="sgmltag-element"><link></code></span></dt><dd><div class="para">
The <code class="sgmltag-element"><link></code> tag provides a general-purpose hyperlink and therefore offers nothing that the <code class="sgmltag-element"><xref></code> and <code class="sgmltag-element"><ulink></code> tags do not, for internal and external hyperlinks respectively. The <code class="sgmltag-element"><link></code> tag is disallowed due to its redundancy.
</div></dd><dt><span class="term"><code class="sgmltag-element"><olink></code></span></dt><dd><div class="para">
The <code class="sgmltag-element"><olink></code> tag provides cross-references between XML documents. For <code class="sgmltag-element"><olink></code>s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <code class="sgmltag-element"><olink></code>s, these URLs can be supplied either as an XML entity or with a server-side script. <span class="application"><strong>Publican</strong></span> produces documents intended for wide dissemination in which URLs are always necessary for cross-references. Therefore, the <code class="sgmltag-element"><olink></code> tag offers no advantage over the <code class="sgmltag-element"><ulink></code> tag, and is disallowed due to its redundancy.
- </div></dd></dl></div></div><div class="section" title="A.2. Disallowed attributes" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes"><div class="titlepage"><div><div><h2 class="title">A.2. Disallowed attributes</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><[element] xreflabel="[any_string_here]"></code></span></dt><dd><div class="para">
+ </div></dd></dl></div></div><div class="section" title="A.2. Disallowed attributes" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes">A.2. Disallowed attributes</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><[element] xreflabel="[any_string_here]"></code></span></dt><dd><div class="para">
The presence of an <code class="sgmltag-element"><xreflabel></code> attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.
</div><div class="para">
For example, if you have the following:
@@ -1900,7 +2070,7 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
Furthermore, note that the combined preposition and article also poses a problem with regard to whether this word should be placed in the text surrounding the <code class="sgmltag-element"><xref></code>, or in the <code class="sgmltag-element"><titleabbrev></code>. Whichever of these two solutions the translator selects will cause problems when the <em class="parameter"><code>endterm</code></em> appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.
</div><div class="para">
Due to the problems that <em class="parameter"><code>endterm</code></em> presents for translation, <span class="application"><strong>Publican</strong></span> disallows this attribute.
- </div></dd></dl></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id617107" href="#id617107" class="para">3</a>] </sup>
+ </div></dd></dl></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id469437" href="#id469437" class="para">3</a>] </sup>
Refer to <a href="http://www.section508.gov/">http://www.section508.gov/</a>
</p></div></div></div><div xml:lang="en-US" class="appendix" title="Appendix B. Command summary" id="appe-Users_Guide-Command_summary" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Command summary</h1></div></div></div><div class="variablelist" title="Command options" id="vari-Users_Guide-Command_summary-Command_options"><h6>Command options</h6><dl><dt><span class="term"><code class="command">publican --help</code></span></dt><dd><div class="para">
displays help
@@ -1930,7 +2100,7 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
removes the temporary directories from a document directory.
</div></dd><dt><span class="term"><code class="command">publican clean_ids</code></span></dt><dd><div class="para">
indents XML files neatly, and rebuilds element IDs.
- </div></dd><dt><span class="term"><code class="command">publican cleanset</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term"><code class="command">publican clean_set</code></span></dt><dd><div class="para">
removes local copies of remote books that are part of a set.
</div></dd><dt><span class="term"><code class="command">publican create</code></span></dt><dd><div class="para">
creates a new book, article, or set. Options:
@@ -1954,9 +2124,25 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
the name of the document (mandatory).
</div></dd><dt><span class="term">--lang</span></dt><dd><div class="para">
the language in which the XML will be authored.
+ </div></dd></dl></div></dd><dt><span class="term">publican create_site</span></dt><dd><div class="para">
+ creates a documentation website. Options:
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file to create (mandatory).
+ </div></dd><dt><span class="term">--db_file</span></dt><dd><div class="para">
+ name of the site database file to create (mandatory).
+ </div></dd><dt><span class="term">--toc_path</span></dt><dd><div class="para">
+ path to the directory in which to create the top-level <code class="filename">toc.html</code> file (mandatory).
+ </div></dd><dt><span class="term">--tmpl_path</span></dt><dd><div class="para">
+ path to the template directory (by default, <code class="filename">/usr/share/publican/templates</code>).
</div></dd></dl></div></dd><dt><span class="term"><code class="command">publican help_config</code></span></dt><dd><div class="para">
displays a list of parameters for the <code class="filename">publican.cfg</code> file.
- </div></dd><dt><span class="term"><code class="command">publican installbrand</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">publican install_book</span></dt><dd><div class="para">
+ installs a document on a documentation website.
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
+ </div></dd><dt><span class="term">--lang</span></dt><dd><div class="para">
+ the language of the document to install (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term"><code class="command">publican install_brand</code></span></dt><dd><div class="para">
configures a brand for installation. Option:
</div><div class="variablelist"><dl><dt><span class="term">--path</span></dt><dd><div class="para">
path to the <span class="application"><strong>Publican</strong></span> Common Content files. By default, <code class="filename">/usr/share/publican/Common_Content</code> on Linux operating systems and at <code class="filename">%SystemDrive%/%ProgramFiles%/Publican/Common_Content</code> on Windows operating systems — typically, <code class="filename">C:/Program Files/Publican/Common_Content</code>
@@ -1986,16 +2172,30 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
prints a list of DocBook tags banned by <span class="application"><strong>Publican</strong></span>.
</div></dd><dt><span class="term">publican print_known</span></dt><dd><div class="para">
prints a list of DocBook tags supported by <span class="application"><strong>Publican</strong></span>.
- </div></dd><dt><span class="term"><code class="command">publican printtree</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term"><code class="command">publican print_tree</code></span></dt><dd><div class="para">
displays a tree of the XML files included in a document.
</div></dd><dt><span class="term">publican print_unused</span></dt><dd><div class="para">
prints a list of the XML files <span class="emphasis"><em>not</em></span> included with the <code class="sgmltag-element"><xi:include></code> tag in a book, article, or set.
- </div></dd><dt><span class="term"><code class="command">publican update_pot</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">publican remove_book</span></dt><dd><div class="para">
+ removes a document from a documentation website.
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
+ </div></dd><dt><span class="term">--lang</span></dt><dd><div class="para">
+ the language of the document to remove (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term">publican site_stats --site_config=<em class="replaceable"><code>name_of_site_config_file</code></em></span></dt><dd><div class="para">
+ generates a site report for a documentation website. Option:
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term"><code class="command">publican update_pot</code></span></dt><dd><div class="para">
updates the POT files in a document.
</div></dd><dt><span class="term"><code class="command">publican update_po</code></span></dt><dd><div class="para">
updates the PO files in a document.
</div><div class="variablelist"><dl><dt><span class="term">--langs</span></dt><dd><div class="para">
comma-separated list of languages to update, or ‘all’ to update all (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term">publican update_site --site_config=<em class="replaceable"><code>name_of_site_config_file</code></em>.cfg</span></dt><dd><div class="para">
+ regenerates the templated content of a documentation website. Option:
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
</div></dd></dl></div></dd></dl></div></div><div xml:lang="en-US" class="appendix" title="Appendix C. publican.cfg parameters" id="appe-Users_Guide-publican.cfg_parameters" lang="en-US"><div class="titlepage"><div><div><h1 class="title">publican.cfg parameters</h1></div></div></div><div class="para">
Every book, article, document set, or brand has a <code class="filename">publican.cfg</code> file in its root directory. Parameters that can be set in the <code class="filename">publican.cfg</code> file are:
</div><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>docname</code></em></span></dt><dd><div class="para">
@@ -2042,6 +2242,8 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
the CVS root into which to import the SRPM.
</div></dd><dt><span class="term"><em class="parameter"><code>debug</code></em></span></dt><dd><div class="para">
whether <span class="application"><strong>Publican</strong></span> should display debugging messages as it works. (Default: <code class="literal">0</code> — suppress messages)
+ </div></dd><dt><span class="term"><em class="parameter"><code>def_lang</code></em></span></dt><dd><div class="para">
+ the default language for a <span class="application"><strong>Publican</strong></span>-managed website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available. (Default: <code class="literal">en-US</code> — American English)
</div></dd><dt><span class="term"><em class="parameter"><code>doc_url</code></em></span></dt><dd><div class="para">
URL for the documentation team for this package. (Default: <code class="literal">https://fedorahosted.org/publican</code>)
</div></dd><dt><span class="term"><em class="parameter"><code>dt_obsoletes</code></em></span></dt><dd><div class="para">
@@ -2085,39 +2287,51 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
</div></dd><dt><span class="term"><em class="parameter"><code>src_url</code></em></span></dt><dd><div class="para">
URL at which to find to find tarballs of source files.
</div></dd><dt><span class="term"><em class="parameter"><code>strict</code></em></span></dt><dd><div class="para">
- <span class="strikethrough strikethrough">use <em class="firstterm">strict mode</em> (Default: <code class="literal">0</code> — not strict)</span> Strict mode is no longer enforced.
+ <span class="strikethrough strikethrough">use <em class="firstterm">strict mode</em> (Default: <code class="literal">0</code> — not strict)</span> Strict mode is not currently enforced.
</div></dd><dt><span class="term"><em class="parameter"><code>tmp_dir</code></em></span></dt><dd><div class="para">
the directory for <span class="application"><strong>Publican</strong></span> output. (Default: <code class="literal">tmp</code>)
</div></dd><dt><span class="term"><em class="parameter"><code>toc_section_depth</code></em></span></dt><dd><div class="para">
the depth of sections that <span class="application"><strong>Publican</strong></span> includes in the main table of contents. (Default: <code class="literal">2</code>)
</div></dd><dt><span class="term"><em class="parameter"><code>web_brew_dist</code></em></span></dt><dd><div class="para">
the <span class="application"><strong>brew</strong></span> build target to use for the web RPM package. (Defaults to <code class="literal">docs-5E</code>)
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_home</code></em></span></dt><dd><div class="para">
+ specifies that the document is the home page of a documentation website, not a standard document.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_host</code></em></span></dt><dd><div class="para">
+ specifies the host name of a documentation website.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_name_label</code></em></span></dt><dd><div class="para">
+ overrides the book name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website.
</div></dd><dt><span class="term"><em class="parameter"><code>web_obsoletes</code></em></span></dt><dd><div class="para">
packages that the web RPM package obsoletes.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_product_label</code></em></span></dt><dd><div class="para">
+ overrides the product name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_search</code></em></span></dt><dd><div class="para">
+ overrides the default search form for a <span class="application"><strong>Publican</strong></span>-managed website. (Defaults: Google search; limited to a site search if <em class="parameter"><code>web_host</code></em> is set.)
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_version_label</code></em></span></dt><dd><div class="para">
+ overrides the version number as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website.
</div></dd></dl></div></div><div xml:lang="en-US" class="appendix" title="Appendix D. Language codes" id="appe-Users_Guide-Language_codes" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Language codes</h1></div></div></div><div class="important"><h2>Region subtags</h2><div class="para">
The only part of the XML language tag that is mandatory in <span class="application"><strong>Publican</strong></span> is the <em class="firstterm">language subtag</em>. However, <span class="application"><strong>Publican</strong></span> is designed with the assumption that you will routinely include the <em class="firstterm">region subtag</em> when you identify languages. In many languages, spelling and vocabulary vary significantly from region to region. If you do not specify the regional variety of a language in which your document is authored or into which it is translated, you might obtain unexpected results when you build the document in <span class="application"><strong>Publican</strong></span>.
</div></div><div class="important"><h2>Other language codes</h2><div class="para">
The system of codes used to identify languages in the XML standard is not the only system of languages codes in use in the world today. However, because <span class="application"><strong>Publican</strong></span> strives to comply with the XML standard, these are the only codes that <span class="application"><strong>Publican</strong></span> supports. In particular, note that the codes used in the GNU tools (identified by their use of underscores and the <code class="literal">@</code> symbol to separate elements — for example, <code class="literal">en_GB</code> or <code class="literal">sr_RS at latin</code>) do not comply with the XML standard and therefore do not work with <span class="application"><strong>Publican</strong></span>.
</div></div><div class="para">
- <span class="application"><strong>Publican</strong></span> is an XML publication tool and therefore is designed to use the language codes — or <em class="firstterm">tags</em> — that the World Wide Web Consortium (W3C) designated in the XML specification.<sup>[<a id="id729198" href="#ftn.id729198" class="footnote">4</a>]</sup> These codes are defined in the Internet Engineering Task Force (IETF) document <em class="citetitle">BCP 47: Tags for Identifying Languages</em>.<sup>[<a id="id707920" href="#ftn.id707920" class="footnote">5</a>]</sup>
+ <span class="application"><strong>Publican</strong></span> is an XML publication tool and therefore is designed to use the language codes — or <em class="firstterm">tags</em> — that the World Wide Web Consortium (W3C) designated in the XML specification.<sup>[<a id="id615853" href="#ftn.id615853" class="footnote">4</a>]</sup> These codes are defined in the Internet Engineering Task Force (IETF) document <em class="citetitle">BCP 47: Tags for Identifying Languages</em>.<sup>[<a id="id451457" href="#ftn.id451457" class="footnote">5</a>]</sup>
</div><div class="para">
Language tags are built from one of more <em class="firstterm">subtags</em>, separated from one another by hyphens. In order of appearance within a language tag, these subtags are:
</div><div class="para">
<code class="literal"><em class="replaceable"><code>language</code></em>-<em class="replaceable"><code>script</code></em>-<em class="replaceable"><code>region</code></em>-<em class="replaceable"><code>variant</code></em></code>
</div><div class="para">
- BCP 47 also allows for considerable customization of language tags for special purposes through the use of <em class="firstterm">extension subtags</em> and <em class="firstterm">private-use subtags</em>. Extension subtags allow for finer-tuning of existing subtags, but must be registered with the IETF (none are currently registered). Private-use subtags are introduced by <code class="literal">x-</code> and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).<sup>[<a id="id701312" href="#ftn.id701312" class="footnote">6</a>]</sup> Although <span class="application"><strong>Publican</strong></span> will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form <code class="literal"><em class="replaceable"><code>langu
age</code></em>-<em class="replaceable"><code>region</code></em></code>. A brief description of subtags follows:
+ BCP 47 also allows for considerable customization of language tags for special purposes through the use of <em class="firstterm">extension subtags</em> and <em class="firstterm">private-use subtags</em>. Extension subtags allow for finer-tuning of existing subtags, but must be registered with the IETF (none are currently registered). Private-use subtags are introduced by <code class="literal">x-</code> and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).<sup>[<a id="id560010" href="#ftn.id560010" class="footnote">6</a>]</sup> Although <span class="application"><strong>Publican</strong></span> will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form <code class="literal"><em class="replaceable"><code>langu
age</code></em>-<em class="replaceable"><code>region</code></em></code>. A brief description of subtags follows:
</div><div class="variablelist"><dl><dt><span class="term">language subtag</span></dt><dd><div class="para">
- The language subtag comprises two or more lower-case letters and is the only mandatory part of the language tag. For most widely spoken languages, the language subtag is a two-letter code identical with the language codes specified in ISO 639-1, <sup>[<a id="id663976" href="#ftn.id663976" class="footnote">7</a>]</sup> for example, <code class="literal">zh</code> (Chinese), <code class="literal">hi</code> (Hindi), <code class="literal">es</code> (Spanish), and <code class="literal">en</code> (English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,<sup>[<a id="id600368" href="#ftn.id600368" class="footnote">8</a>]</sup> for example, <code class="literal">bal</code> (Balochi), <code class="literal">apk</code> (Kiowa Apache), and <code class="literal">tpi</code> (Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or
ISO 639-2 equivalent, such as subtags for the constructed languages <code class="literal">qya</code> (Quenya) and <code class="literal">tlh</code> (Klingon), and for the occult language <code class="literal">i-enochian</code> (Enochian). This last example also illustrates a small number of language subtags <em class="firstterm">grandfathered</em> into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.
+ The language subtag comprises two or more lower-case letters and is the only mandatory part of the language tag. For most widely spoken languages, the language subtag is a two-letter code identical with the language codes specified in ISO 639-1, <sup>[<a id="id536974" href="#ftn.id536974" class="footnote">7</a>]</sup> for example, <code class="literal">zh</code> (Chinese), <code class="literal">hi</code> (Hindi), <code class="literal">es</code> (Spanish), and <code class="literal">en</code> (English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,<sup>[<a id="id537004" href="#ftn.id537004" class="footnote">8</a>]</sup> for example, <code class="literal">bal</code> (Balochi), <code class="literal">apk</code> (Kiowa Apache), and <code class="literal">tpi</code> (Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or
ISO 639-2 equivalent, such as subtags for the constructed languages <code class="literal">qya</code> (Quenya) and <code class="literal">tlh</code> (Klingon), and for the occult language <code class="literal">i-enochian</code> (Enochian). This last example also illustrates a small number of language subtags <em class="firstterm">grandfathered</em> into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.
</div><div class="note"><h2>Extended language subtags</h2><div class="para">
- <em class="citetitle">RFC 5646: Tags for Identifying Languages</em><sup>[<a id="id600424" href="#ftn.id600424" class="footnote">9</a>]</sup> issued in September 2009 allows for <em class="firstterm">extended language subtags</em> to follow the language subtag. Extended language subtags are three-letter codes that represent languages that share a close relationship with a language already represented by a language subtag. For example, <code class="literal">yue</code> represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: <code class="literal">zh-yue</code>. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.
+ <em class="citetitle">RFC 5646: Tags for Identifying Languages</em><sup>[<a id="id551395" href="#ftn.id551395" class="footnote">9</a>]</sup> issued in September 2009 allows for <em class="firstterm">extended language subtags</em> to follow the language subtag. Extended language subtags are three-letter codes that represent languages that share a close relationship with a language already represented by a language subtag. For example, <code class="literal">yue</code> represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: <code class="literal">zh-yue</code>. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.
</div></div></dd><dt><span class="term">script subtag</span></dt><dd><div class="para">
- The script subtag comprises four letters — the first one in upper case, the other three in lower case — and defines a writing system. These codes are identical with the four-letter codes specified in ISO 15924.<sup>[<a id="id661848" href="#ftn.id661848" class="footnote">10</a>]</sup> The script subtag is used to identify languages that are commonly written with more than one writing system; the subtag is omitted when it adds no distinguishing value to the language tag overall. For example, <code class="literal">sr-Latn</code> represents Serbian written with the Latin alphabet and <code class="literal">sr-Cyrl</code> represents Serbian written with the Cyrillic alphabet; <code class="literal">az-Arab</code> represents Azerbaijani written in Arabic script and <code class="literal">az-Cyrl</code> represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as <code class="literal">fr-Latn</code>, because French is not commonl
y written in any script other than the Latin alphabet anywhere in the world.
+ The script subtag comprises four letters — the first one in upper case, the other three in lower case — and defines a writing system. These codes are identical with the four-letter codes specified in ISO 15924.<sup>[<a id="id568455" href="#ftn.id568455" class="footnote">10</a>]</sup> The script subtag is used to identify languages that are commonly written with more than one writing system; the subtag is omitted when it adds no distinguishing value to the language tag overall. For example, <code class="literal">sr-Latn</code> represents Serbian written with the Latin alphabet and <code class="literal">sr-Cyrl</code> represents Serbian written with the Cyrillic alphabet; <code class="literal">az-Arab</code> represents Azerbaijani written in Arabic script and <code class="literal">az-Cyrl</code> represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as <code class="literal">fr-Latn</code>, because French is not commonl
y written in any script other than the Latin alphabet anywhere in the world.
</div></dd><dt><span class="term">region subtag</span></dt><dd><div class="para">
- The region subtag comprises either two upper-case letters (for regions that conform to national boundaries) or three digits (for other areas, such as trans-national regions). The two-letter subtags are identical with those from ISO 3166-1<sup>[<a id="id705360" href="#ftn.id705360" class="footnote">11</a>]</sup>, for example, <code class="literal">AT</code> (Austria), <code class="literal">TZ</code> (Tanzania), and <code class="literal">VE</code> (Venezuela). The three-digit region subtags are based on those in UN M.49, <sup>[<a id="id705386" href="#ftn.id705386" class="footnote">12</a>]</sup> for example, <code class="literal">015</code> (Northern Africa), <code class="literal">061</code> (Polynesia), and <code class="literal">419</code> (Latin America and the Caribbean).
+ The region subtag comprises either two upper-case letters (for regions that conform to national boundaries) or three digits (for other areas, such as trans-national regions). The two-letter subtags are identical with those from ISO 3166-1<sup>[<a id="id568509" href="#ftn.id568509" class="footnote">11</a>]</sup>, for example, <code class="literal">AT</code> (Austria), <code class="literal">TZ</code> (Tanzania), and <code class="literal">VE</code> (Venezuela). The three-digit region subtags are based on those in UN M.49, <sup>[<a id="id568533" href="#ftn.id568533" class="footnote">12</a>]</sup> for example, <code class="literal">015</code> (Northern Africa), <code class="literal">061</code> (Polynesia), and <code class="literal">419</code> (Latin America and the Caribbean).
</div></dd><dt><span class="term">variant subtag</span></dt><dd><div class="para">
Variant subtags identify well-defined, recognizable variants of a language or script and can include upper-case letters, lower-case letters, and numerals. Variant subtags that start with a letter must be at least five characters long, and those that start with a numeral must be at least four characters long. Most variant subtags can only be used in combination with specific subtags or combinations of subtags. Variant subtags do not harmonize with any other standard; they are each the result of a separate registration with the IETF by an interested person or group.
</div><div class="para">
- Under the present standard, dialects of several languages are designated with variant subtags, for example, <code class="literal">nedis</code> denotes Nadiza (also known as Natisone), a dialect of Slovenian. This tag must be used in conjunction with the language subtag for Slovenian, thus: <code class="literal">sl-nedis</code>. In September 2009, the IETF issued a Request for Comments (RFC) that (amongst other things) proposes that dialects be represented by language extension subtags attached to language subtags.<sup>[<a id="id625258" href="#ftn.id625258" class="footnote">13</a>]</sup>
+ Under the present standard, dialects of several languages are designated with variant subtags, for example, <code class="literal">nedis</code> denotes Nadiza (also known as Natisone), a dialect of Slovenian. This tag must be used in conjunction with the language subtag for Slovenian, thus: <code class="literal">sl-nedis</code>. In September 2009, the IETF issued a Request for Comments (RFC) that (amongst other things) proposes that dialects be represented by language extension subtags attached to language subtags.<sup>[<a id="id509084" href="#ftn.id509084" class="footnote">13</a>]</sup>
</div><div class="para">
Most variant subtags mark a particular orthography, most usually as a result of an official spelling reform or a significant work documenting the language. Examples (with their required language subtags) include: <code class="literal">fr-1606nicot</code> (French as documented by Jean Nicot in 1606), <code class="literal">de-1901</code> (German spelling codified by the 2nd Orthographic Conference in 1901) and <code class="literal">be-1959acad</code> (Belarusian as codified by the Orthography Commission in 1959).
</div><div class="para">
@@ -2222,25 +2436,25 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
zh-CN — Chinese (People's Republic of China, implicitly simplified Han script)
</div></li><li class="listitem"><div class="para">
zh-TW — Chinese (Republic of China, implicitly traditional Han script)
- </div></li></ul></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id729198" href="#id729198" class="para">4</a>] </sup>
+ </div></li></ul></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id615853" href="#id615853" class="para">4</a>] </sup>
<a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">http://www.w3.org/TR/REC-xml/#sec-lang-tag</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id707920" href="#id707920" class="para">5</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id451457" href="#id451457" class="para">5</a>] </sup>
<a href="http://tools.ietf.org/html/bcp47">http://tools.ietf.org/html/bcp47</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id701312" href="#id701312" class="para">6</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id560010" href="#id560010" class="para">6</a>] </sup>
<a href="http://www.iana.org/assignments/language-subtag-registry">http://www.iana.org/assignments/language-subtag-registry</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id663976" href="#id663976" class="para">7</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id536974" href="#id536974" class="para">7</a>] </sup>
<a href="http://www.infoterm.info/standardization/iso_639_1_2002.php">http://www.infoterm.info/standardization/iso_639_1_2002.php</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id600368" href="#id600368" class="para">8</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id537004" href="#id537004" class="para">8</a>] </sup>
<a href="http://www.loc.gov/standards/iso639-2/">http://www.loc.gov/standards/iso639-2/</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id600424" href="#id600424" class="para">9</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id551395" href="#id551395" class="para">9</a>] </sup>
<a href="http://tools.ietf.org/html/rfc5646">http://tools.ietf.org/html/rfc5646</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id661848" href="#id661848" class="para">10</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id568455" href="#id568455" class="para">10</a>] </sup>
<a href="http://www.unicode.org/iso15924/">http://www.unicode.org/iso15924/</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id705360" href="#id705360" class="para">11</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id568509" href="#id568509" class="para">11</a>] </sup>
<a href="http://www.iso.org/iso/country_codes.htm">http://www.iso.org/iso/country_codes.htm</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id705386" href="#id705386" class="para">12</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id568533" href="#id568533" class="para">12</a>] </sup>
<a href="http://unstats.un.org/unsd/methods/m49/m49.htm">http://unstats.un.org/unsd/methods/m49/m49.htm</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id625258" href="#id625258" class="para">13</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id509084" href="#id509084" class="para">13</a>] </sup>
<a href="http://tools.ietf.org/html/rfc5646">http://tools.ietf.org/html/rfc5646</a>
</p></div></div></div><div xml:lang="en-US" class="appendix" title="Appendix E. Revision History" id="appe-Users_Guide-Revision_History" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Revision History</h1></div></div></div><div class="para">
<div class="revhistory"><table border="0" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 1.6-1</td><td align="left">Mon May 24 2010</td><td align="left"><span class="author"><span class="firstname">Rüdiger</span> <span class="surname">Landmann</span></span></td></tr><tr><td align="left" colspan="3">
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/common.css b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/common.css
index e1f4d9f..a196f22 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/common.css
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/common.css
@@ -50,7 +50,8 @@ body.desktop .book > .toc {
line-height:1.35em;
}
-.toc .chapter, .toc .appendix, .toc .glossary {
+.toc .glossary,
+.toc .chapter, .toc .appendix {
margin-top:1em;
}
@@ -59,7 +60,8 @@ body.desktop .book > .toc {
display:block;
}
-span.appendix, span.glossary {
+span.glossary,
+span.appendix {
display:block;
margin-top:0.5em;
}
@@ -346,7 +348,6 @@ a.version:focus, a.version:hover {
clear:both;
}
-
/*revision history*/
.revhistory {
display:block;
@@ -362,34 +363,24 @@ a.version:focus, a.version:hover {
}
.revhistory td {
- text-align:right;
+ text-align :left;
padding:0em;
border: none;
border-top: 1px solid #fff;
+ font-weight: bold;
}
-
-.revhistory tr td:first-child {
- text-align:left;
+.revhistory .simplelist td {
+ font-weight: normal;
}
-.revhistory tr td p, .revhistory tr td div.para {
- text-align:left;
- font-weight:bold;
- display:block;
- margin:0em;
- padding:0em;
- padding-bottom:0.7em;
- border-bottom:1px solid #eee;
+.revhistory .simplelist {
+ margin-bottom: 1.5em;
+ margin-left: 1em;
}
.revhistory table th {
- background-color:transparent;
- color:#336699;
- font-size:2em;
- padding: 1em 0em;
- border: none;
- border-bottom:1px solid #eee;
+ display: none;
}
@@ -901,6 +892,10 @@ th, td {
border: 1px solid #000;
}
+.simplelist th, .simplelist td {
+ border: none;
+}
+
table table td {
border-bottom:1px dotted #aaa;
background-color:white;
@@ -964,6 +959,10 @@ span.chapter {
margin-top:0.5em;
}
+table.simplelist td, .calloutlist table td {
+ border-style: none;
+}
+
/*Breadcrumbs*/
#breadcrumbs ul li.first:before {
content:" ";
@@ -1007,7 +1006,8 @@ span.chapter {
margin-bottom:1em;
}
-.glossary dt, .index dt {
+.glossary dt,
+.index dt {
color:#444;
padding-top:.5em;
}
@@ -1375,10 +1375,6 @@ pre {
border-radius: 15px;
}
-.term{
- color:#336699;
-}
-
.package, .citetitle {
font-style: italic;
}
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/lang.css b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/lang.css
index e69de29..81c3115 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/lang.css
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/Common_Content/css/lang.css
@@ -0,0 +1,2 @@
+/* place holder */
+
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Command_summary.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Command_summary.html
index 025d0f4..2f7feec 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Command_summary.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Command_summary.html
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix B. Command summary</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-Disallowed_elements_and_attributes.html" title="Appendix A. Disallowed elements and attributes" /><link rel="next" href="appe-Users_Guide-publican.cfg_parameters.html" title="Appendix C. publican.cfg parameters" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocfram
e" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Disallowed_elements_and_attributes.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-publican.cfg_parameters.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix B. Command summary" id="appe-Users_Guide-Command_summary" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Command summary</h1></div></div></div><div class="variablelist" title="Command options" id="vari-Users_Guide-Command_s
ummary-Command_options"><h6>Command options</h6><dl><dt><span class="term"><code class="command">publican --help</code></span></dt><dd><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix B. Command summary</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-Disallowed_elements_and_attributes.html" title="Appendix A. Disallowed elements and attributes" /><link rel="next" href="appe-Users_Guide-publican.cfg_parameters.html" title="Appendix C. publican.cfg parameters" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe
" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Disallowed_elements_and_attributes.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-publican.cfg_parameters.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix B. Command summary" id="appe-Users_Guide-Command_summary" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Command summary</h1></div></div></div><div class="variablelist" title="Command options" id="vari-Users_Guide-Command_su
mmary-Command_options"><h6>Command options</h6><dl><dt><span class="term"><code class="command">publican --help</code></span></dt><dd><div class="para">
displays help
</div></dd><dt><span class="term"><code class="command">publican --man</code></span></dt><dd><div class="para">
displays the manual page
@@ -28,7 +28,7 @@
removes the temporary directories from a document directory.
</div></dd><dt><span class="term"><code class="command">publican clean_ids</code></span></dt><dd><div class="para">
indents XML files neatly, and rebuilds element IDs.
- </div></dd><dt><span class="term"><code class="command">publican cleanset</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term"><code class="command">publican clean_set</code></span></dt><dd><div class="para">
removes local copies of remote books that are part of a set.
</div></dd><dt><span class="term"><code class="command">publican create</code></span></dt><dd><div class="para">
creates a new book, article, or set. Options:
@@ -52,9 +52,25 @@
the name of the document (mandatory).
</div></dd><dt><span class="term">--lang</span></dt><dd><div class="para">
the language in which the XML will be authored.
+ </div></dd></dl></div></dd><dt><span class="term">publican create_site</span></dt><dd><div class="para">
+ creates a documentation website. Options:
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file to create (mandatory).
+ </div></dd><dt><span class="term">--db_file</span></dt><dd><div class="para">
+ name of the site database file to create (mandatory).
+ </div></dd><dt><span class="term">--toc_path</span></dt><dd><div class="para">
+ path to the directory in which to create the top-level <code class="filename">toc.html</code> file (mandatory).
+ </div></dd><dt><span class="term">--tmpl_path</span></dt><dd><div class="para">
+ path to the template directory (by default, <code class="filename">/usr/share/publican/templates</code>).
</div></dd></dl></div></dd><dt><span class="term"><code class="command">publican help_config</code></span></dt><dd><div class="para">
displays a list of parameters for the <code class="filename">publican.cfg</code> file.
- </div></dd><dt><span class="term"><code class="command">publican installbrand</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">publican install_book</span></dt><dd><div class="para">
+ installs a document on a documentation website.
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
+ </div></dd><dt><span class="term">--lang</span></dt><dd><div class="para">
+ the language of the document to install (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term"><code class="command">publican install_brand</code></span></dt><dd><div class="para">
configures a brand for installation. Option:
</div><div class="variablelist"><dl><dt><span class="term">--path</span></dt><dd><div class="para">
path to the <span class="application"><strong>Publican</strong></span> Common Content files. By default, <code class="filename">/usr/share/publican/Common_Content</code> on Linux operating systems and at <code class="filename">%SystemDrive%/%ProgramFiles%/Publican/Common_Content</code> on Windows operating systems — typically, <code class="filename">C:/Program Files/Publican/Common_Content</code>
@@ -84,14 +100,28 @@
prints a list of DocBook tags banned by <span class="application"><strong>Publican</strong></span>.
</div></dd><dt><span class="term">publican print_known</span></dt><dd><div class="para">
prints a list of DocBook tags supported by <span class="application"><strong>Publican</strong></span>.
- </div></dd><dt><span class="term"><code class="command">publican printtree</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term"><code class="command">publican print_tree</code></span></dt><dd><div class="para">
displays a tree of the XML files included in a document.
</div></dd><dt><span class="term">publican print_unused</span></dt><dd><div class="para">
prints a list of the XML files <span class="emphasis"><em>not</em></span> included with the <code class="sgmltag-element"><xi:include></code> tag in a book, article, or set.
- </div></dd><dt><span class="term"><code class="command">publican update_pot</code></span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">publican remove_book</span></dt><dd><div class="para">
+ removes a document from a documentation website.
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
+ </div></dd><dt><span class="term">--lang</span></dt><dd><div class="para">
+ the language of the document to remove (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term">publican site_stats --site_config=<em class="replaceable"><code>name_of_site_config_file</code></em></span></dt><dd><div class="para">
+ generates a site report for a documentation website. Option:
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term"><code class="command">publican update_pot</code></span></dt><dd><div class="para">
updates the POT files in a document.
</div></dd><dt><span class="term"><code class="command">publican update_po</code></span></dt><dd><div class="para">
updates the PO files in a document.
</div><div class="variablelist"><dl><dt><span class="term">--langs</span></dt><dd><div class="para">
comma-separated list of languages to update, or ‘all’ to update all (mandatory).
+ </div></dd></dl></div></dd><dt><span class="term">publican update_site --site_config=<em class="replaceable"><code>name_of_site_config_file</code></em>.cfg</span></dt><dd><div class="para">
+ regenerates the templated content of a documentation website. Option:
+ </div><div class="variablelist"><dl><dt><span class="term">--site_config</span></dt><dd><div class="para">
+ name of the site configuration file (mandatory).
</div></dd></dl></div></dd></dl></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Disallowed_elements_and_attributes.html"><strong>Prev</strong>Appendix A. Disallowed elements and attributes</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-publican.cfg_parameters.html"><strong>Next</strong>Appendix C. publican.cfg parameters</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Disallowed_elements_and_attributes.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Disallowed_elements_and_attributes.html
index e246562..1d355af 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Disallowed_elements_and_attributes.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Disallowed_elements_and_attributes.html
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix A. Disallowed elements and attributes</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Frequently_Asked_Questions.html" title="Chapter 6. Frequently Asked Questions" /><link rel="next" href="appe-Users_Guide-Command_summary.html" title="Appendix B. Command summary" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc"
src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Command_summary.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix A. Disallowed elements and attributes" id="appe-Users_Guide-Disallowed_elements_and_attributes" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Disallowed elements and attributes</h1></div></div></div><div class="note"><h2>Supported, unsupported, and dis
allowed</h2><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix A. Disallowed elements and attributes</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Frequently_Asked_Questions.html" title="Chapter 7. Frequently Asked Questions" /><link rel="next" href="appe-Users_Guide-Command_summary.html" title="Appendix B. Command summary" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc"
src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Command_summary.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix A. Disallowed elements and attributes" id="appe-Users_Guide-Disallowed_elements_and_attributes" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Disallowed elements and attributes</h1></div></div></div><div class="note"><h2>Supported, unsupported, and disa
llowed</h2><div class="para">
Not every <em class="firstterm">element</em> (tag) and attribute that works with <span class="application"><strong>Publican</strong></span> is <em class="firstterm">supported</em>. Specifically, not every tag has been tested with regards its effect on the presentation of a document once it has been built in HTML or PDF.
</div></div><div class="para">
<span class="application"><strong>Publican</strong></span> works with almost all DocBook 4.5 elements and their attributes, and most of these elements are <em class="firstterm">supported</em>. Supported elements and attributes are those whose presentation in <span class="application"><strong>Publican</strong></span> HTML and PDF output has been tested and is of an acceptable quality.
@@ -10,7 +10,7 @@
Finally, a small group of elements and attributes are <em class="firstterm">disallowed</em>. These elements and attributes are set out below, each accompanied by rationale explaining why it is disallowed.
</div><div class="para">
Use the command <code class="command">publican print_known</code> to print a list of tags that <span class="application"><strong>Publican</strong></span> supports, and the command <code class="command">publican print_banned</code> to print a list of tags that are banned in <span class="application"><strong>Publican</strong></span>.
- </div><div class="section" title="A.1. Disallowed elements" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements"><div class="titlepage"><div><div><h2 class="title">A.1. Disallowed elements</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><caution></code>, </span><span class="term"><code class="sgmltag-element"><tip></code></span></dt><dd><div class="para">
+ </div><div class="section" title="A.1. Disallowed elements" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements">A.1. Disallowed elements</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><caution></code>, </span><span class="term"><code class="sgmltag-element"><tip></code></span></dt><dd><div class="para">
DocBook XML supports five <em class="firstterm">admonitions</em> of varying severity: <code class="sgmltag-element"><tip></code>, <code class="sgmltag-element"><note></code>, <code class="sgmltag-element"><important></code>, <code class="sgmltag-element"><caution></code>, and <code class="sgmltag-element"><warning></code>. Taken together, these represent a very fine-grained set of distinctions. It is unlikely that these fine distinctions can be applied consistently within a document, especially when more than one person writes or maintains the document. Moreover, this level of granularity is meaningless to readers. By design, <span class="application"><strong>Publican</strong></span> disallows the <code class="sgmltag-element"><tip></code> and <code class="sgmltag-element"><caution></code> elements, these elements being the two most redundant in the set.
</div><div class="para">
Use <code class="sgmltag-element"><note></code> instead of <code class="sgmltag-element"><tip></code>, and use either <code class="sgmltag-element"><important></code> or <code class="sgmltag-element"><warning></code> instead of <code class="sgmltag-element"><caution></code>. Some criteria by which you might select a suitable level of severity are presented in the ‘Document Conventions’ section of the preface of books produced with <span class="application"><strong>Publican</strong></span>'s default brand.
@@ -41,14 +41,14 @@
</div></dd></dl></div><div class="para">
In a translated language that does not share the same writing system with the original language in which the XML was written, the result is even more nonsensical.
</div></dd><dt><span class="term"><code class="sgmltag-element"><inlinegraphic></code></span></dt><dd><div class="para">
- This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This tag therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this tag will not satisfy those requirements. Section 508 of the <em class="citetitle">Rehabilitation Act of 1973</em><sup>[<a id="id811927" href="#ftn.id811927" class="footnote">3</a>]</sup> is an example of such a requirement for federal agencies in the United States.
+ This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This tag therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this tag will not satisfy those requirements. Section 508 of the <em class="citetitle">Rehabilitation Act of 1973</em><sup>[<a id="id588881" href="#ftn.id588881" class="footnote">3</a>]</sup> is an example of such a requirement for federal agencies in the United States.
</div><div class="para">
Note that <code class="sgmltag-element"><inlinegraphic></code> is not valid in DocBook version 5.
</div></dd><dt><span class="term"><code class="sgmltag-element"><link></code></span></dt><dd><div class="para">
The <code class="sgmltag-element"><link></code> tag provides a general-purpose hyperlink and therefore offers nothing that the <code class="sgmltag-element"><xref></code> and <code class="sgmltag-element"><ulink></code> tags do not, for internal and external hyperlinks respectively. The <code class="sgmltag-element"><link></code> tag is disallowed due to its redundancy.
</div></dd><dt><span class="term"><code class="sgmltag-element"><olink></code></span></dt><dd><div class="para">
The <code class="sgmltag-element"><olink></code> tag provides cross-references between XML documents. For <code class="sgmltag-element"><olink></code>s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <code class="sgmltag-element"><olink></code>s, these URLs can be supplied either as an XML entity or with a server-side script. <span class="application"><strong>Publican</strong></span> produces documents intended for wide dissemination in which URLs are always necessary for cross-references. Therefore, the <code class="sgmltag-element"><olink></code> tag offers no advantage over the <code class="sgmltag-element"><ulink></code> tag, and is disallowed due to its redundancy.
- </div></dd></dl></div></div><div class="section" title="A.2. Disallowed attributes" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes"><div class="titlepage"><div><div><h2 class="title">A.2. Disallowed attributes</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><[element] xreflabel="[any_string_here]"></code></span></dt><dd><div class="para">
+ </div></dd></dl></div></div><div class="section" title="A.2. Disallowed attributes" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes">A.2. Disallowed attributes</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><[element] xreflabel="[any_string_here]"></code></span></dt><dd><div class="para">
The presence of an <code class="sgmltag-element"><xreflabel></code> attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.
</div><div class="para">
For example, if you have the following:
@@ -210,6 +210,6 @@ msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
Furthermore, note that the combined preposition and article also poses a problem with regard to whether this word should be placed in the text surrounding the <code class="sgmltag-element"><xref></code>, or in the <code class="sgmltag-element"><titleabbrev></code>. Whichever of these two solutions the translator selects will cause problems when the <em class="parameter"><code>endterm</code></em> appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.
</div><div class="para">
Due to the problems that <em class="parameter"><code>endterm</code></em> presents for translation, <span class="application"><strong>Publican</strong></span> disallows this attribute.
- </div></dd></dl></div></div><div class="footnotes"><br /><hr /><div class="footnote"><p><sup>[<a id="ftn.id811927" href="#id811927" class="para">3</a>] </sup>
+ </div></dd></dl></div></div><div class="footnotes"><br /><hr /><div class="footnote"><p><sup>[<a id="ftn.id588881" href="#id588881" class="para">3</a>] </sup>
Refer to <a href="http://www.section508.gov/">http://www.section508.gov/</a>
- </p></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Prev</strong>Chapter 6. Frequently Asked Questions</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Command_summary.html"><strong>Next</strong>Appendix B. Command summary</a></li></ul></body></html>
+ </p></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Prev</strong>Chapter 7. Frequently Asked Questions</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Command_summary.html"><strong>Next</strong>Appendix B. Command summary</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Language_codes.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Language_codes.html
index 0bc638f..93f89a1 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Language_codes.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Language_codes.html
@@ -1,29 +1,29 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix D. Language codes</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-publican.cfg_parameters.html" title="Appendix C. publican.cfg parameters" /><link rel="next" href="appe-Users_Guide-Revision_History.html" title="Appendix E. Revision History" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.h
tml">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-publican.cfg_parameters.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Revision_History.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix D. Language codes" id="appe-Users_Guide-Language_codes" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Language codes</h1></div></div></div><div class="important"><h2>Region subtags</h2><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix D. Language codes</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-publican.cfg_parameters.html" title="Appendix C. publican.cfg parameters" /><link rel="next" href="appe-Users_Guide-Revision_History.html" title="Appendix E. Revision History" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.ht
ml">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-publican.cfg_parameters.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Revision_History.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix D. Language codes" id="appe-Users_Guide-Language_codes" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Language codes</h1></div></div></div><div class="important"><h2>Region subtags</h2><div class="para">
The only part of the XML language tag that is mandatory in <span class="application"><strong>Publican</strong></span> is the <em class="firstterm">language subtag</em>. However, <span class="application"><strong>Publican</strong></span> is designed with the assumption that you will routinely include the <em class="firstterm">region subtag</em> when you identify languages. In many languages, spelling and vocabulary vary significantly from region to region. If you do not specify the regional variety of a language in which your document is authored or into which it is translated, you might obtain unexpected results when you build the document in <span class="application"><strong>Publican</strong></span>.
</div></div><div class="important"><h2>Other language codes</h2><div class="para">
The system of codes used to identify languages in the XML standard is not the only system of languages codes in use in the world today. However, because <span class="application"><strong>Publican</strong></span> strives to comply with the XML standard, these are the only codes that <span class="application"><strong>Publican</strong></span> supports. In particular, note that the codes used in the GNU tools (identified by their use of underscores and the <code class="literal">@</code> symbol to separate elements — for example, <code class="literal">en_GB</code> or <code class="literal">sr_RS at latin</code>) do not comply with the XML standard and therefore do not work with <span class="application"><strong>Publican</strong></span>.
</div></div><div class="para">
- <span class="application"><strong>Publican</strong></span> is an XML publication tool and therefore is designed to use the language codes — or <em class="firstterm">tags</em> — that the World Wide Web Consortium (W3C) designated in the XML specification.<sup>[<a id="id618705" href="#ftn.id618705" class="footnote">4</a>]</sup> These codes are defined in the Internet Engineering Task Force (IETF) document <em class="citetitle">BCP 47: Tags for Identifying Languages</em>.<sup>[<a id="id623889" href="#ftn.id623889" class="footnote">5</a>]</sup>
+ <span class="application"><strong>Publican</strong></span> is an XML publication tool and therefore is designed to use the language codes — or <em class="firstterm">tags</em> — that the World Wide Web Consortium (W3C) designated in the XML specification.<sup>[<a id="id800040" href="#ftn.id800040" class="footnote">4</a>]</sup> These codes are defined in the Internet Engineering Task Force (IETF) document <em class="citetitle">BCP 47: Tags for Identifying Languages</em>.<sup>[<a id="id758361" href="#ftn.id758361" class="footnote">5</a>]</sup>
</div><div class="para">
Language tags are built from one of more <em class="firstterm">subtags</em>, separated from one another by hyphens. In order of appearance within a language tag, these subtags are:
</div><div class="para">
<code class="literal"><em class="replaceable"><code>language</code></em>-<em class="replaceable"><code>script</code></em>-<em class="replaceable"><code>region</code></em>-<em class="replaceable"><code>variant</code></em></code>
</div><div class="para">
- BCP 47 also allows for considerable customization of language tags for special purposes through the use of <em class="firstterm">extension subtags</em> and <em class="firstterm">private-use subtags</em>. Extension subtags allow for finer-tuning of existing subtags, but must be registered with the IETF (none are currently registered). Private-use subtags are introduced by <code class="literal">x-</code> and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).<sup>[<a id="id620242" href="#ftn.id620242" class="footnote">6</a>]</sup> Although <span class="application"><strong>Publican</strong></span> will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form <code class="literal"><em class="replaceable"><code>langu
age</code></em>-<em class="replaceable"><code>region</code></em></code>. A brief description of subtags follows:
+ BCP 47 also allows for considerable customization of language tags for special purposes through the use of <em class="firstterm">extension subtags</em> and <em class="firstterm">private-use subtags</em>. Extension subtags allow for finer-tuning of existing subtags, but must be registered with the IETF (none are currently registered). Private-use subtags are introduced by <code class="literal">x-</code> and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).<sup>[<a id="id438048" href="#ftn.id438048" class="footnote">6</a>]</sup> Although <span class="application"><strong>Publican</strong></span> will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form <code class="literal"><em class="replaceable"><code>langu
age</code></em>-<em class="replaceable"><code>region</code></em></code>. A brief description of subtags follows:
</div><div class="variablelist"><dl><dt><span class="term">language subtag</span></dt><dd><div class="para">
- The language subtag comprises two or more lower-case letters and is the only mandatory part of the language tag. For most widely spoken languages, the language subtag is a two-letter code identical with the language codes specified in ISO 639-1, <sup>[<a id="id699578" href="#ftn.id699578" class="footnote">7</a>]</sup> for example, <code class="literal">zh</code> (Chinese), <code class="literal">hi</code> (Hindi), <code class="literal">es</code> (Spanish), and <code class="literal">en</code> (English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,<sup>[<a id="id679864" href="#ftn.id679864" class="footnote">8</a>]</sup> for example, <code class="literal">bal</code> (Balochi), <code class="literal">apk</code> (Kiowa Apache), and <code class="literal">tpi</code> (Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or
ISO 639-2 equivalent, such as subtags for the constructed languages <code class="literal">qya</code> (Quenya) and <code class="literal">tlh</code> (Klingon), and for the occult language <code class="literal">i-enochian</code> (Enochian). This last example also illustrates a small number of language subtags <em class="firstterm">grandfathered</em> into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.
+ The language subtag comprises two or more lower-case letters and is the only mandatory part of the language tag. For most widely spoken languages, the language subtag is a two-letter code identical with the language codes specified in ISO 639-1, <sup>[<a id="id502869" href="#ftn.id502869" class="footnote">7</a>]</sup> for example, <code class="literal">zh</code> (Chinese), <code class="literal">hi</code> (Hindi), <code class="literal">es</code> (Spanish), and <code class="literal">en</code> (English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,<sup>[<a id="id502899" href="#ftn.id502899" class="footnote">8</a>]</sup> for example, <code class="literal">bal</code> (Balochi), <code class="literal">apk</code> (Kiowa Apache), and <code class="literal">tpi</code> (Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or
ISO 639-2 equivalent, such as subtags for the constructed languages <code class="literal">qya</code> (Quenya) and <code class="literal">tlh</code> (Klingon), and for the occult language <code class="literal">i-enochian</code> (Enochian). This last example also illustrates a small number of language subtags <em class="firstterm">grandfathered</em> into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.
</div><div class="note"><h2>Extended language subtags</h2><div class="para">
- <em class="citetitle">RFC 5646: Tags for Identifying Languages</em><sup>[<a id="id679919" href="#ftn.id679919" class="footnote">9</a>]</sup> issued in September 2009 allows for <em class="firstterm">extended language subtags</em> to follow the language subtag. Extended language subtags are three-letter codes that represent languages that share a close relationship with a language already represented by a language subtag. For example, <code class="literal">yue</code> represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: <code class="literal">zh-yue</code>. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.
+ <em class="citetitle">RFC 5646: Tags for Identifying Languages</em><sup>[<a id="id460518" href="#ftn.id460518" class="footnote">9</a>]</sup> issued in September 2009 allows for <em class="firstterm">extended language subtags</em> to follow the language subtag. Extended language subtags are three-letter codes that represent languages that share a close relationship with a language already represented by a language subtag. For example, <code class="literal">yue</code> represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: <code class="literal">zh-yue</code>. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.
</div></div></dd><dt><span class="term">script subtag</span></dt><dd><div class="para">
- The script subtag comprises four letters — the first one in upper case, the other three in lower case — and defines a writing system. These codes are identical with the four-letter codes specified in ISO 15924.<sup>[<a id="id807860" href="#ftn.id807860" class="footnote">10</a>]</sup> The script subtag is used to identify languages that are commonly written with more than one writing system; the subtag is omitted when it adds no distinguishing value to the language tag overall. For example, <code class="literal">sr-Latn</code> represents Serbian written with the Latin alphabet and <code class="literal">sr-Cyrl</code> represents Serbian written with the Cyrillic alphabet; <code class="literal">az-Arab</code> represents Azerbaijani written in Arabic script and <code class="literal">az-Cyrl</code> represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as <code class="literal">fr-Latn</code>, because French is not commonl
y written in any script other than the Latin alphabet anywhere in the world.
+ The script subtag comprises four letters — the first one in upper case, the other three in lower case — and defines a writing system. These codes are identical with the four-letter codes specified in ISO 15924.<sup>[<a id="id460156" href="#ftn.id460156" class="footnote">10</a>]</sup> The script subtag is used to identify languages that are commonly written with more than one writing system; the subtag is omitted when it adds no distinguishing value to the language tag overall. For example, <code class="literal">sr-Latn</code> represents Serbian written with the Latin alphabet and <code class="literal">sr-Cyrl</code> represents Serbian written with the Cyrillic alphabet; <code class="literal">az-Arab</code> represents Azerbaijani written in Arabic script and <code class="literal">az-Cyrl</code> represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as <code class="literal">fr-Latn</code>, because French is not commonl
y written in any script other than the Latin alphabet anywhere in the world.
</div></dd><dt><span class="term">region subtag</span></dt><dd><div class="para">
- The region subtag comprises either two upper-case letters (for regions that conform to national boundaries) or three digits (for other areas, such as trans-national regions). The two-letter subtags are identical with those from ISO 3166-1<sup>[<a id="id730055" href="#ftn.id730055" class="footnote">11</a>]</sup>, for example, <code class="literal">AT</code> (Austria), <code class="literal">TZ</code> (Tanzania), and <code class="literal">VE</code> (Venezuela). The three-digit region subtags are based on those in UN M.49, <sup>[<a id="id730081" href="#ftn.id730081" class="footnote">12</a>]</sup> for example, <code class="literal">015</code> (Northern Africa), <code class="literal">061</code> (Polynesia), and <code class="literal">419</code> (Latin America and the Caribbean).
+ The region subtag comprises either two upper-case letters (for regions that conform to national boundaries) or three digits (for other areas, such as trans-national regions). The two-letter subtags are identical with those from ISO 3166-1<sup>[<a id="id460209" href="#ftn.id460209" class="footnote">11</a>]</sup>, for example, <code class="literal">AT</code> (Austria), <code class="literal">TZ</code> (Tanzania), and <code class="literal">VE</code> (Venezuela). The three-digit region subtags are based on those in UN M.49, <sup>[<a id="id597425" href="#ftn.id597425" class="footnote">12</a>]</sup> for example, <code class="literal">015</code> (Northern Africa), <code class="literal">061</code> (Polynesia), and <code class="literal">419</code> (Latin America and the Caribbean).
</div></dd><dt><span class="term">variant subtag</span></dt><dd><div class="para">
Variant subtags identify well-defined, recognizable variants of a language or script and can include upper-case letters, lower-case letters, and numerals. Variant subtags that start with a letter must be at least five characters long, and those that start with a numeral must be at least four characters long. Most variant subtags can only be used in combination with specific subtags or combinations of subtags. Variant subtags do not harmonize with any other standard; they are each the result of a separate registration with the IETF by an interested person or group.
</div><div class="para">
- Under the present standard, dialects of several languages are designated with variant subtags, for example, <code class="literal">nedis</code> denotes Nadiza (also known as Natisone), a dialect of Slovenian. This tag must be used in conjunction with the language subtag for Slovenian, thus: <code class="literal">sl-nedis</code>. In September 2009, the IETF issued a Request for Comments (RFC) that (amongst other things) proposes that dialects be represented by language extension subtags attached to language subtags.<sup>[<a id="id636475" href="#ftn.id636475" class="footnote">13</a>]</sup>
+ Under the present standard, dialects of several languages are designated with variant subtags, for example, <code class="literal">nedis</code> denotes Nadiza (also known as Natisone), a dialect of Slovenian. This tag must be used in conjunction with the language subtag for Slovenian, thus: <code class="literal">sl-nedis</code>. In September 2009, the IETF issued a Request for Comments (RFC) that (amongst other things) proposes that dialects be represented by language extension subtags attached to language subtags.<sup>[<a id="id444937" href="#ftn.id444937" class="footnote">13</a>]</sup>
</div><div class="para">
Most variant subtags mark a particular orthography, most usually as a result of an official spelling reform or a significant work documenting the language. Examples (with their required language subtags) include: <code class="literal">fr-1606nicot</code> (French as documented by Jean Nicot in 1606), <code class="literal">de-1901</code> (German spelling codified by the 2nd Orthographic Conference in 1901) and <code class="literal">be-1959acad</code> (Belarusian as codified by the Orthography Commission in 1959).
</div><div class="para">
@@ -128,24 +128,24 @@
zh-CN — Chinese (People's Republic of China, implicitly simplified Han script)
</div></li><li class="listitem"><div class="para">
zh-TW — Chinese (Republic of China, implicitly traditional Han script)
- </div></li></ul></div><div class="footnotes"><br /><hr /><div class="footnote"><p><sup>[<a id="ftn.id618705" href="#id618705" class="para">4</a>] </sup>
+ </div></li></ul></div><div class="footnotes"><br /><hr /><div class="footnote"><p><sup>[<a id="ftn.id800040" href="#id800040" class="para">4</a>] </sup>
<a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag">http://www.w3.org/TR/REC-xml/#sec-lang-tag</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id623889" href="#id623889" class="para">5</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id758361" href="#id758361" class="para">5</a>] </sup>
<a href="http://tools.ietf.org/html/bcp47">http://tools.ietf.org/html/bcp47</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id620242" href="#id620242" class="para">6</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id438048" href="#id438048" class="para">6</a>] </sup>
<a href="http://www.iana.org/assignments/language-subtag-registry">http://www.iana.org/assignments/language-subtag-registry</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id699578" href="#id699578" class="para">7</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id502869" href="#id502869" class="para">7</a>] </sup>
<a href="http://www.infoterm.info/standardization/iso_639_1_2002.php">http://www.infoterm.info/standardization/iso_639_1_2002.php</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id679864" href="#id679864" class="para">8</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id502899" href="#id502899" class="para">8</a>] </sup>
<a href="http://www.loc.gov/standards/iso639-2/">http://www.loc.gov/standards/iso639-2/</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id679919" href="#id679919" class="para">9</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id460518" href="#id460518" class="para">9</a>] </sup>
<a href="http://tools.ietf.org/html/rfc5646">http://tools.ietf.org/html/rfc5646</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id807860" href="#id807860" class="para">10</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id460156" href="#id460156" class="para">10</a>] </sup>
<a href="http://www.unicode.org/iso15924/">http://www.unicode.org/iso15924/</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id730055" href="#id730055" class="para">11</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id460209" href="#id460209" class="para">11</a>] </sup>
<a href="http://www.iso.org/iso/country_codes.htm">http://www.iso.org/iso/country_codes.htm</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id730081" href="#id730081" class="para">12</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id597425" href="#id597425" class="para">12</a>] </sup>
<a href="http://unstats.un.org/unsd/methods/m49/m49.htm">http://unstats.un.org/unsd/methods/m49/m49.htm</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id636475" href="#id636475" class="para">13</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id444937" href="#id444937" class="para">13</a>] </sup>
<a href="http://tools.ietf.org/html/rfc5646">http://tools.ietf.org/html/rfc5646</a>
</p></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-publican.cfg_parameters.html"><strong>Prev</strong>Appendix C. publican.cfg parameters</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Revision_History.html"><strong>Next</strong>Appendix E. Revision History</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Revision_History.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Revision_History.html
index 3c05f72..2d28e2e 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Revision_History.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-Revision_History.html
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix E. Revision History</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-Language_codes.html" title="Appendix D. Language codes" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="
left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Language_codes.html"><strong>Prev</strong></a></li><li class="next"></li></ul><div xml:lang="en-US" class="appendix" title="Appendix E. Revision History" id="appe-Users_Guide-Revision_History" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Revision History</h1></div></div></div><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix E. Revision History</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-Language_codes.html" title="Appendix D. Language codes" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="l
eft" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Language_codes.html"><strong>Prev</strong></a></li><li class="next"></li></ul><div xml:lang="en-US" class="appendix" title="Appendix E. Revision History" id="appe-Users_Guide-Revision_History" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Revision History</h1></div></div></div><div class="para">
<div class="revhistory"><table border="0" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 1.6-1</td><td align="left">Mon May 24 2010</td><td align="left"><span class="author"><span class="firstname">Rüdiger</span> <span class="surname">Landmann</span></span></td></tr><tr><td align="left" colspan="3">
<table border="0" summary="Simple list" class="simplelist"><tr><td>Update Ubuntu installation instructions</td></tr></table>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-publican.cfg_parameters.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-publican.cfg_parameters.html
index 86e395b..4ae8a90 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-publican.cfg_parameters.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/appe-Users_Guide-publican.cfg_parameters.html
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix C. publican.cfg parameters</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-Command_summary.html" title="Appendix B. Command summary" /><link rel="next" href="appe-Users_Guide-Language_codes.html" title="Appendix D. Language codes" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This i
s an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Command_summary.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Language_codes.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix C. publican.cfg parameters" id="appe-Users_Guide-publican.cfg_parameters" lang="en-US"><div class="titlepage"><div><div><h1 class="title">publican.cfg parameters</h1></div></div></div><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix C. publican.cfg parameters</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="appe-Users_Guide-Command_summary.html" title="Appendix B. Command summary" /><link rel="next" href="appe-Users_Guide-Language_codes.html" title="Appendix D. Language codes" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is
an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Command_summary.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Language_codes.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="appendix" title="Appendix C. publican.cfg parameters" id="appe-Users_Guide-publican.cfg_parameters" lang="en-US"><div class="titlepage"><div><div><h1 class="title">publican.cfg parameters</h1></div></div></div><div class="para">
Every book, article, document set, or brand has a <code class="filename">publican.cfg</code> file in its root directory. Parameters that can be set in the <code class="filename">publican.cfg</code> file are:
</div><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>docname</code></em></span></dt><dd><div class="para">
the document name, set by the <code class="option">--name</code> option.
@@ -46,6 +46,8 @@
the CVS root into which to import the SRPM.
</div></dd><dt><span class="term"><em class="parameter"><code>debug</code></em></span></dt><dd><div class="para">
whether <span class="application"><strong>Publican</strong></span> should display debugging messages as it works. (Default: <code class="literal">0</code> — suppress messages)
+ </div></dd><dt><span class="term"><em class="parameter"><code>def_lang</code></em></span></dt><dd><div class="para">
+ the default language for a <span class="application"><strong>Publican</strong></span>-managed website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available. (Default: <code class="literal">en-US</code> — American English)
</div></dd><dt><span class="term"><em class="parameter"><code>doc_url</code></em></span></dt><dd><div class="para">
URL for the documentation team for this package. (Default: <code class="literal">https://fedorahosted.org/publican</code>)
</div></dd><dt><span class="term"><em class="parameter"><code>dt_obsoletes</code></em></span></dt><dd><div class="para">
@@ -89,13 +91,25 @@
</div></dd><dt><span class="term"><em class="parameter"><code>src_url</code></em></span></dt><dd><div class="para">
URL at which to find to find tarballs of source files.
</div></dd><dt><span class="term"><em class="parameter"><code>strict</code></em></span></dt><dd><div class="para">
- <span class="strikethrough strikethrough">use <em class="firstterm">strict mode</em> (Default: <code class="literal">0</code> — not strict)</span> Strict mode is no longer enforced.
+ <span class="strikethrough strikethrough">use <em class="firstterm">strict mode</em> (Default: <code class="literal">0</code> — not strict)</span> Strict mode is not currently enforced.
</div></dd><dt><span class="term"><em class="parameter"><code>tmp_dir</code></em></span></dt><dd><div class="para">
the directory for <span class="application"><strong>Publican</strong></span> output. (Default: <code class="literal">tmp</code>)
</div></dd><dt><span class="term"><em class="parameter"><code>toc_section_depth</code></em></span></dt><dd><div class="para">
the depth of sections that <span class="application"><strong>Publican</strong></span> includes in the main table of contents. (Default: <code class="literal">2</code>)
</div></dd><dt><span class="term"><em class="parameter"><code>web_brew_dist</code></em></span></dt><dd><div class="para">
the <span class="application"><strong>brew</strong></span> build target to use for the web RPM package. (Defaults to <code class="literal">docs-5E</code>)
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_home</code></em></span></dt><dd><div class="para">
+ specifies that the document is the home page of a documentation website, not a standard document.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_host</code></em></span></dt><dd><div class="para">
+ specifies the host name of a documentation website.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_name_label</code></em></span></dt><dd><div class="para">
+ overrides the book name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website.
</div></dd><dt><span class="term"><em class="parameter"><code>web_obsoletes</code></em></span></dt><dd><div class="para">
packages that the web RPM package obsoletes.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_product_label</code></em></span></dt><dd><div class="para">
+ overrides the product name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_search</code></em></span></dt><dd><div class="para">
+ overrides the default search form for a <span class="application"><strong>Publican</strong></span>-managed website. (Defaults: Google search; limited to a site search if <em class="parameter"><code>web_host</code></em> is set.)
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_version_label</code></em></span></dt><dd><div class="para">
+ overrides the version number as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website.
</div></dd></dl></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Command_summary.html"><strong>Prev</strong>Appendix B. Command summary</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Language_codes.html"><strong>Next</strong>Appendix D. Language codes</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Branding.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Branding.html
index b569e03..fa9501b 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Branding.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Branding.html
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 4. Branding</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Creating_a_document.html" title="Chapter 3. Creating a document" /><link rel="next" href="chap-Users_Guide-Using_sets.html" title="Chapter 5. Using sets" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to vi
ew it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Creating_a_document.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Using_sets.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 4. Branding" id="chap-Users_Guide-Branding" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 4. Branding</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</a></span></dt><dt><span class="sect
ion"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-
Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</a></span></
dt></dl></div><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 4. Branding</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Creating_a_document.html" title="Chapter 3. Creating a document" /><link rel="next" href="chap-Users_Guide-Using_sets.html" title="Chapter 5. Using sets" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to vie
w it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Creating_a_document.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Using_sets.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 4. Branding" id="chap-Users_Guide-Branding" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 4. Branding</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</a></span></dt><dt><span class="secti
on"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-U
sers_Guide-Files_in_the_brand_directory-README">4.3.4. README</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</a></span></d
t></dl></div><div class="para">
<em class="firstterm">Brands</em> are collections of files that <span class="application"><strong>Publican</strong></span> uses to apply a consistent look and style to HTML and PDF output. They provide boilerplate text that appears at the beginning of documents, images such as logos, and stylistic elements such as color schemes. <span class="application"><strong>Publican</strong></span> ships with one brand, <code class="filename">common/</code>. Documentation projects can produce and distribute brands to their contributors, either as a package (for example, an RPM package) or as an archive (for example, a tarball or ZIP file).
- </div><div xml:lang="en-US" class="section" title="4.1. Installing a brand" id="sect-Users_Guide-Installing_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.1. Installing a brand</h2></div></div></div><div class="para">
+ </div><div xml:lang="en-US" class="section" title="4.1. Installing a brand" id="sect-Users_Guide-Installing_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</h2></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> brands for Fedora, Genome, and oVirt documents are available as RPM packages in Fedora. Similarly, Red Hat internally distributes RPM packages containing <span class="application"><strong>Publican</strong></span> brands for GIMP, JBoss, and Red Hat documents. Providing that you have access to the relevant repositories, you can install these brands on a computer that runs Red Hat Enterprise Linux or Fedora — or an operating system derived from either — with the command <code class="command">yum install publican-<em class="replaceable"><code>brand</code></em></code> or with a graphical package manager such as <span class="application"><strong>PackageKit</strong></span>.
</div><div class="para">
If you use <span class="application"><strong>Publican</strong></span> on an operating system that does not use RPM packages, your documentation project might provide its brand in another format. Whatever the format in which the brand is supplied, you must place the brand files in a subdirectory of the <span class="application"><strong>Publican</strong></span> Common Content directory. By default, this directory is located at <code class="filename">/usr/share/publican/Common_Content</code> on Linux operating systems and at <code class="filename">%SystemDrive%/%ProgramFiles%/Publican/Common_Content</code> on Windows operating systems — typically, <code class="filename">C:/Program Files/Publican/Common_Content</code>
@@ -14,29 +14,22 @@
If the brand was supplied to you in an archive of some kind, for example, a tarball or ZIP file, unpack the brand into a new directory on your system.
</div></li><li class="step" title="Step 2"><div class="para">
Change into the directory in which you created or unpacked the brand:
- </div><pre class="screen"><code class="command">cd publican-<em class="replaceable"><code>brand</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">cd publican-<em class="replaceable"><code>brand</code></em></code></pre><div class="para">
where <em class="replaceable"><code>brand</code></em> is the name of the brand.
</div></li><li class="step" title="Step 3"><div class="para">
Build the brand:
- </div><pre class="screen"><code class="command">publican build --formats xml --langs all --publish</code>
-</pre></li><li class="step" title="Step 4"><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats xml --langs all --publish</code></pre></li><li class="step" title="Step 4"><div class="para">
Install the brand:
- </div><pre class="screen"><code class="command">sudo publican installbrand --path <em class="replaceable"><code>path</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">sudo publican install_brand --path <em class="replaceable"><code>path</code></em></code></pre><div class="para">
where <em class="replaceable"><code>path</code></em> is the path to the <span class="application"><strong>Publican</strong></span> Common Content files. For example, on a Linux system, run:
- </div><pre class="screen"><code class="command">sudo publican installbrand --path /usr/share/publican/Common_Content</code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">sudo publican install_brand --path /usr/share/publican/Common_Content</code></pre><div class="para">
or on a Windows system, run
- </div><pre class="screen"><code class="command">sudo publican installbrand --path "C:/Program Files/Publican/Common_Content"</code>
-</pre></li><li class="step" title="Step 5"><div class="para">
-
- </div></li><li class="step" title="Step 6"><div class="para">
-
- </div></li></ol></div><div class="table"><div class="table-contents"><table summary="Current Brands and their packages" border="1"><colgroup><col width="14%" /><col width="29%" /><col width="29%" /><col width="29%" /></colgroup><thead><tr><th>
+ </div><pre class="screen"><code class="command">publican install_brand --path "C:/Program Files/Publican/Common_Content"</code></pre></li></ol></div><div class="table" title="Table 4.1. Current Brands and their packages" id="tabl-Users_Guide-Installing_a_brand-Current_Brands_and_their_packages"><div class="table-contents"><table summary="Current Brands and their packages" border="1"><colgroup><col width="11%" /><col width="22%" /><col width="22%" /><col width="22%" /><col width="22%" /></colgroup><thead><tr><th>
Brand
</th><th>
- License
+ License of Common Content files
+ </th><th>
+ Default license for documents
</th><th>
Package
</th><th>
@@ -44,6 +37,8 @@
</th></tr></thead><tbody><tr><td>
common
</td><td>
+ <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0</a>
+ </td><td>
<a href="http://www.gnu.org/licenses/fdl.html">GFDL Version 1.2</a>
</td><td>
publican
@@ -54,13 +49,17 @@
</td><td>
<a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA 3.0</a>
</td><td>
+ <span>CC-BY-SA 3.0</span>
+ </td><td>
publican-redhat
</td><td>
</td></tr><tr><td>
Fedora
</td><td>
- <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA 3.0</a>
+ <span>CC-BY-SA 3.0</span>
+ </td><td>
+ <span>CC-BY-SA 3.0</span>
</td><td>
publican-fedora
</td><td>
@@ -68,7 +67,9 @@
</td></tr><tr><td>
JBoss
</td><td>
- <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA 3.0</a>
+ <span>CC-BY-SA 3.0</span>
+ </td><td>
+ <span>CC-BY-SA 3.0</span>
</td><td>
publican-jboss
</td><td>
@@ -78,6 +79,8 @@
</td><td>
<a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
</td><td>
+ <span>OPL 1.0</span>
+ </td><td>
publican-ovirt
</td><td>
No Options.
@@ -86,31 +89,34 @@
</td><td>
<a href="http://www.gnu.org/licenses/fdl.html">GFDL Version 1.2</a>
</td><td>
+ <span>GFDL Version 1.2</span>
+ </td><td>
publican-gimp
</td><td>
- GPL compatible license. No options.
+ Matches the license for existing GIMP documentation.
</td></tr><tr><td>
Genome
</td><td>
- <a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
+ <span>OPL 1.0</span>
+ </td><td>
+ <span>OPL 1.0</span>
</td><td>
publican-genome
</td><td>
No Options.
- </td></tr></tbody></table></div><h6>Table 4.1. Current Brands and their packages</h6></div><br class="table-break" /></div><div xml:lang="en-US" class="section" title="4.2. Creating a brand" id="sect-Users_Guide-Creating_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.2. Creating a brand</h2></div></div></div><div class="para">
+ </td></tr></tbody></table></div><h6>Table 4.1. Current Brands and their packages</h6></div><br class="table-break" /><div class="para">
+ Note the difference in licensing between the common content files provided in the common brand (CC0) and the default license set for books generated with the common brand (GFDL). The CC0 license allows you to redistribute and relicense the files that make up the common brand (including the CSS and image files) to suit your project. <span class="application"><strong>Publican</strong></span> suggests the GFDL for documentation by default because <span class="application"><strong>Publican</strong></span> is developed primarily to build documentation for software. The GFDL is compatible with the GPL, which is the most commonly used license for open-source software.
+ </div></div><div xml:lang="en-US" class="section" title="4.2. Creating a brand" id="sect-Users_Guide-Creating_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</h2></div></div></div><div class="para">
Use the <code class="command">create_brand</code> action to create a new brand. When you create a new brand, you must give it a name and specify the original language for the brand's XML files. The <code class="option">--name</code> option provides the name, and the <code class="option">--lang</code> option specifies the language. The complete command is therefore:
- </div><pre class="screen"><code class="command">publican create_brand --name=<em class="replaceable"><code>brand</code></em> --lang=<em class="replaceable"><code>language_code</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">publican create_brand --name=<em class="replaceable"><code>brand</code></em> --lang=<em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
<span class="application"><strong>Publican</strong></span> creates a new subdirectory named <code class="filename">publican-<em class="replaceable"><code>brand</code></em></code>, where <em class="replaceable"><code>brand</code></em> is the brand that you specified with the <code class="option">--name</code> option.
</div><div class="para">
For example, to create a brand called <code class="literal">Acme</code>, which will have its Common Content XML files written originally in American English, run:
- </div><pre class="screen"><code class="command">publican create_brand --name=Acme --lang=en-US</code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">publican create_brand --name=Acme --lang=en-US</code></pre><div class="para">
<span class="application"><strong>Publican</strong></span> creates the brand in a subdirectory named <code class="filename">publican-Acme</code>.
</div><div class="para">
To configure your new brand, search for the word <code class="literal">SETUP</code> in the default files that <span class="application"><strong>Publican</strong></span> creates and edit the files to provide the missing details. On Linux operating systems, you can search for the word <code class="literal">SETUP</code> in these files with the command:
- </div><pre class="screen"><code class="command">grep -r 'SETUP' *</code>
-</pre></div><div xml:lang="en-US" class="section" title="4.3. Files in the brand directory" id="sect-Users_Guide-Files_in_the_brand_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.3. Files in the brand directory</h2></div></div></div><div class="para">
+ </div><pre class="screen"><code class="command">grep -r 'SETUP' *</code></pre></div><div xml:lang="en-US" class="section" title="4.3. Files in the brand directory" id="sect-Users_Guide-Files_in_the_brand_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</h2></div></div></div><div class="para">
Running the <code class="command">publican create_brand --name=<em class="replaceable"><code>brand</code></em> --lang=<em class="replaceable"><code>language_code</code></em></code> command creates a directory structure and the required files. The brand directory initially contains:
<div class="itemizedlist"><ul><li class="listitem"><div class="para">
<code class="filename">COPYING</code>
@@ -138,7 +144,7 @@
the <code class="filename">images</code> subdirectory, which contains 43 images in both raster (PNG) and vector (SVG) formats.
</div></li></ul></div></li></ul></div>
- </div><div class="section" title="4.3.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title">4.3.1. The publican.cfg file</h3></div></div></div><div class="para">
+ </div><div class="section" title="4.3.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</h3></div></div></div><div class="para">
The <code class="filename">publican.cfg</code> file in a brand serves a similar purpose to the <code class="filename">publican.cfg</code> file in a document — it configures a number of basic options that define your brand.
</div><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>version</code></em></span></dt><dd><div class="para">
specifies the version number for the brand. When you create the brand with <code class="command">publican create_brand</code>, the version number is set to <code class="literal">1.0</code>. Update the version number here in the brand <code class="filename">publican.cfg</code> file and in the brand <code class="filename">publican.spec</code> file when you prepare a new version of the brand.
@@ -152,7 +158,7 @@
when set to <code class="literal">type=brand</code>, this parameter identifies the contents of this directory as a brand, rather than a book, article, or set.
</div></dd><dt><span class="term"><em class="parameter"><code>brand</code></em></span></dt><dd><div class="para">
specifies the name of the brand, as set by the <code class="option">--name</code> option for <code class="command">publican create_brand</code>.
- </div></dd></dl></div></div><div class="section" title="4.3.2. The defaults.cfg file and overrides.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file"><div class="titlepage"><div><div><h3 class="title">4.3.2. The defaults.cfg file and overrides.cfg file</h3></div></div></div><div class="para">
+ </div></dd></dl></div></div><div class="section" title="4.3.2. The defaults.cfg file and overrides.cfg file" id="sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</h3></div></div></div><div class="para">
Every document built in <span class="application"><strong>Publican</strong></span> has a <code class="filename">publican.cfg</code> file in its root directory, which configures build options for the document. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a> for a full description of these options. The <code class="filename">defaults.cfg</code> file and <code class="filename">overrides.cfg</code> file in a brand supply default values for any of the parameters that you can otherwise set with a document's <code class="filename">publican.cfg</code> file.
</div><div class="para">
When you build a document with a particular brand, <span class="application"><strong>Publican</strong></span> first applies the values in the brand's <code class="filename">defaults.cfg</code> file before it applies the values in the document's <code class="filename">publican.cfg</code> file. Values in the document's <code class="filename">publican.cfg</code> file therefore override those in the brand's <code class="filename">defaults.cfg</code> file.
@@ -160,25 +166,25 @@
<span class="application"><strong>Publican</strong></span> next applies the values in the brand's <code class="filename">overrides.cfg</code> file, which therefore override any values in the brand's <code class="filename">defaults.cfg</code> file and the document's <code class="filename">publican.cfg</code> file.
</div><div class="para">
Use the <code class="filename">defaults.cfg</code> file to set values that you routinely apply to your brand but want to allow writers to change in particular books; use the <code class="filename">overrides.cfg</code> file for values that you do not want to allow writers to change.
- </div></div><div class="section" title="4.3.3. publican-brand.spec file" id="sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file"><div class="titlepage"><div><div><h3 class="title">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.3. publican-brand.spec file" id="sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</h3></div></div></div><div class="para">
Some Linux operating systems use the <span class="application"><strong>RPM Package Manager</strong></span> to distribute software, in the form of <em class="firstterm">RPM packages</em>. In general terms, an RPM package contains software files compressed into an archive, accompanied by a <em class="firstterm">spec file</em> that tells the <span class="application"><strong>RPM Package Manager</strong></span> how and where to install those files.
</div><div class="para">
When you create a brand, <span class="application"><strong>Publican</strong></span> generates the outline of an RPM spec file for the brand. The automatically generated spec file provides you with a starting point from which to create an RPM package to distribute your brand. Refer to <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> to learn how to configure the spec file and use it to produce an RPM package.
- </div></div><div class="section" title="4.3.4. README" id="sect-Users_Guide-Files_in_the_brand_directory-README"><div class="titlepage"><div><div><h3 class="title">4.3.4. README</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.4. README" id="sect-Users_Guide-Files_in_the_brand_directory-README"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</h3></div></div></div><div class="para">
The <code class="filename">README</code> file in an SRPM package includes a brief description of the package.
- </div></div><div class="section" title="4.3.5. COPYING" id="sect-Users_Guide-Files_in_the_brand_directory-COPYING"><div class="titlepage"><div><div><h3 class="title">4.3.5. COPYING</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.5. COPYING" id="sect-Users_Guide-Files_in_the_brand_directory-COPYING"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</h3></div></div></div><div class="para">
The <code class="filename">COPYING</code> file in an SRPM package contains details of the copyright license for the package.
- </div></div><div class="section" title="4.3.6. Common Content for the brand" id="sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand"><div class="titlepage"><div><div><h3 class="title">4.3.6. Common Content for the brand</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.6. Common Content for the brand" id="sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</h3></div></div></div><div class="para">
Inside the brand directory is a subdirectory named after the default XML language for brand, as set with the <code class="option">--lang</code> option when you created the brand. This subdirectory contains XML and image files that override the default Common Content provided with <span class="application"><strong>Publican</strong></span>. Customizing these files provides your brand with its distinctive appearance, including its color scheme and logos.
- </div><div class="section" title="4.3.6.1. Feedback.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Feedback.xml"><div class="titlepage"><div><div><h4 class="title">4.3.6.1. <code class="filename">Feedback.xml</code></h4></div></div></div><div class="para">
+ </div><div class="section" title="4.3.6.1. Feedback.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Feedback.xml"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Common_Content_for_the_brand-Feedback.xml">4.3.6.1. <code class="filename">Feedback.xml</code></h4></div></div></div><div class="para">
The <code class="filename">Feedback.xml</code> file is included by default in the preface of every book produced in <span class="application"><strong>Publican</strong></span>. It invites readers to leave feedback about the document. Customize this file with the contact details of your project. If your project uses a bug tracking system such as <span class="application"><strong>Bugzilla</strong></span>, <span class="application"><strong>JIRA</strong></span>, or <span class="application"><strong>Trac</strong></span>, you could include this information here.
- </div></div><div class="section" title="4.3.6.2. Legal_Notice.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Legal_Notice.xml"><div class="titlepage"><div><div><h4 class="title">4.3.6.2. <code class="filename">Legal_Notice.xml</code></h4></div></div></div><div class="para">
+ </div></div><div class="section" title="4.3.6.2. Legal_Notice.xml" id="sect-Users_Guide-Common_Content_for_the_brand-Legal_Notice.xml"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Common_Content_for_the_brand-Legal_Notice.xml">4.3.6.2. <code class="filename">Legal_Notice.xml</code></h4></div></div></div><div class="para">
The <code class="filename">Legal_Notice.xml</code> file contains the legal notice that appears at the beginning of every document produced by <span class="application"><strong>Publican</strong></span>. Insert the details of your chosen copyright license into this file. Typically, this might include the name of the license, a short summary of the license, and a link to the full details of the license.
- </div></div></div><div class="section" title="4.3.7. The css subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory"><div class="titlepage"><div><div><h3 class="title">4.3.7. The <code class="filename">css</code> subdirectory</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="4.3.7. The css subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</h3></div></div></div><div class="para">
The <code class="filename">css</code> subdirectory contains a single file: <code class="filename">overrides.css</code>.
- </div><div class="section" title="4.3.7.1. overrides.css" id="sect-Users_Guide-The_css_subdirectory-overrides.css"><div class="titlepage"><div><div><h4 class="title">4.3.7.1. overrides.css</h4></div></div></div><div class="para">
+ </div><div class="section" title="4.3.7.1. overrides.css" id="sect-Users_Guide-The_css_subdirectory-overrides.css"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-The_css_subdirectory-overrides.css">4.3.7.1. overrides.css</h4></div></div></div><div class="para">
The <code class="filename">overrides.css</code> file sets the visual style for your brand. Values in this file override those in <span class="application"><strong>Publican</strong></span>'s <code class="filename">Common_Content/common/<em class="replaceable"><code>xml_lang</code></em>/css/common.css</code> file.
- </div></div></div><div class="section" title="4.3.8. The images subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory"><div class="titlepage"><div><div><h3 class="title">4.3.8. The <code class="filename">images</code> subdirectory</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="4.3.8. The images subdirectory" id="sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</h3></div></div></div><div class="para">
The <code class="filename">images</code> subdirectory contains 43 images in both <em class="firstterm">portable network graphics</em> (PNG) and <em class="firstterm">scalable vector graphics</em> (SVG) format. These images are placeholders for various navigation icons, admonition graphics, and brand logos. They include:
</div><div class="variablelist"><dl><dt><span class="term"><code class="filename">image_left</code></span></dt><dd><div class="para">
is a logo for the product to which this document applies. It appears at the top left corner of HTML pages, where it contains a hyperlink to a web page for the product, as defined by <em class="parameter"><code>prod_url</code></em> in the <code class="filename">publican.cfg</code> file for the document. Consider setting <em class="parameter"><code>prod_url</code></em> in the brand's <code class="filename">defaults.cfg</code> or <code class="filename">overrides.cfg</code> file.
@@ -195,8 +201,8 @@
</div></dd><dt><span class="term"><code class="filename">h1-bg</code></span></dt><dd><div class="para">
is a background for the heading that contains the name of your product, as it appears at the very beginning of a HTML document.
</div></dd><dt><span class="term"><code class="filename">watermark_draft</code></span></dt><dd><div class="para">
- is a watermark that appears on pages of draft documentation. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation" title="3.7.2. Denoting draft documentation">Section 3.7.2, “Denoting draft documentation”</a>.
- </div></dd></dl></div></div></div><div xml:lang="en-US" class="section" title="4.4. Packaging a brand" id="sect-Users_Guide-Packaging_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title">4.4. Packaging a brand</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
+ is a watermark that appears on pages of draft documentation. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation" title="3.8.2. Denoting draft documentation">Section 3.8.2, “Denoting draft documentation”</a>.
+ </div></dd></dl></div></div></div><div xml:lang="en-US" class="section" title="4.4. Packaging a brand" id="sect-Users_Guide-Packaging_a_brand" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
This section discusses packaging documents for distribution through the <span class="application"><strong>RPM Package Manager</strong></span>. However, when you use the <code class="command">publican package</code> command, <span class="application"><strong>Publican</strong></span> generates a tarball that you can use to build a package to distribute through different package manager software. If you run <code class="command">publican package</code> on a computer on which <span class="application"><strong>rpmbuild</strong></span> is not installed, <span class="application"><strong>Publican</strong></span> still generates the tarball, even though it cannot then generate an RPM package from that tarball.
</div></div><div class="para">
After you create a brand (as described in <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Creating_a_brand" title="4.2. Creating a brand">Section 4.2, “Creating a brand”</a>), <span class="application"><strong>Publican</strong></span> can help you to distribute the brand to members of your documentation project as <em class="firstterm">RPM packages</em>. RPM packages are used to distribute software to computers with Linux operating systems that use the <span class="application"><strong>RPM Package Manager</strong></span>. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
@@ -215,7 +221,7 @@
</div></dd><dt><span class="term"><code class="option">--scratch</code></span></dt><dd><div class="para">
when used together with the <code class="option">--brew</code> option, specifies that a SRPM package should be built as a <em class="firstterm">scratch build</em> when sent to <span class="application"><strong>Brew</strong></span>. Scratch builds are used to verify that a SRPM package is structured correctly, without updating the package database to use the resulting package.
</div></dd></dl></div><div class="para">
- The <code class="option">--lang</code>, <code class="option">--desktop</code> and <code class="option">--short_sighted</code> options that apply when you package books (described in <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>) are meaningless when you package brands. In particular, note that although the <code class="option">--lang</code> option is mandatory when you package a book, you do not need to use it when you package a brand.
+ The <code class="option">--lang</code>, <code class="option">--desktop</code> and <code class="option">--short_sighted</code> options that apply when you package books (described in <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>) are meaningless when you package brands. In particular, note that although the <code class="option">--lang</code> option is mandatory when you package a book, you do not need to use it when you package a brand.
</div><div class="para">
By default, <span class="application"><strong>Publican</strong></span> brand packages are named <code class="filename">publican-<em class="replaceable"><code>brand</code></em>-<em class="replaceable"><code>version</code></em>-<em class="replaceable"><code>release</code></em>.<em class="replaceable"><code>[build_target]</code></em>.[noarch].<em class="replaceable"><code>file_extension</code></em></code>. <span class="application"><strong>Publican</strong></span> uses the information in the <code class="filename">publican.cfg</code> file to supply the various parameters in the file name. Refer to <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file" title="4.3.1. The publican.cfg file">Section 4.3.1, “The publican.cfg file”</a> for details of configuring this file. Additionally:
<div class="itemizedlist"><ul><li class="listitem"><div class="para">
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Creating_a_document.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Creating_a_document.html
index 2aff8c1..ab73246 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Creating_a_document.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Creating_a_document.html
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 3. Creating a document</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Publican_commands.html" title="Chapter 2. Publican commands" /><link rel="next" href="chap-Users_Guide-Branding.html" title="Chapter 4. Branding" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to
view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Publican_commands.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Branding.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 3. Creating a document" id="chap-Users_Guide-Creating_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Creating a document</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory">3.1. Fil
es in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating
_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation">3.3. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document">3.4. Building a document</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.4.1. Building a document
created with Publican 0</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book">3.5. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.5.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.5.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging">3.6. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.6.1. Conditional tagging and translation</a></span></dt></
dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.7. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.7.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.7.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.7.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></div><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 3. Creating a document</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Publican_commands.html" title="Chapter 2. Publican commands" /><link rel="next" href="chap-Users_Guide-Branding.html" title="Chapter 4. Branding" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to
view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Publican_commands.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Branding.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 3. Creating a document" id="chap-Users_Guide-Creating_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Creating a document</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory">3.1. File
s in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_
a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Adding_files">3.3. Adding files</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation">3.4. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document">3.5. Building a document</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_
Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.5.1. Building a document created with Publican 0</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book">3.6. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.6.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.6.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging">3.7. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document
.html#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.7.1. Conditional tagging and translation</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.8. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.8.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.8.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_sof
tware">3.8.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></div><div class="para">
This chapter describes creating books and articles: the main configuration files, example document files, and how to build a document.
</div><div class="para">
Use the <code class="command">publican create</code> command to create a new document, including all the necessary files for the document.
@@ -27,14 +27,11 @@
</div></dd></dl></div><div class="para">
Before running the <code class="command">publican create</code> command, use the <code class="command">cd</code> command to change into the directory where you want the book to be created. For example, to create a book named <code class="literal">Test_Book</code> in the <code class="filename">my_books/</code> directory, run the following commands:
</div><pre class="screen"><code class="command">cd my_books/</code>
-<code class="command">publican create --name Test_Book</code>
-</pre><div class="para">
+<code class="command">publican create --name Test_Book</code></pre><div class="para">
To see the results of this command on a computer with a Linux operating system, run the following:
- </div><pre class="screen"><code class="command">ls</code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">ls</code></pre><div class="para">
The output should be similar to the following:
- </div><pre class="screen"><code class="computeroutput">en-US publican.cfg</code>
-</pre><div xml:lang="en-US" class="section" title="3.1. Files in the book directory" id="sect-Users_Guide-Files_in_the_book_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.1. Files in the book directory</h2></div></div></div><div class="para">
+ </div><pre class="screen"><code class="computeroutput">en-US publican.cfg</code></pre><div xml:lang="en-US" class="section" title="3.1. Files in the book directory" id="sect-Users_Guide-Files_in_the_book_directory" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</h2></div></div></div><div class="para">
If you run the command <code class="command">publican create --name Test_Book --lang en-US</code>, <span class="application"><strong>Publican</strong></span> creates a directory structure and required files, similar to the following:
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
<code class="filename">publican.cfg</code>
@@ -58,10 +55,9 @@
<code class="filename">images</code> (directory)
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
<code class="filename">icon.svg</code>
- </div></li></ul></div></li></ul></div></li></ul></div><div class="section" title="3.1.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title">3.1.1. The publican.cfg file</h3></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
+ </div></li></ul></div></li></ul></div></li></ul></div><div class="section" title="3.1.1. The publican.cfg file" id="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</h3></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
If you maintain multiple versions of a document, you can create a configuration file for each version. When building or packaging the document, you can use the <code class="option">--config</code> to specify a configuration file other than the <code class="filename">publican.cfg</code> file and therefore a different set of parameters to use in a particular build. For example:
- </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code>
-</pre></div><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code></pre></div><div class="para">
The <code class="filename">publican.cfg</code> file configures build options, and is located in the root of the book directory. The following is an example <code class="filename">publican.cfg</code> file, with a description of <code class="filename">publican.cfg</code> parameters following afterwards:
</div><pre class="programlisting"># Config::Simple 4.59
# Mon Sep 28 16:38:14 2009
@@ -72,6 +68,7 @@ brand: common
+
</pre><div class="variablelist" title="Default parameters" id="vari-Users_Guide-The_publican.cfg_file-Default_parameters"><h6>Default parameters</h6><dl><dt><span class="term"><em class="parameter"><code>xml_lang</code></em></span></dt><dd><div class="para">
specifies the language of the source XML files, for example, <code class="literal">en-US</code>, as set by the <code class="option">--lang</code> option for <code class="command">publican create</code>.
@@ -82,7 +79,7 @@ brand: common
</div></dd></dl></div><div class="variablelist" title="Advanced parameters" id="vari-Users_Guide-The_publican.cfg_file-Advanced_parameters"><h6>Advanced parameters</h6><dl><dt><span class="term"><em class="parameter"><code>arch</code></em></span></dt><dd><div class="para">
filters output by computer <em class="firstterm">architecture</em>. For example, if you set <code class="literal">arch: x86_64</code> in the <code class="filename">publican.cfg</code> file, <span class="application"><strong>Publican</strong></span> will only include XML elements tagged with the equivalent attribute, such as <code class="sgmltag-element"><para arch="x86_64"></code>.
</div><div class="warning"><h2>Use with caution</h2><div class="para">
- As with conditional tagging more generally, <code class="literal">arch</code> can cause great difficulties when translating documents. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation" title="3.6.1. Conditional tagging and translation">Section 3.6.1, “Conditional tagging and translation”</a> for an explanation of the issues.
+ As with conditional tagging more generally, <code class="literal">arch</code> can cause great difficulties when translating documents. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation" title="3.7.1. Conditional tagging and translation">Section 3.7.1, “Conditional tagging and translation”</a> for an explanation of the issues.
</div></div><div class="important"><h2>arch set for root nodes</h2><div class="para">
If the root node of an XML file is excluded by the <em class="parameter"><code>arch</code></em> attribute, your document will not build, because empty files are not valid XML. For example, if <code class="filename">Installation_and_configuration-PPC.xml</code> contains a single chapter:
</div><pre class="programlisting">
@@ -105,7 +102,7 @@ brand: common
</div></div></dd><dt><span class="term"><em class="parameter"><code>books</code></em></span></dt><dd><div class="para">
specifies a space-separated list of books used in a remote set. Refer to <a class="xref" href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Distributed_sets" title="5.2. Distributed sets">Section 5.2, “Distributed sets”</a> for more information on distributed sets.
</div></dd><dt><span class="term"><em class="parameter"><code>brew_dist</code></em></span></dt><dd><div class="para">
- specifies the build target to use for building the desktop RPM package in <span class="application"><strong>Brew</strong></span>, Red Hat's internal build system. This parameter defaults to <code class="literal">docs-5E</code>. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a> and <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more information on building RPM packages.
+ specifies the build target to use for building the desktop RPM package in <span class="application"><strong>Brew</strong></span>, Red Hat's internal build system. This parameter defaults to <code class="literal">docs-5E</code>. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a> and <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more information on building RPM packages.
</div></dd><dt><span class="term"><em class="parameter"><code>chunk_first</code></em></span></dt><dd><div class="para">
controls whether the first section should appear on the same page as its parent when rendered in HTML. To make the first section appear on the same page as its parent, set this parameter to <code class="literal">chunk_first: 1</code>. Otherwise, the parameter defaults to <code class="literal">0</code>, and the first section starts a new HTML page.
</div></dd><dt><span class="term"><em class="parameter"><code>chunk_section_depth</code></em></span></dt><dd><div class="para">
@@ -117,7 +114,7 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>common_content</code></em></span></dt><dd><div class="para">
sets the path to the <span class="application"><strong>Publican</strong></span> <em class="firstterm">Common Content</em> files. These files provide default formatting, plus some boilerplate text and generic graphics. The default location on a computer with a Linux operating system is <code class="filename">/usr/share/publican/Common_Content</code>. On a computer with a Windows operating system, the default location is <code class="filename">%SystemDrive%/%ProgramFiles%/publican/Common_Content</code> — most usually <code class="filename">C:/Program Files/publican/Common_Content</code>.
</div></dd><dt><span class="term"><em class="parameter"><code>condition</code></em></span></dt><dd><div class="para">
- specifies conditions on which to prune XML before transformation. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging" title="3.6. Conditional tagging">Section 3.6, “Conditional tagging”</a> for more information.
+ specifies conditions on which to prune XML before transformation. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging" title="3.7. Conditional tagging">Section 3.7, “Conditional tagging”</a> for more information.
</div><div class="important"><h2>Root nodes and conditional tagging</h2><div class="para">
If the root node of an XML file is excluded with a conditional, your document will not build, because empty files are not valid XML. For example, if <code class="filename">Installation_and_configuration_on_Fedora.xml</code> contains a single chapter:
</div><pre class="programlisting">
@@ -142,19 +139,21 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>confidential_text</code></em></span></dt><dd><div class="para">
specifies the text to use when the <em class="parameter"><code>confidential</code></em> parameter is set to <code class="literal">1</code>. The default text is <code class="literal">CONFIDENTIAL</code>.
</div></dd><dt><span class="term"><em class="parameter"><code>cvs_branch</code></em></span></dt><dd><div class="para">
- the CVS branch into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a>.
+ the CVS branch into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>cvs_pck</code></em></span></dt><dd><div class="para">
- the CVS package into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a>.
+ the CVS package into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>cvs_root</code></em></span></dt><dd><div class="para">
- the CVS root into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.5.2. The publican package command">Section 3.5.2, “The <code class="command">publican package</code> command”</a>.
+ the CVS root into which to import the SRPM. Specify this parameter when packaging a document with the <code class="option">--cvs</code> option — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command" title="3.6.2. The publican package command">Section 3.6.2, “The <code class="command">publican package</code> command”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>debug</code></em></span></dt><dd><div class="para">
controls whether <span class="application"><strong>Publican</strong></span> should display debugging messages as it works. When set to its default of <code class="literal">0</code>, <span class="application"><strong>Publican</strong></span> does not display debugging messages. Change this value to <code class="literal">1</code> to view these messages.
+ </div></dd><dt><span class="term"><em class="parameter"><code>def_lang</code></em></span></dt><dd><div class="para">
+ sets the default language for a <span class="application"><strong>Publican</strong></span>-managed website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>doc_url</code></em></span></dt><dd><div class="para">
provides a URL for the documentation team for this package. In multi-page HTML output, <span class="application"><strong>Publican</strong></span> links to this URL at the top right of each page, through the <code class="filename">image_right.png</code> image in the <code class="filename">Common_Content/images</code> directory for the brand. This parameter defaults to <code class="literal">https://fedorahosted.org/publican</code>
</div></dd><dt><span class="term"><em class="parameter"><code>docname</code></em></span></dt><dd><div class="para">
specifies the document name. If set, this value overrides the content of the <code class="sgmltag-element"><title></code> tag in the <code class="filename">Book_Info.xml</code> 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 ‘ ’).
</div></dd><dt><span class="term"><em class="parameter"><code>dt_obsoletes</code></em></span></dt><dd><div class="para">
- specifies the desktop packages that this package obsoletes. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the desktop packages that this package obsoletes. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>dtdver</code></em></span></dt><dd><div class="para">
specifies the version of the DocBook XML <em class="firstterm">Document Type Definition</em> (DTD) on which this project is based. <span class="application"><strong>Publican</strong></span> defaults to version 4.5. The specification for DocBook XML DTD version 4.5 is available from <a href="http://www.docbook.org/specs/docbook-4.5-spec.html">http://www.docbook.org/specs/docbook-4.5-spec.html</a>.
</div><div class="important"><h2>A different DTD might slow your build</h2><div class="para">
@@ -170,9 +169,9 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>generate_section_toc_level</code></em></span></dt><dd><div class="para">
controls the section depth at which <span class="application"><strong>Publican</strong></span> will generate a table of contents. At the default value of <code class="literal">0</code>, <span class="application"><strong>Publican</strong></span> 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 <code class="literal">1</code>, 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 <code class="literal">2</code>, tables of contents also appear in "level 2" sections, such as sections 1.1.1, 1.1.2, and 1.2.1.
</div></dd><dt><span class="term"><em class="parameter"><code>ignored_translations</code></em></span></dt><dd><div class="para">
- specifies translations to ignore. If you build or package a book in a language specified by this parameter, <span class="application"><strong>Publican</strong></span> ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation" title="3.3. Preparing a document for translation">Section 3.3, “Preparing a document for translation”</a>.
+ specifies translations to ignore. If you build or package a book in a language specified by this parameter, <span class="application"><strong>Publican</strong></span> ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation" title="3.4. Preparing a document for translation">Section 3.4, “Preparing a document for translation”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>license</code></em></span></dt><dd><div class="para">
- specifies the license this package uses. By default, <span class="application"><strong>Publican</strong></span> selects the GNU Free Documentation License (GFDL). Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the license this package uses. By default, <span class="application"><strong>Publican</strong></span> selects the GNU Free Documentation License (GFDL). Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>max_image_width</code></em></span></dt><dd><div class="para">
specifies the maximum width allowable for images in the document in pixels. By default, <span class="application"><strong>Publican</strong></span> scales down any images wider than 444 pixels so that they fit within this limit. Keeping images no wider than 444 pixels ensures that they present no wider than the right-hand margin of the text in HTML output and that they fit within the pages of PDF output.
</div><div class="important"><h2>Important — 444 pixels is the maximum safe width</h2><div class="para">
@@ -182,7 +181,7 @@ brand: common
</div><div class="para">
To safeguard the quality of your images, crop or scale them so that they are no wider than 444 pixels before including them in a document.
</div></div></dd><dt><span class="term"><em class="parameter"><code>os_ver</code></em></span></dt><dd><div class="para">
- specifies the operating system for which to build packages. <span class="application"><strong>Publican</strong></span> appends the value that you provide here to the RPM packages that it builds. For example, the default value is <code class="literal">.el5</code>, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a> and <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a>.
+ specifies the operating system for which to build packages. <span class="application"><strong>Publican</strong></span> appends the value that you provide here to the RPM packages that it builds. For example, the default value is <code class="literal">.el5</code>, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a> and <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>prod_url</code></em></span></dt><dd><div class="para">
provides a URL for the product to which this document applies. In multi-page HTML output, <span class="application"><strong>Publican</strong></span> links to this URL at the top left of each page, through the <code class="filename">image_left.png</code> image in the <code class="filename">Common_Content/images</code> directory for the brand. This parameter defaults to <code class="literal">https://fedorahosted.org/publican</code>.
</div></dd><dt><span class="term"><em class="parameter"><code>product</code></em></span></dt><dd><div class="para">
@@ -198,9 +197,9 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>show_unknown</code></em></span></dt><dd><div class="para">
controls whether <span class="application"><strong>Publican</strong></span> reports unknown tags when processing XML. By default, this value is set to <code class="literal">1</code>, so <span class="application"><strong>Publican</strong></span> reports unknown tags. Set this value to <code class="literal">0</code> to hide this output. <span class="strikethrough strikethrough"><span class="application"><strong>Publican</strong></span> ignores this parameter in <em class="firstterm">strict mode</em>.</span>
</div></dd><dt><span class="term"><em class="parameter"><code>src_url</code></em></span></dt><dd><div class="para">
- specifies the URL at which to find tarballs of source files. This parameter provides the <code class="literal">Source:</code> field in the header of an RPM spec file. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the URL at which to find tarballs of source files. This parameter provides the <code class="literal">Source:</code> field in the header of an RPM spec file. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
</div></dd><dt><span class="term"><em class="parameter"><code>strict</code></em></span></dt><dd><div class="para">
- <span class="strikethrough strikethrough">sets <span class="application"><strong>Publican</strong></span> to use <em class="firstterm">strict mode</em>, which prevents the use of tags that are unusable for professional output and translation. By default, the <code class="literal">strict</code> parameter is set of <code class="literal">0</code>, which disables strict mode. To enable strict mode, set this parameter to <code class="literal">1</code></span> Strict mode is no longer enforced.
+ <span class="strikethrough strikethrough">sets <span class="application"><strong>Publican</strong></span> to use <em class="firstterm">strict mode</em>, which prevents the use of tags that are unusable for professional output and translation. By default, the <code class="literal">strict</code> parameter is set of <code class="literal">0</code>, which disables strict mode. To enable strict mode, set this parameter to <code class="literal">1</code></span> Strict mode is not currently enforced.
</div></dd><dt><span class="term"><em class="parameter"><code>tmp_dir</code></em></span></dt><dd><div class="para">
specifies the directory for <span class="application"><strong>Publican</strong></span> output. By default, this is set to <code class="literal">tmp</code>, which creates a directory named <code class="filename">tmp</code> inside the directory that holds your article or book.
</div></dd><dt><span class="term"><em class="parameter"><code>toc_section_depth</code></em></span></dt><dd><div class="para">
@@ -208,12 +207,24 @@ brand: common
</div></dd><dt><span class="term"><em class="parameter"><code>version</code></em></span></dt><dd><div class="para">
specifies the version number of that product to which this document applies. If set, this value overrides the content of the <code class="sgmltag-element"><productnumber></code> tag in the <code class="filename">Book_Info.xml</code> file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).
</div></dd><dt><span class="term"><em class="parameter"><code>web_brew_dist</code></em></span></dt><dd><div class="para">
- specifies the <span class="application"><strong>brew</strong></span> build target to use for building the web RPM packages. <span class="application"><strong>Brew</strong></span> is the internal build system used by Red Hat. By default, this value is set to <code class="literal">docs-5E</code>, representing documentation packages for Red Hat Enterprise Linux 5. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies the <span class="application"><strong>brew</strong></span> build target to use for building the web RPM packages. <span class="application"><strong>Brew</strong></span> is the internal build system used by Red Hat. By default, this value is set to <code class="literal">docs-5E</code>, representing documentation packages for Red Hat Enterprise Linux 5. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_home</code></em></span></dt><dd><div class="para">
+ specifies that the document is the home page of a documentation website, not a standard document. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_host</code></em></span></dt><dd><div class="para">
+ specifies the host name of a documentation website, used for the Sitemap and searches. Be sure to specify the protocol and the full path to the document tree, for example: <code class="literal">http://www.example.com/docs/</code>. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_name_label</code></em></span></dt><dd><div class="para">
+ overrides the book name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
</div></dd><dt><span class="term"><em class="parameter"><code>web_obsoletes</code></em></span></dt><dd><div class="para">
- specifies packages that the web RPM obsoletes. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a>.
+ specifies packages that the web RPM obsoletes. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_product_label</code></em></span></dt><dd><div class="para">
+ overrides the product name as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_search</code></em></span></dt><dd><div class="para">
+ overrides the default search form for a <span class="application"><strong>Publican</strong></span>-managed website. Defaults to a search on Google which is limited to a site search if <em class="parameter"><code>web_host</code></em> is set. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
+ </div></dd><dt><span class="term"><em class="parameter"><code>web_version_label</code></em></span></dt><dd><div class="para">
+ overrides the version number as it appears on the menu of a <span class="application"><strong>Publican</strong></span>-managed website. Set this value to <code class="literal">UNUSED</code> for general documentation that does not apply to any particular version of a product. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a>.
</div></dd></dl></div><div class="note"><h2>Help from the command line</h2><div class="para">
Run the <code class="command">publican help_config</code> command in the root directory of a book for a summary of these parameters.
- </div></div></div><div class="section" title="3.1.2. Book_Info.xml" id="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml"><div class="titlepage"><div><div><h3 class="title">3.1.2. Book_Info.xml</h3></div></div></div><div class="note"><h2><code class="filename">Article_Info.xml</code> and <code class="filename">Set_Info.xml</code></h2><div class="para">
+ </div></div></div><div class="section" title="3.1.2. Book_Info.xml" id="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</h3></div></div></div><div class="note"><h2><code class="filename">Article_Info.xml</code> and <code class="filename">Set_Info.xml</code></h2><div class="para">
This description of the <code class="filename">Book_Info.xml</code> file applies to <code class="filename">Article_Info.xml</code> and <code class="filename">Set_Info.xml</code> files too. However, for the sake of simplicity, the file is referred to as <code class="filename">Book_Info.xml</code> throughout this section.
</div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
This section discusses packaging documents for distribution through the <span class="application"><strong>RPM Package Manager</strong></span>. However, when you use the <code class="command">publican package</code> command, <span class="application"><strong>Publican</strong></span> generates a tarball that you can use to build a package to distribute through different package manager software. If you run <code class="command">publican package</code> on a computer on which <span class="application"><strong>rpmbuild</strong></span> is not installed, <span class="application"><strong>Publican</strong></span> still generates the tarball, even though it cannot then generate an RPM package from that tarball.
@@ -235,12 +246,12 @@ brand: common
<span class="perl_Keyword"><title></span>Users Guide<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><subtitle></span>Publishing books, articles, papers and multi-volume sets with DocBook XML<span class="perl_Keyword"></subtitle></span>
<span class="perl_Keyword"><productname></span>Publican<span class="perl_Keyword"></productname></span>
- <span class="perl_Keyword"><productnumber></span>1.6<span class="perl_Keyword"></productnumber></span>
- <span class="perl_Keyword"><edition></span>1.6<span class="perl_Keyword"></edition></span>
- <span class="perl_Keyword"><pubsnumber></span>1<span class="perl_Keyword"></pubsnumber></span>
+ <span class="perl_Keyword"><productnumber></span>2.0<span class="perl_Keyword"></productnumber></span>
+ <span class="perl_Keyword"><edition></span>1.0<span class="perl_Keyword"></edition></span>
+ <span class="perl_Keyword"><pubsnumber></span>3<span class="perl_Keyword"></pubsnumber></span>
<span class="perl_Keyword"><abstract></span>
<span class="perl_Keyword"><para></span>
- This book will help you install <span class="perl_Keyword"><application></span>Publican<span class="perl_Keyword"></application></span>. 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 <span class="perl_DecVal">&D_B;</span> XML.
+ This book will help you install <span class="perl_Keyword"><application></span>Publican<span class="perl_Keyword"></application></span>. 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.
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></abstract></span>
@@ -293,6 +304,7 @@ brand: common
<span class="perl_Keyword"></bookinfo></span>
+
</pre><div class="variablelist"><dl><dt><span class="term"><code class="sgmltag-element"><bookinfo id="<em class="replaceable"><code>book_id</code></em>"></code>, </span><span class="term"><code class="sgmltag-element"><articleinfo id="<em class="replaceable"><code>article_id</code></em>"></code>, </span><span class="term"><code class="sgmltag-element"><setinfo id="<em class="replaceable"><code>set_id</code></em>"></code></span></dt><dd><div class="para">
The document ID is used internally and is not displayed to readers when the book is built. If you run the <code class="command">publican clean_ids</code> command, any manually entered ID, including this one, changes to a <em class="replaceable"><code>Doc_Name-Title</code></em> format, where <em class="replaceable"><code>Title</code></em> is the title of the associated book, article, section, or chapter.
@@ -363,7 +375,7 @@ brand: common
</pre><div class="para">
As with all the other images in your document, place the cover images in the <code class="filename">images</code> subdirectory.
- </div></dd></dl></div><div class="section" title="3.1.2.1. RPM packages, editions, impressions and versions" id="sect-Users_Guide-Book_Info.xml-RPM_packages_editions_impressions_and_versions"><div class="titlepage"><div><div><h4 class="title">3.1.2.1. RPM packages, editions, impressions and versions</h4></div></div></div><div class="para">
+ </div></dd></dl></div><div class="section" title="3.1.2.1. RPM packages, editions, impressions and versions" id="sect-Users_Guide-Book_Info.xml-RPM_packages_editions_impressions_and_versions"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Book_Info.xml-RPM_packages_editions_impressions_and_versions">3.1.2.1. RPM packages, editions, impressions and versions</h4></div></div></div><div class="para">
As noted above, the default <code class="filename">Book_Info.xml</code> used by <span class="application"><strong>Publican</strong></span> includes an <em class="parameter"><code><edition></code></em> tag.
</div><div class="para">
If you distribute a book as an RPM package, the data placed within this tag sets 'the first two digits of the version number in the RPM file name.
@@ -385,7 +397,7 @@ brand: common
We recommend following bibliographic practice in this regard. When using <span class="application"><strong>Publican</strong></span> to re-publish a book from 'substantially the same XML', increment the <em class="parameter"><code><pubsnumber></code></em> tag, not the <em class="parameter"><code><edition></code></em> tag. It functions as a near-equivalent to the impression or printing number of traditional publishing.
</div><div class="para">
As for changing the edition number, we recommend changing this in the same circumstances traditional publishers change the edition of a work: when it is revised and re-written significantly. What constitutes significant, and how much re-writing is needed to increment an edition number by a whole number and how much is needed to increment it by one-tenth of a whole number, is a matter of editorial discretion.
- </div></div></div><div class="section" title="3.1.3. Author_Group.xml" id="sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml"><div class="titlepage"><div><div><h3 class="title">3.1.3. Author_Group.xml</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.1.3. Author_Group.xml" id="sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</h3></div></div></div><div class="para">
<code class="filename">Author_Group.xml</code> is not required but is the standard place to record author, editor, artist and other credit details. The following is an example <code class="filename">Author_Group.xml</code> file:
</div><pre class="programlisting"><span class="perl_Keyword"><?xml</span> version='1.0'<span class="perl_Keyword">?></span>
<span class="perl_DataType"><!DOCTYPE </span>authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" <span class="perl_DataType">[</span>
@@ -404,10 +416,11 @@ brand: common
<span class="perl_Keyword"></author></span>
<span class="perl_Keyword"></authorgroup></span>
+
</pre><div class="para">
<code class="filename">Author_Group.xml</code> does not have to contain all of the above information: include as much or as little as required.
- </div></div><div class="section" title="3.1.4. Chapter.xml" id="sect-Users_Guide-Files_in_the_book_directory-Chapter.xml"><div class="titlepage"><div><div><h3 class="title">3.1.4. Chapter.xml</h3></div></div></div><div class="important"><h2>Articles and chapters</h2><div class="para">
+ </div></div><div class="section" title="3.1.4. Chapter.xml" id="sect-Users_Guide-Files_in_the_book_directory-Chapter.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</h3></div></div></div><div class="important"><h2>Articles and chapters</h2><div class="para">
DocBook articles cannot contain chapters. If you use the <code class="option">--type=article</code> option with <code class="command">publican create</code>, <span class="application"><strong>Publican</strong></span> does not create a <code class="filename">Chapter.xml</code> file. Use sections to organize content within articles.
</div><div class="para">
Refer to <em class="citetitle">DocBook: The Definitive Guide</em> by Norman Walsh and Leonard Muellner available at <a href="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</a> for details of the different ways that sets, books, articles, parts, chapters, and sections interact. In particular, note that articles can be stand-alone documents, or can be incorporated into books.
@@ -439,12 +452,13 @@ brand: common
<span class="perl_Keyword"></chapter></span>
+
</pre><div class="para">
This chapter has two sections, <code class="filename">Section 1 Test</code> and <code class="filename">Section 2 Test</code>. Refer to <a href="http://docbook.org/tdg/en/html/chapter.html">http://docbook.org/tdg/en/html/chapter.html</a> for further information about chapters.
</div><div class="note"><h2>Note</h2><div class="para">
The chapter file should be renamed to reflect the chapter subject. For example, a chapter on product installation could be named <code class="filename">Installation.xml</code>, whereas a chapter on setting up a piece of software would be better called <code class="filename">Setup.xml</code> or <code class="filename">Configuration.xml</code>.
- </div></div></div><div class="section" title="3.1.5. Doc_Name.xml" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml"><div class="titlepage"><div><div><h3 class="title">3.1.5. Doc_Name.xml</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.1.5. Doc_Name.xml" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</h3></div></div></div><div class="para">
The <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.xml</code> file contains <code class="literal">xi:include</code> 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 <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.xml</code> file brings together chapters that are contained in separate XML files.
</div><div class="para">
The following is an example <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.xml</code> file that describes a DocBook book — note the <em class="parameter"><code>DOCTYPE</code></em> is set to <code class="literal">book</code>.
@@ -461,6 +475,7 @@ brand: common
<span class="perl_Keyword"></book></span>
+
</pre><div class="para">
This example loads the <code class="filename">Book_Info.xml</code>, <code class="filename">Preface.xml</code>, <code class="filename">Chapter.xml</code>, and <code class="filename">Appendix.xml</code> XML files.
@@ -500,7 +515,7 @@ brand: common
</pre><div class="para">
This book contains two chapters. Chapter one contains two sections. Refer to <a href="http://docbook.org/tdg/en/html/section.html">http://docbook.org/tdg/en/html/section.html</a> for further information about sections, and <a href="http://docbook.org/tdg/en/html/book.html">http://docbook.org/tdg/en/html/book.html</a> for further information about books.
- </div></div><div class="section" title="3.1.6. Doc_Name.ent" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent"><div class="titlepage"><div><div><h3 class="title">3.1.6. Doc_Name.ent</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="3.1.6. Doc_Name.ent" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</h3></div></div></div><div class="para">
The <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> file is used to define local entities. The <em class="parameter"><code>YEAR</code></em> and <em class="parameter"><code>HOLDER</code></em> entities are used for copyright information. By default, <span class="application"><strong>Publican</strong></span> sets <em class="parameter"><code>YEAR</code></em> to the current year, and inserts a message into <em class="parameter"><code>HOLDER</code></em> to remind you to specify the copyright holder for the document. If the <em class="parameter"><code>YEAR</code></em> and <em class="parameter"><code>HOLDER</code></em> entities are missing altogether, the document will not build.
</div><div class="para">
Other entities might be required by the <em class="firstterm">brand</em> applied to your document. For example, the <span class="application"><strong>Publican</strong></span> brand for Fedora documents uses the entity <code class="computeroutput">BOOKID</code> to specify how readers should refer to a document when they submit feedback about it.
@@ -510,8 +525,9 @@ brand: common
<!ENTITY HOLDER "YOUR NAME GOES HERE">
+
-</pre><div xml:lang="en-US" class="section" title="3.1.6.1. Entities and translation" id="sect-Users_Guide-Entities_and_translation" lang="en-US"><div class="titlepage"><div><div><h4 class="title">3.1.6.1. Entities and translation</h4></div></div></div><div class="warning"><h2>Use entities with extreme caution</h2><div class="para">
+</pre><div xml:lang="en-US" class="section" title="3.1.6.1. Entities and translation" id="sect-Users_Guide-Entities_and_translation" lang="en-US"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Entities_and_translation">3.1.6.1. Entities and translation</h4></div></div></div><div class="warning"><h2>Use entities with extreme caution</h2><div class="para">
Entities offer convenience but they should be used with extreme caution in documents that will be translated. Writing (for example) <code class="sgmltag-element">&FDS;</code> instead of <span class="application"><strong>Fedora Directory Server</strong></span> saves the writer time but transformed entities do not appear in the <em class="firstterm">portable object</em> (PO) files that translators use. Complete translations of documents containing entities are, as a consequence, impossible.
</div></div><div class="para">
Entities present special obstacles to translators and can preclude the production of high-quality translations. The very nature of an entity is that the word or phrase represented by the entity is rendered exactly the same way every time that it occurs in the document, in every language. This inflexibility means that the word or word group represented by the entity might be illegible or incomprehensible in the target language and that the word or word group represented by the entity cannot change when the grammatical rules of the target language require them to change. Furthermore, because entities are not transformed when XML is converted to PO, translators cannot select the correct words that surround the entity, as required by the grammatical rules of the target language.
@@ -585,7 +601,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Finally, consider that although a particular word never changes its form in English, this is not necessarily true of other languages, even when the word is a <em class="firstterm">proper noun</em> such as the name of a product. In many languages, nouns change (<em class="firstterm">inflect</em>) their form according to their role in a sentence (their grammatical <em class="firstterm">case</em>). An XML entity set to represent an English noun or noun phrase therefore makes correct translation impossible in such languages.
</div><div class="para">
For example, if you write a document that could apply to more than one product, you might be tempted to set an entity such as <code class="sgmltag-element">&PRODUCT;</code>. The advantage of this approach is that by simply changing this value in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> file, you could easily adjust the book to document (for example) Red Hat Enterprise Linux, Fedora, or CentOS. However, while the proper noun <em class="firstterm">Fedora</em> never varies in English, it has six different forms in Czech, depending on one of seven ways that you can use it in a sentence:
- </div><div class="table"><div class="table-contents"><table summary="'Fedora' in Czech" border="1"><colgroup><col align="left" width="33%" /><col align="left" width="33%" /><col align="left" width="33%" /></colgroup><thead><tr><th align="left">
+ </div><div class="table" title="Table 3.1. 'Fedora' in Czech" id="tabl-Users_Guide-Entities_and_translation-Fedora_in_Czech"><div class="table-contents"><table summary="'Fedora' in Czech" border="1"><colgroup><col align="left" width="33%" /><col align="left" width="33%" /><col align="left" width="33%" /></colgroup><thead><tr><th align="left">
Case
</th><th align="left">
Usage
@@ -655,9 +671,9 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Nouns in most Slavic languages like Russian, Ukrainian, Czech, Polish, Serbian, and Croatian have seven different cases. Nouns in Finno–Ugaric languages such as Finnish, Hungarian, and Estonian have between fifteen and seventeen cases. Other languages alter nouns for other reasons. For example, Scandinavian languages inflect nouns to indicate <em class="firstterm">definiteness</em> — whether the noun refers to '<span class="emphasis"><em>a</em></span> thing' or '<span class="emphasis"><em>the</em></span> thing' — and some dialects of those languages inflect nouns both for definiteness <span class="emphasis"><em>and</em></span> for grammatical case.
</div><div class="para">
Now multiply such problems by the more than 40 languages that <span class="application"><strong>Publican</strong></span> currently supports. Other than the few non-translated strings that <span class="application"><strong>Publican</strong></span> specifies by default in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> 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.
- </div></div></div><div class="section" title="3.1.7. Revision_History.xml" id="sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml"><div class="titlepage"><div><div><h3 class="title">3.1.7. Revision_History.xml</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.1.7. Revision_History.xml" id="sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</h3></div></div></div><div class="para">
The <code class="command">publican package</code> command searches for the first XML file in the document's XML directory containing a <code class="literal"><revhistory></code> tag. <span class="application"><strong>Publican</strong></span> then uses that file to build the RPM revision history.
- </div></div></div><div xml:lang="en-US" class="section" title="3.2. Adding images" id="sect-Users_Guide-Adding_images" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.2. Adding images</h2></div></div></div><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.2. Adding images" id="sect-Users_Guide-Adding_images" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Adding_images">3.2. Adding images</h2></div></div></div><div class="para">
Store images in the <code class="filename">images</code> subdirectory in the directory that holds your XML files. Use <code class="computeroutput">./images/<em class="replaceable"><code>image-name</code></em></code> to insert images into a book. The following is an example that inserts the <code class="filename">testimage.png</code> image:
</div><pre class="programlisting"><span class="perl_Keyword"><mediaobject></span>
<span class="perl_Keyword"><imageobject></span>
@@ -667,7 +683,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
<span class="perl_Keyword"></mediaobject></span>
</pre><div class="para">
- Ensure that you supply a <code class="sgmltag-element"><textobject></code> 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 <em class="citetitle">Rehabilitation Act of 1973</em>.<sup>[<a id="id734623" href="#ftn.id734623" class="footnote">1</a>]</sup>
+ Ensure that you supply a <code class="sgmltag-element"><textobject></code> 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 <em class="citetitle">Rehabilitation Act of 1973</em>.<sup>[<a id="id756284" href="#ftn.id756284" class="footnote">1</a>]</sup>
</div><div class="para">
If your book contains images that need to be localized — for example, screenshots of a user interface in a language other than the original language of your book — place these images in the <code class="filename">images</code> 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, <span class="application"><strong>Publican</strong></span> uses the file from the <code class="filename">images</code> subdirectory of the translated language instead of the file from the <code class="filename">images</code> subdirectory of the original language.
</div><div class="para">
@@ -678,16 +694,19 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
<span class="application"><strong>Publican</strong></span> depends on an external application, <span class="application"><strong>FOP</strong></span>, to render documents as PDF files. At present, some versions of <span class="application"><strong>FOP</strong></span> contain a bug that alters the colors in certain images in PNG format. Specifically, 32-bit PNG images are rendered correctly, while 24-bit PNG images are not.
</div><div class="para">
If you notice that <span class="application"><strong>Publican</strong></span> produces a PDF file that contains images with incorrect colors, convert the original PNG files to 32-bit PNG format by adding an <em class="firstterm">alpha channel</em> to the image and rebuild the book. If your chosen image manipulation software does not include an option specifically labeled <code class="literal">Add alpha channel</code>, the option might be labeled <code class="literal">Add transparency</code> instead.
- </div></div></div><div xml:lang="en-US" class="section" title="3.3. Preparing a document for translation" id="sect-Users_Guide-Preparing_a_document_for_translation" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.3. Preparing a document for translation</h2></div></div></div><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.3. Adding files" id="sect-Users_Guide-Adding_files" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Adding_files">3.3. Adding files</h2></div></div></div><div class="para">
+ <span class="application"><strong>Publican</strong></span> allows you to include arbitrary files together with your documents. These files are included in RPM packages that you build with <span class="application"><strong>Publican</strong></span> and are installed on users' systems alongside the document itself. For example, you might want to include multimedia files of tutorials that complement the document, or sample files of source code or other materials that allow users to work through the examples or tutorials in a document.
+ </div><div class="para">
+ To ship arbitrary files with a document, include them in a directory named <code class="filename">files</code> and include it in the language directory for the original language of the book, for example, <code class="filename">en-US/files/</code>.
+ </div></div><div xml:lang="en-US" class="section" title="3.4. Preparing a document for translation" id="sect-Users_Guide-Preparing_a_document_for_translation" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Preparing_a_document_for_translation">3.4. Preparing a document for translation</h2></div></div></div><div class="para">
Support for localization of documents was a key consideration in the design of <span class="application"><strong>Publican</strong></span>. The general translation workflow for documents developed in <span class="application"><strong>Publican</strong></span> is as follows:
- </div><div class="procedure"><ol class="1"><li class="step" title="Step 1" id="step1"><div class="para">
+ </div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Complete the XML of a document.
</div><div class="para">
The XML for this version of the document should now be considered ‘frozen’. If your document is stored in a version-controlled repository, you should now move this version into a separate directory or branch. This allows writers to begin work on subsequent versions of the document in one branch, while providing a stable base for translation in another branch.
</div></li><li class="step" title="Step 2"><div class="para">
Generate <em class="firstterm">portable object template</em> (POT) files from the XML files:
- </div><pre class="screen">$ <code class="command">publican update_pot</code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_pot</code></pre><div class="para">
If this is the first time that POT files have been created for this document, <span class="application"><strong>Publican</strong></span> creates a new subdirectory, named <code class="filename">pot</code>. The <code class="filename">pot</code> subdirectory holds a POT file for each XML file in the document. If <span class="application"><strong>Publican</strong></span> has created POT files for this document previously, <span class="application"><strong>Publican</strong></span> updates the existing POT files to reflect any changes in the XML since the POT files were last updated.
</div><div class="important"><h2>Remove unused XML files</h2><div class="para">
<span class="application"><strong>Publican</strong></span> generates a POT file for every XML file in the XML directory, whether the XML file is used in the document or not. If you transform unused XML files into POT files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
@@ -695,14 +714,11 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Use the <code class="command">publican print_unused</code> command to generate a list of XML files that are not used in your document.
</div></div></li><li class="step" title="Step 3"><div class="para">
Generate <em class="firstterm">portable object</em> (PO) files from the POT files to begin translation into a particular language:
- </div><pre class="screen">$ <code class="command">publican update_po --langs=<em class="replaceable"><code>language_code</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_po --langs=<em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
where <em class="replaceable"><code>language_code</code></em> is the code for the target language. Refer to <a class="xref" href="appe-Users_Guide-Language_codes.html" title="Appendix D. Language codes">Appendix D, <i>Language codes</i></a> for more information about language codes. You can provide multiple language codes, separated by commas, to generate PO files for more than one language at a time. For example:
- </div><pre class="screen">$ <code class="command">publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN</code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN</code></pre><div class="para">
If this is the first time that PO files have been created for a particular language, <span class="application"><strong>Publican</strong></span> creates a new subdirectory, named with the language code that you specified with the <code class="option">--langs=</code> option. This subdirectory holds a PO file for each POT file in <code class="filename">pot</code> subdirectory. If <span class="application"><strong>Publican</strong></span> has created PO files for this language previously, <span class="application"><strong>Publican</strong></span> 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 <code class="option">--langs=all</code> option:
- </div><pre class="screen">$ <code class="command">publican update_po --langs=all</code>
-</pre><div class="important"><h2>Remove unused POT files</h2><div class="para">
+ </div><pre class="screen">$ <code class="command">publican update_po --langs=all</code></pre><div class="important"><h2>Remove unused POT files</h2><div class="para">
<span class="application"><strong>Publican</strong></span> generates a PO file for every POT file in the <code class="filename">pot</code> 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.
</div><div class="para">
When you generate PO files, <span class="application"><strong>Publican</strong></span> presents you with a warning for any POT files that do not have corresponding XML files, but will generate the PO file nevertheless. However, <span class="application"><strong>Publican</strong></span> will not warn you if a POT file exists for an XML file that is not used in the document.
@@ -710,31 +726,25 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Translators translate the <em class="firstterm">strings</em> contained in the PO files.
</div></li><li class="step" title="Step 5"><div class="para">
Build the document in the target language, for example:
- </div><pre class="screen">$ <code class="command">publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO</code>
-</pre><div class="para">
+ </div><pre class="screen">$ <code class="command">publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO</code></pre><div class="para">
or package it in the target language, for example:
- </div><pre class="screen">$ <code class="command">publican package --lang=is-IS</code>
-</pre><div class="para">
- You can build the document in all languages for which you have translations with the <code class="option">--langs=all</code> option, but note that you must package each language individually. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document" title="3.4. Building a document">Section 3.4, “Building a document”</a> for more information on building a document, and <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a> on packaging a document.
- </div></li></ol></div></div><div xml:lang="en-US" class="section" title="3.4. Building a document" id="sect-Users_Guide-Building_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.4. Building a document</h2></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
+ </div><pre class="screen">$ <code class="command">publican package --lang=is-IS</code></pre><div class="para">
+ You can build the document in all languages for which you have translations with the <code class="option">--langs=all</code> option, but note that you must package each language individually. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document" title="3.5. Building a document">Section 3.5, “Building a document”</a> for more information on building a document, and <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a> on packaging a document.
+ </div></li></ol></div></div><div xml:lang="en-US" class="section" title="3.5. Building a document" id="sect-Users_Guide-Building_a_document" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Building_a_document">3.5. Building a document</h2></div></div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
The parameters set in the document configuration file (by default, <code class="filename">publican.cfg</code>) allow you to control many aspects of the way in which a document is presented — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a>.
</div><div class="para">
If you maintain multiple versions of a document, you can create a configuration file for each version. When building the document, you can use the <code class="option">--config</code> to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
- </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code>
-</pre></div><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</code></pre></div><div class="para">
To build a document:
</div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Confirm the <em class="parameter"><code>YEAR</code></em> and <em class="parameter"><code>HOLDER</code></em> entities have been configured in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>.ent</code> file, as described in <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent" title="3.1.6. Doc_Name.ent">Section 3.1.6, “Doc_Name.ent”</a>.
</div></li><li class="step" title="Step 2"><div class="para">
Change into the root directory of the document. For example, if the document was named <code class="literal">Test_Book</code> and was located in the <code class="filename">books/</code> directory, run the following command:
- </div><pre class="screen"><code class="command">cd books/Test_Book</code>
-</pre></li><li class="step" title="Step 3"><div class="para">
+ </div><pre class="screen"><code class="command">cd books/Test_Book</code></pre></li><li class="step" title="Step 3"><div class="para">
Run a test for any errors that would stop the book from building in your chosen language, for example:
- </div><pre class="screen"><code class="command">publican build --formats=test --langs=en-US</code>
-</pre></li><li class="step" title="Step 4"><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats=test --langs=en-US</code></pre></li><li class="step" title="Step 4"><div class="para">
Run the following command to build the book:
- </div><pre class="screen"><code class="command">publican build --formats=<em class="replaceable"><code>formats</code></em> --langs=<em class="replaceable"><code>languages</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command">publican build --formats=<em class="replaceable"><code>formats</code></em> --langs=<em class="replaceable"><code>languages</code></em></code></pre><div class="para">
Replace <em class="replaceable"><code>formats</code></em> with a comma-separated list of the formats that you want to build, for example, <code class="literal">--formats=html,html-single,pdf</code>. Replace <em class="replaceable"><code>langs</code></em> with a comma-separated list of the languages that you want to build, for example, <code class="literal">--langs=en-US,sv-SE,uk-UA,ko-KR</code>.
</div></li></ol></div><div class="variablelist" title="Formats for the build action" id="vari-Users_Guide-Building_a_document-Formats_for_the_build_action"><h6>Formats for the <code class="command">build</code> action</h6><dl><dt><span class="term"><code class="option">html</code></span></dt><dd><div class="para">
<span class="application"><strong>Publican</strong></span> outputs the document as in multiple HTML pages, with each chapter and major section on a separate page. <span class="application"><strong>Publican</strong></span> places an index at the start of the document, and places navigational elements on each page.
@@ -768,7 +778,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Build the book as a PDF file. <span class="application"><strong>Publican</strong></span> relies on an external application, <span class="application"><strong>FOP</strong></span> to render PDF. Therefore, building PDF might not be available on all systems, depending on the availability of <span class="application"><strong>FOP</strong></span>. The output will be a single PDF file located in the <code class="filename"><em class="replaceable"><code>Doc_Name</code></em>/tmp/<em class="replaceable"><code>language</code></em>/pdf/</code> directory.
</div></dd><dt><span class="term"><code class="command">publican build --formats=html,html-single,pdf --langs=<em class="replaceable"><code>languages</code></em></code></span></dt><dd><div class="para">
Build the book in multi-page HTML, single-page HTML, and PDF formats.
- </div></dd></dl></div><div class="section" title="3.4.1. Building a document created with Publican 0" id="sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0"><div class="titlepage"><div><div><h3 class="title">3.4.1. Building a document created with Publican 0</h3></div></div></div><div class="para">
+ </div></dd></dl></div><div class="section" title="3.5.1. Building a document created with Publican 0" id="sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.5.1. Building a document created with Publican 0</h3></div></div></div><div class="para">
Documents produced with early versions of <span class="application"><strong>Publican</strong></span> (versions up to and including 0.45) did not have a <code class="filename">publican.cfg</code> file; a similar set of parameters was defined in a <code class="filename">Makefile</code>. Before you build such a document in a current version of <span class="application"><strong>Publican</strong></span> (version 0.99 onwards), you must convert the <code class="filename">Makefile</code> into a <code class="filename">publican.cfg</code> file. <span class="application"><strong>Publican</strong></span> can do this conversion automatically:
</div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Change into the document directory, the one that holds the <code class="filename">Makefile</code>.
@@ -776,28 +786,27 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
Run <code class="command">publican old2new</code>. <span class="application"><strong>Publican</strong></span> parses the <code class="filename">Makefile</code> and creates a <code class="filename">publican.cfg</code> file with equivalent parameters wherever available.
</div></li></ol></div><div class="para">
When you run <code class="command">publican old2new</code>, <span class="application"><strong>Publican</strong></span> does not alter or delete the original <code class="filename">Makefile</code>. A <code class="filename">Makefile</code> and a <code class="filename">publican.cfg</code> file can coexist in the same document.
- </div></div></div><div xml:lang="en-US" class="section" title="3.5. Packaging a book" id="sect-Users_Guide-Packaging_a_book" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.5. Packaging a book</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.6. Packaging a book" id="sect-Users_Guide-Packaging_a_book" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Packaging_a_book">3.6. Packaging a book</h2></div></div></div><div class="important"><h2>Packages other than RPM packages</h2><div class="para">
This section discusses packaging documents for distribution through the <span class="application"><strong>RPM Package Manager</strong></span>. However, when you use the <code class="command">publican package</code> command, <span class="application"><strong>Publican</strong></span> generates a tarball that you can use to build a package to distribute through different package manager software. If you run <code class="command">publican package</code> on a computer on which <span class="application"><strong>rpmbuild</strong></span> is not installed, <span class="application"><strong>Publican</strong></span> still generates the tarball, even though it cannot then generate an RPM package from that tarball.
</div></div><div class="note"><h2>Note — Customizing output</h2><div class="para">
The parameters set in the document configuration file (by default, <code class="filename">publican.cfg</code>) allow you to control many aspects of the way in which a document is presented and packaged — refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a>.
</div><div class="para">
If you maintain multiple versions of a document, you can create a configuration file for each version. When packaging the document, you can use the <code class="option">--config</code> to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
- </div><pre class="screen"><code class="command">publican package --lang hi-IN --config community.cfg</code>
-</pre></div><div class="para">
+ </div><pre class="screen"><code class="command">publican package --lang hi-IN --config community.cfg</code></pre></div><div class="para">
<span class="application"><strong>Publican</strong></span> not only builds documentation as HTML and PDF files, but it can package these files for distribution to individual workstations and to web servers as <em class="firstterm">RPM packages</em>. RPM packages are used to distribute software to computers with Linux operating systems that use the <span class="application"><strong>RPM Package Manager</strong></span>. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
- </div><div class="section" title="3.5.1. Types of RPM packages" id="sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages"><div class="titlepage"><div><div><h3 class="title">3.5.1. Types of RPM packages</h3></div></div></div><div class="para">
+ </div><div class="section" title="3.6.1. Types of RPM packages" id="sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.6.1. Types of RPM packages</h3></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> can produce both <em class="firstterm">source RPM packages</em> (<em class="firstterm">SRPM packages</em>) and <em class="firstterm">binary RPM packages</em>. Furthermore, both SRPM packages and binary RPM packages can be configured to deploy to workstations or web servers.
- </div><div class="section" title="3.5.1.1. Source RPM packages and binary RPM packages" id="sect-Users_Guide-Types_of_RPM_packages-Source_RPM_packages_and_binary_RPM_packages"><div class="titlepage"><div><div><h4 class="title">3.5.1.1. Source RPM packages and binary RPM packages</h4></div></div></div><div class="para">
+ </div><div class="section" title="3.6.1.1. Source RPM packages and binary RPM packages" id="sect-Users_Guide-Types_of_RPM_packages-Source_RPM_packages_and_binary_RPM_packages"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Types_of_RPM_packages-Source_RPM_packages_and_binary_RPM_packages">3.6.1.1. Source RPM packages and binary RPM packages</h4></div></div></div><div class="para">
An SRPM package contains the source code used to generate software rather than the software itself. To use an SRPM package, a computer must <em class="firstterm">compile</em> the source code into software — or in this case, into documents. SRPM packages of <span class="application"><strong>Publican</strong></span> documents contain XML files rather than finished documents. To install documentation from the SRPM package to a computer, the computer must have <span class="application"><strong>Publican</strong></span> installed on it. When you try to install the SRPM package on a computer that does not have <span class="application"><strong>Publican</strong></span> installed, the <span class="application"><strong>RPM Package Manager</strong></span> looks for <span class="application"><strong>Publican</strong></span> in the software repositories that are available to it. The <span class="application"><strong>RPM Package Manager</strong></span> installs <span class="applicat
ion"><strong>Publican</strong></span> first, so that it can build and install the document contained in the SRPM package. If the <span class="application"><strong>RPM Package Manager</strong></span> cannot find and install <span class="application"><strong>Publican</strong></span>, installation of the SRPM package will fail.
</div><div class="para">
Conversely, binary RPM packages contain software — or in this case, a document — that is ready to copy to a location in the computer's file system and use immediately. The contents of the binary RPM package do not need to be compiled by the computer onto which they are installed, and therefore, the computer does not need to have <span class="application"><strong>Publican</strong></span> installed.
- </div></div><div class="section" title="3.5.1.2. Desktop packages and web packages" id="sect-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages"><div class="titlepage"><div><div><h4 class="title">3.5.1.2. Desktop packages and web packages</h4></div></div></div><div class="para">
+ </div></div><div class="section" title="3.6.1.2. Desktop packages and web packages" id="sect-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages">3.6.1.2. Desktop packages and web packages</h4></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> can package documents for reading on a computer workstation (a <em class="firstterm">desktop RPM package</em>) or to install on a web server and publish on the world-wide web (a <em class="firstterm">web RPM package</em>). The desktop RPM package of a <span class="application"><strong>Publican</strong></span> document and the web RPM package of the same document differ in that the desktop RPM package installs documentation only for local use on a computer, while the web RPM installs documentation for local use, but also to be served to the World Wide Web.
</div><div class="para">
- Desktop RPM packages of <span class="application"><strong>Publican</strong></span> documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of <code class="filename">/usr/share/doc/</code>, the location specified by the <em class="citetitle">Filesystem Hierarchy Standard</em> (<em class="citetitle">FHS</em>) for ‘Miscellaneous documentation’.<sup>[<a id="id573564" href="#ftn.id573564" class="footnote">2</a>]</sup> The desktop RPM package also contains a <em class="firstterm">desktop file</em>, to be placed in <code class="filename">/usr/share/applications/</code>. This file enables <em class="firstterm">desktop environments</em> such as GNOME and KDE to add the installed document to their menus for ease of reference by users.
+ Desktop RPM packages of <span class="application"><strong>Publican</strong></span> documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of <code class="filename">/usr/share/doc/</code>, the location specified by the <em class="citetitle">Filesystem Hierarchy Standard</em> (<em class="citetitle">FHS</em>) for ‘Miscellaneous documentation’.<sup>[<a id="id580077" href="#ftn.id580077" class="footnote">2</a>]</sup> The desktop RPM package also contains a <em class="firstterm">desktop file</em>, to be placed in <code class="filename">/usr/share/applications/</code>. This file enables <em class="firstterm">desktop environments</em> such as GNOME and KDE to add the installed document to their menus for ease of reference by users.
</div><div class="para">
Web RPM packages of <span class="application"><strong>Publican</strong></span> documents contain the documentation in single-page HTML, multi-page HTML, and PDF formats. They are installed in a subdirectory of <code class="filename">/var/www/html/</code>, a common <em class="firstterm">document root</em> for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.
- </div></div></div><div class="section" title="3.5.2. The publican package command" id="sect-Users_Guide-Packaging_a_book-The_publican_package_command"><div class="titlepage"><div><div><h3 class="title">3.5.2. The <code class="command">publican package</code> command</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.6.2. The publican package command" id="sect-Users_Guide-Packaging_a_book-The_publican_package_command"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.6.2. The <code class="command">publican package</code> command</h3></div></div></div><div class="para">
Use the <code class="command">publican package --lang=<em class="replaceable"><code>Language_Code</code></em></code> command to package documents for distribution in the language that you specify with the <code class="option">--lang</code> option. Refer to <a class="xref" href="appe-Users_Guide-Language_codes.html" title="Appendix D. Language codes">Appendix D, <i>Language codes</i></a> for more information about language codes.
</div><div class="para">
If you run <code class="command">publican package</code> with no options other than the mandatory <code class="option">--lang</code> option, <span class="application"><strong>Publican</strong></span> produces a web SRPM package. The full range of options for <code class="command">publican package</code> is as follows:
@@ -837,7 +846,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
use of the <code class="option">--short_sighted</code> option removes the <code class="literal">-<em class="replaceable"><code>productnumber</code></em>-</code> from the package name.
</div></li></ul></div>
- </div><div class="section" title="3.5.2.1. The publican package command — Example usage" id="sect-Users_Guide-The_publican_package_command-The_publican_package_command_Example_usage"><div class="titlepage"><div><div><h4 class="title">3.5.2.1. The <code class="command">publican package</code> command — Example usage</h4></div></div></div><div class="para">
+ </div><div class="section" title="3.6.2.1. The publican package command — Example usage" id="sect-Users_Guide-The_publican_package_command-The_publican_package_command_Example_usage"><div class="titlepage"><div><div><h4 class="title" id="sect-Users_Guide-The_publican_package_command-The_publican_package_command_Example_usage">3.6.2.1. The <code class="command">publican package</code> command — Example usage</h4></div></div></div><div class="para">
The following examples illustrate some common options, illustrated with the <em class="citetitle">Foomaster 9 Configuration Guide</em>, edition 2, revision 6.
</div><div class="variablelist"><dl><dt><span class="term"><code class="command">publican package --lang=cs-CZ</code></span></dt><dd><div class="para">
produces a web SRPM package named <span class="package">Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.src.rpm</span> that contains documentation in Czech.
@@ -849,7 +858,7 @@ msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle&g
produces a desktop binary RPM package named <span class="package">Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm</span> that contains documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
</div></dd><dt><span class="term"><code class="command">publican package --desktop --short_sighted --lang=cs-CZ</code></span></dt><dd><div class="para">
produces a desktop SRPM package named <span class="package">Foomaster-Configuration_Guide-cs-CZ-2-6.src.rpm</span> that contains documentation in Czech. This package will replace any Configuration Guides for previous versions of <span class="application"><strong>Foomaster</strong></span> that exists on a system. Users cannot have access to both the <em class="citetitle">Foomaster 8 Configuration Guide</em> and the <em class="citetitle">Foomaster 9 Configuration Guide</em>.
- </div></dd></dl></div></div></div></div><div xml:lang="en-US" class="section" title="3.6. Conditional tagging" id="sect-Users_Guide-Conditional_tagging" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.6. Conditional tagging</h2></div></div></div><div class="para">
+ </div></dd></dl></div></div></div></div><div xml:lang="en-US" class="section" title="3.7. Conditional tagging" id="sect-Users_Guide-Conditional_tagging" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Conditional_tagging">3.7. Conditional tagging</h2></div></div></div><div class="para">
In some cases you may need to maintain multiple versions of a book; for example, a HOWTO guide for product FOO can have an upstream version and an enterprise version, with very subtle differences between them.
</div><div class="para">
<span class="application"><strong>Publican</strong></span> makes it easy to manage differences between multiple versions of a book by allowing you to use a single source for all versions. <em class="firstterm">Conditional tagging</em> allows you to make sure that version-specific content only appears in the correct version; that is, you <em class="firstterm">conditionalize</em> the content.
@@ -898,12 +907,12 @@ publican build --formats=pdf --langs=en-US
To exclude this chapter, add a condition to the <code class="sgmltag-element"><xi:include></code> tag in <code class="filename">User_Guide.xml</code>, not to the <code class="sgmltag-element"><chapter></code> tag in <code class="filename">Installation_and_configuration_on_Fedora.xml</code>.
</div></div><div class="important"><h2>xrefs and conditional tagging</h2><div class="para">
If an <code class="sgmltag-element"><xref></code> points to content not included in the build due to conditional tagging, the build will fail. For example, with <code class="command">condition: upstream</code> set in the <code class="filename">publican.cfg</code> file, <code class="command">publican build --formats=pdf --langs=en-US</code> will fail if the book has the tag <code class="sgmltag-element"><xref linkend="betasection"></code> pointing to <code class="sgmltag-element"><section id="betasection" condition="beta"></code>.
- </div></div><div class="section" title="3.6.1. Conditional tagging and translation" id="sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation"><div class="titlepage"><div><div><h3 class="title">3.6.1. Conditional tagging and translation</h3></div></div></div><div class="warning"><h2>Use conditional tagging with great caution</h2><div class="para">
+ </div></div><div class="section" title="3.7.1. Conditional tagging and translation" id="sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.7.1. Conditional tagging and translation</h3></div></div></div><div class="warning"><h2>Use conditional tagging with great caution</h2><div class="para">
Use conditional tagging only with great caution in books that you expect to be translated, as conditional tagging creates extra difficulties for translators.
</div></div><div class="para">
Conditional tagging creates difficulty for translators in two ways: it obscures context in the <em class="firstterm">portable object</em> (PO) files through which translators work, and it makes proofreading more difficult for translators who are not deeply familiar with your book and all the conditions that you have set.
</div><div class="para">
- PO files do not include attributes from tags. When translators open the PO file for the example from <em class="citetitle">How To Use Product Foo</em> in <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging" title="3.6. Conditional tagging">Section 3.6, “Conditional tagging”</a>, they see:
+ PO files do not include attributes from tags. When translators open the PO file for the example from <em class="citetitle">How To Use Product Foo</em> in <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging" title="3.7. Conditional tagging">Section 3.7, “Conditional tagging”</a>, they see:
</div><pre class="programlisting">
#. Tag: para
#, no-c-format
@@ -931,13 +940,13 @@ msgstr ""
Furthermore, unless the translators who work on your book know how to configure <span class="application"><strong>Publican</strong></span>'s <code class="filename">publican.cfg</code> 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.
</div><div class="para">
As an alternative to conditionals, consider maintaining separate versions of your book in separate branches of a version-controlled repository. You can still share XML files and even PO files between the various branches as necessary, and some version control systems allow you to share changes readily among branches.
- </div></div></div><div xml:lang="en-US" class="section" title="3.7. Pre-release software and draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation" lang="en-US"><div class="titlepage"><div><div><h2 class="title">3.7. Pre-release software and draft documentation</h2></div></div></div><div class="para">
+ </div></div></div><div xml:lang="en-US" class="section" title="3.8. Pre-release software and draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation">3.8. Pre-release software and draft documentation</h2></div></div></div><div class="para">
Completed documentation for pre-release software is not the same thing as draft documentation.
</div><div class="para">
Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.
</div><div class="para">
In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.
- </div><div class="section" title="3.7.1. Denoting pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software"><div class="titlepage"><div><div><h3 class="title">3.7.1. Denoting pre-release software</h3></div></div></div><div class="para">
+ </div><div class="section" title="3.8.1. Denoting pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.8.1. Denoting pre-release software</h3></div></div></div><div class="para">
Documentation for pre-release software, especially pre-release software being distributed to testers, customers and partners, should carry a clear mark denoting the beta-status of the software.
</div><div class="para">
To create that mark do the following:
@@ -955,7 +964,7 @@ msgstr ""
Because this approach makes no changes to the information in <code class="filename">Book_Info.xml</code> used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.
</div><div class="important"><h2>Important</h2><div class="para">
It is the writer's responsibility to remove the <code class="sgmltag-element"><remark></code> tag and its contents and remove or turn off <code class="varname">show_remarks</code> when documentation is updated for use with the release version of the software.
- </div></div></div><div class="section" title="3.7.2. Denoting draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation"><div class="titlepage"><div><div><h3 class="title">3.7.2. Denoting draft documentation</h3></div></div></div><div class="para">
+ </div></div></div><div class="section" title="3.8.2. Denoting draft documentation" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.8.2. Denoting draft documentation</h3></div></div></div><div class="para">
Unfinished documentation made available to others for review should be labeled clearly as such.
</div><div class="procedure"><ul><li class="step" title="Step 1"><div class="para">
To add the draft watermark to your documentation add the <strong class="userinput"><code>status="draft"</code></strong> attribute to the <code class="sgmltag-element"><article></code>, <code class="sgmltag-element"><book></code> or <code class="sgmltag-element"><set></code> tag in your document's root node. For example:
@@ -969,10 +978,10 @@ msgstr ""
Adding the <strong class="userinput"><code>status="draft"</code></strong> attribute causes each page of the document to show the draft watermark. This is by design.
</div><div class="para">
Even if you change only a portion of a work before sending it out for review, marking every page as draft will encourage reviewers to report errors or typos they spot in passing. It will also ensure non-reviewers who encounter the work do not mistake a draft for a finished version.
- </div></div><div class="section" title="3.7.3. Denoting draft documentation of pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software"><div class="titlepage"><div><div><h3 class="title">3.7.3. Denoting draft documentation of pre-release software</h3></div></div></div><div class="para">
+ </div></div><div class="section" title="3.8.3. Denoting draft documentation of pre-release software" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.8.3. Denoting draft documentation of pre-release software</h3></div></div></div><div class="para">
To denote unfinished documentation of pre-release software properly, do both previously noted procedures.
- </div></div></div><div class="footnotes"><br /><hr /><div class="footnote"><p><sup>[<a id="ftn.id734623" href="#id734623" class="para">1</a>] </sup>
+ </div></div></div><div class="footnotes"><br /><hr /><div class="footnote"><p><sup>[<a id="ftn.id756284" href="#id756284" class="para">1</a>] </sup>
Refer to <a href="http://www.section508.gov/">http://www.section508.gov/</a>
- </p></div><div class="footnote"><p><sup>[<a id="ftn.id573564" href="#id573564" class="para">2</a>] </sup>
+ </p></div><div class="footnote"><p><sup>[<a id="ftn.id580077" href="#id580077" class="para">2</a>] </sup>
Refer to <a href="http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA">http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA</a>
</p></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Publican_commands.html"><strong>Prev</strong>Chapter 2. Publican commands</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Branding.html"><strong>Next</strong>Chapter 4. Branding</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Frequently_Asked_Questions.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Frequently_Asked_Questions.html
index b54be32..356ab38 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Frequently_Asked_Questions.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Frequently_Asked_Questions.html
@@ -1,76 +1,74 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 6. Frequently Asked Questions</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Using_sets.html" title="Chapter 5. Using sets" /><link rel="next" href="appe-Users_Guide-Disallowed_elements_and_attributes.html" title="Appendix A. Disallowed elements and attributes" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" sr
c="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Using_sets.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Disallowed_elements_and_attributes.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 6. Frequently Asked Questions" id="chap-Users_Guide-Frequently_Asked_Questions" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 6. Frequently Asked Questions</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><dl><dt>Q
: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id690442">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 7. Frequently Asked Questions</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican" /><link rel="next" href="appe-Users_Guide-Disallowed_elements_and_attributes.html" title="Appendix A. Disallowed elements and attributes" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocfra
me" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Website.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Disallowed_elements_and_attributes.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 7. Frequently Asked Questions" id="chap-Users_Guide-Frequently_Asked_Questions" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 7. Frequently Asked Questions</h2></div></div></div><div class="qandaset" title="Frequently Asked Quest
ions"><dl><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id507836">
How do I add a language to my book?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id727413">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id487658">
What if I do not want to use the country code? For example, can I run publican update_po --langs=es,de,fr?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id686497">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id631597">
How do I update all po files?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id718806">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id610083">
Where can I get a complete list of Publican's build options?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id582740">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id470791">
Where can I get a complete list of parameters that can be set in the publican.cfg?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id813894">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id579870">
Where are the Publican common files located?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id551751">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id1620075">
I have extensive code samples for my book, how can I include them without having to XML escape everything?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id688676">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id553444">
Is it possible to include arbitrary files in tarballs and RPM packages?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id686741">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id440778">
Why does Publican give me warnings about unknown tags?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id686766">
- Which brands enable strict mode? Strict mode is no longer enforced.
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id595474">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id440803">
+ Which brands enable strict mode? Strict mode is not currently enforced.
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id425086">
I get an error saying Batik is not in the classpath but Batik is installed! What is wrong?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id692140">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id660074">
I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id692177">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id660110">
Previous versions of Publican removed empty <para> tags. Does Publican still do this?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id749157">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id1682624">
What happened to the spell check?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id749182">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id1682648">
Why don't <segmentedlist>s work when I build PDFs?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id549151">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id1657217">
What happened to the colors in my images in this PDF?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id549176">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id1657242">
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
- </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id551707">
+ </a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#id560422">
Why does Jeff call Isaac ‘Ivan’?
- </a></dt></dl><div class="qandaset"><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </a></dt></dl><div class="qandaset"><div id="id507836" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
How do I add a language to my book?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run <code class="command">publican update_po --langs=<em class="replaceable"><code>language</code></em></code>, where <em class="replaceable"><code>language</code></em> is the code for the new language that you want to add. You can add more than one language at a time, with the language codes separated by commas. For example, <code class="command">publican update_po --langs=ja-JP</code> creates the Japanese language directory and Japanese PO files, and <code class="command">publican update_po --langs=ja-JP,ko-KR</code> creates directories and PO files for both Japanese and Korean.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id487658" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
What if I do not want to use the country code? For example, can I run <code class="command">publican update_po --langs=es,de,fr</code>?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Yes — this command works. However, if you omit the country code, the output might be unpredictable when <span class="application"><strong>Publican</strong></span> or a brand has definitions for more than one regional variety of a language — for example, <code class="literal">zh-CN</code> (Simplified Chinese as used in the People's Republic of China) and <code class="literal">zh-TW</code> (Traditional Chinese as used in the Republic of China, on Taiwan). Even when only one variety is currently defined, it is always safest to include the country code so that, for example, a future update of <span class="application"><strong>Publican</strong></span> does not suddenly cause your German (<code class="literal">de-DE</code>) documents to switch to Schweizerdeutsch (Swiss German, <code class="literal">de-CH</code>) Common Content and headings.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id631597" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
How do I update all po files?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run the <code class="command">publican update_po --langs=all</code> command.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id610083" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Where can I get a complete list of <span class="application"><strong>Publican</strong></span>'s build options?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run the <code class="command">publican build --help</code> command.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id470791" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Where can I get a complete list of parameters that can be set in the <code class="filename">publican.cfg</code>?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Run the <code class="command">publican help_config</code> command in a directory that holds any <span class="application"><strong>Publican</strong></span> document.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id579870" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Where are the <span class="application"><strong>Publican</strong></span> common files located?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
By default, they are in <code class="filename">/usr/share/publican/</code> on Linux operating systems and in <code class="filename">%SystemDrive%/%ProgramFiles%/publican/Common_Content</code> on Windows operating systems — typically, <code class="filename">C:/Program Files/publican/Common_Content</code>.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id1620075" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
I have extensive code samples for my book, how can I include them without having to XML escape everything?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
The best way to do this is to create a directory named <code class="filename">extras</code> in your source language directory and use an <code class="sgmltag-element">xi:include</code> to pull in the code file.
- </div><div class="procedure"><h6>Procedure 6.1. Including code samples</h6><ol class="1"><li class="step" title="Step 1"><div class="para">
+ </div><div class="procedure"><h6>Procedure 7.1. Including code samples</h6><ol class="1"><li class="step" title="Step 1"><div class="para">
Create the extras directory
- </div><pre class="screen"><code class="command">mkdir <code class="filename">en-US/extras</code></code>
-</pre></li><li class="step" title="Step 2"><div class="para">
+ </div><pre class="screen"><code class="command">mkdir <code class="filename">en-US/extras</code></code></pre></li><li class="step" title="Step 2"><div class="para">
Copy the code file to the extras directory
- </div><pre class="screen"><code class="command">cp <code class="filename">~/samples/foo.c en-US/extras/.</code></code>
-</pre></li><li class="step" title="Step 3"><div class="para">
+ </div><pre class="screen"><code class="command">cp <code class="filename">~/samples/foo.c en-US/extras/.</code></code></pre></li><li class="step" title="Step 3"><div class="para">
<code class="sgmltag-element">xi:include</code> the sample file in your xml file
</div><pre class="programlisting"><span class="perl_Keyword"><programlisting></span>
<span class="perl_Keyword"><xi:include</span><span class="perl_Others"> parse=</span><span class="perl_String">"text"</span><span class="perl_Others"> href=</span><span class="perl_String">"extras/foo.c"</span><span class="perl_Others"> xmlns:xi=</span><span class="perl_String">"http://www.w3.org/2001/XInclude"</span> <span class="perl_Keyword">/></span>
@@ -78,21 +76,21 @@
</pre></li><li class="step" title="Step 4"><div class="para">
You can now edit <code class="filename">en-US/extras/foo.c</code> in your favorite editor without having to be concerned about how it will affect the XML.
- </div></li></ol></div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></li></ol></div></div></div></div><div id="id553444" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Is it possible to include arbitrary files in tarballs and RPM packages?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Yes. If you make a directory named <code class="filename">files</code> in your source language directory it will be included in any tarballs or SRPM packages that <span class="application"><strong>Publican</strong></span> creates.
</div><div class="important"><h2>Important</h2><div class="para">
The <code class="filename">files</code> directory will not be available during the validation process so you can not <code class="sgmltag-element">xi:include</code> or otherwise embed any files in this directory in your XML.
- </div></div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div></div><div id="id440778" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Why does <span class="application"><strong>Publican</strong></span> give me warnings about unknown tags?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
This warning informs you that you are using a tag whose output has not been tested for attractiveness, XHTML 1.0 Strict compliance, or Section 508 (Accessibility) compliance.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
- <span class="strikethrough strikethrough">Which brands enable strict mode?</span> Strict mode is no longer enforced.
+ </div></div></div></div><div id="id440803" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ <span class="strikethrough strikethrough">Which brands enable strict mode?</span> Strict mode is not currently enforced.
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
<span class="strikethrough strikethrough">Currently the Red Hat and JBoss brands enable strict mode.</span>
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id425086" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
I get an error saying <span class="application"><strong>Batik</strong></span> is not in the classpath but <span class="application"><strong>Batik</strong></span> is installed! What is wrong?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
We believe this is due to classpath issues caused by having different JRE and JDK versions installed. Sometimes this can be fixed by upgrading your JDK to the same version of your JRE.
@@ -100,38 +98,37 @@
Sometimes this issue can be revealed by running <code class="command">alternatives --config java</code> and <code class="command">alternatives --config javac</code>, if the versions are different then selecting the same version in both can fix this problem.
</div><div class="para">
Some Java installs do not set-up the <code class="command">alternatives</code> environment correctly, no fix has been determined for this situation.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id660074" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
I get an error <code class="computeroutput">Exception in thread "main" java.lang.OutOfMemoryError: Java heap space</code> when trying to build PDF. What is wrong?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to <span class="application"><strong>FOP</strong></span>. Before running <code class="command">make </code> run <code class="command">echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc</code>. This sets the initial heap space to 50 MB and allows it to grow to a maximum of 700 MB.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id660110" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Previous versions of <span class="application"><strong>Publican</strong></span> removed empty <code class="sgmltag-element"><para></code> tags. Does <span class="application"><strong>Publican</strong></span> still do this?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
No. <span class="application"><strong>Publican</strong></span> previously removed empty <code class="sgmltag-element"><para></code> tags while it transformed XML because empty <code class="sgmltag-element"><para></code> tags broke earlier translation toolchains used within Red Hat and the Fedora Project. Empty <code class="sgmltag-element"><para></code> tags are valid DocBook XML, and <span class="application"><strong>Publican</strong></span> no longer removes them.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id1682624" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
What happened to the spell check?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Early versions of <span class="application"><strong>Publican</strong></span> (up to and including 0.45) ran a spell check while transforming a document's XML. Due to negative feedback from users, this feature was dropped.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id1682648" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Why don't <code class="sgmltag-element"><segmentedlist></code>s work when I build PDFs?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Check the number of columns in your <code class="sgmltag-element"><segmentedlist></code>s. When <code class="sgmltag-element"><segmentedlist></code>s are formatted as tables, the DocBook XSL limits the number of columns to two, and <span class="application"><strong>Publican</strong></span> formats <code class="sgmltag-element"><segmentedlist></code>s as tables.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id1657217" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
What happened to the colors in my images in this PDF?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
This is the result of a bug in <span class="application"><strong>FOP</strong></span> that distorts colors in 24-bit PNG images. Convert your images to 32-bit PNG images to work around the problem.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id1657242" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Code highlighting in <span class="application"><strong>Publican</strong></span> is generated with the <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> Perl module. If you specify a language in a <code class="sgmltag-element"><programlisting></code> tag that <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> does not recognize, you receive an error when you build your book. The first lines of the error message are similar to:
</div><pre class="screen"><code class="computeroutput">undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pm line 615.</code>
-<code class="computeroutput">cannot create plugin for language 'JAVA'</code>
-</pre><div class="para">
+<code class="computeroutput">cannot create plugin for language 'JAVA'</code></pre><div class="para">
Note that <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> is very strict about names of languages and is case sensitive. Therefore, <code class="sgmltag-element"><programlisting language="Java"></code> works, but <code class="sgmltag-element"><programlisting language="java"></code> and <code class="sgmltag-element"><programlisting language="JAVA"></code> do not. The error message that you receive identifies the problematic language attribute.
</div><div class="para">
Refer to <a href="http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS">http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS</a> for the full list of languages that <span class="application"><strong>Syntax::Highlight::Engine::Kate</strong></span> supports, including their expected capitalization and punctuation.
- </div></div></div></div><div class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
+ </div></div></div></div><div id="id560422" class="qandaentry"><div class="question"><label>Q:</label><div class="data"><div class="para">
Why does Jeff call Isaac ‘Ivan’?
</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
Because Jeff's memory is pants!
- </div></div></div></div></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Using_sets.html"><strong>Prev</strong>Chapter 5. Using sets</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Disallowed_elements_and_attributes.html"><strong>Next</strong>Appendix A. Disallowed elements and attributes</a></li></ul></body></html>
+ </div></div></div></div></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Website.html"><strong>Prev</strong>Chapter 6. Building a website with Publican</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Disallowed_elements_and_attributes.html"><strong>Next</strong>Appendix A. Disallowed elements and attributes</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Installing_Publican.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Installing_Publican.html
index b925df7..9677ffe 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Installing_Publican.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Installing_Publican.html
@@ -1,20 +1,18 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 1. Installing Publican</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="pref-Users_Guide-Introduction.html" title="Introduction" /><link rel="next" href="chap-Users_Guide-Publican_commands.html" title="Chapter 2. Publican commands" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view
it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="pref-Users_Guide-Introduction.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Publican_commands.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 1. Installing Publican" id="chap-Users_Guide-Installing_Publican" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 1. Installing Publican</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Installing_Publica
n_on_Linux_operating_systems">1.1. Installing Publican on Linux operating systems</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Fedora">1.1.1. Installing Publican on Fedora</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Red_Hat_Enterprise_Linux_5">1.1.2. Installing Publican on Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Ubuntu">1.1.3. Installing Publican on Ubuntu</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Debian">
1.1.4. Installing Publican on Debian</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Windows_operating_systems">1.2. Installing Publican on Windows operating systems</a></span></dt></dl></div><div class="section" title="1.1. Installing Publican on Linux operating systems" id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux_operating_systems"><div class="titlepage"><div><div><h2 class="title">1.1. Installing Publican on Linux operating systems</h2></div></div></div><div class="important"><h2>Important — Availability in repositories</h2><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 1. Installing Publican</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="pref-Users_Guide-Introduction.html" title="Introduction" /><link rel="next" href="chap-Users_Guide-Publican_commands.html" title="Chapter 2. Publican commands" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view
it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="pref-Users_Guide-Introduction.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Publican_commands.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 1. Installing Publican" id="chap-Users_Guide-Installing_Publican" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 1. Installing Publican</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Installing_Publican
_on_Linux">1.1. Linux operating systems</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Fedora">1.1.1. Fedora</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5">1.1.2. Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Ubuntu">1.1.3. Ubuntu</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Debian">1.1.4. Debian</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Windows_operating_systems">1.2. Windows operating systems</a></span></dt></dl></div><div class="section" title="1.1. Linux operating systems"
id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux">1.1. Linux operating systems</h2></div></div></div><div class="important"><h2>Important — Availability in repositories</h2><div class="para">
The procedures documented in this section assume that <span class="application"><strong>Publican</strong></span> and its various dependencies are available in repositories to which your system has access.
- </div></div><div class="section" title="1.1.1. Installing Publican on Fedora" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Fedora"><div class="titlepage"><div><div><h3 class="title">1.1.1. Installing Publican on Fedora</h3></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ </div></div><div class="section" title="1.1.1. Fedora" id="sect-Users_Guide-Linux_operating_systems-Fedora"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Fedora">1.1.1. Fedora</h3></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Open a terminal.
</div></li><li class="step" title="Step 2"><div class="para">
Change to the root user: <code class="command"> su - </code>
</div></li><li class="step" title="Step 3"><div class="para">
Run the following command to install the <span class="package">publican</span> package and the <span class="package">publican-doc</span> documentation package:
- </div><pre class="screen"><code class="command"> yum install publican publican-doc</code>
-</pre></li></ol></div><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican publican-doc</code></pre></li></ol></div><div class="para">
Several brand packages are available for use with <span class="application"><strong>Publican</strong></span>. Run the following command as the root user to install packages for building branded books:
- </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code></pre><div class="para">
Replace <em class="replaceable"><code>brand</code></em> with, for example, <code class="literal">redhat</code>, <code class="literal">fedora</code>, <code class="literal">jboss</code>, <code class="literal">ovirt</code>, or <code class="literal">gimp</code>. Refer to <a class="xref" href="chap-Users_Guide-Branding.html" title="Chapter 4. Branding">Chapter 4, <i>Branding</i></a> for more information on branding.
- </div></div><div class="section" title="1.1.2. Installing Publican on Red Hat Enterprise Linux 5" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Red_Hat_Enterprise_Linux_5"><div class="titlepage"><div><div><h3 class="title">1.1.2. Installing Publican on Red Hat Enterprise Linux 5</h3></div></div></div><div class="important"><h2>Important — Unsupported software</h2><div class="para">
+ </div></div><div class="section" title="1.1.2. Red Hat Enterprise Linux 5" id="sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5">1.1.2. Red Hat Enterprise Linux 5</h3></div></div></div><div class="important"><h2>Important — Unsupported software</h2><div class="para">
<span class="application"><strong>Publican</strong></span> is not part of the Red Hat Enterprise Linux distribution. Therefore, Red Hat does not offer support for <span class="application"><strong>Publican</strong></span>.
</div></div><div class="important"><h2>Important — Dependencies available only internally to Red Hat</h2><div class="para">
Installing <span class="application"><strong>Publican</strong></span> on Red Hat Enterprise Linux 5 requires a number of dependencies that are presently available only in yum repositories that are internal to Red Hat.
@@ -24,20 +22,17 @@
Change to the root user: <code class="command"> su - </code>
</div></li><li class="step" title="Step 3"><div class="para">
Run the following command to install the <span class="package">publican</span> package and the <span class="package">publican-doc</span> documentation package:
- </div><pre class="screen"><code class="command"> yum install publican publican-doc</code>
-</pre></li></ol></div><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican publican-doc</code></pre></li></ol></div><div class="para">
Several brand packages are available for use with <span class="application"><strong>Publican</strong></span>. Run the following command as the root user to install packages for building branded books:
- </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code>
-</pre><div class="para">
+ </div><pre class="screen"><code class="command"> yum install publican-<em class="replaceable"><code>brand</code></em></code></pre><div class="para">
Replace <em class="replaceable"><code>brand</code></em> with, for example, <code class="literal">redhat</code>, <code class="literal">fedora</code>, <code class="literal">jboss</code>, <code class="literal">ovirt</code>, or <code class="literal">gimp</code>. Refer to <a class="xref" href="chap-Users_Guide-Branding.html" title="Chapter 4. Branding">Chapter 4, <i>Branding</i></a> for more information on branding.
- </div></div><div class="section" title="1.1.3. Installing Publican on Ubuntu" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Ubuntu"><div class="titlepage"><div><div><h3 class="title">1.1.3. Installing Publican on Ubuntu</h3></div></div></div><div class="important"><h2> Important — New in 10.4 "Lucid Lynx"</h2><div class="para">
+ </div></div><div class="section" title="1.1.3. Ubuntu" id="sect-Users_Guide-Linux_operating_systems-Ubuntu"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Ubuntu">1.1.3. Ubuntu</h3></div></div></div><div class="important"><h2> Important — New in 10.4 "Lucid Lynx"</h2><div class="para">
<span class="application"><strong>Publican</strong></span> is new in Ubuntu 10.4 "Lucid Lynx".
</div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Open a terminal.
</div></li><li class="step" title="Step 2"><div class="para">
Run the following command to install the <span class="package">publican</span> package:
- </div><pre class="screen"><code class="command">sudo apt-get install publican</code>
-</pre></li></ol></div></div><div class="section" title="1.1.4. Installing Publican on Debian" id="sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Debian"><div class="titlepage"><div><div><h3 class="title">1.1.4. Installing Publican on Debian</h3></div></div></div><div class="warning"><h2> Warning — Complete this procedure </h2><div class="para">
+ </div><pre class="screen"><code class="command">sudo apt-get install publican</code></pre></li></ol></div></div><div class="section" title="1.1.4. Debian" id="sect-Users_Guide-Linux_operating_systems-Debian"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Linux_operating_systems-Debian">1.1.4. Debian</h3></div></div></div><div class="warning"><h2> Warning — Complete this procedure </h2><div class="para">
Complete every step of this procedure. If you do not undo the changes that you make to the <code class="filename">/etc/apt/sources.list</code> file as described, your system might become unstable.
</div></div><div class="para">
<span class="application"><strong>Publican</strong></span> is not available in the current stable version of Debian (version 5.0, "Lenny"), but is available in the current testing version ("Squeeze"). To install <span class="application"><strong>Publican</strong></span> on a computer that runs Debian, temporarily enable access to the <code class="literal">squeeze</code> repository. When you enable access to this repository, you allow your computer to install newer software and newer versions of existing software than what is available in the current stable version of Debian. However, not all of the software available in the testing repository has completed quality assurance testing yet. If you do not disable access to this repository after you install <span class="application"><strong>Publican</strong></span>, the next time that your system updates, it will replace software packages on your system with newer but possibly untested versions of those packages that it downlo
ads from the testing repository.
@@ -45,8 +40,7 @@
Open a terminal.
</div></li><li class="step" title="Step 2"><div class="para">
Open your <code class="filename">/etc/apt/sources.list</code> file in a text editor. For example, to edit the file in <span class="application"><strong>gedit</strong></span> run:
- </div><pre class="screen"><code class="command">sudo gedit /etc/apt/sources.list</code>
-</pre></li><li class="step" title="Step 3"><div class="para">
+ </div><pre class="screen"><code class="command">sudo gedit /etc/apt/sources.list</code></pre></li><li class="step" title="Step 3"><div class="para">
Add the following line to the end of the file:
</div><pre class="programlisting">deb http://ftp.debian.org/debian/ squeeze main
@@ -54,17 +48,15 @@
Save the file and close the text editor.
</div></li><li class="step" title="Step 5"><div class="para">
Run the following command to update the list of packages available to your computer:
- </div><pre class="screen"><code class="command">sudo apt-get update</code>
-</pre></li><li class="step" title="Step 6"><div class="para">
+ </div><pre class="screen"><code class="command">sudo apt-get update</code></pre></li><li class="step" title="Step 6"><div class="para">
Run the following command to install the <span class="package">publican</span> package:
- </div><pre class="screen"><code class="command">sudo apt-get install publican</code>
-</pre></li><li class="step" title="Step 7"><div class="para">
+ </div><pre class="screen"><code class="command">sudo apt-get install publican</code></pre></li><li class="step" title="Step 7"><div class="para">
Open your <code class="filename">/etc/apt/sources.list</code> file again, and delete the extra line that you added in this procedure.
</div></li></ol></div><div class="para">
Note that until the release of "Squeeze" as the stable version of Debian, you must manually enable and disable access to the testing repository as described in this procedure whenever a new version of <span class="application"><strong>Publican</strong></span> becomes available in the testing repository. You can find up-to-date information about the status of <span class="application"><strong>Publican</strong></span> for Debian at <a href="http://packages.debian.org/squeeze/publican">http://packages.debian.org/squeeze/publican</a>, including the version number of <span class="application"><strong>Publican</strong></span> available in the repository (1.0 at the time of writing).
</div><div class="para">
When "Squeeze" becomes the stable version of Debian, you will not need to enable or disable access to extra repositories to install <span class="application"><strong>Publican</strong></span> on systems that run that version of the operating system.
- </div></div></div><div class="section" title="1.2. Installing Publican on Windows operating systems" id="sect-Users_Guide-Installing_Publican-Installing_Publican_on_Windows_operating_systems"><div class="titlepage"><div><div><h2 class="title">1.2. Installing Publican on Windows operating systems</h2></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ </div></div></div><div class="section" title="1.2. Windows operating systems" id="sect-Users_Guide-Installing_Publican-Windows_operating_systems"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Installing_Publican-Windows_operating_systems">1.2. Windows operating systems</h2></div></div></div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
Download the Publican installer from <a href="https://fedorahosted.org/releases/p/u/publican/">https://fedorahosted.org/releases/p/u/publican/</a>.
</div></li><li class="step" title="Step 2"><div class="para">
Browse to the folder to which you downloaded <code class="filename">Publican-Installer-<em class="replaceable"><code>version</code></em>.exe</code>.
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Publican_commands.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Publican_commands.html
index 1693552..c302ca8 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Publican_commands.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Publican_commands.html
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 2. Publican commands</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Installing_Publican.html" title="Chapter 1. Installing Publican" /><link rel="next" href="chap-Users_Guide-Creating_a_document.html" title="Chapter 3. Creating a document" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.htm
l">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Installing_Publican.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Creating_a_document.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 2. Publican commands" id="chap-Users_Guide-Publican_commands" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 2. Publican commands</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican
_commands-Command_options">2.1. Command options</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican_commands-Actions">2.2. Actions</a></span></dt></dl></div><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 2. Publican commands</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Installing_Publican.html" title="Chapter 1. Installing Publican" /><link rel="next" href="chap-Users_Guide-Creating_a_document.html" title="Chapter 3. Creating a document" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html
">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Installing_Publican.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Creating_a_document.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 2. Publican commands" id="chap-Users_Guide-Publican_commands" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 2. Publican commands</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican_
commands-Command_options">2.1. Command options</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican_commands-Actions">2.2. Actions</a></span></dt></dl></div><div class="para">
<span class="application"><strong>Publican</strong></span> is a command-line tool. To use <span class="application"><strong>Publican</strong></span> on a computer with a Linux operating system, you must either start a terminal emulator program (such as <span class="application"><strong>GNOME Terminal</strong></span> or <span class="application"><strong>Konsole</strong></span>) or switch to a virtual console. To use <span class="application"><strong>Publican</strong></span> on a computer with a Windows operating system, run the <code class="command">cmd</code> command from the <span class="guimenu"><strong>Start menu</strong></span> to open a command prompt.
</div><div class="para">
<span class="application"><strong>Publican</strong></span> commands take one of the following formats:
@@ -12,7 +12,7 @@
Some <em class="replaceable"><code>command_options</code></em> affect the output of <em class="replaceable"><code>actions</code></em>, for example, whether <span class="application"><strong>Publican</strong></span> should use ANSI colors in its output.
</div></dd></dl></div>
- </div><div class="section" title="2.1. Command options" id="sect-Users_Guide-Publican_commands-Command_options"><div class="titlepage"><div><div><h2 class="title">2.1. Command options</h2></div></div></div><div class="para">
+ </div><div class="section" title="2.1. Command options" id="sect-Users_Guide-Publican_commands-Command_options"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Publican_commands-Command_options">2.1. Command options</h2></div></div></div><div class="para">
The options for the <code class="command">publican</code> command are:
<div class="variablelist"><dl><dt><span class="term"><code class="option">--help</code></span></dt><dd><div class="para">
This option displays a help message, a condensed version of the contents of this chapter.
@@ -30,10 +30,10 @@
This option disables all logging.
</div></dd></dl></div>
- </div></div><div class="section" title="2.2. Actions" id="sect-Users_Guide-Publican_commands-Actions"><div class="titlepage"><div><div><h2 class="title">2.2. Actions</h2></div></div></div><div class="para">
+ </div></div><div class="section" title="2.2. Actions" id="sect-Users_Guide-Publican_commands-Actions"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Publican_commands-Actions">2.2. Actions</h2></div></div></div><div class="para">
<span class="application"><strong>Publican</strong></span> can perform the following actions:
<div class="variablelist"><dl><dt><span class="term">build</span></dt><dd><div class="para">
- transforms XML to other formats (for example: PDF, single-page HTML, or multiple-page HTML). Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document" title="3.4. Building a document">Section 3.4, “Building a document”</a> for more details and a description of the available options.
+ transforms XML to other formats (for example: PDF, single-page HTML, or multiple-page HTML). Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document" title="3.5. Building a document">Section 3.5, “Building a document”</a> for more details and a description of the available options.
</div></dd><dt><span class="term">clean</span></dt><dd><div class="para">
removes all files and folders in the <code class="filename">tmp/</code> subdirectory. The <code class="filename">tmp/</code> subdirectory is created after running the <code class="command">publican build</code> command to build a document, such as <code class="command">publican build --formats=html --langs=en-US</code>.
</div></dd><dt><span class="term">clean_ids</span></dt><dd><div class="para">
@@ -42,34 +42,44 @@
To make translation easier, <code class="command">make clean_ids</code> uses the first four characters of the tag as a prefix for the ID. Consequently, you must check out the latest versions of the XML source and translations before running this command.
</div><div class="para">
If you do not have the current versions of the PO files checked out before running <code class="command">make clean_ids</code>, the XML and PO files will no longer in synchrony with each other. In this case, all links in the PO files must be manually updated.
- </div></div></dd><dt><span class="term">cleanset</span></dt><dd><div class="para">
+ </div></div></dd><dt><span class="term">clean_set</span></dt><dd><div class="para">
removes local copies of remote books in a distributed set. Refer to <a class="xref" href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Distributed_sets" title="5.2. Distributed sets">Section 5.2, “Distributed sets”</a> for details of using distributed sets.
</div></dd><dt><span class="term">create</span></dt><dd><div class="para">
creates a new book, article, or set. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html" title="Chapter 3. Creating a document">Chapter 3, <i>Creating a document</i></a> for details of creating a book or article, and to <a class="xref" href="chap-Users_Guide-Using_sets.html" title="Chapter 5. Using sets">Chapter 5, <i>Using sets</i></a> for details of using sets.
</div></dd><dt><span class="term">create_brand</span></dt><dd><div class="para">
creates a new brand. Refer to <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Creating_a_brand" title="4.2. Creating a brand">Section 4.2, “Creating a brand”</a> for details of creating a brand.
+ </div></dd><dt><span class="term">create_site</span></dt><dd><div class="para">
+ creates a documentation website. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
</div></dd><dt><span class="term">help_config</span></dt><dd><div class="para">
displays help text for the configuration file contained in each book or brand, <code class="filename">publican.cfg</code>. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" title="3.1.1. The publican.cfg file">Section 3.1.1, “The publican.cfg file”</a> for more detail.
- </div></dd><dt><span class="term">installbrand</span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">install_book</span></dt><dd><div class="para">
+ installs a document on a documentation website. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
+ </div></dd><dt><span class="term">install_brand</span></dt><dd><div class="para">
configures a brand for installation. Refer to <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Installing_a_brand" title="4.1. Installing a brand">Section 4.1, “Installing a brand”</a> for details of installing a brand.
</div></dd><dt><span class="term">lang_stats --lang=<em class="replaceable"><code>language_code</code></em></span></dt><dd><div class="para">
generates a translation report for the language specified by <em class="replaceable"><code>language_code</code></em>.
</div></dd><dt><span class="term">old2new</span></dt><dd><div class="para">
- creates a <code class="filename">publican.cfg</code> file based on the <code class="filename">Makefile</code> of a book, article, or set originally created with a developmental version of <span class="application"><strong>Publican</strong></span> (versions up to and including <span class="application"><strong>Publican 0.45</strong></span>). Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0" title="3.4.1. Building a document created with Publican 0">Section 3.4.1, “Building a document created with Publican 0”</a> for more detail.
+ creates a <code class="filename">publican.cfg</code> file based on the <code class="filename">Makefile</code> of a book, article, or set originally created with a developmental version of <span class="application"><strong>Publican</strong></span> (versions up to and including <span class="application"><strong>Publican 0.45</strong></span>). Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0" title="3.5.1. Building a document created with Publican 0">Section 3.5.1, “Building a document created with Publican 0”</a> for more detail.
</div></dd><dt><span class="term">package</span></dt><dd><div class="para">
- packages a book, article, set, or brand for shipping as an RPM package. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.5. Packaging a book">Section 3.5, “Packaging a book”</a> and <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more detail.
+ packages a book, article, set, or brand for shipping as an RPM package. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book" title="3.6. Packaging a book">Section 3.6, “Packaging a book”</a> and <a class="xref" href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand" title="4.4. Packaging a brand">Section 4.4, “Packaging a brand”</a> for more detail.
</div></dd><dt><span class="term">print_banned</span></dt><dd><div class="para">
prints a list of DocBook tags banned by <span class="application"><strong>Publican</strong></span>. Refer to <a class="xref" href="appe-Users_Guide-Disallowed_elements_and_attributes.html" title="Appendix A. Disallowed elements and attributes">Appendix A, <i>Disallowed elements and attributes</i></a> for a discussion of banned tags.
</div></dd><dt><span class="term">print_known</span></dt><dd><div class="para">
prints a list of DocBook tags supported by <span class="application"><strong>Publican</strong></span>. <em class="firstterm">Supported</em> are those tags whose output has undergone at least cursory verification for quality when used in <span class="application"><strong>Publican</strong></span> — refer to <a class="xref" href="appe-Users_Guide-Disallowed_elements_and_attributes.html" title="Appendix A. Disallowed elements and attributes">Appendix A, <i>Disallowed elements and attributes</i></a>.
- </div></dd><dt><span class="term">printtree</span></dt><dd><div class="para">
+ </div></dd><dt><span class="term">print_tree</span></dt><dd><div class="para">
prints a tree of the XML files included with the <code class="sgmltag-element"><xi:include></code> tag in a book, article, or set.
</div></dd><dt><span class="term">print_unused</span></dt><dd><div class="para">
prints a list of the XML files <span class="emphasis"><em>not</em></span> included with the <code class="sgmltag-element"><xi:include></code> tag in a book, article, or set.
+ </div></dd><dt><span class="term">remove_book</span></dt><dd><div class="para">
+ removes a document from a documentation website. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
+ </div></dd><dt><span class="term">site_stats</span></dt><dd><div class="para">
+ generates a site report for a documentation website.
</div></dd><dt><span class="term">update_po</span></dt><dd><div class="para">
- updates the <em class="firstterm">portable object</em> (PO) files. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation" title="3.3. Preparing a document for translation">Section 3.3, “Preparing a document for translation”</a> for more detail.
+ updates the <em class="firstterm">portable object</em> (PO) files. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation" title="3.4. Preparing a document for translation">Section 3.4, “Preparing a document for translation”</a> for more detail.
</div></dd><dt><span class="term">update_pot</span></dt><dd><div class="para">
- updates the <em class="firstterm">portable object template</em> (POT) files. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation" title="3.3. Preparing a document for translation">Section 3.3, “Preparing a document for translation”</a> for more detail.
+ updates the <em class="firstterm">portable object template</em> (POT) files. Refer to <a class="xref" href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation" title="3.4. Preparing a document for translation">Section 3.4, “Preparing a document for translation”</a> for more detail.
+ </div></dd><dt><span class="term">update_site</span></dt><dd><div class="para">
+ updates the templated content of the documentation website. Refer to <a class="xref" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican">Chapter 6, <i>Building a website with Publican</i></a> for details.
</div></dd></dl></div>
</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Installing_Publican.html"><strong>Prev</strong>Chapter 1. Installing Publican</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Creating_a_document.html"><strong>Next</strong>Chapter 3. Creating a document</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Using_sets.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Using_sets.html
index 6514182..132cd8b 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Using_sets.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Using_sets.html
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5. Using sets</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Branding.html" title="Chapter 4. Branding" /><link rel="next" href="chap-Users_Guide-Frequently_Asked_Questions.html" title="Chapter 6. Frequently Asked Questions" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an i
frame, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Branding.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 5. Using sets" id="chap-Users_Guide-Using_sets" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 5. Using sets</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</a><
/span></dt><dt><span class="section"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</a></span></dt></dl></div><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5. Using sets</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Branding.html" title="Chapter 4. Branding" /><link rel="next" href="sect-Users_Guide-Website.html" title="Chapter 6. Building a website with Publican" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view
it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Branding.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Website.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 5. Using sets" id="chap-Users_Guide-Using_sets" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 5. Using sets</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</a></span></dt><dt><span class="secti
on"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</a></span></dt></dl></div><div class="para">
A <em class="firstterm">set</em> is a collection of books, published as a single output. The <em class="citetitle">Services Plan</em> for example is a set comprised of many books such as the <em class="citetitle">Developer Guide</em>, <em class="citetitle">Engineering Content Services Guide</em> and the <em class="citetitle">Engineering Operations Guide</em> to name just a few. The <code class="command">create_book</code> command creates a template for a set by setting the <em class="parameter"><code>type</code></em> parameter to <code class="literal">Set</code>. There are two types of sets, <em class="firstterm">stand-alone sets</em> and <em class="firstterm">distributed sets</em>.
- </div><div class="section" title="5.1. Stand-alone sets" id="sect-Users_Guide-Using_sets-Stand_alone_sets"><div class="titlepage"><div><div><h2 class="title">5.1. Stand-alone sets</h2></div></div></div><div class="para">
+ </div><div class="section" title="5.1. Stand-alone sets" id="sect-Users_Guide-Using_sets-Stand_alone_sets"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</h2></div></div></div><div class="para">
A stand-alone set contains the XML files for each book, all of which are located inside the directory of the set.
</div><div class="para">
The procedure that follows will guide you through the process of creating a stand-alone set named <em class="citetitle">My Set</em> located in a directory called <code class="filename">books/My_Set/</code>. The set will contain <em class="citetitle">Book A</em> and <em class="citetitle">Book B</em> both of which will be manually created inside the <code class="filename">books/My_Set/en-US</code> directory.
@@ -44,10 +44,11 @@ mkdir Book_A Book_B
<span class="perl_Keyword"><xi:include</span><span class="perl_Others"> href=</span><span class="perl_String">"Revision_History.xml"</span><span class="perl_Others"> xmlns:xi=</span><span class="perl_String">"http://www.w3.org/2001/XInclude"</span> <span class="perl_Keyword">/></span>
<span class="perl_Keyword"></set></span>
+
</pre></li><li class="step" title="Step 6"><div class="para">
Test your set by running the <code class="command">publican build --formats=test langs=en-US</code> command.
- </div></li></ol></div></div><div class="section" title="5.2. Distributed sets" id="sect-Users_Guide-Using_sets-Distributed_sets"><div class="titlepage"><div><div><h2 class="title">5.2. Distributed sets</h2></div></div></div><div class="para">
+ </div></li></ol></div></div><div class="section" title="5.2. Distributed sets" id="sect-Users_Guide-Using_sets-Distributed_sets"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</h2></div></div></div><div class="para">
A <em class="firstterm">distributed set</em> contains books that are located in a version-controlled repository. Although several version control systems exist, this version of <span class="application"><strong>Publican</strong></span> supports only one: <span class="application"><strong>Subversion</strong></span> (<span class="application"><strong>SVN</strong></span>). By setting the repository location and titles of the included books in the <code class="filename">publican.cfg</code> file, each book can be exported to build the entire set. The procedure that follows will guide you through the process of creating a set named <em class="citetitle">My Set</em> containing <em class="citetitle">Book A</em> and <em class="citetitle">Book B</em>.
</div><div class="important"><h2>Important</h2><div class="para">
The following procedure assumes that <em class="citetitle">Book A</em> and <em class="citetitle">Book B</em> already exist and are available in your <span class="application"><strong>SVN</strong></span> repository. Currently <span class="application"><strong>Publican</strong></span> only supports <span class="application"><strong>SVN</strong></span>.
@@ -76,9 +77,10 @@ scm = SVN
<span class="perl_Keyword"><xi:include</span><span class="perl_Others"> href=</span><span class="perl_String">"Revision_History.xml"</span><span class="perl_Others"> xmlns:xi=</span><span class="perl_String">"http://www.w3.org/2001/XInclude"</span> <span class="perl_Keyword">/></span>
<span class="perl_Keyword"></set></span>
+
</pre></li><li class="step" title="Step 4"><div class="para">
Test your set by running the <code class="command">publican build --formats=test --langs=en-US</code> command.
</div><div class="important"><h2>Important</h2><div class="para">
When building a set, the <code class="command">publican clean_ids</code> command will be run over each book because of the constraint that IDs must be unique across all books. Be careful of creating IDs that rely on content that may not be available when building books independently of the set.
- </div></div></li></ol></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Branding.html"><strong>Prev</strong>Chapter 4. Branding</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Next</strong>Chapter 6. Frequently Asked Questions</a></li></ul></body></html>
+ </div></div></li></ol></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Branding.html"><strong>Prev</strong>Chapter 4. Branding</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Website.html"><strong>Next</strong>Chapter 6. Building a website with Publican</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/index.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/index.html
index 78c47d4..bc90922 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/index.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/index.html
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Users Guide</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="description" content="This book will help you install Publican. 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." /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="next" href="pref-Users_Guide-Preface.html" title="Preface" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="
tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"></li><li class="next"><a accesskey="n" href="pref-Users_Guide-Preface.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="book" title="Users Guide" lang="en-US"><div class="titlepage"><div><div class="producttitle"><span class="productname">Publican</span> <span class="productnumber">1.6</span></div><div><h1 id="id1775435" class="title">Users Guide</h1></div><div><h2 class="subtitle">Publishing books, articles, papers and multi-volume sets with DocBook XML</h2></div><p class="edition">Edition 1.6</p>
<div><h3 class="corpauthor">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Users Guide</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="description" content="This book will help you install Publican. 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." /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="next" href="pref-Users_Guide-Preface.html" title="Preface" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="t
ocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"></li><li class="next"><a accesskey="n" href="pref-Users_Guide-Preface.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="book" title="Users Guide" id="id450666" lang="en-US"><div class="titlepage"><div><div class="producttitle"><span class="productname">Publican</span> <span class="productnumber">2.0</span></div><div><h1 id="id450666" class="title">Users Guide</h1></div><div><h2 class="subtitle">Publishing books, articles, papers and multi-volume sets with DocBook XML</h2></div><p class="edition">Edi
tion 1.0</p><div><h3 class="corpauthor">
<span class="inlinemediaobject"><object data="Common_Content/images/title_logo.svg" type="image/svg+xml"> Team Publican</object></span>
</h3></div><div><div xml:lang="en-US" class="authorgroup" lang="en-US"><div class="author"><h3 class="author"><span class="firstname">Don</span> <span class="surname">Domingo</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:ddomingo at redhat.com">ddomingo at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Brian</span> <span class="surname">Forté</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:bforte at redhat.com">bforte at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Rüdiger</span> <span class="surname">Landmann</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Serv
ices</span></div><code class="email"><a class="email" href="mailto:r.landmann at redhat.com">r.landmann at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Joshua</span> <span class="surname">Oakes</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:joakes at redhat.com">joakes at redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Joshua</span> <span class="surname">Wulf</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:jwulf at redhat.com">jwulf at redhat.com</a></code></div><div class="editor"><h4 class="editedby">Edited by</h4><h3 class="editor"><span class="firstname">Brian</span> <span class="surname">Forté</span></h3><div class="affiliation"><s
pan class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:bforte at redhat.com">bforte at redhat.com</a></code></div><div class="editor"><h4 class="editedby">Edited by</h4><h3 class="editor"><span class="firstname">Rüdiger</span> <span class="surname">Landmann</span></h3><div class="affiliation"><span class="orgname">Red Hat</span> <span class="orgdiv">Engineering Content Services</span></div><code class="email"><a class="email" href="mailto:r.landmann at redhat.com">r.landmann at redhat.com</a></code></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Jeff</span> <span class="surname">Fearn</span></h3><span class="contrib">Extensive review, rough drafts, persistent annoyances.</span> <div class="affiliation"><span class="shortaffil"> <span class="inlinemediaobject"><img src="images/logos/engops.png" alt="Red Hat, Engineering Operations Logo" /></span>
- <br /></span></div><code class="email"><a class="email" href="mailto:jfearn at redhat.com">jfearn at redhat.com</a></code></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Josef</span> <span class="surname">Hruška</span></h3><span class="contrib">Checking the Czech examples in Entities and translation</span> <div class="affiliation"><span class="orgname">Fedora</span> <span class="orgdiv">Localization Project</span></div></div></div></div><hr /><div><div id="id550497" class="legalnotice"><h1 class="legalnotice">Legal Notice</h1><div class="para">
+ <br /></span></div><code class="email"><a class="email" href="mailto:jfearn at redhat.com">jfearn at redhat.com</a></code></div><div class="othercredit"><h3 class="othercredit"><span class="firstname">Josef</span> <span class="surname">Hruška</span></h3><span class="contrib">Checking the Czech examples in Entities and translation</span> <div class="affiliation"><span class="orgname">Fedora</span> <span class="orgdiv">Localization Project</span></div></div></div></div><hr /><div><div id="id553222" class="legalnotice"><h1 class="legalnotice">Legal Notice</h1><div class="para">
Copyright <span class="trademark"></span>© 2009 Red Hat, Inc This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at <a href="http://www.gnu.org/licenses/fdl.txt">http://www.gnu.org/licenses/fdl.txt</a>).
</div></div></div><div><div class="abstract" title="Abstract"><h6>Abstract</h6><div class="para">
This book will help you install <span class="application"><strong>Publican</strong></span>. 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.
- </div></div></div></div><hr /></div><div class="toc"><dl><dt><span class="preface"><a href="pref-Users_Guide-Preface.html">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id582094">1. Document Conventions</a></span></dt><dd><dl><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id582071">1.1. Typographic Conventions</a></span></dt><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id701980">1.2. Pull-quote Conventions</a></span></dt><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id554675">1.3. Notes and Warnings</a></span></dt></dl></dd><dt><span class="section"><a href="pref-Users_Guide-Preface.html#sect-Users_Guide-Preface-We_Need_Feedback">2. We Need Feedback!</a></span></dt></dl></dd><dt><span class="preface"><a href="pref-Users_Guide-Introduction.html">Introduction</a></span></dt><dt><span class="chapter"><a href="chap-Users_Guide-Installing_Publican.html">1. Installing Publi
can</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux_operating_systems">1.1. Installing Publican on Linux operating systems</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Fedora">1.1.1. Installing Publican on Fedora</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Red_Hat_Enterprise_Linux_5">1.1.2. Installing Publican on Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Ubuntu">1.1.3. Installing Publican on Ubuntu</a></span></dt><dt><span cla
ss="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican_on_Linux_operating_systems-Installing_Publican_on_Debian">1.1.4. Installing Publican on Debian</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Windows_operating_systems">1.2. Installing Publican on Windows operating systems</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Publican_commands.html">2. Publican commands</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican_commands-Command_options">2.1. Command options</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican_commands-Actions">2.2. Actions</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Creating_a_document.html">3. Crea
ting a document</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_
a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation">3.3. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document">3.4. Building a document</a></span></dt><dd><dl><dt><span class=
"section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.4.1. Building a document created with Publican 0</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book">3.5. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.5.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.5.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging">3.6. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="chap-U
sers_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.6.1. Conditional tagging and translation</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.7. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.7.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.7.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_do
cumentation_of_pre_release_software">3.7.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Branding.html">4. Branding</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_defaults.c
fg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-publican_brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">cs
s</code> subdirectory</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code> subdirectory</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Using_sets.html">5. Using sets</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Frequently_Asked_Questions.html">6. Frequently Asked Questions</a></span></dt><dt><span class="appendix"><a h
ref="appe-Users_Guide-Disallowed_elements_and_attributes.html">A. Disallowed elements and attributes</a></span></dt><dd><dl><dt><span class="section"><a href="appe-Users_Guide-Disallowed_elements_and_attributes.html#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements">A.1. Disallowed elements</a></span></dt><dt><span class="section"><a href="appe-Users_Guide-Disallowed_elements_and_attributes.html#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes">A.2. Disallowed attributes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appe-Users_Guide-Command_summary.html">B. Command summary</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-publican.cfg_parameters.html">C. publican.cfg parameters</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-Language_codes.html">D. Language codes</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-Revision_History.html">E. Revision History</a><
/span></dt></dl></div></div><ul class="docnav"><li class="previous"></li><li class="next"><a accesskey="n" href="pref-Users_Guide-Preface.html"><strong>Next</strong>Preface</a></li></ul></body></html>
+ </div></div></div></div><hr /></div><div class="toc"><dl><dt><span class="preface"><a href="pref-Users_Guide-Preface.html">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id1663356">1. Document Conventions</a></span></dt><dd><dl><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id1663330">1.1. Typographic Conventions</a></span></dt><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id806457">1.2. Pull-quote Conventions</a></span></dt><dt><span class="section"><a href="pref-Users_Guide-Preface.html#id459050">1.3. Notes and Warnings</a></span></dt></dl></dd><dt><span class="section"><a href="pref-Users_Guide-Preface.html#sect-Users_Guide-Preface-We_Need_Feedback">2. We Need Feedback!</a></span></dt></dl></dd><dt><span class="preface"><a href="pref-Users_Guide-Introduction.html">Introduction</a></span></dt><dt><span class="chapter"><a href="chap-Users_Guide-Installing_Publican.html">1. Installing Pub
lican</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Installing_Publican-Installing_Publican_on_Linux">1.1. Linux operating systems</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Fedora">1.1.1. Fedora</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Red_Hat_Enterprise_Linux_5">1.1.2. Red Hat Enterprise Linux 5</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Ubuntu">1.1.3. Ubuntu</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-Linux_operating_systems-Debian">1.1.4. Debian</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Installing_Publican.html#sect-Users_Guide-
Installing_Publican-Windows_operating_systems">1.2. Windows operating systems</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Publican_commands.html">2. Publican commands</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican_commands-Command_options">2.1. Command options</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Publican_commands.html#sect-Users_Guide-Publican_commands-Actions">2.2. Actions</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Creating_a_document.html">3. Creating a document</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory">3.1. Files in the book directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file
">3.1.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml">3.1.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Author_Group.xml">3.1.3. Author_Group.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Chapter.xml">3.1.4. Chapter.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.xml">3.1.5. Doc_Name.xml</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent">3.1.6. Doc_Name.ent</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sec
t-Users_Guide-Files_in_the_book_directory-Revision_History.xml">3.1.7. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Adding_images">3.2. Adding images</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Adding_files">3.3. Adding files</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Preparing_a_document_for_translation">3.4. Preparing a document for translation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document">3.5. Building a document</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Building_a_document-Building_a_document_created_with_Publican_0">3.5.1. Building a document created with Publican 0</a></span></dt></dl></dd><
dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book">3.6. Packaging a book</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-Types_of_RPM_packages">3.6.1. Types of RPM packages</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Packaging_a_book-The_publican_package_command">3.6.2. The <code class="command">publican package</code> command</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging">3.7. Conditional tagging</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">3.7.1. Conditional tagging and translation</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Us
ers_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation">3.8. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.8.1. Denoting pre-release software</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.8.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">3.8.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Branding.html">4. Branding</a></span
></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Installing_a_brand">4.1. Installing a brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Creating_a_brand">4.2. Creating a brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory">4.3. Files in the brand directory</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_publican.cfg_file">4.3.1. The publican.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_defaults.cfg_file_and_overrides.cfg_file">4.3.2. The defaults.cfg file and overrides.cfg file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-publican_
brand.spec_file">4.3.3. publican-<em class="replaceable"><code>brand</code></em>.spec file</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-README">4.3.4. README</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-COPYING">4.3.5. COPYING</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-Common_Content_for_the_brand">4.3.6. Common Content for the brand</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_css_subdirectory">4.3.7. The <code class="filename">css</code> subdirectory</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Files_in_the_brand_directory-The_images_subdirectory">4.3.8. The <code class="filename">images</code
> subdirectory</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Users_Guide-Branding.html#sect-Users_Guide-Packaging_a_brand">4.4. Packaging a brand</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Using_sets.html">5. Using sets</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Stand_alone_sets">5.1. Stand-alone sets</a></span></dt><dt><span class="section"><a href="chap-Users_Guide-Using_sets.html#sect-Users_Guide-Using_sets-Distributed_sets">5.2. Distributed sets</a></span></dt></dl></dd><dt><span class="chapter"><a href="sect-Users_Guide-Website.html">6. Building a website with Publican</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure">6.1. The website structure</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-cfg_a
nd_db">6.1.1. Creating the website structure</a></span></dt></dl></dd><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-home_page">6.2. The home page</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-documents">6.3. Installing, updating and removing documents</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-documents-manual">6.3.1. Installing, updating and removing documents manually</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-documents-rpm">6.3.2. Installing, updating and removing documents as RPM packages</a></span></dt></dl></dd><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-automation">6.4. Automating publishing</a></span></dt></dl></dd><dt><span class="chapter"><a href="ch
ap-Users_Guide-Frequently_Asked_Questions.html">7. Frequently Asked Questions</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-Disallowed_elements_and_attributes.html">A. Disallowed elements and attributes</a></span></dt><dd><dl><dt><span class="section"><a href="appe-Users_Guide-Disallowed_elements_and_attributes.html#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_elements">A.1. Disallowed elements</a></span></dt><dt><span class="section"><a href="appe-Users_Guide-Disallowed_elements_and_attributes.html#sect-Users_Guide-Disallowed_elements_and_attributes-Disallowed_attributes">A.2. Disallowed attributes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appe-Users_Guide-Command_summary.html">B. Command summary</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-publican.cfg_parameters.html">C. publican.cfg parameters</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-Language_codes.html">D. Langua
ge codes</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-Revision_History.html">E. Revision History</a></span></dt></dl></div></div><ul class="docnav"><li class="previous"></li><li class="next"><a accesskey="n" href="pref-Users_Guide-Preface.html"><strong>Next</strong>Preface</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Introduction.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Introduction.html
index f921962..e6bac73 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Introduction.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Introduction.html
@@ -1,11 +1,12 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Introduction</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="pref-Users_Guide-Preface.html" title="Preface" /><link rel="next" href="chap-Users_Guide-Installing_Publican.html" title="Chapter 1. Installing Publican" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser o
r enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="pref-Users_Guide-Preface.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Installing_Publican.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="preface" title="Introduction" id="pref-Users_Guide-Introduction" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Introduction</h1></div></div></div><div class="para">
- <a id="id586523" class="indexterm"></a>
- <span class="application"><strong>Publican</strong></span> is a tool for publishing material authored in DocBook XML. This guide explains how to create and build books and articles using <span class="application"><strong>Publican</strong></span>. It is not a general DocBook XML tutorial; refer to <em class="citetitle">DocBook: The Definitive Guide</em> by Norman Walsh and Leonard Muellner, available at <a href="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</a> for more general help with DocBook XML.
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Introduction</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="pref-Users_Guide-Preface.html" title="Preface" /><link rel="next" href="chap-Users_Guide-Installing_Publican.html" title="Chapter 1. Installing Publican" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or
enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="pref-Users_Guide-Preface.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Installing_Publican.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="preface" title="Introduction" id="pref-Users_Guide-Introduction" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Introduction</h1></div></div></div><a id="id637095" class="indexterm"></a><div class="para">
+ <a id="id415568" class="indexterm"></a>
+ <span class="application"><strong>Publican</strong></span> <a id="id431045" class="indexterm"></a>
+ is a tool for publishing material authored in DocBook XML. This guide explains how to create and build books and articles using <span class="application"><strong>Publican</strong></span>. It is not a general DocBook XML tutorial; refer to <em class="citetitle">DocBook: The Definitive Guide</em> by Norman Walsh and Leonard Muellner, available at <a href="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</a> for more general help with DocBook XML.
</div><div class="para">
<span class="application"><strong>Publican</strong></span> began life as an internal tool used by Red Hat's Documentation Group (now known as Engineering Content Services). On occasion, this legacy is visible.
- </div><div class="formalpara"><h5 class="formalpara">Design</h5>
+ </div><div class="formalpara" id="form-Users_Guide-Introduction-Design"><h5 class="formalpara">Design</h5>
<span class="application"><strong>Publican</strong></span> is a publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, <span class="application"><strong>Publican</strong></span> works to ensure your XML is up to publishable standard.
</div><div class="para">
The branding functionality allows you to create your own presentation rules and look, overriding many parts of the default style to meet your publishing needs. Choices executed in code, however, are not changeable.
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Preface.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Preface.html
index eb66cb9..7eb8e4b 100644
--- a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Preface.html
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/pref-Users_Guide-Preface.html
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Preface</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 1.99" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.6-1" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="index.html" title="Users Guide" /><link rel="next" href="pref-Users_Guide-Introduction.html" title="Introduction" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="t
itle"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="index.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="pref-Users_Guide-Introduction.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="preface" title="Preface" id="pref-Users_Guide-Preface" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Preface</h1></div></div></div><div xml:lang="en-US" class="section" title="1. Document Conventions" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="id582094">1. Document Conventions</h2></div></div></div><div class="para">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Preface</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="index.html" title="Users Guide" /><link rel="next" href="pref-Users_Guide-Introduction.html" title="Introduction" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="ti
tle"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="index.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="pref-Users_Guide-Introduction.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="preface" title="Preface" id="pref-Users_Guide-Preface" lang="en-US"><div class="titlepage"><div><div><h1 class="title">Preface</h1></div></div></div><div xml:lang="en-US" class="section" title="1. Document Conventions" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="id1663356">1. Document Conventions</h2></div></div></div><div class="para">
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
</div><div class="para">
In PDF and paper editions, this manual uses typefaces drawn from the <a href="https://fedorahosted.org/liberation-fonts/">Liberation Fonts</a> set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
- </div><div class="section" title="1.1. Typographic Conventions"><div class="titlepage"><div><div><h3 class="title" id="id582071">1.1. Typographic Conventions</h3></div></div></div><div class="para">
+ </div><div class="section" title="1.1. Typographic Conventions"><div class="titlepage"><div><div><h3 class="title" id="id1663330">1.1. Typographic Conventions</h3></div></div></div><div class="para">
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
</div><div class="para">
<code class="literal">Mono-spaced Bold</code>
@@ -52,14 +52,12 @@
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Publican is a <em class="firstterm">DocBook</em> publishing system.
- </div></blockquote></div></div><div class="section" title="1.2. Pull-quote Conventions"><div class="titlepage"><div><div><h3 class="title" id="id701980">1.2. Pull-quote Conventions</h3></div></div></div><div class="para">
+ </div></blockquote></div></div><div class="section" title="1.2. Pull-quote Conventions"><div class="titlepage"><div><div><h3 class="title" id="id806457">1.2. Pull-quote Conventions</h3></div></div></div><div class="para">
Terminal output and source code listings are set off visually from the surrounding text.
</div><div class="para">
Output sent to a terminal is set in <code class="computeroutput">mono-spaced roman</code> and presented thus:
</div><pre class="screen">books Desktop documentation drafts mss photos stuff svn
-books_tests Desktop1 downloads images notes scripts svgs
-
-</pre><div class="para">
+books_tests Desktop1 downloads images notes scripts svgs</pre><div class="para">
Source-code listings are also set in <code class="computeroutput">mono-spaced roman</code> but add syntax highlighting as follows:
</div><pre class="programlisting">package org.<span class="perl_Function">jboss</span>.<span class="perl_Function">book</span>.<span class="perl_Function">jca</span>.<span class="perl_Function">ex1</span>;
@@ -79,9 +77,7 @@ books_tests Desktop1 downloads images notes scripts svgs
System.<span class="perl_Function">out</span>.<span class="perl_Function">println</span>(<span class="perl_String">"Echo.echo('Hello') = "</span> + echo.<span class="perl_Function">echo</span>(<span class="perl_String">"Hello"</span>));
}
-}
-
-</pre></div><div class="section" title="1.3. Notes and Warnings"><div class="titlepage"><div><div><h3 class="title" id="id554675">1.3. Notes and Warnings</h3></div></div></div><div class="para">
+}</pre></div><div class="section" title="1.3. Notes and Warnings"><div class="titlepage"><div><div><h3 class="title" id="id459050">1.3. Notes and Warnings</h3></div></div></div><div class="para">
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
</div><div class="note"><h2>Note</h2><div class="para">
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
@@ -89,7 +85,7 @@ books_tests Desktop1 downloads images notes scripts svgs
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' won't cause data loss but may cause irritation and frustration.
</div></div><div class="warning"><h2>Warning</h2><div class="para">
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
- </div></div></div></div><div class="section" title="2. We Need Feedback!" id="sect-Users_Guide-Preface-We_Need_Feedback"><div class="titlepage"><div><div><h2 class="title">2. We Need Feedback!</h2></div></div></div><a id="id592502" class="indexterm"></a><div class="para">
+ </div></div></div></div><div class="section" title="2. We Need Feedback!" id="sect-Users_Guide-Preface-We_Need_Feedback"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Preface-We_Need_Feedback">2. We Need Feedback!</h2></div></div></div><a id="id487605" class="indexterm"></a><div class="para">
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: <a href="https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&version=rawhide&component=publican">https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&version=rawhide&component=publican</a> against the product <span class="application"><strong>fedora</strong></span>. When submitting a bug report, be sure to mention the manual's identifier: <em class="citetitle">publican</em>
</div><div class="para">
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/sect-Users_Guide-Website.html b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/sect-Users_Guide-Website.html
new file mode 100644
index 0000000..3f4488e
--- /dev/null
+++ b/public_html/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/sect-Users_Guide-Website.html
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 6. Building a website with Publican</title><link rel="stylesheet" href="Common_Content/css/default.css" type="text/css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.0" /><meta name="package" content="Fedora_Contributor_Documentation-Users_Guide-1-en-US-1.0-3" /><meta name="keywords" content="publican, docbook, publishing" /><link rel="home" href="index.html" title="Users Guide" /><link rel="up" href="index.html" title="Users Guide" /><link rel="prev" href="chap-Users_Guide-Using_sets.html" title="Chapter 5. Using sets" /><link rel="next" href="chap-Users_Guide-Frequently_Asked_Questions.html" title="Chapter 7. Frequently Asked Questions" /></head><body class="toc_embeded "><div id="tocdiv" class="toc"><iframe id="tocframe" class="toc" src="../../../
../toc.html">This is an iframe, to view it upgrade your browser or enable iframe display.</iframe></div><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Using_sets.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" title="Chapter 6. Building a website with Publican" id="sect-Users_Guide-Website" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 6. Building a website with Publican</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Us
ers_Guide-Website-structure">6.1. The website structure</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-cfg_and_db">6.1.1. Creating the website structure</a></span></dt></dl></dd><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-home_page">6.2. The home page</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-documents">6.3. Installing, updating and removing documents</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-documents-manual">6.3.1. Installing, updating and removing documents manually</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-structure-documents-rpm">6.3.2. Installing, updating and removing documents as RPM packages</a></span></dt></dl></dd><dt><sp
an class="section"><a href="sect-Users_Guide-Website.html#sect-Users_Guide-Website-automation">6.4. Automating publishing</a></span></dt></dl></div><div class="para">
+ <span class="application"><strong>Publican</strong></span> not only builds documents for publication but can build and manage a documentation website as well. For a suite of documents that you maintain by yourself, you can use <span class="application"><strong>Publican</strong></span> to build a site on your local system; you can then upload the site to a webserver by whatever means you choose. This approach does not scale well, however, so for team-based documentation projects, <span class="application"><strong>Publican</strong></span> can generate RPM packages of documentation to install on the webserver.
+ </div><div class="para">
+ The websites that <span class="application"><strong>Publican</strong></span> creates consist of three parts: the website structure, a home page, and the documents published on the site.
+ </div><div class="section" title="6.1. The website structure" id="sect-Users_Guide-Website-structure"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-structure">6.1. The website structure</h2></div></div></div><div class="para">
+ The website structure itself consists of:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ a configuration file.
+ </div></li><li class="listitem"><div class="para">
+ an SQLite database file.
+ </div></li><li class="listitem"><div class="para">
+ a subdirectory for the published documents, which contains:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="filename">index.html</code> — an index page with no content that redirects to localized versions of a home page for the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">interactive.css</code> — a CSS stylesheet that contains styles for the navigation menu, map, and site statistics page.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">Sitemap</code> — an XML Sitemap to assist search engines to crawl the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">toc.html</code> — a static map of the documents on the site, to assist visitors to the site who do not have JavaScript enabled on their browsers.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">toc.js</code> — a JavaScript script that directs visitors to localized content based on the locale set in their browser and controls the presentation of the navigation menu.
+ </div></li><li class="listitem"><div class="para">
+ subdirectories for each language in which you publish. Initially, this contains: <code class="filename">Site_Statistics.html</code>
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="filename">Site_Statistics.html</code> — an overview of the documentation installed on the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">Site_Tech.html</code> — an overview of the technology used to build the site.
+ </div></li><li class="listitem"><div class="para">
+ <code class="filename">toc.html</code> — the table of contents for that language, initially empty.
+ </div></li></ul></div></li></ul></div></li></ul></div><div class="section" title="6.1.1. Creating the website structure" id="sect-Users_Guide-Website-structure-cfg_and_db"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Website-structure-cfg_and_db">6.1.1. Creating the website structure</h3></div></div></div><div class="para">
+ To build the website structure:
+ </div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ Create a new directory and change into it. For example, on a Linux system, run:
+ </div><pre class="screen"><code class="command">mkdir ~/docsite</code>
+<code class="command">cd ~/docsite</code></pre></li><li class="step" title="Step 2"><div class="para">
+ Run <code class="command">publican create_site</code>, specifying the following parameters:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="option">--site_config</code> — the name of the configuration file for your site, with the filename extension <code class="filename">.cfg</code>
+ </div></li><li class="listitem"><div class="para">
+ <code class="option">--db_file</code> — the name of the SQLite database file for your site, with the filename extension <code class="filename">.db</code>
+ </div></li><li class="listitem"><div class="para">
+ <code class="option">--toc_path</code> — the path to the directory in which you will place your documents
+ </div></li></ul></div><div class="para">
+ On a computer with an operating system other than Linux, also set:
+ </div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
+ <code class="option">--temp_path</code> — the path to the <code class="filename">templates/</code> directory of your <span class="application"><strong>Publican</strong></span> installation. On computers with Windows operating systems, this is typically <code class="filename"><em class="replaceable"><code>%SystemDrive%</code></em>\<em class="replaceable"><code>%ProgramFiles%</code></em>\Publican\templates</code>.
+ </div></li></ul></div><div class="para">
+ For example:
+ </div><pre class="screen"><code class="command">publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs</code></pre><div class="para">
+ Typically, you might give names to the site configuration file and database file that help you to recognize the site to which they belong. For example, for the <span class="application"><strong>FooMaster</strong></span> documentation site, you might call these files <code class="filename">foomaster.cfg</code> and <code class="filename">foomaster.db</code>.
+ </div><div class="para">
+ If you plan to install documentation on the webserver with <span class="application"><strong>Publican</strong></span>-generated RPM packages, set <em class="parameter"><code>--toc_path</code></em> to <code class="literal">/var/www/html/docs</code>. If you plan to build the site manually and upload it to the webserver, you can set <em class="parameter"><code>--toc_path</code></em> to whatever you choose.
+ </div></li><li class="step" title="Step 3"><div class="para">
+ If you plan to install <span class="application"><strong>Publican</strong></span>-generated RPM packages of documents on the site, transfer the site structure to the <code class="filename">/var/www/</code> directory of your webserver now by whatever process you usually use, for example <span class="application"><strong>scp</strong></span>, <span class="application"><strong>rsync</strong></span>, or an FTP client. If you plan to build the site manually, you can wait until you finish building the site and then upload the complete site.
+ </div></li></ol></div><div class="para">
+ To make <span class="application"><strong>Publican</strong></span> refresh the site structure at any time, run:
+ </div><pre class="screen"><code class="command">publican update_site --site_config <em class="replaceable"><code>path_to_site_configuration_file</code></em>.cfg</code></pre></div></div><div class="section" title="6.2. The home page" id="sect-Users_Guide-Website-structure-home_page"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-structure-home_page">6.2. The home page</h2></div></div></div><div class="para">
+ The <span class="application"><strong>Publican</strong></span>-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook <code class="sgmltag-element"><article></code> with an extra <em class="parameter"><code>web_home</code></em> parameter in its <code class="filename">publican.cfg</code> file. To create the home page:
+ </div><div class="procedure"><ol class="1"><li class="step" title="Step 1"><div class="para">
+ Change into a convenient directory and run the following <code class="command">publican create</code> command:
+ </div><pre class="screen"><code class="command">publican create --type Article --name <em class="replaceable"><code>page_name</code></em></code></pre><div class="para">
+ For example:
+ </div><pre class="screen"><code class="command">publican create --type Article --name Home_Page</code></pre></li><li class="step" title="Step 2"><div class="para">
+ Change into the article directory. For example:
+ </div><pre class="screen"><code class="command">cd Home_Page</code></pre></li><li class="step" title="Step 3"><div class="para">
+ Edit the <code class="filename">Article_Info.xml</code> file to configure the product name and version number. As with other documents created with <span class="application"><strong>Publican</strong></span>, the product name and product version number appear in a banner at the top of the page when built as HTML. Unless the entire site documents only a single version of a product, you might want to suppress the version number. If so, make the <code class="sgmltag-element"><productnumber></code> tag empty, thus:
+ </div><pre class="programlisting"><productnumber></productnumber></pre><div class="para">
+ You might also want to remove or re-order some of the typical content of a DocBook article as rendered by <span class="application"><strong>Publican</strong></span>, such as the <code class="sgmltag-element"><abstract></code>, <code class="sgmltag-element"><corpauthor></code>, and the transcluded <code class="sgmltag-element"><authorgroup></code> and <code class="sgmltag-element"><legalnotice></code>.
+ </div><div class="para">
+ Alternatively, edit the root XML file of your home page to remove the <code class="sgmltag-element"><xi:include></code> that links to <code class="filename">Article_Info.xml</code>. <span class="application"><strong>Publican</strong></span> still uses the information in <code class="filename">Article_Info.xml</code> for packaging, but does not include it on the page itself.
+ </div></li><li class="step" title="Step 4"><div class="para">
+ Edit the <code class="filename">publican.cfg</code> file to add the <em class="parameter"><code>web_home</code></em> parameter and set it to <code class="literal">1</code> (enabled):
+ </div><pre class="programlisting">web_home: 1</pre><div class="para">
+ The <em class="parameter"><code>web_home</code></em> parameter instructs <span class="application"><strong>Publican</strong></span> to process this document differently from product documentation. This is the only mandatory change to the <code class="filename">publican.cfg</code> file. The rest of this step describes other parameters that might be useful but which are not required.
+ </div><div class="para">
+ To style your home page to match your documents, add:
+ </div><pre class="programlisting">brand: <em class="replaceable"><code>name_of_brand</code></em></pre><div class="para">
+ If you emptied the <code class="sgmltag-element"><productnumber></code> tag in the <code class="filename">Article_Info.xml</code> file, set:
+ </div><pre class="programlisting">version: 0.1</pre><div class="para">
+ If the <code class="sgmltag-element"><title></code> or the <code class="sgmltag-element"><product></code> that you set in the <code class="filename">Article_Info</code> file included anything other than basic, unaccented Latin characters, set the <em class="parameter"><code>docname</code></em> and <em class="parameter"><code>product</code></em> as necessary.
+ </div><div class="para">
+ <span class="application"><strong>Publican</strong></span> creates a separate, translatable navigation menu for each language in which you publish documentation. However, a document is not available in a particular language, <span class="application"><strong>Publican</strong></span> links visitors to the translated version of that document. To specify the default, untranslated language for the site, set <em class="parameter"><code>def_lang</code></em> with a language code. For example:
+ </div><pre class="programlisting">def_lang: fr-FR</pre><div class="para">
+ With <em class="parameter"><code>def_lang</code></em> set to <code class="literal">fr-FR</code>, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.
+ </div><div class="para">
+ The navigation menu also includes a search box that submits a query to Google. To constrain the results to only hits on your site, set the <em class="parameter"><code>web_host</code></em> parameter. For example, to limit the Google results to only pages on your website at <code class="literal">http://docs.example.com</code>, set:
+ </div><pre class="programlisting">web_host: http://docs.example.com</pre><div class="para">
+ <span class="application"><strong>Publican</strong></span> also uses the value set for <em class="parameter"><code>web_host</code></em> to construct the URLs in the XML <code class="filename">Sitemap</code> that it creates for search engine crawlers. Therefore, when you set this parameter, make sure you use the full URL, including the protocol (for example, <code class="literal">http://</code>).
+ </div><div class="para">
+ If you prefer to use a search engine other than Google, or want to customize the search, use the <em class="parameter"><code>web_search</code></em> parameter to specify the entire content of a HTML <code class="sgmltag-element"><form></code>. For example, to construct a Yahoo! search limited to <code class="literal">docs.example.com</code>, set:
+ </div><pre class="programlisting">web_search: '<span class="perl_Keyword"><form</span><span class="perl_Others"> target=</span><span class="perl_String">"_top"</span><span class="perl_Others"> method=</span><span class="perl_String">"get"</span><span class="perl_Others"> action=</span><span class="perl_String">"http://search.yahoo.com/search"</span><span class="perl_Keyword">></span> <span class="perl_Keyword"><div</span><span class="perl_Others"> class=</span><span class="perl_String">"search"</span><span class="perl_Keyword">></span> <span class="perl_Keyword"><input</span><span class="perl_Others"> type=</span><span class="perl_String">"text"</span><span class="perl_Others"> name=</span><span class="perl_String">"p"</span><span class="perl_Others"> value=</span><span class="perl_String">""</span> <span class="perl_Keyword">/></span> <span class="perl_Keyword"><input</span><span class="perl_Others"> type=</span><span class="perl_String">"hidden"</s
pan><span class="perl_Others"> name=</span><span class="perl_String">"vs"</span><span class="perl_Others"> value=</span><span class="perl_String">"docs.example.com"</span> <span class="perl_Keyword">/></span> <span class="perl_Keyword"><input</span><span class="perl_Others"> type=</span><span class="perl_String">"submit"</span><span class="perl_Others"> value=</span><span class="perl_String">"###Search###"</span> <span class="perl_Keyword">/></span> <span class="perl_Keyword"></div></span> <span class="perl_Keyword"></form></span>'</pre><div class="para">
+ Refer to the documentation of your chosen search engine for details of how to construct custom searches.
+ </div><div class="para">
+ If you set <code class="literal">value="###Search###"</code> on the code for a submit button, <span class="application"><strong>Publican</strong></span> uses the word <code class="literal">Search</code> on the button, localized into any language that <span class="application"><strong>Publican</strong></span> supports.
+ </div><div class="important"><h2>Important — Publican does not validate the web_search parameter</h2><div class="para">
+ <span class="application"><strong>Publican</strong></span> does not validate the <em class="parameter"><code>web_search</code></em> parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.
+ </div></div></li><li class="step" title="Step 5"><div class="para">
+ Edit the content of the <code class="filename"><em class="replaceable"><code>page_name</code></em>.xml</code> file (for example, <code class="filename">Home_Page.xml</code>) as you would any other DocBook document.
+ </div><div class="para">
+ If you remove the <code class="sgmltag-element"><xi:include></code> that links to <code class="filename">Article_Info.xml</code>, specify a title for your page in the following format:
+ </div><pre class="programlisting"><span class="perl_Keyword"><title</span><span class="perl_Others"> role=</span><span class="perl_String">"producttitle"</span><span class="perl_Keyword">></span>FooMaster Documentation<span class="perl_Keyword"></title></span></pre></li><li class="step" title="Step 6"><div class="para">
+ If you publish documentation in more than one language, create a set of POT files and a set of PO files for each language with the <code class="command">publican update_pot</code> and <code class="command">publican update_po</code> commands.
+ </div></li><li class="step" title="Step 7"><div class="para">
+ To customize the logo at the top of the navigation menu that provides a link back to the home page, create a PNG image 300 px × 100 px and name it <code class="filename">web_home.png</code>. Place this image in the <code class="filename">images/</code> directory in the document's XML directory, for example <code class="filename">en-US/images/</code>.
+ </div></li><li class="step" title="Step 8"><div class="para">
+ If you are building your website manually, build the home page in single-page HTML format with the <code class="option">--embedtoc</code> option and install it in your website structure. For example:
+ </div><pre class="screen"><code class="command">publican build --publish --formats html-single --embedtoc</code>
+<code class="command">publican install_book --site_config ~/docsite/foomaster.cfg</code></pre><div class="para">
+ Alternatively, to build RPM packages to install on your webserver, run the following command for each language in which you publish documentation:
+ </div><pre class="screen"><code class="command">publican package --binary --lang <em class="replaceable"><code>language_code</code></em></code></pre></li></ol></div></div><div class="section" title="6.3. Installing, updating and removing documents" id="sect-Users_Guide-Website-structure-documents"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-structure-documents">6.3. Installing, updating and removing documents</h2></div></div></div><div class="section" title="6.3.1. Installing, updating and removing documents manually" id="sect-Users_Guide-Website-structure-documents-manual"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Website-structure-documents-manual">6.3.1. Installing, updating and removing documents manually</h3></div></div></div><div class="para">
+ To install a document on a website that you are building manually, change into the directory that contains the source for the document and run:
+ </div><pre class="screen"><code class="command">publican build --embedtoc --formats=<em class="replaceable"><code>list_of_formats</code></em> --langs=<em class="replaceable"><code>language_codes</code></em> --publish</code>
+<code class="command">publican install_book --site_config <em class="replaceable"><code>path_to_site_configuration_file</code></em>.cfg --lang <em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
+ Note that you can run a single <code class="command">publican build</code> command for all languages that you want to publish, but must run a separate <code class="command">publican install_book</code> for each language. You must include <code class="literal">html</code> as one of the formats in the <code class="command">publican build</code>; optionally, include any or all of the following formats in a comma-separated list: <code class="literal">html-single</code>, <code class="literal">pdf</code>, and <code class="literal">epub</code>.
+ </div><div class="para">
+ To update a document, change into the directory that contains the updated source for the document and run the same commands as if you were installing the document for the first time. <span class="application"><strong>Publican</strong></span> replaces the old version with the new version.
+ </div><div class="para">
+ To remove a document, change into the directory that contains the source for the document and run:
+ </div><pre class="screen"><code class="command">publican remove_book --site_config <em class="replaceable"><code>path_to_site_configuration_file</code></em>.cfg --lang <em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
+ When you have installed the documents, the website is ready to upload to your webserver by whatever process you usually use, for example <span class="application"><strong>scp</strong></span>, <span class="application"><strong>rsync</strong></span>, or an FTP client.
+ </div></div><div class="section" title="6.3.2. Installing, updating and removing documents as RPM packages" id="sect-Users_Guide-Website-structure-documents-rpm"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Website-structure-documents-rpm">6.3.2. Installing, updating and removing documents as RPM packages</h3></div></div></div><div class="para">
+ To use an RPM package to install a document on a website, change into the directory that contains the source for the document and run:
+ </div><pre class="screen"><code class="command">publican package --binary --lang <em class="replaceable"><code>language_code</code></em></code></pre><div class="para">
+ <span class="application"><strong>Publican</strong></span> builds an RPM package and places it in the <code class="filename">/tmp/rpms/noarch/</code> directory of the document. Note that by default, <span class="application"><strong>Publican</strong></span> generates an RPM package to install on a Red Hat Enterprise Linux 5 server. To build an RPM package to install on a server that runs a different operating system, set the <em class="parameter"><code>os_var</code></em> parameter in the <code class="filename">publican.cfg</code> file.
+ </div><div class="para">
+ Either upload the document packages to the webserver and install them with the <code class="command">rpm -i</code> or <code class="command">yum localinstall</code> command, or place the packages in a repository and configure the webserver to install from that repository when you run <code class="command">yum install</code>.
+ </div><div class="para">
+ To update a document, build a new package with a higher <code class="sgmltag-element"><edition></code> number or <code class="sgmltag-element"><pubsnumber></code> in the <code class="filename">Book_Info.xml</code> or <code class="filename">Article_Info.xml</code>. <span class="application"><strong>Publican</strong></span> uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, <span class="application"><strong>yum</strong></span> can replace the old version with the new when you run <code class="command">yum localinstall</code> for a local package, or <code class="command">yum update</code> for a package fetched from a repository.
+ </div><div class="para">
+ Remove a document from the webserver with the <code class="command">rpm -e</code> or <code class="command">yum erase</code> command.
+ </div></div></div><div class="section" title="6.4. Automating publishing" id="sect-Users_Guide-Website-automation"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Website-automation">6.4. Automating publishing</h2></div></div></div><div class="para">
+ Because <span class="application"><strong>Publican</strong></span> can generate RPM packages, you can use <span class="application"><strong>Publican</strong></span> together with an RPM build system like <span class="application"><strong>Koji</strong></span> to automate your publishing process. When a document is ready for publication, the writer or translator runs the following command:
+ </div><pre class="screen"><code class="command">publican package --cvs</code></pre><div class="para">
+ <span class="application"><strong>Publican</strong></span> then carries out the following actions:
+ </div><div class="orderedlist"><ol><li class="listitem"><div class="para">
+ generates an SRPM
+ </div></li><li class="listitem"><div class="para">
+ imports the SRPM into the CVS root for the <span class="application"><strong>Koji</strong></span> instance specified in the document's <code class="filename">publican.cfg</code> file
+ </div></li><li class="listitem"><div class="para">
+ runs <code class="command">cvs up</code>
+ </div></li><li class="listitem"><div class="para">
+ runs <code class="command">make build</code>
+ </div></li></ol></div><div class="para">
+ If your webserver periodically checks for updated packages in the repository in which <span class="application"><strong>Koji</strong></span> places built packages, the webserver can automatically install updated versions of your documents.
+ </div><div class="para">
+ You might also implement a system of tags where a writer or translator could run <code class="command">koji tag-pkg</code> to apply a tag that tells the webserver to publish the document only on a staging site for proofreading and review; or a different tag that tells the webserver to publish the document publicly.
+ </div><div class="para">
+ To prepare a document for building in a <span class="application"><strong>Koji</strong></span> instance, edit the <code class="filename">publican.cfg</code> file to specify:
+ </div><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>cvs_branch</code></em></span></dt><dd><div class="para">
+ the name of the <em class="firstterm">branch</em> for the package; typically, a particular software version.
+ </div></dd><dt><span class="term"><em class="parameter"><code>cvs_pkg</code></em></span></dt><dd><div class="para">
+ the name of the package in CVS. <span class="application"><strong>Publican</strong></span> defaults to: <code class="literal"><em class="replaceable"><code>product</code></em>-<em class="replaceable"><code>title</code></em>-<em class="replaceable"><code>product_version</code></em>-web-<em class="replaceable"><code>language</code></em>-<em class="replaceable"><code>edition</code></em>-<em class="replaceable"><code>pubsnumber</code></em></code>
+ </div></dd><dt><span class="term"><em class="parameter"><code>cvs_root</code></em></span></dt><dd><div class="para">
+ the CVS root into which to import the SRPM. For example, the CVS root for the Fedora Project's <span class="application"><strong>Koji</strong></span> instance is <code class="literal">:ext:USERNAME at cvs.fedoraproject.org:/cvs/pkgs</code>
+ </div></dd></dl></div><div class="para">
+ For more information about <span class="application"><strong>Koji</strong></span>, visit <a href="https://fedorahosted.org/koji/wiki">https://fedorahosted.org/koji/wiki</a>.
+ </div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Using_sets.html"><strong>Prev</strong>Chapter 5. Using sets</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Next</strong>Chapter 7. Frequently Asked Questions</a></li></ul></body></html>
diff --git a/public_html/en-US/Fedora_Contributor_Documentation/1/pdf/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.pdf b/public_html/en-US/Fedora_Contributor_Documentation/1/pdf/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.pdf
index e6362a4..e802c42 100644
Binary files a/public_html/en-US/Fedora_Contributor_Documentation/1/pdf/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.pdf and b/public_html/en-US/Fedora_Contributor_Documentation/1/pdf/Users_Guide/Fedora_Contributor_Documentation-1-Users_Guide-en-US.pdf differ
More information about the docs-commits
mailing list