Wed Jun 17 01:04:40 UTC 2009

Author: rlandmann

Update of /cvs/fedora/web/html/docs/publican-user-guide/en-US
In directory cvs1.fedora.phx.redhat.com:/tmp/cvs-serv13052/en-US

Added Files:
	appe-Users_Guide-Makefile_Parameters.html 
	appe-Users_Guide-Revision_History.html 
	chap-Users_Guide-Branding.html 
	chap-Users_Guide-Frequently_Asked_Questions.html 
	chap-Users_Guide-Introduction.html 
	chap-Users_Guide-Using_Sets.html 
	chap-Users_Guide-Using_the_publican_package.html index.html 
	pref-Users_Guide-Preface.html 
	sect-Users_Guide-Conditional_Tagging.html 
	sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html 
	sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html 
	sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html 
	sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html 
	sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html 
	sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html 
	sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html 
	sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html 
	sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html 
	sect-Users_Guide-Preface-We_Need_Feedback.html 
	sect-Users_Guide-Using_Sets-Distributed_Sets.html 
	sect-Users_Guide-Using_the_publican_package-Adding_Images.html 
	sect-Users_Guide-Using_the_publican_package-Building_a_Book.html 
	sect-Users_Guide-Using_the_publican_package-Creating_a_Book.html 
	sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html 
	sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html 
Log Message:
move en-US

--- NEW FILE appe-Users_Guide-Makefile_Parameters.html ---
<?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><title>AppendixÂ A.Â Makefile Parameters</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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Â 5.Â Frequently Asked Questions"/><link rel="next" href="appe-Users_Guide-Revision_History.html" title="AppendixÂ B.Â Revision History"/></head><body class=""><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-Revision_History.html"><strong>Next</strong></a></li></ul><div class="appendix" lang="en-US"><div class="titlepage"><div><div><h1 id="appe-Users_Guide-Makefile_Parameters" class="title">Makefile Parameters</h1></div></div></div><div class="para">
		Every Book, Article or Book Set has a Makefile in its root directory. Parameters that can be set in a Book's Makefile are:
	</div><div class="variablelist"><dl><dt><span class="term">BOOKS</span></dt><dd><div class="para">
					This defines the Books a Set contains. It is only useful for Book Sets.
				</div><div class="para">
					Default value: Undefined.
				</div></dd><dt><span class="term">BRAND</span></dt><dd><div class="para">
					This parameter tells Publican which Brand to apply to a book's html and pdf output. Its default value is: common.
				</div></dd><dt><span class="term">BREW_DIST</span></dt><dd><div class="para">
					BREW_DIST sets the Brew tag for desktop RPMs. Default: dist-5E-qu-candidate.
				</div></dd><dt><span class="term">CHUNK_FIRST</span></dt><dd><div class="para">
					Controls chunking of first sections. 0 or 1. Default: 0.
				</div></dd><dt><span class="term">CHUNK_SECTION_DEPTH</span></dt><dd><div class="para">
					Override the max section depth to chunk to. Default: 4.
				</div></dd><dt><span class="term">COMMON_CONFIG</span></dt><dd><div class="para">
					Sets the path to Publican's configuration and common files, including Brand files. Default: <code class="filename">/usr/share/publican</code>.
				</div></dd><dt><span class="term">CONFIDENTIAL</span></dt><dd><div class="para">
					The default value â€” 0 â€” is not confidential. To set a book to confidential, change this to 1.
				</div><div class="para">
					Setting this parameter to 1 places a large <span class="emphasis"><em>Confidential</em></span> footer on each page.
				</div></dd><dt><span class="term">DEFAULT_LANGS</span></dt><dd><div class="para">
					Languages that should be included in xi:include even if the translation is not complete. Used in update_includes. Default: Undefined.
				</div></dd><dt><span class="term">DESKTOP</span></dt><dd><div class="para">
					Use the desktop CSS (1) or not (0). Default: 0
				</div></dd><dt><span class="term">DOC_TYPE</span></dt><dd><div class="para">
					Sets the sort of publication being produced: Book, Article or Set. Default value is Book. This paremeter has no relationship to the DOCTYPE declaration in a publication's XML files.
				</div></dd><dt><span class="term">DOC_URL</span></dt><dd><div class="para">
					Sets the URL used for the link in the right-hand header of every html page. Also sets the URL entry in a publication's RPM spec file. Default: https://fedorahosted.org/publican
				</div></dd><dt><span class="term">DT_OBSOLETES</span></dt><dd><div class="para">
					A comma seperated list of desk top packages the package should obsolete. Default: undefined.
				</div></dd><dt><span class="term">EMBEDTOC</span></dt><dd><div class="para">
					Embed the web navigation TOC in the html. 0 or 1. Default: 0.
				</div></dd><dt><span class="term">GENERATE_SECTION_TOC_LEVEL</span></dt><dd><div class="para">
					Include a Table of Contents at the given section level. Valid values: 0 â€“ 5. Default: 0.
				</div></dd><dt><span class="term">IGNORED_TRANSLATIONS</span></dt><dd><div class="para">
					When building, replace any languages in this list with the source langauge text. This allows you to work on translations without shipping incomplete translations. Default: Undefined.
				</div></dd><dt><span class="term">OTHER_LANGS</span></dt><dd><div class="para">
					Space seperated list of language locales. Default: Undefined.
				</div></dd><dt><span class="term">PRODUCT</span></dt><dd><div class="para">
					The product this book is associated with. Default: Documentation.
				</div></dd><dt><span class="term">PROD_URL</span></dt><dd><div class="para">
					Sets the URL used for the link in the left-hand header of every html page. Default: https://fedorahosted.org/publican
				</div></dd><dt><span class="term">SHOW_REMARKS</span></dt><dd><div class="para">
					Display contents of remark tags in output? Two possible values: 0 (off) or 1 (on). Off by default.
				</div></dd><dt><span class="term">TOC_SECTION_DEPTH</span></dt><dd><div class="para">
					How many section levels should be included in the main Table of Contents. Default: 2.
				</div></dd><dt><span class="term">WEB_BREW_DIST</span></dt><dd><div class="para">
					WEB_BREW_DIST sets the Brew tag for web RPMs. Default: docs-5E.
				</div></dd><dt><span class="term">WEB_OBSOLETES</span></dt><dd><div class="para">
					A comma seperated list of web site packages the web package should obsolete. Default: Undefined.
				</div></dd><dt><span class="term">XML_LANG</span></dt><dd><div class="para">
					Language of a publication's source xml. Default: en-US (US English).
				</div></dd><dt><span class="term">USE_SAXON</span></dt><dd><div class="para">
					Use saxon for xslt. Two possible values: 0 (off) or 1 (on). On by default.
				</div></dd><dt><span class="term">USE_XALAN</span></dt><dd><div class="para">
					Test xalan for xslt. 0 or 1. Default: 0.
				</div></dd></dl></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Frequently_Asked_Questions.html"><strong>Prev</strong>ChapterÂ 5.Â 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-Revision_History.html"><strong>Next</strong>AppendixÂ B.Â Revision History</a></li></ul></body></html>

--- NEW FILE appe-Users_Guide-Revision_History.html ---
<?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><title>AppendixÂ B.Â Revision History</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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-Makefile_Parameters.html" title="AppendixÂ A.Â Makefile Parameters"/></head><body class=""><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-Makefile_Parameters.html"><strong>P
 rev</strong></a></li><li class="next"/></ul><div class="appendix" lang="en-US"><div class="titlepage"><div><div><h1 id="appe-Users_Guide-Revision_History" 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 0.5</td><td align="left">Thu Dec 18 2008</td><td align="left"><span class="author"><span class="firstname">Jeff</span> <span class="surname">Fearn</span></span></td></tr><tr><td align="left" colspan="3">
					<table class="simplelist" border="0" summary="Simple list"><tr><td>Added appendix on Makefile parameters</td></tr><tr><td>Added entry to FAQ about java heap space.</td></tr></table>
				</td></tr><tr><td align="left">Revision 0.4</td><td align="left">Tue Nov 25 2008</td><td align="left"><span class="author"><span class="firstname">Brian</span> <span class="surname">FortÃ©</span></span></td></tr><tr><td align="left" colspan="3">
					<table class="simplelist" border="0" summary="Simple list"><tr><td>Added "Pre-release and draft documentation" section.</td></tr></table>
				</td></tr><tr><td align="left">Revision 0.3</td><td align="left">Fri Oct 10 2008</td><td align="left"><span class="author"><span class="firstname">Don</span> <span class="surname">Domingo</span></span></td></tr><tr><td align="left" colspan="3">
					<table class="simplelist" border="0" summary="Simple list"><tr><td>Adding "Conditional Tagging" section.</td></tr></table>
				</td></tr><tr><td align="left">Revision 0.2</td><td align="left">Fri Sep 05 2008</td><td align="left"><span class="author"><span class="firstname">Brian</span> <span class="surname">FortÃ©</span></span></td></tr><tr><td align="left" colspan="3">
					<table class="simplelist" border="0" summary="Simple list"><tr><td>General edits and updates related to Publican 0.36 release. Also, new section added to Chapter 3.3.</td></tr></table>
				</td></tr><tr><td align="left">Revision 0.1.1</td><td align="left">Fri Jun 06 2008</td><td align="left"><span class="author"><span class="firstname">Murray</span> <span class="surname">McAllister</span></span></td></tr><tr><td align="left" colspan="3">
					<table class="simplelist" border="0" summary="Simple list"><tr><td>Updated Branding to note addition of oVirt and GIMP brands</td></tr></table>
				</td></tr><tr><td align="left">Revision 0.1</td><td align="left">Tue May 16 2008</td><td align="left"><span class="author"><span class="firstname">Jeff</span> <span class="surname">Fearn</span></span></td></tr><tr><td align="left" colspan="3">
					<table class="simplelist" border="0" summary="Simple list"><tr><td>Updated FAQ</td></tr></table>
				</td></tr><tr><td align="left">Revision 0.0</td><td align="left">Thu Dec 13 2007</td><td align="left"><span class="author"><span class="firstname">Murray</span> <span class="surname">McAllister</span></span></td></tr><tr><td align="left" colspan="3">
					<table class="simplelist" border="0" summary="Simple list"><tr><td>Initial content release</td></tr></table>
				</td></tr></table></div>
	</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="appe-Users_Guide-Makefile_Parameters.html"><strong>Prev</strong>AppendixÂ A.Â Makefile 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></ul></body></html>

