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