Publican a openSUSE

Publican je systém pro generování dokumentace. Je jedním z projektů RedHatu a právě třeba v RedHatu slouží jako hlavní nástroj pro její tvorbu. Dostupný je v nativních balíčcích pro RHEL, CentOS, Fedoru a Debian. A my si dnes ukážeme, jak ho napasovat i na openSUSE.

Proč vlastně Publican

Při tvorbě dokumentace k CzechIdM jsme dlouho používali kombinaci DocBook + Jadetex, která nám ale přišla postupem času stále více krkolomná. Rozhodli jsme se proto přejít právě na Publican, jehož základní šablony jsme si upravili pro potřebu firmy. Na Publicanu se nám líbila jeho relativní jednoduchost, poměrně malé nároky na používané knihovny a hlavně vzhled generovaného výstupu – jak se ostatně můžete přesvědčit.
publican_exmpl

Příprava prostředí a zdrojový kód Publicanu

Nevýhodou je, že openSUSE nemá pro Publican balíčky, proto si budeme muset prográmek zkompilovat. Základní informace nám poskytne oficiální návod, který je ale dosti stručný.

Začneme tím, že si naklonujeme repozitář projektu. Všechno budeme dělat pod rootem, ušetříme si trochu času.

mkdir /opt/tmp
cd /opt/tmp
git clone git://git.fedorahosted.org/publican.git

Build probíhá tak, že je vytvořen klasický rpm balík, který je přes systémový balíčkovač poté nainstalován. Proto potřebujeme následující nástroje / balíčky:

rpmbuild
rpmlint
rpm-devel

Ty už v systému buď jsou nebo se dají doinstalovat přes zypper či YaST. Také musíme mít nainstalované DocBook šablony – ty jsou součástí standardních balíčků. Publican ale vyžaduje šablony verze 1.77 a vyšší. Pokud je nemáme, můžeme je stáhnout zde. Do systému je nainstalujeme klasicky přes package manager.
Ještě budeme potřebovat Perl a některé jeho moduly – a zde na nás čeká první zrada. Rpm se zkompilovaným Publicanem obsahuje závislosti na balíčcích, včetně balíčků s Perlovými moduly. Pokud instalujete (jako já) moduly do Perlu přes CPAN, tak jejich přítomnost nebude vidět ve výpisu nainstalovaných balíčků. To způsobí, že instalace Publicanu selže na nesplněných závislostech, i když jsou ve skutečnosti splněné. Této situaci můžete předejít instalací modulů přes package manager. Pokud budete instalovat přes CPAN, musíte následně upravit specifikační soubor pro rpm Pulicanu (viz. dále). Dále najdete seznam modulů pro Perl, které budete potřebovat.

Devel::Cover
Locale::Maketext::Gettext
Config::Simple
DateTime
DateTime::Format::DateParse
File::Copy::Recursive
File::Find::Rule
File::Inplace
File::pushd
HTML::FormatText
HTML::FormatText::WithLinks
HTML::FormatText::WithLinks::AndTables
Locale::PO
String::Similarity
Syntax::Highlight::Engine::Kate
Template
Template::Constants
Template::Toolkit
XML::LibXSLT
XML::TreeBuilder
XML::XSLT
Text::CSV_XS
Sort::Versions

Pokud moduly nenainstalujete, bude si build skript Publicanu stěžovat. Dobrou zprávou je, že příkazem

./Build installdeps

můžete drtivou většinu modulů nechat automaticky nainstalovat. (Tento příkaz ale vyžaduje CPAN. Skript navíc neexistuje implicitně, nejdříve musíte spustit obdobu configure.) Někdy se může stát, že se CPAN při instalaci modulu zasekne a odmítne modul nainstalovat – v takovém případě pomůže instalace modulu přes package manager.

Fonty

Publican vyžaduje poměrně dost sad fontů. Jejich seznam najdete na Publican Wiki. V době překladu jsem měl nainstalovány tyto sady fontů (a drtivá většina z nich nebyla zapotřebí).

unfonts-1.0.20080608-10.1.2.noarch
sazanami-fonts-20040629-199.1.3.noarch
liberation-fonts-1.06.0.20100721-7.2.1.noarch
lmfonts-1.106-3.1.1.noarch
patterns-openSUSE-fonts-12.1-25.21.1.i586
xorg-x11-fonts-core-7.6-16.1.2.noarch
fonts-config-20080121-66.1.2.noarch
xorg-x11-fonts-7.6-16.1.2.noarch
xorg-x11-fonts-devel-7.6-10.1.2.i586
mplus-fonts-1.0.42-2.1.1.noarch
bpg-fonts-0.20050518-193.1.1.noarch
cantarell-fonts-0.0.7-2.1.1.noarch
ghostscript-fonts-other-9.00-13.4.1.noarch
free-ttf-fonts-1.0-353.1.1.noarch
patterns-openSUSE-fonts_opt-12.1-25.21.1.i586
droid-fonts-1.0-16.1.1.noarch
ghostscript-fonts-std-9.00-13.4.1.noarch
bitstream-vera-1.10-316.1.1.noarch
IPAGothic-003.02-6.1.2.noarch
IPAPGothic-003.02-6.1.2.noarch
baekmuk-ttf-2.1-645.1.2.noarch
baekmuk-2.1-645.1.2.noarch
lklug-0.3-120.1.1.noarch
efont-unicode-0.4.2-228.1.2.noarch
cm-unicode-0.4.2-191.1.2.noarch
liberation-fonts-1.06.0.20100721-7.2.1.noarch
ttf-arphic-ukai-0.1.20060928-99.1.2.noarch
ttf-arphic-uming-0.1.20060928-99.1.2.noarch
ttf-arphic-20001125-777.1.2.noarch