--- NEW FILE chap-Users_Guide-Branding.html ---
<?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><title>ChapterÂ 2.Â Branding</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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-Introduction.html" title="ChapterÂ 1.Â Introduction"/><link rel="next" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/></head><body class=""><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-Introduction.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="chap-Users_Guide-Using_the_publican_package.html"><strong>Next</strong></a></li></ul><div class="chapter" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="chap-Users_Guide-Branding">ChapterÂ 2.Â Branding</h2></div></div></div><div class="para">
		Publican uses brands to apply a consistent look and style to html and pdf output. Brands are collections of files installed to <code class="filename">/usr/share/publican/Common_Content/<em class="replaceable"><code>brand</code></em>/</code>. Publican ships with one brand, <code class="filename">common/</code>.
	</div><div class="para">
		Brands for JBoss, GIMP, Red Hat Enterprise Linux, Fedora and oVirt can be installed using <code class="command">yum install publican-<em class="replaceable"><code>brand</code></em></code>.
	</div><div class="para">
		Each currently available brand is distributed under a brand-specific license as follows:
	</div><div class="table" id="tabl-Users_Guide-Branding-Current_Brands_and_their_packages"><div class="table-contents"><table summary="Current Brands and their packages" border="1"><colgroup><col width="1*"/><col width="2*"/><col width="1*"/><col width="3*"/></colgroup><thead><tr><th>
						Brand
					</th><th>
						License
					</th><th>
						Package
					</th><th>
						Comment
					</th></tr></thead><tbody><tr><td>
						common
					</td><td>
						<a href="http://www.gnu.org/licenses/fdl.html">GFDL Version 1.2</a>
					</td><td>
						publican
					</td><td>
						GPL compatible license. No options.
					</td></tr><tr><td>
						RedHat
					</td><td>
						<a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
					</td><td>
						publican-redhat
					</td><td>
						No Options.
					</td></tr><tr><td>
						Fedora
					</td><td>
						<a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
					</td><td>
						publican-fedora
					</td><td>
						No Options.
					</td></tr><tr><td>
						JBoss
					</td><td>
						<a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
					</td><td>
						publican-jboss
					</td><td>
						No Options.
					</td></tr><tr><td>
						oVirt
					</td><td>
						<a href="http://www.opencontent.org/openpub/">OPL 1.0</a>
					</td><td>
						publican-ovirt
					</td><td>
						No Options.
					</td></tr><tr><td>
						GIMP
					</td><td>
						<a href="http://www.gnu.org/licenses/fdl.html">GFDL Version 1.2</a>
					</td><td>
						publican-gimp
					</td><td>
						GPL compatible license. No options.
					</td></tr></tbody></table></div><h6>TableÂ 2.1.Â Current Brands and their packages</h6></div><br class="table-break"/><div class="para">
		To make a custom brand, use the brand with the license you wish to use as base for your new brand. If you want to use a different open source license, and none of the shipped brands are compatible with your license, submit a <a href="https://bugzilla.redhat.com/">bug using Red Hat Bugzilla</a> against the product <span class="application"><strong>fedora</strong></span>, component <em class="citetitle">publican</em>, and ask for a new brand to be shipped under that license.
	</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Introduction.html"><strong>Prev</strong>ChapterÂ 1.Â Introduction</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-Using_the_publican_package.html"><strong>Next</strong>ChapterÂ 3.Â Using the publican package</a></li></ul></body></html>

--- NEW FILE chap-Users_Guide-Frequently_Asked_Questions.html ---
<?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><title>ChapterÂ 5.Â Frequently Asked Questions</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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-Using_Sets-Distributed_Sets.html" title="4.2.Â Distributed Sets"/><link rel="next" href="appe-Users_Guide-Makefile_Parameters.html" title="AppendixÂ A.Â Makefile Parameters"/></head><body class=""><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-Using_Sets-Distributed_Sets.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="appe-Users_Guide-Makefile_Parameters.html"><strong>Next</strong></a></li></ul><div class="chapter" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="chap-Users_Guide-Frequently_Asked_Questions">ChapterÂ 5.Â Frequently Asked Questions</h2></div></div></div><div class="qandaset"><dl><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2332">
					How do I add a language to my book?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2345">
					How do I add another language to my book?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2366">
					What if I only use the country code? For example, OTHER_LANGS = en de fr?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2379">
					How do I update all po files?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2389">
					Where can I get a complete list of make targets?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2399">
					Where can I get a complete list of parameters that can be set in the Makefile?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2412">
					Where are the Publican common files located?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2422">
					Can I use the OASIS DocBook DTD for XML completion in editors such as Kate?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2432">
					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#d0e2483">
					Is it possible to include arbitrary files in tar and RPM files?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2504">
					Why does publican give me warnings about unknown tags?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2511">
					How do I find out which tags have been tested in publican?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2521">
					Why does publican give me an error about banned tags?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2531">
					How do I find out which tags are banned in publican?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2541">
					Which brands enable STRICT mode?
				</a></dt><dt>Q: <a href="chap-Users_Guide-Frequently_Asked_Questions.html#d0e2548">
					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#d0e2568">
					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#d0e2584">
					Why does Jeff call Isaac Ivan?
				</a></dt></dl><div class="qandaset"><div class="qandaentry"><div class="question" id="d0e2332"><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">
					Edit your book's <code class="filename">Makefile</code> and uncomment the <code class="computeroutput">OTHER_LANGS</code> entry. Add the required language code after the '=' sign.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2345"><label>Q:</label><div class="data"><div class="para">
					How do I add another language to my book?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Append the language to <code class="computeroutput">OTHER_LANGS</code> in the <code class="filename">Makefile</code>. Run the <code class="command">make update-po-<em class="replaceable"><code>language</code></em></code> command. For example, <code class="command">make update-po-ja-JP</code> creates the Japanese language directory and the Japanese po files.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2366"><label>Q:</label><div class="data"><div class="para">
					What if I only use the country code? For example, <code class="computeroutput">OTHER_LANGS = en de fr</code>?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Run the <code class="command">make update-po-en</code> command.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2379"><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">make update-po-all</code> command.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2389"><label>Q:</label><div class="data"><div class="para">
					Where can I get a complete list of make targets?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Run the <code class="command">make help</code> command.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2399"><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">Makefile</code>?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Run the <code class="command">make help_params</code> command.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2412"><label>Q:</label><div class="data"><div class="para">
					Where are the Publican 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>.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2422"><label>Q:</label><div class="data"><div class="para">
					Can I use the OASIS DocBook DTD for XML completion in editors such as Kate?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Yes. The OASIS DocBook DTD is included in the publican package, and is located here: <code class="filename">/usr/share/publican/xsl/docbook.dtd.xml</code>
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2432"><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" id="proc-Users_Guide-Frequently_Asked_Questions-Including_code_samples"><h6>ProcedureÂ 5.1.Â Including code samples</h6><ol class="1"><li><div class="para">
							Create the extras directory 
<pre class="programlisting"><code class="command">mkdir <code class="filename">en-US/extras</code></code>
</pre>
						</div></li><li><div class="para">
							Copy the code file to the extras directory 
<pre class="programlisting"><code class="command">cp <code class="filename">~/samples/foo.c en-US/extras/.</code></code>
</pre>
						</div></li><li><div class="para">
							<code class="sgmltag-element">xi:include</code> the sample file in your xml file 
<pre class="programlisting"><programlisting>
<xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
</pre>
						</div></li><li><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" id="d0e2483"><label>Q:</label><div class="data"><div class="para">
					Is it possible to include arbitrary files in tar and RPM files?
				</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 tar or SRPM files created by publican.
				</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" id="d0e2504"><label>Q:</label><div class="data"><div class="para">
					Why does publican 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" id="d0e2511"><label>Q:</label><div class="data"><div class="para">
					How do I find out which tags have been tested in publican?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Run <code class="command">xmlClean --known</code>
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2521"><label>Q:</label><div class="data"><div class="para">
					Why does publican give me an error about banned tags?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					This error indicates that the brand you are using has STRICT mode enabled for <code class="command">xmlClean</code> and that the tag in question has been marked as undesirable. The error message should contain a reason why the tag was banned.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2531"><label>Q:</label><div class="data"><div class="para">
					How do I find out which tags are banned in publican?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Run <code class="command">xmlClean --banned</code>
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2541"><label>Q:</label><div class="data"><div class="para">
					Which brands enable STRICT mode?
				</div></div></div><div class="answer"><label>A:</label><div class="data"><div class="para">
					Currently the Red Hat and JBoss brands enable STRICT mode.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2548"><label>Q:</label><div class="data"><div class="para">
					I get an error saying Batik is not in the classpath but batik 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.
				</div><div class="para">
					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" id="d0e2568"><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 FOP. 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 50MB and allows it to grow to a maximum of 700MB.
				</div></div></div></div><div class="qandaentry"><div class="question" id="d0e2584"><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="sect-Users_Guide-Using_Sets-Distributed_Sets.html"><strong>Prev</strong>4.2.Â Distributed 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-Makefile_Parameters.html"><strong>Next</strong>AppendixÂ A.Â Makefile Parameters</a></li></ul></body></html>

