# 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

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 publican-doc

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.

### Red Hat Enterprise Linux 5

#### Important — Unsupported software

Publican is not part of the Red Hat Enterprise Linux distribution. Therefore, Red Hat does not offer support for Publican.

#### Important — Dependencies available only internally to Red Hat

Installing Publican on Red Hat Enterprise Linux 5 requires a number of dependencies that are presently available only in yum repositories that are internal to Red Hat.

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 publican-doc

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

#### Important — New in 10.4 "Lucid Lynx"

Publican is new in Ubuntu 10.4 "Lucid Lynx".

1. Open a terminal.

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

       $ sudo apt-get install publican

### Debian

#### Warning — Complete this procedure

Complete every step of this procedure. If you do not undo the changes that you make to the `/etc/apt/sources.list` file as described, your system might become unstable.

Publican is not available in the current stable version of Debian (version 5.0, "Lenny"), but is available in the current testing version ("Squeeze"). To install Publican on a computer that runs Debian, temporarily enable access to the `squeeze` repository. When you enable access to this repository, you allow your computer to install newer software and newer versions of existing software than what is available in the current stable version of Debian. However, not all of the software available in the testing repository has completed quality assurance testing yet. If you do not disable access to this repository after you install Publican, the next time that your system updates, it will replace software packages on your system with newer but possibly untested versions of those packages that it downloads from the testing repository.

1. Open a terminal.

2. Open your `/etc/apt/sources.list` file in a text editor. For example, to edit the file in gedit run:

       $ sudo gedit /etc/apt/sources.list

3. Add the following line to the end of the file:

       deb http://ftp.debian.org/debian/ squeeze main

4. Save the file and close the text editor.

5. Run the following command to update the list of packages available to your computer:

       $ sudo apt-get update

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

       $ sudo apt-get install publican

7. Open your `/etc/apt/sources.list` file again, and delete the extra line that you added in this procedure.

Note that until the release of "Squeeze" as the stable version of Debian, you must manually enable and disable access to the testing repository as described in this procedure whenever a new version of Publican becomes available in the testing repository. You can find up-to-date information about the status of Publican for Debian at , including the version number of Publican available in the repository (2.1 at the time of writing).

When "Squeeze" becomes the stable version of Debian, you will not need to enable or disable access to extra repositories to install Publican on systems that run that version of the operating system.

## Windows operating systems

1. Download the Publican installer from .

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

Test

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

   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.