⁠Chapter 1. Installing Publican

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

⁠1.1.1. Fedora

Open a terminal.
Change to the root user: su -
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 Chapter 5, Branding for more information on branding.

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

Open a terminal.
Change to the root user: su -
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 Chapter 5, Branding for more information on branding.

⁠1.1.3. Ubuntu

Important — New in 10.4 "Lucid Lynx"

Publican is new in Ubuntu 10.4 "Lucid Lynx".

Open a terminal.
Run the following command to install the publican package:
```
$ sudo apt-get install publican
```

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

Open a terminal.
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
```

Add the following line to the end of the file:

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

Save the file and close the text editor.
Run the following command to update the list of packages available to your computer:
```
$ sudo apt-get update
```
Run the following command to install the publican package:
```
$ sudo apt-get install publican
```
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 http://packages.debian.org/squeeze/publican, 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.

⁠1.1.5. OpenSuse 12

Publican has not been usable on OpenSuse up until release 12.1. Certain dependencies were missing and could not be found in any known OpenSuse repository. This is not the case with OpenSuse 12.1 as all dependencies can now be found and installed.

The following instructions describe installing Publican from source because, as yet, there is no Publican RPM for OpenSuse 12.1. The version of Publican is 2.9 taken directly from the source repository - previous versions have not been tested but may work.

At the time of writing, Publican 2.8 was the release version and work on 2.9 was still ongoing. For this reason the following instructions are subject to change.

The OpenSuse install was a default one with the following software categories added at install time:

Technical Writing - for the Docbook tools etc.
Perl Development
Web and LAMP Server

The system used had KDE installed which shouldn't make a difference. The following KDE specific categories were also installed:

KDE Development
Desktop Effects

Finally, the entire Games category was removed.

After OpenSuse had completed installing, and all current updates had been applied, the following steps were followed to install Publican.

Open a terminal session.

Install the dependencies that are available from various online repositories - many of these are not present in the installation DVD repository.

$ sudo zypper install perl-Config-Simple perl-DateTime \ perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \ perl-File-Find-Rule perl-File-Which perl-HTML-Format \ perl-Locale-MakeText-Gettext perl-Template-Toolkit \ perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \ perl-YAML liberation-fonts

Note

Liberation-fonts is most likely already installed, but it is required. Zypper will not reinstall it if it is already present.

Use cpan to install the remaining dependencies which cannot be installed by zypper:

$ sudo sh cpan File::pushd File::Copy::Recursive Locale::PO pp \ Syntax::Highlight::Engine::Kate XML::TreeBuilder exit

Download the source code:

$ cd ~ mkdir -p SourceCode/publican cd SourceCode/publican svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./

Build the Publican build script:
```
$ perl Build.PL 
```
If all the dependencies are installed, you should see the following:
```
WARNING: the following files are missing in your kit:
 META.yml
 Please inform the author.

Created MYMETA.yml and MYMETA.json
Creating new 'Build' script for 'Publican' version '2.9'
```
If not, then use cpan (as root) to install the missing modules and run the build again. Replace any forward slashes '/' by a double colon '::' and make sure you use exactly the same letter case, for example: If File/pushd.pm is reported as missing, you would use this to install it:
```
$ sudo sh cpan File::pushd exit 
```
Assuming all went well, the Build.PL script will have created a new script named Build which we will use to create, test and install Publican 2.9.
```
$ ./Build 
```
There will be lots of text scrolling up the screen for a few minutes, you should eventually see the following:
```
DEBUG: Publican::Builder: end of build
```
Test the build:
```
$ ./Build test 
```
Again, lots of scrolling text at the end of which you may see the following:
```
Test Summary Report
-------------------
t/910.publican.Users_Guide.t (Wstat: 256 Tests: 5 Failed: 1)
 Failed test: 5
 Non-zero exit status: 1
t/pod-coverage.t (Wstat: 256 Tests: 9 Failed: 1)
 Failed test: 7
 Non-zero exit status: 1