--- NEW FILE chap-Users_Guide-Introduction.html ---
<?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><title>ChapterÂ 1.Â Introduction</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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-Preface-We_Need_Feedback.html" title="2.Â We Need Feedback!"/><link rel="next" href="chap-Users_Guide-Branding.html" title="ChapterÂ 2.Â Branding"/></head><body class=""><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-Preface-We_Need_Feedback.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 class="chapter" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="chap-Users_Guide-Introduction">ChapterÂ 1.Â Introduction</h2></div></div></div><div class="para">
		Publican is a tool for publishing material authored in DocBook XML. This guide explains how to to create and build books and articles using publican. It is not a DocBook XML tutorial and concentrates solely on using the publican tools. See <a href="http://docbook.org/tdg/en/html/docbook.html">docbook.org</a> for information about DocBook XML.
	</div><div class="para">
		Publican 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" id="form-Users_Guide-Introduction-Design">Design</h5>
			Publican is a publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, publican 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, over-riding many parts of the default style to meet your publishing needs. Choices executed in code, however, are not changeable.
	</div><div class="para">
		Entities, for example, can be validly defined in any XML file. However, to ensure the DTD declaration is present, valid and standardized, Publican rewrites the declaration in every XML file before it builds a book or article. Consequently, all entities declared in all XML files are lost. Publican, therefore, requires you define Entities in the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.ent</code> file (see <a class="xref" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html" title="3.3.7.Â Book_Name.ent">SectionÂ 3.3.7, â€œBook_Name.entâ€</a>).
	</div><div class="para">
		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 (see <a class="xref" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html" title="3.3.7.Â Book_Name.ent">SectionÂ 3.3.7, â€œBook_Name.entâ€</a>). Consequently, while we are not reducing the <code class="filename"><em class="replaceable"><code>Book_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><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Preface-We_Need_Feedback.html"><strong>Prev</strong>2.Â We Need Feedback!</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Â 2.Â Branding</a></li></ul></body></html>

--- NEW FILE chap-Users_Guide-Using_Sets.html ---
<?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><title>ChapterÂ 4.Â Using Sets</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html" title="3.7.3.Â Denoting draft documentation of pre-release software"/><link rel="next" href="sect-Users_Guide-Using_Sets-Distributed_Sets.html" title="4.2.Â Distributed Sets"/></head><body class=""><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/publ
 ican"><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-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Using_Sets-Distributed_Sets.html"><strong>Next</strong></a></li></ul><div class="chapter" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="chap-Users_Guide-Using_Sets">ChapterÂ 4.Â 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">4.1. Stand-alone Sets</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_Sets-Distributed_Sets.html">4.2. Distributed Sets</a></span></dt></dl></div><div class="para">
		A set 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, Stand-alone Sets and Distributed Sets.
	</div><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_Sets-Stand_alone_Sets">4.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.
		</div><div class="procedure" id="proc-Users_Guide-Stand_alone_Sets-Creating_a_Stand_alone_Set"><h6>ProcedureÂ 4.1.Â Creating a Stand-alone Set</h6><ol class="1"><li><div class="para">
					Run the following command in a shell in the <code class="filename">books/</code> directory to create a set named <code class="literal">My_Set</code> branded in the Red Hat style.
				</div><pre class="programlisting">create_book --type=Set --name=My_Set --brand=RedHat
</pre></li><li><div class="para">
					<code class="command">cd</code> into the <code class="filename">My_Set/en-US</code> directory and create two directories called <code class="filename">Book_A</code> and <code class="filename">Book_B</code>.
				</div><pre class="screen">cd My_Set/en-US
mkdir Book_A Book_B
</pre></li><li><div class="para">
					<code class="command">cd</code> into the <code class="filename">books/My_Set/en-US/Book_A</code> directory. Create and edit the <code class="filename">Book_A.xml</code>, <code class="filename">Book_Info.xml</code>, and any other xml files required for your book such as those required for individual chapters. Ensure that <code class="filename">Book_A.xml</code> contains the correct <code class="sgmltag-element">xi:include</code> references to all of your xml files in the directory. For example, if <em class="citetitle">Book A</em> contained <code class="filename">Book_Info.xml</code> and <code class="filename">Chapter_1.xml</code>, the <code class="filename">Book_A.xml</code> file would look like this:
				</div><pre class="programlisting"><?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<book>
	  <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
	  <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</book>
</pre></li><li><div class="para">
					Use the same process for <em class="citetitle">Book_B</em>, located in the <code class="filename">books/My_Set/en-US/Book_B</code> directory, as per the step above.
				</div></li><li><div class="para">
					Open the <code class="filename">books/My_Set/en-US/My_Set.xml</code> file in an editor. For each book in the set, add an <code class="sgmltag-element">xi:include</code> reference to the primary xml file from the book. The primary xml file for <em class="citetitle">Book A</em> will be <code class="filename">Book_A.xml</code> and for <em class="citetitle">Book B</em>, <code class="filename">Book_B.xml</code>. The <code class="filename">My_Set.xml</code> file should now look like this:
				</div><pre class="programlisting"><?xml version="1.0"?>
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<set>
	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</set>

</pre></li><li><div class="para">
					Test your set by running the <code class="command">make test-en-US</code> command.
				</div></li></ol></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html"><strong>Prev</strong>3.7.3.Â Denoting draft documentation of pre-releas...</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-Using_Sets-Distributed_Sets.html"><strong>Next</strong>4.2.Â Distributed Sets</a></li></ul></body></html>

--- NEW FILE chap-Users_Guide-Using_the_publican_package.html ---
<?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><title>ChapterÂ 3.Â Using the publican package</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><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Â 2.Â Branding"/><link rel="next" href="sect-Users_Guide-Using_the_publican_package-Creating_a_Book.html" title="3.2.Â Creating a Book"/></head><body class=""><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-Using_the_publican_package-Creating_a_Book.html"><strong>Next</strong></a></li></ul><div class="chapter" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="chap-Users_Guide-Using_the_publican_package">ChapterÂ 3.Â Using the publican package</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="chap-Users_Guide-Using_the_publican_package.html#sect-Users_Guide-Using_the_publican_package-Installing_publican">3.1. Installing publican</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Creating_a_Book.html">3.2. Creating a Book</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html">3.3. Files in the Book director
 y</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html#sect-Users_Guide-Files_in_the_Book_directory-The_Makefile">3.3.1. The Makefile</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html">3.3.2. Book_Info.xml</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html">3.3.3. RPMs, Editions, Impressions and Versions</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html">3.3.4. Author_Group.xml</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html">3.3.5. Chapter.xml</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html">3.3.6. Book_Name.xml</a></span></dt><dt><span class="section
 "><a href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html">3.3.7. Book_Name.ent</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html">3.3.8. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Adding_Images.html">3.4. Adding Images</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Building_a_Book.html">3.5. Building a Book</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Conditional_Tagging.html">3.6. Conditional Tagging</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html">3.7. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.ht
 ml#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.html">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.html">3.7.3. Denoting draft documentation of pre-release software</a></span></dt></dl></dd></dl></div><div class="para">
		This chapter describesâ€”the process of installing the publican package, creating books, the main configuration files, example book files, and how to build a book.
	</div><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_the_publican_package-Installing_publican">3.1.Â Installing publican</h2></div></div></div><div class="para">
			To install publican:
		</div><div class="itemizedlist"><ul><li><div class="para">
					Change to the root user: <code class="command"><code class="prompt">$</code> su - </code>
				</div></li><li><div class="para">
					Run the following command to install the publican package: <code class="command"><code class="prompt">#</code> yum install publican publican-doc</code>
				</div></li></ul></div><div class="para">
			There are several brand packages available for use with publican. Run the following command as the root user to install packages for building branded books:
		</div><pre class="screen"># yum install publican-<em class="replaceable"><code>brand</code></em>
</pre><div class="para">
			Replace <em class="replaceable"><code>brand</code></em> with redhat, fedora, jboss, ovirt, or gimp.
		</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Branding.html"><strong>Prev</strong>ChapterÂ 2.Â 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-Using_the_publican_package-Creating_a_Book.html"><strong>Next</strong>3.2.Â Creating a Book</a></li></ul></body></html>

--- NEW FILE index.html ---
<?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><title>Users Guide</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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 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=""><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 class="next"><a accesskey="n" href="pref-Users_Guide-Preface.html"><strong>Next</strong></a></li></ul><div class="book" lang="en-US"><div class="titlepage"><div><div class="producttitle"><span class="productname">Publican</span> <span class="productnumber">0.44</span></div><div><h1 id="d0e1" 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.2</p><div><h3 class="corpauthor">
				<span class="inlinemediaobject"><object type="image/svg+xml" data="Common_Content/images/title_logo.svg"/></span>
			</h3></div><div><div class="authorgroup"><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">Murray</span> <span class="surname">McAllister</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:mmcallis at redhat.com">mmcallis 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"><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="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/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></div><hr/><div><div id="d0e34" class="legalnotice"><h1 class="legalnotice">Legal Notice</h1><div class="para">
		Copyright <span class="trademark"/>Â© 2008 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"><h6>Abstract</h6><div class="para">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 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#d0e137">1. Document Conventions</a></span></dt><dd><dl><dt><span class="section"><a href="pref-Users_Guide-Preface.html#d0e147">1.1. Typographic Conventions</a></span></dt><dt><span class="section"><a href="pref-Users_Guide-Preface.html#d0e363">1.2. Pull-quote Conventions</a></span></dt><dt><span class="section"><a href="pref-Users_Guide-Preface.html#d0e382">1.3. Notes and Warnings</a></span></dt></dl></dd><dt><span class="section"><a href="sect-Users_Guide-Preface-We_Need_Feedback.html">2. We Need Feedback!</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Introduction.html">1. Introduction</a></span></dt><dt><span class="chapter"><a href="chap-Users_Guide-Branding.html">2. Branding</a></span></dt><dt
 ><span class="chapter"><a href="chap-Users_Guide-Using_the_publican_package.html">3. Using the publican package</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Users_Guide-Using_the_publican_package.html#sect-Users_Guide-Using_the_publican_package-Installing_publican">3.1. Installing publican</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Creating_a_Book.html">3.2. Creating a Book</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html">3.3. Files in the Book directory</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html#sect-Users_Guide-Files_in_the_Book_directory-The_Makefile">3.3.1. The Makefile</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html">3.3.2. Book_Info.xml</a></span></dt><dt><span class="
 section"><a href="sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html">3.3.3. RPMs, Editions, Impressions and Versions</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html">3.3.4. Author_Group.xml</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html">3.3.5. Chapter.xml</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html">3.3.6. Book_Name.xml</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html">3.3.7. Book_Name.ent</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html">3.3.8. Revision_History.xml</a></span></dt></dl></dd><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Adding_Images.html">3.4. Adding I
 mages</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Building_a_Book.html">3.5. Building a Book</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Conditional_Tagging.html">3.6. Conditional Tagging</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html">3.7. Pre-release software and draft documentation</a></span></dt><dd><dl><dt><span class="section"><a href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.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="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html">3.7.2. Denoting draft documentation</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-P
 re_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html">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-Using_Sets.html">4. 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">4.1. Stand-alone Sets</a></span></dt><dt><span class="section"><a href="sect-Users_Guide-Using_Sets-Distributed_Sets.html">4.2. Distributed Sets</a></span></dt></dl></dd><dt><span class="chapter"><a href="chap-Users_Guide-Frequently_Asked_Questions.html">5. Frequently Asked Questions</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-Makefile_Parameters.html">A. Makefile Parameters</a></span></dt><dt><span class="appendix"><a href="appe-Users_Guide-Revision_History.html">B. Revision History</a></span></dt></dl></div></div><ul class="docnav"><li cla
 ss="previous"/><li class="next"><a accesskey="n" href="pref-Users_Guide-Preface.html"><strong>Next</strong>Preface</a></li></ul></body></html>

--- NEW FILE pref-Users_Guide-Preface.html ---
<?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><title>Preface</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><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="sect-Users_Guide-Preface-We_Need_Feedback.html" title="2.Â We Need Feedback!"/></head><body class=""><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="index.html"><strong>Prev</
 strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Preface-We_Need_Feedback.html"><strong>Next</strong></a></li></ul><div class="preface" lang="en-US"><div class="titlepage"><div><div><h1 id="pref-Users_Guide-Preface" class="title">Preface</h1></div></div></div><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="d0e137">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" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="d0e147">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>
		</div><div class="para">
			Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:
		</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
				To see the contents of the file <code class="filename">my_next_bestselling_novel</code> in your current working directory, enter the <code class="command">cat my_next_bestselling_novel</code> command at the shell prompt and press <span class="keycap"><strong>Enter</strong></span> to execute the command.
			</div></blockquote></div><div class="para">
			The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.
		</div><div class="para">
			Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:
		</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
				Press <span class="keycap"><strong>Enter</strong></span> to execute the command.
			</div><div class="para">
				Press <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>F1</strong></span> to switch to the first virtual terminal. Press <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>F7</strong></span> to return to your X-Windows session.
			</div></blockquote></div><div class="para">
			The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
		</div><div class="para">
			If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in <code class="literal">Mono-spaced Bold</code>. For example:
		</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
				File-related classes include <code class="classname">filesystem</code> for file systems, <code class="classname">file</code> for files, and <code class="classname">dir</code> for directories. Each class has its own associated set of permissions.
			</div></blockquote></div><div class="para">
			<span class="application"><strong>Proportional Bold</strong></span>
		</div><div class="para">
			This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
		</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
				Choose <span class="guimenu"><strong>System > Preferences > Mouse</strong></span> from the main menu bar to launch <span class="application"><strong>Mouse Preferences</strong></span>. In the <span class="guilabel"><strong>Buttons</strong></span> tab, click the <span class="guilabel"><strong>Left-handed mouse</strong></span> check box and click <span class="guibutton"><strong>Close</strong></span> to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
			</div><div class="para">
				To insert a special character into a <span class="application"><strong>gedit</strong></span> file, choose <span class="guimenu"><strong>Applications > Accessories > Character Map</strong></span> from the main menu bar. Next, choose <span class="guimenu"><strong>Search > Findâ€¦</strong></span> from the <span class="application"><strong>Character Map</strong></span> menu bar, type the name of the character in the <span class="guilabel"><strong>Search</strong></span> field and click <span class="guibutton"><strong>Next</strong></span>. The character you sought will be highlighted in the <span class="guilabel"><strong>Character Table</strong></span>. Double-click this highlighted character to place it in the <span class="guilabel"><strong>Text to copy</strong></span> field and then click the <span class="guibutton"><strong>Copy</strong></span> button. Now switch back to your document and choose <span class="guimenu"><strong>Edit > Paste</strong></span> from the <
 span class="application"><strong>gedit</strong></span> menu bar.
			</div></blockquote></div><div class="para">
			The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.
		</div><div class="para">
			Note the <span class="guimenu"><strong>></strong></span> shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select <span class="guimenuitem"><strong>Mouse</strong></span> from the <span class="guimenu"><strong>Preferences</strong></span> sub-menu in the <span class="guimenu"><strong>System</strong></span> menu of the main menu bar' approach.
		</div><div class="para">
			<code class="command"><em class="replaceable"><code>Mono-spaced Bold Italic</code></em></code> or <span class="application"><strong><em class="replaceable"><code>Proportional Bold Italic</code></em></strong></span>
		</div><div class="para">
			Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
		</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
				To connect to a remote machine using ssh, type <code class="command">ssh <em class="replaceable"><code>username</code></em>@<em class="replaceable"><code>domain.name</code></em></code> at a shell prompt. If the remote machine is <code class="filename">example.com</code> and your username on that machine is john, type <code class="command">ssh john at example.com</code>.
			</div><div class="para">
				The <code class="command">mount -o remount <em class="replaceable"><code>file-system</code></em></code> command remounts the named file system. For example, to remount the <code class="filename">/home</code> file system, the command is <code class="command">mount -o remount /home</code>.
			</div><div class="para">
				To see the version of a currently installed package, use the <code class="command">rpm -q <em class="replaceable"><code>package</code></em></code> command. It will return a result as follows: <code class="command"><em class="replaceable"><code>package-version-release</code></em></code>.
			</div></blockquote></div><div class="para">
			Note the words in bold italics above â€” username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
		</div><div class="para">
			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">
				When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a <em class="firstterm">server-pool</em>. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called <em class="firstterm">Multi-Processing Modules</em> (<em class="firstterm">MPMs</em>). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.
			</div></blockquote></div></div><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="d0e363">1.2.Â Pull-quote Conventions</h3></div></div></div><div class="para">
			Two, commonly multi-line, data types 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">
			Source-code listings are also set in <code class="computeroutput">Mono-spaced Roman</code> but are presented and highlighted as follows:
		</div><pre class="programlisting">
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }

}
</pre></div><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="d0e382">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">
				A Note is a tip or shortcut or alternative approach 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.
			</div></div><div class="important"><h2>Important</h2><div class="para">
				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 Important boxes won't cause data loss but may cause irritation and frustration.
			</div></div><div class="warning"><h2>Warning</h2><div class="para">
				A Warning should not be ignored. Ignoring warnings will most likely cause data loss.
			</div></div></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="index.html"><strong>Prev</strong>Users Guide</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-Preface-We_Need_Feedback.html"><strong>Next</strong>2.Â We Need Feedback!</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Conditional_Tagging.html ---
