# 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

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

   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

   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

   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.