Chapter 1. Installing Publican

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. 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 Chapter 5, Branding for more information on branding.

1.2. Ubuntu

  1. Open a terminal.

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

    $ sudo apt-get install publican

1.3. Debian

This procedure will install the publican version that is in your default Debian repository. It will also install a large number of packages that publican depends on, like Java, XML and image processing libraries and many ancillary Perl modules.

  1. Open a terminal.

  2. Change to the root user: su -

  3. Run the following command to install the publican package: 

    $ apt-get install publican

  4. Run the following command to determine what version of publican is installed: 

    $ publican -v
version=2.8
Important — Installing more recent packages using Apt-Pinning

If you need a more recent release of publican than installed by the procedure above, you can query if there other versions available: http://packages.debian.org/publican.

To date, there has not been any backport (http://backports.debian.org/Instructions/) available for publican, so we need to use Apt Pinning https://wiki.debian.org/AptPreferences

Alternatively, you could run Debian testing or unstable in a virtual machine, chroot or linux container.

Assuming there is a more recent version of publican available in the testing repository, and that you are running the current stable, then you can upgrade by:

  1. Open a terminal.

  2. Change to the root user: su -

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

    $ gedit /etc/apt/sources.list

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

    #### testing  #########
deb http://ftp.us.debian.org/debian testing main contrib non-free

  5. Save the file and close the text editor.

  6. Open (or create) your /etc/apt/preferences file in a text editor. For example, to edit the file in gedit run: 

    $ gedit /etc/apt/preferences

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

    Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release a=testing
Pin-Priority: 400

Package: *
Pin: release o=Debian
Pin-Priority: -10

  8. Save the file and close the text editor.

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

    $ apt-get update

  10. Run the following command to try to install the testing version of publican package, and any updated dependancies: 

    $ apt-get -t testing install publican

Because Apt Pinning mixes 2 different debian streams in an un-tested way, incompatibilities may happen. For example, you may get a warning like: 

$ publican
Warning: program compiled against libxml 209 using older 208
Warning: XML::LibXML compiled against libxml2 20901, but runtime libxml2 is older 20800
Warning: program compiled against libxml 209 using older 208
Warning: XML::LibXSLT compiled against libxslt 10128, but runtime libxslt is older 10126
Can't open publican: No such file or directory at /usr/bin/publican line 430.
Which indicates that you might need to upgrade libxml2 and libxslt to the testing repository version too. This can be done by searching to find the likely library: 

  1. [Show All][Hide]$ apt-get search libxslt
gambas3-gb-xml-xslt - Gambas XSLT component
libidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)
libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)
libical-parser-html-perl - generates HTML calendars from iCalendars
libxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Java
libxml-filter-xslt-perl - Perl module for XSLT as a SAX Filter
libxml-libxslt-perl - Perl interface to the GNOME libxslt library
libxslt1-dbg - XSLT 1.0 processing library - debugging symbols
libxslt1-dev - XSLT 1.0 processing library - development kit
libxslt1.1 - XSLT 1.0 processing library - runtime library
python-libxslt1 - Python bindings for libxslt1
python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)
python-lxml - pythonic binding for the libxml2 and libxslt libraries
python-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)
python3-lxml - pythonic binding for the libxml2 and libxslt libraries
python3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
php5-xsl - XSL module for php5
libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxslt
libsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxslt
swfmill - xml2swf and swf2xml processor
libxslthl-java - XSLT syntax highlighting
    (and the same again for libxml2)

  2. And then upgrading those packages to testing. 

    $ apt-get -t testing upgrade libxml2 libxslt1.1

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

  1. Open a terminal session.

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

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

  4. Download the source code: 

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

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

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

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

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

  9. 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.5. Docker container

Note

This installation procedure assumes you have already installed a working docker (see http://docker.io) environment.

Docker is a lightweight Jail (currently using LXC) that allows you to install and run publican without installing your main Linux installation with all its dependencies.

  1. Open a terminal.

  2. Download and install the svendowideit/publican container from https://index.docker.io/u/svendowideit/publican/: 

    $ docker pull svendowideit/publican
    This will take some time, as it downloads a fedora based container, and then the dependencies needed for publican

  3. Add a publican bash alias to simplify your usage: 

    $ echo 'alias publican="docker run -t -i -v $(pwd):/mnt svendowideit/publican"' >> ~/.bashrc

    This alias assumes that you are running publican in the documentation root directory (the one with the publican.cfg file in it.

  4. now you can use publican as per the documentation: 

    $ publican --version 
version=3.2.1

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