<?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><title>3.6.Â Conditional Tagging</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/><link rel="prev" href="sect-Users_Guide-Using_the_publican_package-Building_a_Book.html" title="3.5.Â Building a Book"/><link rel="next" href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html" title="3.7.Â Pre-release software and draft documentation"/></head><body class=""><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/i
 mage_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-Using_the_publican_package-Building_a_Book.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Conditional_Tagging">3.6.Â 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">
		Publican makes it easy to manage differences between multiple versions of a book by allowing you to simply use one 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; i.e. "conditionalizing content".
	</div><div class="para">
		To conditionalize content in a book, use the tag attribute <code class="command">condition</code>. For example, let's say the book <em class="citetitle">How To Use Product Foo</em> has an "upstream", "enterprise", and "beta" version:
	</div><pre class="programlisting">
<para condition="upstream">
This paragraph will only appear in the upstream version of How To Use Product Foo.
</para>

<para condition="enterprise">
This paragraph will only appear in the enterprise version of How To Use Product Foo.
</para>	

<para condition="beta">
This paragraph will only appear in the beta version of How To Use Product Foo.
</para>

<para condition="beta,enterprise">
This paragraph will only appear in the beta and enterprise versions of How To Use Product Foo.
</para>
</pre><div class="para">
		To build a specific version (thereby capturing all content conditionalized for that version), use <code class="command">make</code> parameter <code class="command">CONDITION="<em class="replaceable"><code>version</code></em>" <em class="replaceable"><code>format</code></em></code>. Using the same example for the book <em class="citetitle">How To Use Product Foo</em>, you can build the "upstream" version of the book in pdf using:
	</div><pre class="screen">
make CONDITION="upstream" pdf-en-US
</pre><div class="para">
		This will capture all tags that use <code class="command">condition="upstream"</code> and build <em class="citetitle">How To Use Product Foo</em> in PDF format.
	</div><div class="note"><h2>Note</h2><div class="para">
			You can conditionalize content as per the <code class="command">BRAND</code> setting. To do so, add the following line to <code class="filename">Makefile</code>:
		</div><pre class="screen">
CONDITION=$(BRAND)
</pre><div class="para">
			In this manner, <code class="command">make CONDITION="brand1" pdf-en-US</code> will build the book in PDF <span class="emphasis"><em>and</em></span> capture all tags that use the <code class="command">condition="brand1"</code> attribute.
		</div></div><div class="para">
		Further, if an <code class="command"><xref></code> points to content that is not going to be included in the build due to conditional tagging, the build will fail. For example, <code class="command">make CONDITION="upstream" pdf-en-US</code> will fail if the book has the tag <code class="command"><xref linkend="betasection"</code> pointing to <code class="command"><section id="betasection" CONDITION="beta"></code>.
	</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Using_the_publican_package-Building_a_Book.html"><strong>Prev</strong>3.5.Â Building a Book</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-Using_the_publican_package-Pre_release_software_and_draft_documentation.html"><strong>Next</strong>3.7.Â Pre-release software and draft documentation</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html ---
<?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><title>3.3.4.Â Author_Group.xml</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="prev" href="sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html" title="3.3.3.Â RPMs, Editions, Impressions and Versions"/><link rel="next" href="sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html" title="3.3.5.Â Chapter.xml"/></head><body class=""><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-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml">3.3.4.Â 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"><?xml version='1.0'?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<authorgroup>
	<corpauthor>FF0000 Headgear Documentation Group</corpauthor>
	<author>
		<firstname>Dude</firstname>
		<surname>McDude</surname>
		<affiliation>
			<orgname>My Org</orgname>
			<orgdiv>Best Div in the place</orgdiv>
		</affiliation>
		<email>dude.mcdude at myorg.org</email>
	</author>
</authorgroup>

</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 class="para">
				If you do not want or need <code class="filename">Author_Group.xml</code> included in a book, delete the following line from <code class="filename">Book_Info.xml</code> before building:
			</div><pre class="programlisting"><xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</pre></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html"><strong>Prev</strong>3.3.3.Â RPMs, Editions, Impressions and Versions</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-Files_in_the_Book_directory-Chapter.xml.html"><strong>Next</strong>3.3.5.Â Chapter.xml</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html ---
<?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><title>3.3.2.Â Book_Info.xml</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="prev" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="next" href="sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html" title="3.3.3.Â RPMs, Editions, Impressions and Versions"/></head><body class=""><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-Using_the_publican_package-Files_in_the_Book_directory.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml">3.3.2.Â Book_Info.xml</h3></div></div></div><div class="para">
				The <code class="filename">Book_Info.xml</code> file contains the key meta-data concerning a book: the book's ID; title; subtitle; author and edition number. It also contains the name and version of the product the book is about and an abstract.
			</div><div class="para">
				Aside from, as you'd expect, constituting much of a book's front matter, this meta-data is also used when building books as RPMs. Consequently, if you wish to distribute a book as a .rpm file, several of the tags included by default in <code class="filename">Book_Info.xml</code> must have appropriate data within them, and that data must conform to the requirements of the RPM format.
			</div><div class="para">
				Data from seven of the default tags in <code class="filename">Book_Info.xml</code> is required to build books as RPMs. Most immediately, the file name of a book built as an RPM is constructed as follows: <code class="filename"><em class="replaceable"><code>productname</code></em>-<em class="replaceable"><code>title</code></em>-<em class="replaceable"><code>productnumber</code></em>-<em class="replaceable"><code>language</code></em>-<em class="replaceable"><code>edition</code></em>-<em class="replaceable"><code>pubsnumber</code></em>.src.rpm</code>. Everything but <em class="replaceable"><code>language</code></em> above is pulled from <code class="filename">Book_Info.xml</code>. (Language is supplied by the user at make time.) As well, the <em class="replaceable"><code>subtitle</code></em> and <em class="replaceable"><code>abstract</code></em> are used in the rpm spec file.
			</div><div class="para">
				An example <code class="filename">Book_Info.xml</code> file, for the Test_Book book, is presented below. Details regarding this file, and what the RPM format requirements are for each tag, follow.
			</div><pre class="programlisting">
