<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<chapter conformance="181" version="5.0" xml:id="chap-Publican-Users_Guide-Installing_Publican" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
	<info>
		<title>Installing Publican</title>

	</info>
	 <section conformance="182" xml:id="sect-Publican-Users_Guide-Installing_Publican-Linux_operating_systems">
		<info>
			<title>Linux operating systems</title>

		</info>
		 <important>
			<info>
				<title>Important — Availability in repositories</title>

			</info>
			 <para>
				The procedures documented in this section assume that <application>Publican</application> and its various dependencies are available in repositories to which your system has access.
			</para>

		</important>
		 <section conformance="183" xml:id="sect-Publican-Users_Guide-Linux_operating_systems-Fedora">
			<info>
				<title>Fedora &amp; Red Hat Enterprise Linux 6</title>

			</info>
			 <procedure>
				<step>
					<para>
						Open a terminal.
					</para>

				</step>
				 <step>
					<para>
						Change to the root user: <command> su - </command>
					</para>

				</step>
				 <step>
					<para>
						Run the following command to install the <package>publican</package> package and the <package>publican-doc</package> documentation package:
					</para>
					 
<screen><prompt>$</prompt> yum install publican\*</screen>

				</step>

			</procedure>
			 <para>
				Several brand packages are available for use with <application>Publican</application>. Run the following command as the root user to install packages for building branded books:
			</para>
			 
<screen><prompt>$</prompt> <command> yum install publican-<replaceable>brand</replaceable></command></screen>
			 <para>
				Replace <replaceable>brand</replaceable> with, for example, <literal>redhat</literal>, <literal>fedora</literal>, <literal>jboss</literal>, <literal>ovirt</literal>, or <literal>gimp</literal>. Refer to <xref linkend="chap-Publican-Users_Guide-Branding" /> for more information on branding.
			</para>

		</section>
		 <section conformance="185" xml:id="sect-Publican-Users_Guide-Linux_operating_systems-Ubuntu">
			<info>
				<title>Ubuntu</title>

			</info>
			 <procedure>
				<step>
					<para>
						Open a terminal.
					</para>

				</step>
				 <step>
					<para>
						Run the following command to install the <package>publican</package> package:
					</para>
					 
<screen><prompt>$</prompt> <command>sudo apt-get install publican</command></screen>

				</step>

			</procedure>

		</section>
		 <xi:include href="Installing_Publican_Debian.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
		 <xi:include href="Installing_Publican_OpenSuse.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
		 <xi:include href="Installing_Publican_Docker.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
		 <section>
			<info>
				<title>Running publican from a GIT checkout</title>

			</info>
			 <para>
				It is possible to run publican from a <application>GIT</application> checkout, without installing it, if the dependencies are installed.
			</para>
			 <procedure>
				<step>
					<para>
						To checkout the source from GIT open a terminal.
					</para>

				</step>
				 <step>
					<para>
						Run the following commands to checkout the <package>publican</package> source from GIT:
					</para>
					 
<screen><prompt>$</prompt> cd <replaceable>PATH TO PLACE SOURCE</replaceable>
<prompt>$</prompt> git clone git://git.fedorahosted.org/publican.git publican</screen>

				</step>
				 <step>
					<para>
						To run publican from this checkout run the following commands:
					</para>
					 
