# Installing Publican

## Linux operating systems

### Important — Availability in repositories

The procedures documented in this section assume that Publican and its various dependencies are available in repositories to which your system has access.

### Fedora & Red Hat Enterprise Linux 6

1. Open a terminal.

2. Change to the root user: `su -`

3. Run the following command to install the `publican` package and the `publican-doc` documentation package:

       $ yum install publican\*

Several brand packages are available for use with Publican. Run the following command as the root user to install packages for building branded books:

    $  yum install publican-brand

Replace brand with, for example, `redhat`, `fedora`, `jboss`, `ovirt`, or `gimp`. Refer to for more information on branding.

### Ubuntu

1. Open a terminal.

2. Run the following command to install the `publican` package:

       $ sudo apt-get install publican

### Running publican from a GIT checkout

It is possible to run publican from a GIT checkout, without installing it, if the dependencies are installed.

1. To checkout the source from GIT open a terminal.

2. Run the following commands to checkout the `publican` source from GIT:

       $ cd PATH TO PLACE SOURCE
       $ git clone git://git.fedorahosted.org/publican.git publican

3. To run publican from this checkout run the following commands:

       $ PUBLICAN_PATH="PATH TO PLACE SOURCE/publican"
       $ perl -CDAS -I $PUBLICAN_PATH/lib $PUBLICAN_PATH/bin/publican build  --brand_dir $PUBLICAN_PATH/datadir/Common_Content/common --formats html

## Windows operating systems

1. Download the Publican installer from `https://fedorahosted.org/releases/p/u/publican/`.

2. Browse to the folder to which you downloaded `Publican-Installer-version.exe`.

3. Double-click the `Publican-Installer-version.exe` file.

4. The installer presents you with a series of license agreements. All of the files that constitute a Publican installation are available under a free license. However, because different licenses are more suitable for certain parts of Publican than others, the Publican 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 Publican installation. We chose this combination of licenses to allow you to use Publican as freely as possible and to allow you to choose whatever license you prefer for the documents that you publish with Publican.

   Read the terms of the various license agreements. If you agree to their terms, click I Agree on each of them, otherwise, click Cancel.

5. The installer offers to install several components: Publican itself (labeled `Main` in the installer window), a number of brands (including `RedHat`, `JBoss`, and `fedora`), and two DocBook components (the DocBook Data Type Definition (DTD) and DocBook Extensible Stylesheet Language (XSL) stylesheets). The three brands are grouped under the collapsible heading `Brands` and the DocBook components are grouped under the collapsible heading `DocBook` in the installer window. Refer to for an explanation of brands in Publican. Publican 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, Publican must download this data from the Internet every time it processes a document, which creates lengthy delays.

   All components are selected by default. Click the checkboxes to deselect any components that you do not require and click Next to continue.

6. By default, the installer software creates a folder named `Publican` within the `%ProgramFiles%` folder of your computer — typically `C:\Program Files\Publican`. You can manually edit the path displayed in the Destination Folder box to select a different folder.

7. When you are satisfied with the destination folder, click Install.

   The installer displays a progress bar as it installs Publican. To see more detailed information about the progress of the installation, click Show details.

8. When the process finishes, the installer notifies you with the message `Completed`.

   Click Close to close the installer.

## OSX Lion

1. Install Xcode from Mac App store.

   Xcode is about 4GB. Be prepared to wait. It has things you need, though.

2. Install Macports from `http://guide.macports.org/chunked/installing.macports.html`. Everything you install with it goes into `/opt/local`, away from your normal OS files.

3. Open a terminal.

4. Install dependencies for publican, which are available as ports:

       $sudo port install 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

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

       $sudo cpanLocale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables

6. Install FOP if you want PDFs to work:

       $ sudo port install fop

       $ echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc

7. Check out Publican Main branch. This command should be run from your user home directory, for instance `/Users/yourusername`

       $ git clone git://git.fedorahosted.org/publican.git

8. Change directories:

       $ cd publican/publican

9. This directory should contain a file named `Build.pl`. Verify that you are in the correct directory, then run the following command. Ignore all the messages you get.

       $ perl ./Build.PL

       $ ./Build

10. Run the following command to install Publican and put all of its bits into `/opt/local`:

        $ sudo ./Build install

### Create and build a book

1.     $ publican create --name=testbook

2.     $ cd testbook

3.     $ publican build --formats=html --langs=en-US

4. Open the `tmp/en-US/html/index.html` file in a browser to prove that it built correctly.

### Install a brand

1. Fix the permissions of the Commons Brand. You have to do this only once. This is a bug that will be addressed eventually.

       $ find /opt/local/share/publican -type f |xargs sudo chmod 644

2. Either check out the SVN for your brand, or get a pre-built brand from a friend.

   1. The SVN location for the brands supplied by Red Hat is `http://svn.fedorahosted.org/svn/publican`

   2. If you use a pre-built brand, extract it as necessary.

3. If you got the brand from SVN, build it.

       $ cd publican/publican-jboss

       $ publican build --formats=xml --langs=all --publish

4. Install the brand.

       $ sudo publican install_brand --path=/opt/local/share/publican/Common_Content

   You can now use the brand in your books by editing your book's `publican.cfg` file or specifying the `--brand` option when creating your book.