<?xml version='1.0'?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<bookinfo id="MYBOOK-MYPRODUCT">
	<title>MYBOOKNAME</title>
	<subtitle>short descriptor</subtitle>
	<productname>MYPRODUCTNAME</productname>
	<productnumber>0.0</productnumber>
	<edition>0.0</edition>
	<pubsnumber>0</pubsnumber>
	<abstract>
		<para>A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the #description field of the book's RPM spec file.</para>
	</abstract>
	<corpauthor>
		<inlinemediaobject>
			<imageobject>
				<imagedata format='SVG' fileref="Common_Content/images/title_logo.svg" />
			</imageobject>
			<textobject><phrase>Logo</phrase></textobject>
		</inlinemediaobject>
	</corpauthor>
	<copyright>
		<year>&YEAR;</year>
		<holder>&HOLDER;</holder>
	</copyright>
	<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

</pre><div class="variablelist"><dl><dt><span class="term"><code class="filename"><bookinfo id="<em class="replaceable"><code>book_id</code></em>"></code></span></dt><dd><div class="para">
							The Book ID is used internally and is not displayed to end users when the book is built. If you run the <code class="command">make clean_ids</code> command, any manually entered ID, including this one, will be changed to a <em class="replaceable"><code>Book_Name-Title</code></em> format, where <em class="replaceable"><code>Title</code></em> is the title of the associated book, article, section, or chapter.
						</div></dd><dt><span class="term"><code class="filename"><productname><em class="replaceable"><code>productname</code></em></productname></code></span></dt><dd><div class="para">
							The name of the product or product stream the book is about (for example: <span class="emphasis"><em>Red Hat Enterprise Linux</em></span> or <span class="emphasis"><em>JBoss Enterprise Application Platform</em></span>). When building a book as an RPM, data in the <productname> tag is used as part of the filename of the resultant .rpm file.
						</div><div class="important"><h2>Important</h2><div class="para">
								Because data in this tag also appears as part of the .rpm filename, this field can only contain upper- and lower-case un-accented letters and the underscore and space characters (ie â€˜aâ€“zâ€™, â€˜Aâ€“Zâ€™ and â€˜_â€™ and â€˜ â€™).
							</div></div></dd><dt><span class="term"><code class="filename"><title><em class="replaceable"><code>title</code></em></title></code></span></dt><dd><div class="para">
							Obviously enough, the book's title (for example, <span class="emphasis"><em>Server Configuration Guide</em></span>). The title appears under the product name in both HTML and PDF editions. A title is required to build an RPM. When building a book as an RPM the title is used as the part of the file-name of the RPM package.
						</div><div class="important"><h2>Important</h2><div class="para">
								Because data in this tag also appears as part of the .rpm filename, this field can only contain upper- and lower-case un-accented letters and the underscore and space characters (ie â€˜aâ€“zâ€™, â€˜Aâ€“Zâ€™ and â€˜_â€™ and â€˜ â€™).
							</div></div></dd><dt><span class="term"><code class="filename"><subtitle><em class="replaceable"><code>subtitle</code></em></subtitle></code></span></dt><dd><div class="para">
							Again, plainly enough, the subtitle tag contains a book's subtitle: an alternative, and commonly explanatory title for the book (for example: <span class="emphasis"><em>Server Configuration Guide: Preparing Red Hat Enterprise Linux for Production Use</em></span>). The subtitle appears under the title in both HTML and PDF editions. A subtitle is also required to make a book available as an RPM. When building a book as an RPM, the subtitle is used as the <code class="computeroutput">Summary</code> in the RPM spec file. The <code class="command">rpm -qi</code> returns the contents of several spec file fields, including the Summary field.
						</div></dd><dt><span class="term"><code class="filename"><productnumber><em class="replaceable"><code>productnumber</code></em></productnumber></code></span></dt><dd><div class="para">
							The version number of the product the book covers, for example â€˜5.2â€™ for Red Hat Enterprise Linux 5.2 and â€˜4.3â€™ for JBoss EAP 4.3.
						</div><div class="para">
							Running the <code class="command">create_book --name <em class="replaceable"><code>Book_Name</code></em> --version <em class="replaceable"><code>version</code></em></code> command correctly configures the product number.
						</div><div class="important"><h2>Important</h2><div class="para">
								Because data in this tag is used in the RPM spec file, this tag can only contain numbers and the full stop or period (ie â€˜0â€“9â€™ and â€˜.â€™).
							</div></div></dd><dt><span class="term"><code class="filename"><edition><em class="replaceable"><code>edition</code></em></edition></code></span></dt><dd><div class="para">
							This is the edition number of the book. The first edition of the book should be 1.0 (you may like to use 0.y for pre-release versions of a book). Subsequent editions should increment the 1.y to indicate to readers that the book is a new edition. The edition changes the first two digits of the version number in the .rpm filename when building a book with the <code class="command">tar</code> or <code class="command">srpm</code> options.
						</div><div class="para">
							For example, setting the edition to <code class="filename">1.2</code> and building the book using the <code class="command">make srpm-en-US</code> command, would create an RPM file named <code class="filename"><em class="replaceable"><code>productname</code></em>-<em class="replaceable"><code>title</code></em>-<em class="replaceable"><code>productnumber</code></em>-en-US-1.2-0.src.rpm</code>.
						</div><div class="para">
							Running the <code class="command">create_book --name<em class="replaceable"><code> Book_Name</code></em> --edition <em class="replaceable"><code>x</code></em>.<em class="replaceable"><code>y</code></em></code> command correctly configures the edition.
						</div><div class="important"><h2>Important</h2><div class="para">
								Because data in this tag sets the <em class="parameter"><code>Version</code></em> in the RPM spec file, this tag can only contain numbers and the full stop or period (ie â€˜0â€“9â€™ and â€˜.â€™).
							</div></div></dd><dt><span class="term"><code class="filename"><pubsnumber><em class="replaceable"><code>pubsnumber</code></em></pubsnumber></code></span></dt><dd><div class="para">
							The pubsnumber changes the release number (the last digit) when building a book with the <code class="filename">tar</code> or <code class="filename">srpm</code> options. For example, setting the pubsnumber to <code class="filename">1</code> and building the book using the <code class="command">make srpm-en-US</code> command, would create an RPM file named <code class="filename"><em class="replaceable"><code>productname</code></em>-<em class="replaceable"><code>title</code></em>-<em class="replaceable"><code>productnumber</code></em>-en-US-<em class="replaceable"><code>edition</code></em>-1.src.rpm</code>.
						</div><div class="important"><h2>Important</h2><div class="para">
								Because data in this tag sets the <em class="parameter"><code>Release</code></em> in the RPM spec file, this tag can only contain numbers (ie â€˜0â€“9â€™).
							</div></div></dd><dt><span class="term"><code class="filename"><abstract><para><em class="replaceable"><code>abstract</code></em></para></abstract></code></span></dt><dd><div class="para">
							A short overview and summary of the book's subject and purpose, traditionally no more than a paragraph long. The abstract appears before the table of contents in HTML editions and on the second page of PDF editions. When a book is built as an RPM, the abstract sets the <em class="parameter"><code>Description</code></em> field of the RPM's spec file. This makes the abstract for a package available via the <code class="command">rpm -qi</code>.
						</div></dd></dl></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html"><strong>Prev</strong>3.3.Â Files in the Book directory</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-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html"><strong>Next</strong>3.3.3.Â RPMs, Editions, Impressions and Versions</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html ---
<?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><title>3.3.7.Â Book_Name.ent</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="prev" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html" title="3.3.6.Â Book_Name.xml"/><link rel="next" href="sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html" title="3.3.8.Â Revision_History.xml"/></head><body class=""><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-Files_in_the_Book_directory-Book_Name.xml.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent">3.3.7.Â Book_Name.ent</h3></div></div></div><div class="para">
				The <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.ent</code> file is used to define local entities. The <code class="computeroutput">YEAR</code> and <code class="computeroutput">HOLDER</code> entities are used for copyright information. You must define <code class="computeroutput">YEAR</code> and <code class="computeroutput">HOLDER</code> entities, otherwise the book will not build:
			</div><div class="para">

<pre class="screen"><!ENTITY PRODUCT "MYPRODUCT">
<!ENTITY BOOKID "MYBOOK">
<!ENTITY YEAR "2008">
<!ENTITY HOLDER "YOUR NAME GOES HERE">

</pre>
			</div><div class="important"><h2>Important</h2><div class="para">
					Entities offer convenience but they should be used with extreme caution. 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 <code class="filename">.po</code> files. Complete translations of documents containing entities are, as a consequence, impossible.
				</div></div><div class="para">
				If you define an entity â€” <code class="sgmltag-element"><!ENTITY LIFT "Liberty Installation and Formatting Tome"></code> â€” you can enter <code class="sgmltag-element">&LIFT;</code> in your XML and it will appear as <span class="emphasis"><em>The Secret to Eternal Life</em></span> every time the book is built to HTML, PDF or Text.
			</div><div class="para">
				Entities are not transformed when XML is converted to PO, however. Which means translators never see <span class="emphasis"><em>Liberty Installation and Formatting Tome</em></span>. Instead they see <code class="sgmltag-element">&LIFT;</code>, which they cannot translate.
			</div><div class="para">
				Consider something as simple as the following English sentence fragment being translated into a related language: German.
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					As noted in the <span class="emphasis"><em>Liberty Installation and Formatting Tome</em></span>, Chapter 3â€¦
				</div></blockquote></div><div class="para">
				A translation of this might be as follows:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					<span class="foreignphrase"><em class="foreignphrase">Wie in dem <span class="emphasis"><em>WÃ¤lzer fÃ¼r die Installation und Formatierung von Liberty</em></span>, Kapitel 3, erwÃ¤hntâ€¦</em></span>
				</div></blockquote></div><div class="para">
				Because there is no text missing, the title can be translated into elegant German, avoiding the multi-syllabic mega-word syndrome. Also, note the use of <span class="foreignphrase"><em class="foreignphrase">â€˜in demâ€™</em></span>, the correct pronoun when referring to a <span class="foreignphrase"><em class="foreignphrase">WÃ¤lzer</em></span> (tome).
			</div><div class="para">
				By contrast, if entities are used, the English would be
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					As noted in the <code class="sgmltag-element">&LIFT;</code>, Chapter 3â€¦
				</div></blockquote></div><div class="para">
				The translation of this would probably run thus:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					<span class="foreignphrase"><em class="foreignphrase">Wie in <code class="sgmltag-element">&LIFT;</code>, Kapitel 3, erwÃ¤hntâ€¦</em></span>
				</div></blockquote></div><div class="para">
				And the presentation would be thus:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					<span class="foreignphrase"><em class="foreignphrase">Wie in <span class="emphasis"><em>Liberty Installation and Formatting Tome</em></span>, Kapitel 3, erwÃ¤hntâ€¦</em></span>
				</div></blockquote></div><div class="para">
				This, of course, leaves the title in English, including words like Tome and Formatting that are unlikely to be understood. Also, the translator is forced to use the pronoun â€˜inâ€™, a more general construction that comes close to <span class="foreignphrase"><em class="foreignphrase">Denglisch or Angleutsch</em></span>. Many German speakers consider this approach incorrect and almost all consider it inelegant.
			</div><div class="para">
				Equivalent problems emerge with a fragment such as this:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					However, a careful reading of the <span class="emphasis"><em>Liberty Installation and Formatting Tome</em></span> afterword, shows thatâ€¦
				</div></blockquote></div><div class="para">
				With no text hidden behind an entity, a German translation of this might be:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					<span class="foreignphrase"><em class="foreignphrase">Jedoch ergibt ein sorgfÃ¤ltiges Lesen des Nachworts fÃ¼r den <span class="emphasis"><em>WÃ¤lzer fÃ¼r die Installation und Formatierung von Liberty</em></span>, dassâ€¦</em></span>
				</div></blockquote></div><div class="para">
				If an entity was used to save the writer time, the translator has to deal with this:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					However, a careful reading of the <code class="sgmltag-element">&LIFT;</code> afterword, shows thatâ€¦
				</div></blockquote></div><div class="para">
				And the translation would be subtly but importantly different:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					<span class="foreignphrase"><em class="foreignphrase">Jedoch ergibt ein sorgfÃ¤ltiges Lesen des Nachworts fÃ¼r <code class="sgmltag-element">&LIFT;</code>, dassâ€¦</em></span>
				</div></blockquote></div><div class="para">
				When presented to a reader, this would appear as follows:
			</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
					<span class="foreignphrase"><em class="foreignphrase">Jedoch ergibt ein sorgfÃ¤ltiges Lesen des Nachworts fÃ¼r <span class="emphasis"><em>Liberty Installation and Formatting Tome</em></span>, dassâ€¦</em></span>
				</div></blockquote></div><div class="para">
				Again, note the missing pronoun, <span class="foreignphrase"><em class="foreignphrase">â€˜denâ€™</em></span>. This is inelegant but necessary since the translator can otherwise only guess which pronoun <span class="foreignphrase"><em class="foreignphrase">(der, die or das)</em></span> to use, which would inevitably lead to error.
			</div><div class="para">
				Now multiply such problems by the 22 languages Publican currently supports. Using entities for anything other than the few non-translated strings currently supported is arguably a conscious effort to inhibit and reduce the quality of translations.
			</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html"><strong>Prev</strong>3.3.6.Â Book_Name.xml</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-Files_in_the_Book_directory-Revision_History.xml.html"><strong>Next</strong>3.3.8.Â Revision_History.xml</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html ---