<screen><prompt>$</prompt> PUBLICAN_PATH="<replaceable>PATH TO PLACE SOURCE</replaceable>/publican"
<prompt>$</prompt> perl -CDAS -I $PUBLICAN_PATH/lib $PUBLICAN_PATH/bin/publican build  --brand_dir $PUBLICAN_PATH/datadir/Common_Content/common --formats html</screen>

				</step>

			</procedure>

		</section>

	</section>
	 <section conformance="187" xml:id="sect-Publican-Users_Guide-Installing_Publican-Windows_operating_systems">
		<info>
			<title>Windows operating systems</title>

		</info>
		 <procedure>
			<step>
				<para>
					Download the Publican installer from <uri xlink:href="https://fedorahosted.org/releases/p/u/publican/" xmlns:xlink="http://www.w3.org/1999/xlink">https://fedorahosted.org/releases/p/u/publican/</uri>.
				</para>

			</step>
			 <step>
				<para>
					Browse to the folder to which you downloaded <filename>Publican-Installer-<replaceable>version</replaceable>.exe</filename>.
				</para>

			</step>
			 <step>
				<para>
					Double-click the <filename>Publican-Installer-<replaceable>version</replaceable>.exe</filename> file.
				</para>

			</step>
			 <step>
				<para>
					The installer presents you with a series of license agreements. All of the files that constitute a <application>Publican</application> installation are available under a free license. However, because different licenses are more suitable for certain parts of <application>Publican</application> than others, the <application>Publican</application> files are not all available under the same free license. Each license grants you a different set of rights and responsibilities when you copy or modify the files in your <application>Publican</application> installation. We chose this combination of licenses to allow you to use <application>Publican</application> as freely as possible and to allow you to choose whatever license you prefer for the documents that you publish with <application>Publican</application>.
				</para>
				 <para>
					Read the terms of the various license agreements. If you agree to their terms, click <guibutton>I Agree</guibutton> on each of them, otherwise, click <guibutton>Cancel</guibutton>.
				</para>

			</step>
			 <step>
				<para>
					The installer offers to install several components: <application>Publican</application> itself (labeled <literal>Main</literal> in the installer window), a number of <firstterm>brands</firstterm> (including <literal>RedHat</literal>, <literal>JBoss</literal>, and <literal>fedora</literal>), and two DocBook components (the DocBook <firstterm>Data Type Definition</firstterm> (DTD) and DocBook <firstterm>Extensible Stylesheet Language</firstterm> (XSL) stylesheets). The three brands are grouped under the collapsible heading <literal>Brands</literal> and the DocBook components are grouped under the collapsible heading <literal>DocBook</literal> in the installer window. Refer to <xref linkend="chap-Publican-Users_Guide-Branding" /> for an explanation of brands in <application>Publican</application>. <application>Publican</application> uses the DTD and the XSL stylesheets to render XML documents in other presentation formats (such as HTML and PDF). If you do not install these components, <application>Publican</application> must download this data from the Internet every time it processes a document, which creates lengthy delays.
				</para>
				 <para>
					All components are selected by default. Click the checkboxes to deselect any components that you do <emphasis>not</emphasis> require and click <guibutton>Next</guibutton> to continue.
				</para>

			</step>
			 <step>
				<para>
					By default, the installer software creates a folder named <filename>Publican</filename> within the <filename><replaceable>%ProgramFiles%</replaceable></filename> folder of your computer — typically <filename>C:\Program Files\Publican</filename>. You can manually edit the path displayed in the <guilabel>Destination Folder</guilabel> box to select a different folder.
				</para>

			</step>
			 <step>
				<para>
					When you are satisfied with the destination folder, click <guibutton>Install</guibutton>.
				</para>
				 <para>
					The installer displays a progress bar as it installs <application>Publican</application>. To see more detailed information about the progress of the installation, click <guibutton>Show details</guibutton>.
				</para>

			</step>
			 <step>
				<para>
					When the process finishes, the installer notifies you with the message <computeroutput>Completed</computeroutput>.
				</para>
				 <para>
					Click <guibutton>Close</guibutton> to close the installer.
				</para>

			</step>

		</procedure>

	</section>
	 <section conformance="235" xml:id="sect-Publican-Users_Guide-Installing_Publican-OSX_Lion">
		<info>
			<title>OSX Lion</title>

		</info>
		 <procedure>
			<step>
				<para>
					Install <application>Xcode</application> from Mac App store.
				</para>
				 <note>
					<para>
						<application>Xcode</application> is about 4GB. Be prepared to wait. It has things you need, though.
					</para>

				</note>

			</step>
			 <step>
				<para>
					Install <application>Macports</application> from <uri xlink:href="http://guide.macports.org/chunked/installing.macports.html" xmlns:xlink="http://www.w3.org/1999/xlink">http://guide.macports.org/chunked/installing.macports.html</uri>. Everything you install with it goes into <filename>/opt/local</filename>, away from your normal OS files.
				</para>

			</step>
			 <step>
				<para>
					Open a terminal.
				</para>

			</step>
			 <step>
				<para>
					Install dependencies for publican, which are available as ports:
				</para>
				 
<screen><prompt>$</prompt><command>sudo port install</command> <option>docbook-xml docbook-xsl docbook-sgml-4.2 perl5 bash-completion p5-file-pushd p5-config-simple p5-file-find-rule p5-file-slurp p5-class-trigger p5-time-hires p5-list-moreutils p5-ipc-run3 p5-class-accessor p5-test-perl-critic p5-xml-libxslt p5-locale-gettext p5-image-size p5-file-copy-recursive p5-datetime p5-archive-zip p5-timedate p5-html-format p5-dbd-sqlite p5-xml-simple p5-devel-cover p5-test-pod p5-test-pod-coverage p5-template-toolkit</option></screen>

			</step>
			 <step>
				<para>
					Install CPAN modules for dependencies which can't be satisfied with ports. Note: this step will generate lots of messages, including warnings. Don't worry about them.
				</para>
				 