Files=10, Tests=68, 420 wallclock secs ( 0.31 usr 0.17 sys + 246.87 cusr 18.73 csys = 266.08 CPU)
Result: FAIL
Failed 2/10 test programs. 2/68 subtests failed.
```
Don't worry. This is because of a missing wkhtmltopdf utility which is undergoing tests to be added to Publican in the future to replace Apache FOP as the pdf generation tool of choice. If Publican finds wkhtmltopdf it will use it, otherwise it uses FOP.
Unfortunately, at the time of writing, because OpenSuse names one of the dependencies of wkhtmltopdf differently (ghostscript-fonts-std as opposed to ghostscript-fonts) wkhtmltopdf will not run even if force installed with no dependency checks.
Install wkhtmltopdf.
This step is optional. At the time of writing wkhtmltopdf did not work on OpenSuse 12.1 However, as the problems which prevent it working correctly from Publican may have been resolved, the following instructions give details on installing wkhtmltopdf.
Note
If you intend to create indices in your generated pdf documents, you are advised to use Apache FOP rather than wkhtmltopdf. With FOP you get actual page numbers which is better in a printed document.
```
$ JFEARN=http://jfearn.fedorapeople.org/wkhtmltopdf/f15 MYSYSTEM=i686 ## For 64bit system use MYSYSTEM=x86_64 instead. wget $JFEARN/$MYSYSTEM/wkhtmltopdf-qt-4.7.1-1.git20110804.fc15.i686.rpm wget $JFEARN/$MYSYSTEM/wkhtmltopdf-0.10.0_rc2-1.fc15.i686.rpm 
```
Note
If you use a 64 bit system, make sure to set MYSYSTEM appropriately.
Once downloaded, install both rpms as follows:
```
$ sudo sh rpm -ivh wkhtmltopdf-qt* rpm -ivh --nodeps wkhtmltopdf-0* exit 
```
You have to use the option to ignore dependencies on the latter rpm due to the ghostscript-fonts problem described above.
Install Publican.
The final stage is to install Publican, even though the testing stage had a couple of sub-tests which failed.
```
$ sudo sh ./Build test exit 
```
The following steps are optional but it's a good idea to test that everything is working before you spend time on your own documents.

Test the installed Publican build:

$ publican create --type=book --product=testing --version=1.2.3 --name=TestPublican
  Processing file en-US/Author_Group.xml -> en-US/Author_Group.xml
  Processing file en-US/Book_Info.xml -> en-US/Book_Info.xml
  Processing file en-US/Chapter.xml -> en-US/Chapter.xml
  Processing file en-US/Preface.xml -> en-US/Preface.xml
  Processing file en-US/Revision_History.xml -> en-US/Revision_History.xml
  Processing file en-US/TestPublican.xml -> en-US/TestPublican.xml

$ cd TestPublican/ publican build --lang=all --formats=html,html-single,html-desktop,txt,pdf,epub

Note

At the time of writing, creating epubs with Publican 2.9 on OpenSuse gave the following error:

runtime error: file /usr/share/publican/xsl/epub.xsl element choose
Variable 'epub.embedded.fonts' has not been declared.
 at /usr/lib/perl5/site_perl/5.14.2/Publican/Builder.pm line 915

No epub file was created. The individual working files were however, and can be built into an epub book using Sigil, if desired.

Using the Dolphin file manager, you can browse to SourceCode/TestPublican/tmp/en-US/ and view the various output formats that you find there.

⁠1.2. Windows operating systems

Download the Publican installer from https://fedorahosted.org/releases/p/u/publican/.
Browse to the folder to which you downloaded Publican-Installer-version.exe.
Double-click the Publican-Installer-version.exe file.
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.
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 Chapter 5, Branding 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.
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.
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.
When the process finishes, the installer notifies you with the message Completed.
Click Close to close the installer.

⁠1.3. OSX Lion

Test

Install Xcode from Mac App store.
Note
Xcode is about 4GB. Be prepared to wait. It has things you need, though.
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.
Open a terminal.

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

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

Install FOP if you want PDFs to work:

$ sudo port install fop

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

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
```
Change directories:
```
$ cd publican/publican
```
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
```
Run the following command to install Publican and put all of its bits into /opt/local:
```
$ sudo ./Build install
```

⁠

Procedure 1.1. Create and build a book

```
$ publican create --name=testbook
```
```
$ cd testbook
```

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

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

⁠

Procedure 1.2. Install a brand

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

If you got the brand from SVN, build it.

$ cd publican/publican-jboss

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

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.