<?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><title>3.3.6.Â Book_Name.xml</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="prev" href="sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html" title="3.3.5.Â Chapter.xml"/><link rel="next" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html" title="3.3.7.Â Book_Name.ent"/></head><body class=""><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_left.png" alt="Product Site"/></a><a clas
 s="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-Files_in_the_Book_directory-Chapter.xml.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml">3.3.6.Â Book_Name.xml</h3></div></div></div><div class="para">
				The <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.xml</code> file contains <code class="filename">xi:include</code> directives to include the chapters for a book. Chapters are contained in separate XML files, and the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.xml</code> file brings them together into a single book.
			</div><div class="para">
				The following is an example <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.xml</code> file. Note the <code class="filename">DOCTYPE</code> is set to <code class="filename">book</code>.
			</div><pre class="programlisting"><?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<book>
	<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<index />
</book>

</pre><div class="para">
				This example loads the <code class="computeroutput">Book_Info.xml</code>, <code class="computeroutput">Preface.xml</code>, <code class="computeroutput">Chapter.xml</code>, and <code class="computeroutput">Appendix.xml</code> XML files.
			</div><div class="important"><h2>Important</h2><div class="para">
					The order in which chapters are listed matters. When this example book is built, Book_Info.xml will precede Preface.xml which will precede Chapter.xml, and so on.
				</div></div><div class="para">
				The <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.xml</code> file is not limited to using <code class="filename">xi:include</code> directives. Books can be created using a single XML file. The following is an example of a book created using a single XML file:
			</div><pre class="programlisting"><book>

<chapter>
<title>Chapter 1</title>
	<para>
		A paragraph in Chapter 1.
	</para>
	<section id="section1">
	<title>Chapter 1 Section 1</title>
		<para>
			A paragraph in Section 1.
		</para>
	</section>
	<section id="section2">
	<title>Chapter 1 Section 2</title>
		<para>
			A paragraph in Section 2.
		</para>
	</section>
</chapter>

<chapter>
<title>Chapter 2</title>
	<para>
		A paragraph in Chapter 2.
	</para>
</chapter>

</book>
</pre><div class="para">
				This book contains two chapters. Chapter one contains two sections. Please 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><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html"><strong>Prev</strong>3.3.5.Â Chapter.xml</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-Files_in_the_Book_directory-Book_Name.ent.html"><strong>Next</strong>3.3.7.Â Book_Name.ent</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml.html ---
<?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><title>3.3.5.Â Chapter.xml</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="prev" href="sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html" title="3.3.4.Â Author_Group.xml"/><link rel="next" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html" title="3.3.6.Â Book_Name.xml"/></head><body class=""><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-Files_in_the_Book_directory-Author_Group.xml.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.xml.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-Chapter.xml">3.3.5.Â Chapter.xml</h3></div></div></div><div class="para">
				The <code class="filename">Chapter.xml</code> file is a template for creating chapter files. Chapter files contain the content that make up a book. The following is a chapter template (<code class="filename">Chapter.xml</code>) that is created after running the <code class="command">create_book</code> command. Note the <code class="filename">DOCTYPE</code> is set to <code class="filename">chapter</code>:
			</div><pre class="programlisting"><?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="MYBOOK-Test">
	<title>Test</title>
	<para>
		This is a test paragraph
	</para>
	<section id="MYBOOK-Test-Section_1_Test">
		<title>Section 1 Test</title>
		<para>
			Test of a section
		</para>
	</section>

	<section id="MYBOOK-Test-Section_2_Test">
		<title>Section 2 Test</title>
		<para>
			Test of a section
		</para>
	</section>

</chapter>

</pre><div class="para">
				This chapter has two sections, <code class="filename">Section 1 Test</code> and <code class="filename">Section 2 Test</code>. Please 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><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html"><strong>Prev</strong>3.3.4.Â Author_Group.xml</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-Files_in_the_Book_directory-Book_Name.xml.html"><strong>Next</strong>3.3.6.Â Book_Name.xml</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions.html ---
<?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><title>3.3.3.Â RPMs, Editions, Impressions and Versions</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="prev" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html" title="3.3.2.Â Book_Info.xml"/><link rel="next" href="sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html" title="3.3.4.Â Author_Group.xml"/></head><body class=""><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-Files_in_the_Book_directory-Book_Info.xml.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Files_in_the_Book_directory-Author_Group.xml.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-RPMs_Editions_Impressions_and_Versions">3.3.3.Â RPMs, Editions, Impressions and Versions</h3></div></div></div><div class="para">
				As noted above, the default Book_Info.xml used by Publican 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 filename'.
			</div><div class="para">
				So, an edition of '1.0' becomes a version of '1.0'.
			</div><div class="para">
				Book_Info.xml also includes the <em class="parameter"><code><pubsnumber></code></em> tag. Any data placed within this tag changes the release number of RPM-packaged books.
			</div><div class="para">
				A book with an edition of 1.0 and a pubsnumber of 5, would be version 1.0, release 5 (1.0-5).
			</div><div class="para">
				The edition and pubsnumber are not tied to the <em class="parameter"><code><productnumber></code></em> tag also found in Book_Info.xml: productnumber denotes the version number of the product being documented or otherwise written about.
			</div><div class="para">
				It is entirely possible to have a 2nd edition of a book pertaining to a particular version of a product.
			</div><div class="para">
				In Bibliography, two copies of a book are the same edition if they are printed using substantially the same type-set master plates or pages. ('Substantially' offers some wiggle room for typo corrections and the like.)
			</div><div class="para">
				Book collectors routinely conflate 'first edition' with 'first print run', while Bibliographers pay attention to the text commonly placed in the front matter of a book, which calls a 2nd print run off the same (or substantially the same) plates a '1st edition, 2nd impression' or '1st edition, 2nd printing'.
			</div><div class="para">
				We recommend following Bibliographic practice in this regard. When using Publican 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><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html"><strong>Prev</strong>3.3.2.Â Book_Info.xml</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-Files_in_the_Book_directory-Author_Group.xml.html"><strong>Next</strong>3.3.4.Â Author_Group.xml</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html ---
<?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><title>3.3.8.Â Revision_History.xml</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/><link rel="prev" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html" title="3.3.7.Â Book_Name.ent"/><link rel="next" href="sect-Users_Guide-Using_the_publican_package-Adding_Images.html" title="3.4.Â Adding Images"/></head><body class=""><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-Files_in_the_Book_directory-Book_Name.ent.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Using_the_publican_package-Adding_Images.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml">3.3.8.Â Revision_History.xml</h3></div></div></div><div class="para">
				The <code class="command">make</code> searches for the first XML file in the $(XML_LANG) directory containing a revhistory tag. Publican then uses that file to build the RPM revision history.
			</div><div class="important"><h2>Important</h2><div class="para">
					All dates must be in the correct RPM format, other formats will break the spec file creation.
				</div><div class="para">
					Mon Aug 4 2008
				</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html"><strong>Prev</strong>3.3.7.Â Book_Name.ent</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-Using_the_publican_package-Adding_Images.html"><strong>Next</strong>3.4.Â Adding Images</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html ---
<?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><title>3.7.2.Â Denoting draft documentation</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html" title="3.7.Â Pre-release software and draft documentation"/><link rel="prev" href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html" title="3.7.Â Pre-release software and draft documentation"/><link rel="next" href="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html" title="3.7.3.Â Denoting draft docum
 entation of pre-release software"/></head><body class=""><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-Using_the_publican_package-Pre_release_software_and_draft_documentation.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">3.7.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><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:
					</div><pre class="programlisting"><book status="draft">
</pre></li></ul></div><div class="para">
				By default, your root node is the <code class="sgmltag-element"><book></code> tag in your <code class="filename"><em class="replaceable"><code>[book_name]</code></em>.xml</code> file.
			</div><div class="para">
				If you are working on an article or set, the root node is the <code class="sgmltag-element"><article></code> or <code class="sgmltag-element"><set></code> tag in <code class="filename"><em class="replaceable"><code>[book_name]</code></em>.xml</code>.
			</div><div class="para">
				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><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html"><strong>Prev</strong>3.7.Â Pre-release software and draft documentation</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-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html"><strong>Next</strong>3.7.3.Â Denoting draft documentation of pre-releas...</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software.html ---