<screen><prompt>$</prompt><command>sudo cpan</command><option>Locale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables</option></screen>

			</step>
			 <step>
				<para>
					Install FOP if you want PDFs to work:
				</para>
				 
<screen><prompt>$</prompt> <command>sudo port install</command> <option>fop</option></screen>
				 
<screen><prompt>$</prompt> <command>echo</command> <option>"FOP_OPTS='-Xms50m -Xmx700m'" &gt; ~/.foprc</option></screen>

			</step>
			 <step>
				<para>
					Check out Publican Main branch. This command should be run from your user home directory, for instance <filename>/Users/yourusername</filename>
				</para>
				 
<screen><prompt>$</prompt> <command>git clone</command> <option>git://git.fedorahosted.org/publican.git</option></screen>

			</step>
			 <step>
				<para>
					Change directories:
				</para>
				 
<screen><prompt>$</prompt> <command>cd</command> <option>publican/publican</option></screen>

			</step>
			 <step>
				<para>
					This directory should contain a file named <filename>Build.pl</filename>. Verify that you are in the correct directory, then run the following command. Ignore all the messages you get.
				</para>
				 
<screen><prompt>$</prompt> <command>perl ./Build.PL</command></screen>
				 
<screen><prompt>$</prompt> <command>./Build</command></screen>

			</step>
			 <step>
				<para>
					Run the following command to install <application>Publican</application> and put all of its bits into <filename>/opt/local</filename>:
				</para>
				 
<screen><prompt>$</prompt> <command>sudo ./Build install</command></screen>

			</step>

		</procedure>
		 <procedure conformance="247" xml:id="proc-Publican-Users_Guide-OSX_Lion-Create_and_build_a_book">
			<title>Create and build a book</title>

			 <step>
				
<screen><prompt>$</prompt> <command>publican create</command> <option>--name=testbook</option></screen>

			</step>
			 <step>
				
<screen><prompt>$</prompt> <command>cd testbook</command></screen>

			</step>
			 <step>
				
<screen><prompt>$</prompt> <command>publican build</command> <option>--formats=html --langs=en-US</option></screen>

			</step>
			 <step>
				<para>
					Open the <filename>tmp/en-US/html/index.html</filename> file in a browser to prove that it built correctly.
				</para>

			</step>

		</procedure>
		 <procedure conformance="248" xml:id="proc-Publican-Users_Guide-OSX_Lion-Install_a_brand">
			<title>Install a brand</title>
			 <step>
				<para>
					Fix the permissions of the Commons Brand. You have to do this only once. This is a bug that will be addressed eventually.
				</para>
				 
<screen><prompt>$</prompt> <command>find /opt/local/share/publican</command> <option>-type f</option> |<command>xargs sudo chmod 644</command></screen>

			</step>
			 <step>
				<para>
					Either check out the SVN for your brand, or get a pre-built brand from a friend.
				</para>
				 <substeps role="alternatives">
					<step>
						<para>
							The SVN location for the brands supplied by Red Hat is <uri xlink:href="http://svn.fedorahosted.org/svn/publican" xmlns:xlink="http://www.w3.org/1999/xlink">http://svn.fedorahosted.org/svn/publican</uri>
						</para>

					</step>
					 <step>
						<para>
							If you use a pre-built brand, extract it as necessary.
						</para>

					</step>

				</substeps>

			</step>
			 <step>
				<para>
					If you got the brand from SVN, build it.
				</para>
				 
<screen><prompt>$</prompt> <command>cd publican/publican-jboss</command></screen>
				 
<screen><prompt>$</prompt> <command>publican build</command> <option>--formats=xml --langs=all --publish</option></screen>

			</step>
			 <step>
				<para>
					Install the brand.
				</para>
				 
<screen><prompt>$</prompt> <command>sudo publican install_brand</command> <option>--path=/opt/local/share/publican/Common_Content</option></screen>
				 <para>
					You can now use the brand in your books by editing your book's <filename>publican.cfg</filename> file or specifying the <option>--brand</option> option when creating your book.
				</para>

			</step>

		</procedure>

	</section>

</chapter>