A aby to nebylo tak jednoduché, tak budeme potřebovat i fonty, které nejsou v balíčcích. Jmenovitě cjkuni (které jsem osobně vynechal) a Overpass fonty. Overpass fonty nainstalujeme snadno. Tar stáhneme zde, a dva ttf soubory z něj vybalíme do adresáře

/usr/share/fonts/overpass

Následně spustíme příkaz

fonts-config

kterým aktualizujeme seznam fontů.

Wkhtmltopdf

Publican využívá služeb prográmku wkhtmltopdf, který (překvapivě…) opět nenajdeme v balíčcích. Na openSUSE portálu je sice ke stažení, ale tato verze je zkompilovaná proti neopatchované verzi knihovny Qt4, a tedy pro nás nepoužitelná. Stáhneme tedy statickou verzi wkhtmltopdf odsud (x86,x64). Starší verzi 0.10rc2 stahujeme vědomě. Aktuální verze (v době psaní článku 0.11) trpí totiž na linuxu chybou způsobující nefunkčnost v kombinaci s Publicanem. Archiv rozbalíme a soubor wkhtmltopdf-* přesuneme do

/usr/bin/wkhtmltopdf

Osobně se mi toto řešení moc nelíbí, protože zastávám názor, že cokoli neinstalované z balíčků by mělo skončit v /opt. Proto jsem vytvořil strukturu u sebe takto:

mkdir -pv /opt/wkhtmltopdf
cd /opt/wkhtmltopdf
mv /home/fiisch/Downloads/wkhtmltopdf-i386 ./
cd /usr/bin
ln -s /opt/wkhtmltopdf/wkhtmltopdf-i386 wkhtmltopdf

Tím jsme vyřešili problém závislostí. Nicméně nemáme instalován příslušný balíček, takže budeme stejně muset upravovat specifikační soubor Publicanu.

Úprava specifikačního souboru publican.spec

Soubor publican.spec je základem pro generování metadat našeho rpm balíku. To, co nás na něm bude nejvíce zajímat, jsou seznamy závislostí Requires a BuildRequires. Problémy nám budou činit hlavně rozdílné názvy balíčků. Protože jsme všechny problémy se závislostmi už (snad:-) )odstranili, můžeme tyto kontroly obejít prostě tím, že přílušné klauzule ze souboru smažeme. Toto jsou prováděné úpravy v publican.spec:

řetězec úprava
wkhtmltopdf (smazat řádky, které tento řetězec obsahují)
docbook-style-xsl docbook-xsl-stylesheets
liberation-mono-fonts liberation-sans-fonts liberation-serif-fonts liberation-fonts
ipa-gothic-fonts IPAGothic
ipa-pgothic-fonts IPAPGothic
lklug-fonts lklug
baekmuk-ttf-batang-fonts baekmuk-ttf
cjkuni-uming-fonts (odebrat)
rpmbuild (odebrat; tento program ale musí být přístupný v /usr/bin/rpmbuild)

Teprve teď je vše připraveno a můžeme jít kompilovat.

Kompilace Publicanu

Publican nemá standardní autoconf konfigurační soubory. Prvotním bodem je ale spuštění obdoby konfiguračního skriptu (parametry viz. readme v repozitáři):

cd /opt/tmp/publican/publican

perl Build.PL [parametry]

Tím dostaneme skript s názvem Build, který budeme používat dále. Nyní můžeme (pokud jsme to ještě neudělali) doinstalovat Perl moduly pomocí příkazu

./Build installdeps

Pokud je vše připraveno, pomocí

./Build

spustíme kompilaci. Po úspěšné kompilaci ověříme funkčnost příkazem

./Build test

který nám poskytne nezbytný sanity check. Dokud testy neprojdou, nemá cenu se pokoušet o vygenerování rpm a instalaci.
Pokud testy projdou, spustíme

./Build local

který udělá všechno (včetně kompilace). To je krok zbytečný, ale ničemu nevadí. Výsledkem tohoto příkazu by měl být nainstalovaný a funkční Publican. Další konfigurace (šablony,…) se pak provádí standardní cestou.

Závěr

V článku jsme si ukázali, jak zprovoznit nástroj Publican na openSUSE. Protože nebyly k dispozici binární balíčky, museli jsme ho zkompilovat a řešit problémy se závislostmi. Postup se nicméně může mírně lišit systém od systému – záleží na aktuálně nainstalovaných systémových balíčcích. Pokud byste měli jakékoliv dotazy, neváhejte mi napsat na info@bcvsolutions.eu.