<?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><title>3.7.3.Â Denoting draft documentation of pre-release software</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html" title="3.7.Â Pre-release software and draft documentation"/><link rel="prev" href="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html" title="3.7.2.Â Denoting draft documentation"/><link rel="next" href="chap-Users_Guide-Using_Sets.html" title="ChapterÂ 4.Â Using Sets"/></head><body class=""><p id="title"><a class="left" href="https://fedorahoste
 d.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-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.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 class="section" lang="en-US"><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.7.3.Â Denoting draft documentation of pre-release software</h3></div></div></div><div class="para">
				To denote unfinished documentation of pre-release software properly simply do both previously noted procedures.
			</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html"><strong>Prev</strong>3.7.2.Â Denoting draft documentation</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-Using_Sets.html"><strong>Next</strong>ChapterÂ 4.Â Using Sets</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Preface-We_Need_Feedback.html ---
<?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><title>2.Â We Need Feedback!</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="pref-Users_Guide-Preface.html" title="Preface"/><link rel="prev" href="pref-Users_Guide-Preface.html" title="Preface"/><link rel="next" href="chap-Users_Guide-Introduction.html" title="ChapterÂ 1.Â Introduction"/></head><body class=""><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-Introduction.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><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="d0e405" class="indexterm"/><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><ul class="docnav"><li class="previous"><a accesskey="p" href="pref-Users_Guide-Preface.html"><strong>Prev</strong>Preface</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-Introduction.html"><strong>Next</strong>ChapterÂ 1.Â Introduction</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Using_Sets-Distributed_Sets.html ---
<?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><title>4.2.Â Distributed Sets</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="chap-Users_Guide-Using_Sets.html" title="ChapterÂ 4.Â Using Sets"/><link rel="prev" href="chap-Users_Guide-Using_Sets.html" title="ChapterÂ 4.Â Using Sets"/><link rel="next" href="chap-Users_Guide-Frequently_Asked_Questions.html" title="ChapterÂ 5.Â Frequently Asked Questions"/></head><body class=""><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 S
 ite"/></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 class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_Sets-Distributed_Sets">4.2.Â Distributed Sets</h2></div></div></div><div class="para">
			A Distributed Set contains books that are located in <span class="package">SVN</span>. By setting the repository location and titles of the included books in the <code class="filename">Makefile</code>, 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="package">SVN</span> repository. Currently <span class="package">publican</span> only supports <span class="package">SVN</span>.
			</div></div><div class="procedure" id="proc-Users_Guide-Distributed_Sets-Creating_a_Set"><h6>ProcedureÂ 4.2.Â Creating a Set</h6><ol class="1"><li><div class="para">
					Run the following command in a shell to create a set named <code class="literal">My_Set</code> branded in the Red Hat style.
				</div><pre class="programlisting">$ create_book --type=Set --name=My_Set --brand=RedHat
</pre></li><li><div class="para">
					Uncomment the following lines in the <code class="filename">Makefile</code> from:
				</div><pre class="programlisting">#BOOKS		= My_Other_Book His_Book Her_Book Their_Book
#SET_REPO	= http://svn.repo.com/repos/project
#SET_REPO_TYPE	= SVN
...
#pre:: get_books set_books
#clean:: clean_set_books
</pre><div class="para">
					to :
				</div><pre class="programlisting">BOOKS 		= Book_A Book_B
SET_REPO	= <em class="replaceable"><code>http://PATH-TO-YOUR-SVN-REPOSITORY</code></em>SET_REPO_TYPE	= SVN
...
pre:: get_books set_books
clean:: clean_set_books
</pre></li><li><div class="para">
					Open the <code class="filename">My_Set.xml</code> file in an editor. For each book in the set, add an <code class="sgmltag-element">xi:include</code> reference to the primary xml file from the book. The primary xml file for <em class="citetitle">Book A</em> will be <code class="filename">Book_A.xml</code> and for <em class="citetitle">Book B</em>, <code class="filename">Book_B.xml</code>. The <code class="filename">My_Set.xml</code> file should now look like this:
				</div><pre class="programlisting"><?xml version="1.0"?>
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<set>
	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</set>

</pre></li><li><div class="para">
					Test your set by running the <code class="command">make test-en-US</code> command.
				</div><div class="important"><h2>Important</h2><div class="para">
						When building a set, the <code class="command">make clean_ids</code> command will be run over each book because of the constraint that ID's 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><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Using_Sets.html"><strong>Prev</strong>ChapterÂ 4.Â 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Â 5.Â Frequently Asked Questions</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Using_the_publican_package-Adding_Images.html ---
<?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><title>3.4.Â Adding Images</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/><link rel="prev" href="sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html" title="3.3.8.Â Revision_History.xml"/><link rel="next" href="sect-Users_Guide-Using_the_publican_package-Building_a_Book.html" title="3.5.Â Building a Book"/></head><body class=""><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="ri
 ght" 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-Files_in_the_Book_directory-Revision_History.xml.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Using_the_publican_package-Building_a_Book.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_the_publican_package-Adding_Images">3.4.Â Adding Images</h2></div></div></div><div class="para">
			Use the <code class="filename">images</code> subdirectory in the <code class="filename">en-<em class="replaceable"><code>US</code></em>/</code> directory to store images. 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><div class="para">

<pre class="programlisting"><mediaobject>
	<imageobject>
		<imagedata fileref="./images/testimage.png" />
	</imageobject>
	<textobject><phrase>alternate text goes here</phrase></textobject>
</mediaobject>
</pre>
		</div><div class="para">
			<div class="warning"><h2>Image File Locations</h2><div class="para">
					The build system only uses images in the <code class="filename">en-<em class="replaceable"><code>US</code></em>/images</code> subdirectory. Other directories do not work.
				</div></div>
		</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Files_in_the_Book_directory-Revision_History.xml.html"><strong>Prev</strong>3.3.8.Â Revision_History.xml</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-Using_the_publican_package-Building_a_Book.html"><strong>Next</strong>3.5.Â Building a Book</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Using_the_publican_package-Building_a_Book.html ---
<?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><title>3.5.Â Building a Book</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/><link rel="prev" href="sect-Users_Guide-Using_the_publican_package-Adding_Images.html" title="3.4.Â Adding Images"/><link rel="next" href="sect-Users_Guide-Conditional_Tagging.html" title="3.6.Â Conditional Tagging"/></head><body class=""><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.or
 g/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-Using_the_publican_package-Adding_Images.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Conditional_Tagging.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_the_publican_package-Building_a_Book">3.5.Â Building a Book</h2></div></div></div><div class="para">
			To build a book:
		</div><div class="orderedlist"><ol><li><div class="para">
					Confirm the <code class="computeroutput">YEAR</code> and <code class="computeroutput">HOLDER</code> entities have been configured in the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.ent</code> file, as per <a class="xref" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Name.ent.html" title="3.3.7.Â Book_Name.ent">SectionÂ 3.3.7, â€œBook_Name.entâ€</a>.
				</div></li><li><div class="para">
					Change into the root directory of the book. For example, if the book was named <code class="computeroutput">Test_Book</code> and was located in the <code class="filename">/books/</code> directory, run the following command:
				</div><div class="para">

<pre class="screen">cd <em class="replaceable"><code>/books/Test_Book</code></em>
</pre>
				</div></li><li><div class="para">
					Run the following command to check for any errors that would stop the book from building:
				</div><div class="para">

<pre class="screen">make test-en-US
</pre>
				</div></li><li><div class="para">
					Run the following command to build the book:
				</div><div class="para">

<pre class="screen">make <em class="replaceable"><code>format</code></em>-en-US
</pre>
				</div><div class="para">
					Replace <em class="replaceable"><code>format</code></em> with the desired format, for example, <code class="computeroutput">html</code>.
				</div></li></ol></div><div class="para">
			The following table lists commonly used <code class="command">make</code> commands:
		</div><div class="segmentedlist"><table border="0"><thead><tr class="segtitle"><th>Command</th><th>Result</th></tr></thead><tbody><tr class="seglistitem"><td class="seg"><code class="command">make help</code></td><td class="seg">List available <code class="command">make</code> commands for building a book.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make help_params</code></td><td class="seg">List available parameters that can be set in the <code class="filename">Makefile</code>.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make test-en-US</code></td><td class="seg">Check that the book can be built correctly. Run the <code class="command">make test</code> command before running any other <code class="command">make</code> command, and before checking a book back into a repository (i.e. CVS or SVN).</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make html-en-US</code></td><td class="seg">Build the bo
 ok in HTML format. The HTML output will be located in the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>/tmp/en-<em class="replaceable"><code>US</code></em>/html/</code> directory.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make html-single-en-US</code></td><td class="seg">Build the book HTML format. The output will be a single HTML file located in the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>/tmp/en-<em class="replaceable"><code>US</code></em>/html-single/</code> directory.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make htmlhelp-en-US</code></td><td class="seg">Build the book in HTML HELP format. HTML HELP is a limited form of HTML, designed to be viewed regardless of your platform or Web browser. The output is located in the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>/tmp/en-<em class="replaceable"><code>US</code></em>/htmlhel
 p/</code> directory.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make pdf-en-US</code></td><td class="seg">Build the book in PDF format. This may not be supported on all systems.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make clean</code></td><td class="seg">Remove all files and folders in the <code class="filename">tmp/</code> subdirectory. The <code class="filename">tmp/</code> subdirectory is created after running a <code class="command">make</code> command to build a book, such as <code class="command">make html</code>.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make web-srpm-en-US</code></td><td class="seg">Create a source RPM to generate web based documentation RPMs from.</td></tr><tr class="seglistitem"><td class="seg"><code class="command">make clean_ids</code></td><td class="seg">Change all IDs to a standard format. This format is <em class="replaceable"><code>Book_Name-title</code><
 /em>. For example, a section with a title of <code class="computeroutput">First Section</code> in a book named <code class="computeroutput">Test_Book</code> will have the following ID after running <code class="command">make clean_ids</code>: <code class="computeroutput"><section id="Test_Book-First_Section"></code></td></tr></tbody></table></div><div class="warning"><h2>Warning: make clean_ids</h2><div class="para">
				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">
				Failing to have the po files checked out before running <code class="command">make clean_ids</code> causes the XML and po files to slip out of sync. And this means all links in the po files have to be manually updated.
			</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Using_the_publican_package-Adding_Images.html"><strong>Prev</strong>3.4.Â Adding Images</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-Conditional_Tagging.html"><strong>Next</strong>3.6.Â Conditional Tagging</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Using_the_publican_package-Creating_a_Book.html ---
<?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><title>3.2.Â Creating a Book</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/><link rel="prev" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/><link rel="next" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html" title="3.3.Â Files in the Book directory"/></head><body class=""><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_the_publican_package.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_the_publican_package-Creating_a_Book">3.2.Â Creating a Book</h2></div></div></div><div class="para">
			Use the <code class="command">create_book</code> command to create a new book. The <code class="command">create_book</code> command creates all the necessary files to create a book.
		</div><div class="para">
			The following is a list of valid options for the <code class="command">create_book</code> command. Append these options to the end of the <code class="command">create_book</code> command. For example, <code class="command">create_book --help</code>, <code class="command">create_book --name New_Book</code>, and so on:
		</div><div class="variablelist"><dl><dt><span class="term"><code class="filename">--help</code></span></dt><dd><div class="para">
						print a list of all <code class="command">create_book</code> command options.
					</div></dd><dt><span class="term"><code class="filename">--man</code></span></dt><dd><div class="para">
						view the publican manual page. The manual page contains the same information returned by the <code class="command">create_book --help</code> command.
					</div></dd><dt><span class="term"><code class="filename">--name<em class="replaceable"><code> Book_Name</code></em></code></span></dt><dd><div class="para">
						replace <em class="replaceable"><code>Book_Name</code></em> with the name of the book or article. This variable must not contain any spaces. For example, running the <code class="command">create_book --name Test_Book</code> command creates a book named Test_Book, and all the necessary files to build the book. This updates the <code class="filename">Makefile</code> with the correct <code class="computeroutput">DOCNAME</code>, and the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.ent</code> file with the correct <code class="computeroutput">BOOKID</code>.
					</div></dd><dt><span class="term"><code class="filename">--version<em class="replaceable"><code> version</code></em></code></span></dt><dd><div class="para">
						replace <em class="replaceable"><code>version</code></em> with the version number of the product that the book describes. For example, for Red Hat Enterprise Linux 5.1 you would use 5.1. The default version is 0.1. Using <code class="command">--version <em class="replaceable"><code> version</code></em></code> updates the <code class="computeroutput"><issuenum></issuenum></code> tags in the <code class="filename">Book_Info.xml</code> file. For more information see <a class="xref" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html" title="3.3.2.Â Book_Info.xml">SectionÂ 3.3.2, â€œBook_Info.xmlâ€</a>.
					</div></dd><dt><span class="term"><code class="filename">--edition<em class="replaceable"><code> edition</code></em></code></span></dt><dd><div class="para">
						replace <em class="replaceable"><code> edition</code></em> with the edition number of the book. This number indicates to users when a new edition of the book is released. The initial GA release of the book should be edition 1.0. The default value is 0. Using <code class="command">--edition<em class="replaceable"><code> edition</code></em></code> updates the <code class="computeroutput"><edition></edition></code> tags in the <code class="filename">Book_Info.xml</code> file. For more information see <a class="xref" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html" title="3.3.2.Â Book_Info.xml">SectionÂ 3.3.2, â€œBook_Info.xmlâ€</a>.
					</div></dd><dt><span class="term"><code class="filename">--product<em class="replaceable"><code> Product_Name</code></em></code></span></dt><dd><div class="para">
						replace <em class="replaceable"><code> Product_Name</code></em> with the product name. This variable must not contain any spaces. Set this to <code class="computeroutput">Fedora</code> for core Fedora documentation, and the name of the product for other products, for example, <code class="computeroutput">Fedora_Directory_Server</code>. The <code class="command">--product<em class="replaceable"><code> Product_Name</code></em></code> option updates the <code class="filename">Makefile</code> and the <code class="filename"><em class="replaceable"><code>Book_Name</code></em>.ent</code> file with the correct product name.
					</div></dd><dt><span class="term"><code class="filename">--type Article --name<em class="replaceable"><code> Article_Name</code></em></code></span></dt><dd><div class="para">
						create an article instead of a book. Replace <em class="replaceable"><code> Article_Name</code></em> with the article name. This variable must not contain any spaces.
					</div></dd><dt><span class="term"><code class="filename">--brand <em class="replaceable"><code>brand</code></em></code></span></dt><dd><div class="para">
						replace <em class="replaceable"><code>brand</code></em> with RedHat, fedora, JBoss, oVirt, or GIMP. This requires the appropriate publican package to be installed. For example, to build Red Hat branded books, you must install the publican-redhat package. See <a class="xref" href="chap-Users_Guide-Using_the_publican_package.html#sect-Users_Guide-Using_the_publican_package-Installing_publican" title="3.1.Â Installing publican">SectionÂ 3.1, â€œInstalling publicanâ€</a> for instructions on installing the branded publican packages. If no brand is specified, the default brand is used.
					</div></dd></dl></div><div class="para">
			Before running the <code class="command">create_book</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 Test_Book in the <code class="filename">/my/books/</code> directory, run the following commands:
		</div><div class="para">

<pre class="screen">cd /my/books/
</pre>
		</div><div class="para">

<pre class="screen">create_book --name Test_Book
</pre>
		</div><div class="para">
			To see the results of this command, run the following:
		</div><div class="para">

<pre class="screen">ls
</pre>
		</div><div class="para">
			The output should be similar to the following:
		</div><div class="para">

<pre class="screen">en-US  Makefile
</pre>
		</div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Users_Guide-Using_the_publican_package.html"><strong>Prev</strong>ChapterÂ 3.Â Using the publican package</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-Using_the_publican_package-Files_in_the_Book_directory.html"><strong>Next</strong>3.3.Â Files in the Book directory</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory.html ---
<?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><title>3.3.Â Files in the Book directory</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/><link rel="prev" href="sect-Users_Guide-Using_the_publican_package-Creating_a_Book.html" title="3.2.Â Creating a Book"/><link rel="next" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html" title="3.3.2.Â Book_Info.xml"/></head><body class=""><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="ri
 ght" 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-Using_the_publican_package-Creating_a_Book.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Files_in_the_Book_directory-Book_Info.xml.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_the_publican_package-Files_in_the_Book_directory">3.3.Â Files in the Book directory</h2></div></div></div><div class="para">
			Running the <code class="command">create_book --name <em class="replaceable"><code>Book_Name</code></em></code> command will create a directory structure and the required files, similar to the following:
		</div><div class="figure" id="figu-Users_Guide-Files_in_the_Book_directory-directory_structure"><div class="figure-contents"><div class="mediaobject"><img src="./images/directory_structure.png" alt="directory structure"/></div></div><h6>FigureÂ 3.1.Â directory structure</h6></div><br class="figure-break"/><div class="section" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Files_in_the_Book_directory-The_Makefile">3.3.1.Â The Makefile</h3></div></div></div><div class="para">
				The <code class="filename">Makefile</code> is used to configure build options, and is located in the root of the book directory. The following is an example <code class="filename">Makefile</code>, with instructions following afterwards:
			</div><pre class="programlisting">#Makefile for MYBOOK

XML_LANG	= en-US
BRAND		= common

#OTHER_LANGS	= as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW

# Extra Parameters start here

# Extra Parameters stop here
COMMON_CONFIG  = /usr/share/publican
include $(COMMON_CONFIG)/make/Makefile.common

</pre><div class="variablelist"><dl><dt><span class="term"><code class="filename">XML_LANG</code></span></dt><dd><div class="para">
							set this to the language of the source xml files, for example, <code class="computeroutput">en-US</code>.
						</div></dd><dt><span class="term"><code class="filename">BRAND</code></span></dt><dd><div class="para">
							set the brand of the book. Accepted values are <code class="computeroutput">RedHat</code>, <code class="computeroutput">fedora</code>, <code class="computeroutput">JBoss</code>, <code class="computeroutput">oVirt</code> and <code class="computeroutput">GIMP</code>. If no brand is specified, the default brand is used.
						</div><div class="para">
							Running the <code class="command">create_book --name <em class="replaceable"><code>Book_Name</code></em> --brand <em class="replaceable"><code>brand</code></em></code> command correctly configures the <code class="computeroutput">BRAND</code>.
						</div></dd><dt><span class="term"><code class="filename">OTHER_LANGS</code></span></dt><dd><div class="para">
							space-separated list of other language locales. Used to specify other language locales to build the book in.
						</div></dd></dl></div><div class="para">
				The following is an example <code class="filename">Makefile</code> that includes translations:
			</div><div class="para">

<pre class="programlisting">XML_LANG       = en-US
BRAND	       = RedHat

OTHER_LANGS    = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW

COMMON_CONFIG  = /usr/share/publican
include $(COMMON_CONFIG)/make/Makefile.common
</pre>
			</div><div class="note"><h2>Note</h2><div class="para">
					<code class="computeroutput">OTHER_LANGS</code> is no longer commented out.
				</div></div><div class="note"><h2>Note</h2><div class="para">
					Run the <code class="command">make help_params</code> command in the root directory of a book for a full list of parameters that can be set in the <code class="filename">Makefile</code>.
				</div></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Using_the_publican_package-Creating_a_Book.html"><strong>Prev</strong>3.2.Â Creating a Book</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-Files_in_the_Book_directory-Book_Info.xml.html"><strong>Next</strong>3.3.2.Â Book_Info.xml</a></li></ul></body></html>

--- NEW FILE sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation.html ---
<?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><title>3.7.Â Pre-release software and draft documentation</title><link rel="stylesheet" href="./Common_Content/css/default.css" type="text/css"/><meta name="generator" content="publican"/><meta name="package" content="Publican-Users_Guide-0.44-en-US-1.2-0"/><meta name="keywords" content="using, help"/><meta name="keywords" content="publican, docbook, publishing"/><link rel="home" href="index.html" title="Users Guide"/><link rel="up" href="chap-Users_Guide-Using_the_publican_package.html" title="ChapterÂ 3.Â Using the publican package"/><link rel="prev" href="sect-Users_Guide-Conditional_Tagging.html" title="3.6.Â Conditional Tagging"/><link rel="next" href="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html" title="3.7.2.Â Denoting draft documentation"/></head><body class=""><p id="title"><a class="left" href="https://fedorahosted.org/publican"><img src="Common_Content/images/image_l
 eft.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-Conditional_Tagging.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html"><strong>Next</strong></a></li></ul><div class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="sect-Users_Guide-Using_the_publican_package-Pre_release_software_and_draft_documentation">3.7.Â 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" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">3.7.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:
			</div><div class="procedure"><ol class="1"><li><div class="para">
						Add the software's pre-release version number, or equivalent state information, to the subtitle in your <code class="filename">Book_Info.xml</code> file. Place this additional text in <code class="sgmltag-element"><remark></code> tags. For example:
					</div><pre class="programlisting"><subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
</pre></li><li><div class="para">
						add <code class="varname">SHOW_REMARKS</code> to the <code class="filename">Makefile</code> and set it to '1':
					</div><pre class="programlisting">SHOW_REMARKS = 1
</pre></li></ol></div><div class="para">
				When your book is built with this text and setting, the software's status is displayed in clear and unmistakable fashion. PDF builds display the remark on their cover and title pages. HTML builds (both html and html-single) display the remark near the beginning of index.html
			</div><div class="para">
				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><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Users_Guide-Conditional_Tagging.html"><strong>Prev</strong>3.6.Â Conditional Tagging</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-Pre_release_software_and_draft_documentation-Denoting_draft_documentation.html"><strong>Next</strong>3.7.2.Â Denoting draft documentation</a></li></ul></body></html>