Copyright © 2013 Red Hat, Inc This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.txt).
Abstrakt
Tato kniha vám poradí při instalaci Publican. Také vám poskytne návody jak použít Publican pro tvorbu a zveřejnění knih, článků a sad knih založených na DocBook XML. Příručka předpokládá, že již máte znalosti DocBook XML.
V tomto manuálu je použito několik konvencí pro zvýraznění určitých slov nebo vět a ke zdůraznění konkrétních informací.
Pro zvýraznění slov nebo vět se používají čtyři typografické konvence. Tyto konvence a situace, v nichž se uplatňují, jsou následující.
Neproporcionální tučné
Používá se pro zvýraznění systémového vstupu, včetně příkazů pro shell, názvy souborů a cest. A také pro zvýraznění kláves a jejich kombinací. Například:
Chcete-li zobrazit obsah souboru
my_next_bestselling_novel
v aktuálním adresáři, napište příkaz cat my_next_bestselling_novel v příkazovém řádku a stisknutím Enter ho spustťe.
Příklad výše obsahuje název souboru, příkaz shellu a klávesu. Vše vyznačeno neproporcionálním tučným písmem a odlišené díky kontextu.
Kombinace kláves mohou být odlišeny od jednotlivých kláves znaménkem plus, které spojuje každou část kombinace. Například:
Příkaz spusťte stisknutímEnter .
Do virtuálního terminálu se přepnete stiskem Ctrl+Alt+F2.
První příklad zvýrazňuje konkrétní klávesu, kterou máte stisknout. Druhý příklad zvýrazňuje kombinaci kláves: tři klávesy stisknuté najednou.
Hovoří-li se o zdrojovém kódu, názvy tříd, metody, funkce, názvy proměnných a návratové hodnoty uvedené v odstavci budou rovněž vysázeny jako v příkladu výše, neproporcionálním tučným
písmem. Například:
Mezi třídy související se soubory patří
filesystem
pro souborový systém,file
pro soubory adir
pro adresáře. Každá z těchto tříd má vlastní sadu oprávnění.
Proporcionální tučné
Tak se odlišují slova nebo fráze, které lze spatřit na systému, včetně názvů aplikací; textu v dialogových oknech; názvů tlačítek; popisků výběrových tlačítek; názvů nabídek a podnabídek. Například:
Choose Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
→ → from the main menu bar to launchChcete-li do souboru gedit vložit speciální znak, vyberte → → z lišty hlavní nabídky. Dále vyberte → z nabídkové lišty Mapa znaků, napiště jméno znaku v poli Hledat a klepněte na . Znak, který hledáte bude zvýrazněn v Tabulce znaků. Poklepejte na tento zvýrazněný znak k přesunutí do pole Text ke zkopírování a poté klepněte na tlačítko . Nyní přejděte zpět do vašeho dokumentu a vyberte → z nabídkové lišty gedit.
Výše uvedený text obsahuje názvy aplikací; názvy systémových nabídek a položek; názvy aplikačních nabídek; a tlačítka a text nalézající se v GUI rozhraní, vše vysázené proporcionálním tučným písmem a odlišené kontextem.
Neproporcionální tučná kurzíva nebo Proporcionální tučná kurzíva
Ať již neproporcionální či proporcionální tučné písmo, je-li doplněno o kurzívu, označuje proměnný či nahraditelný text. Kurzíva odlišuje text, který nevkládáme doslovně, nebo zobrazený text, který se mění v závislosti na podmínkách. Například:
Chcete-li se připojit ke vzdálenému systému prostřednictvím ssh, zadejte ssh username@domain.name v příkazovém řádku. Je-li vzdáleným systémem
example.com
a vaše uživatelské jméno v tomto systému je john, zadejte ssh john@example.com.Příkaz mount -o remount file-system znovu připojí zadaný souborový systém. Chcete-li například znovu připojit souborový systém
/home
, je odpovídajícím příkazem mount -o remount /home.Chcete-li zobrazit verzi nainstalovaného balíčku, použijte příkaz rpm -q package. Jeho výstup bude následující: package-version-release.
Všimněte si slov v tučné kurzívě výše - username, domain.name, file-system, package, version a release.
Vedle obvyklého použití pro název díla se kurzíva používá k vyznačení prvího použití nového důležitého termínu. Například:
Publican je publikační systém DocBook.
Výstup terminálu a výpisy zdrojového kódu jsou od ostatního textu odděleny vizuálně.
Výstup poslaný na terminál je uveden v neproporcionální roman
a vysázen takto:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Výpisy zdrojového kódu jsou také uváděny v neproporcionální roman
, ale s přidaným zvýrazňováním systaxe, jako zde:
package org.jboss.book.jca.ex1; import javax.naming.InitialContext; public class ExClient { public static void main(String args[]) throws Exception { InitialContext iniCtx = new InitialContext(); Object ref = iniCtx.lookup("EchoBean"); EchoHome home = (EchoHome) ref; Echo echo = home.create(); System.out.println("Created Echo"); System.out.println("Echo.echo('Hello') = " + echo.echo("Hello")); } }
Pro zvýraznění informací, které by jinak mohly být přehlédnuty, používáme tři vizuální styly.
Poznámky jsou typy, zkratky či alternativní přístupy ke zpracovávaným úkolům. Přehlížení poznámek by nemělo mít negativní důsledky, ale můžete se tak ochudit o informace (triky), které mohou usnadnit váš život.
Tips are tips, shortcuts or alternative approaches to the task at hand. Ignoring a tip should have no negative consequences, but you might miss out on a trick that makes your life easier.
Důležitá pole poskytují podrobnosti o věcech, které lze snadno přehlédnout: změny konfigurace, které se týkají pouze současného sezení, nebo služby, které je nutné restartovat, než se projeví aktualizace. Přehlížení pole označeného 'Důležité' nezpůsobí ztrátu dat, ale může způsobit rozčílení a pocit zmaru.
Varování by neměla být přehlížena. Přehlížení varování povede většinou ke ztrátě dat.
Varování by neměla být přehlížena. Přehlížení varování povede většinou ke ztrátě dat.
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: https://bugzilla.redhat.com/enter_bug.cgi?product=Publican&component=Publican%20Users%20Guide&version=4.1.
Máte-li návrh na vylepšení dokumentace, pokuste se být co nejpřesnější při jeho popisu. Pokud jste nalezli chybu, prosíme uveďte číslo oddílu (kapitoly) a trochu okolního textu, ať ji můžeme snáze nalézt.
Publican \ \n \p is a tool for publishing material authored in DocBook XML. This guide explains how to create and build books and articles using Publican. It is not a general DocBook XML tutorial; refer to DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner, available at http://www.docbook.org/tdg/en/html/docbook.html for more general help with DocBook XML.
Publican zahájil svou existenci jako interní nástroj Dokumentační skupiny Red Hat (jejíž současný název je Engineering Content Services). Občas se tato historie projevuje.
Návrh. Publican je publikační systém, nikoliv jen nástroj pro zpracování DocBook. Stejně jako zajistí validitu vašeho DocBook XML, Publican funguje rovněž tak, že zajistí, aby vaše XML odpovídalo publikační normě.
Funkce grafické úpravy vám umožní vytvořit vlastní pravidla a vzhled své prezentace potlačením mnoha částí výchozího stylu, a dosáhnout tak svých publikačních potřeb. Avšak volby učiněné v kódu nelze změnit.
Entity lze na příklad definovat validně v kterémkoliv souboru XML. Nicméně Publican přepíše deklaraci v každém souboru XML před tím, než sestaví knihu nebo článek, aby zajistil, že deklarace DTD je přítomna, validní a normovaná. Důsledkem je ztráta všech entit deklarovaných ve všech souborech XML. Proto po vás Publican vyžaduje, abyste definovali entity v souboru Doc_Nazev.ent
(viz 1.6 – „Nazev_Dok.ent“).
Tak jak narůstají pracovní toky u zveřejňování, neomezená definice entit vede k duplicitám a dalším postupům, které způsobují obtíže s údržbou. Sjednocení definice entit do jednoho, předvídatelného místa zjednoduší tyto záležitosti údržby a je nápomocno zachování robustní automatizace sestavovacího procesu.
Entity rovněž představují nepřekonatelnou překážku pro kvalitu překladu (viz 1.6.1 – „Entity a překlad“). Proto sice nijak neomezujeme funkční vybavenost souboru Doc_Nazev.ent
, ale také již neodpovídáme na žádosti o přidání funkcí nebo vlastností spojených s používáním entit.
Postupy zdokumentované v tomto oddílu předpokládají, že jsou Publican a jeho různé závislosti dostupné v repositářích, k nimž má váš systém přístup.
Otevřete terminál.
Přihlaste se jako uživatel root: su -
Spusťe následující příkaz, abyste nainstalovali balíček publican a dokumentační balíček publican-doc:
$
yum install publican\*
Je k dispozici několik balíčků grafické úpravy, které lze využít s Publicanem. Spusťte následující příkaz jako uživatel root, abyste nainstalovali balíčky pro sestavení knih s grafickými úpravami.
$
yum install publican-grafuprava
Nahraďte grafupravu na příklad slovem redhat
, fedora
, jboss
, ovirt
nebo gimp
. Více informací o grafických úpravách viz 5 – „Branding“.
Otevřete terminál.
Run the following command to install the publican package:
$
sudo apt-get install publican
Tento postup nainstaluje verzi publicanu, kterou máte ve svém výchozím repozitáři Debianu. Rovněž nainstaluje velké množství balíčků, na nichž je publican závislý, jako je Java, knihovny pro zpracování XML a obrázků a mnoho pomocných modulů Perlu.
Otevřete terminál.
Přihlaste se jako uživatel root: su -
Spusťte následující příkaz, abyste nainstalovali balíček publican:
$
apt-get install publican
Spusťte následující příkaz, abyste určili, která verze publicanu je nainstalována:
$
publican -vversion=2.8
Potřebujete-li novější vydání publicanu, než je vydání nainstalované postupem uvedeným výše, můžete provést dotaz, zda jsou k dispozici jiné verze: 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
Popřípadě můžete spustit Debian testing nebo unstable ve virtuálním stroji, chrootu nebo linuxovém kontejneru.
Za předpokladu že je k dispozici novější verze publicanu v testovacím repozitáří, a že provozujete současné stabilní vydání, můžete přejít na novější verzi takto:
Otevřete terminál.
Přihlaste se jako uživatel root: su -
Otevřete soubor /etc/apt/sources.list
v textovém editoru. Na příklad chcete-li upravit soubor v gedit, spusťte:
$
gedit /etc/apt/sources.list
Přidejte tuto řádku na konec souboru:
#### testing ######### deb http://ftp.us.debian.org/debian testing main contrib non-free
Uložte soubor a zavřete textový editor.
Otevřete (nebo vytvořte) soubor /etc/apt/preferences
v textovém editoru. Na příklad chcete-li upravit soubor v gedit, spusťte:
$
gedit /etc/apt/preferences
Přidejte tuto řádku na konec souboru:
Package: * Pin: release a=stable Pin-Priority: 900 Package: * Pin: release a=testing Pin-Priority: 400 Package: * Pin: release o=Debian Pin-Priority: -10
Uložte soubor a zavřete textový editor.
Spusťte následující příkaz, aby se zaktualizoval seznam balíčků dostupných pro váš počítač:
$
apt-get update
Spusťte následující příkaz, abyste zkusili nainstalovat testovací verzi balíčku publican i všechny aktualizované závislosti:
$
apt-get -t testing install publican
Jelikož Apt Pinning kombinuje 2 různé proudy debianu neprověřeném způsobem, mohou nastat nekompatibility. Na příklad můžete obdržet varování jako:
Která naznačují, že bude nutné také povýšit knihovnu libxml2 a libxslt na verzi testovacího repozitáře. Lze tak učinit vyhledáním podobných knihoven:$
publicanWarning: 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.
[Show All][Hide](a to samé znovu pro libxml2)$
apt-get search libxsltgambas3-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
A poté povýšit verzi těchto balíčků na testovací.
$
apt-get -t testing upgrade libxml2 libxslt1.1
Publican nebylo možné používat v OpenSuse do vydání 12.1. Chyběly určité závislosti a v žádném známém repozitáři OpenSuse nebylo možné je nalézt. To už ovšem není případ OpenSuse 12.1, kde lze všechny závislosti vyhledat a nainstalovat.
Následující pokyny popisují instalaci Publicanu ze zdrojových souborů, neboť dosud není pro OpenSuse 12.1 připraven RPM Publicanu. Verze 2.9 Publicanu je vzata přímo ze zdrojového repozitáře - dřívější verze nebyly testovány, mohou však fungovat.
V době psaní tohoto dokumentu byla vydaná verze Publicanu 2.8 a na verzi 2.9 se stále pracovalo. Z tohoto důvodu mohou být následující pokyny předmětem změny.
Instalace OpenSuse byla výchozí, s těmito přidanými kategoriemi softwaru v době instalace:
Tvorba technické dokumentace - pro nástroje Docbook, atd.
Vývoj Perl
Web a LAMP Server
Použitý systém měl nainstalováno KDE, což by nemělo být nijak odlišné. Byly nainstalovány následující zvláštní kategorie KDE:
Vývoj KDE
Efekty pracovního prostředí
A konečně byla zcela odstraněna kategorie Hry.
Po skončení instalace OpenSuse a provedení všech současných aktualizací byly učiněny pro účely instalace Publicanu tyto kroky:
Otevřete sezení terminálu.
Nainstalujte závislosti, které jsou k dispozici z různých online repozitářů - mnoho z nich se nenachází v repozitáři instalačního DVD.
$
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
Balíček Liberation-fonts
je již nejspíše nainstalován, ale zkrátka se vyžaduje. Zypper ho nebude instalovat znovu, pokud se v systému již nachází.
Využijte cpan pro instalaci zbývajících závislostí, které nelze instalovat pomocí zypper:
$
sudo sh cpan File::pushd File::Copy::Recursive Locale::PO pp \ Syntax::Highlight::Engine::Kate XML::TreeBuilder exit
Stáhněte zdrojový kód:
$
cd ~
mkdir -p SourceCode/publican
cd SourceCode/publican
svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./
Sestavte sestavovací skript Publicanu:
$
perl Build.PL
Jsou-li nainstalovány všechny závislosti, mělo by se zobrazit toto:
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'
Pokud ne, pak použitím cpan (jako uživatel root) nainstalujte chybějící moduly a spusťte opět sestavovací příkaz. Odstraňte všechna lomítka '/'pomocí dvojité dvojtečky '::' a ujistěte se, že jste použili přesně stejnou velikost písmen, na příklad: Je-li prohlášen soubor File/pushd.pm
za chybějící, měli byste použít k jeho instalaci toto:
$
sudo sh
cpan File::pushd
exit
Za předpokladu, že vše proběhlo jak má, skript Build.PL
vytvoří nový skript s názvem Build
, který použijeme pro vytvoření, otestování a instalaci Publicanu 2.9.
$
./Build
Na obrazovku bude vypisováno po několik minut mnoho textu, nakonec byste měli spatřit toto:
DEBUG: Publican::Builder: end of build
Otestujte sestavení:
$
./Build test
Opět bude probíhat dlouhý výpis textových informací, na jejichž konci byste měli narazit na toto:
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.
Nelekejte se. Toto se děje kvůli chybějícímu pomocnému programu wkhtmltopdf, který prochází testy z důvodu přidaní do Publicanu v budoucnu, aby jako vybraný nástroj pro vytváření pdf nahradil Apache FOP. Nalezne-li Publican wkhtmltopdf, použije ho, jinak použije FOP.
Naneštěstí v době psaní nazývá OpenSuse jednu ze závislostí wkhtmltopdf odlišně (ghostscript-fonts-std
namísto ghostscript-fonts
), proto wkhtmltopdf se nespustí, ani když bude instalován silou bez kontroly závislostí.
Nainstalujte wkhtmltopdf.
Tento krok je volitelný. V době psaní wkhtmltopdf na OpenSuse 12.1 nefungoval. Nicméně jelikož problémy, které brání jeho správné funkčnosti z Publicanu, mohou být vyřešeny, následující pokyny poskytují podrobnosti k instalaci wkhtmltopdf.
Zamýšlíte-li ve svých vytvořených dokumentech pdf vytvářet rejstříky, je vám doporučeno používat raději Apache FOP než wkhtmltopdf. S FOP získáte aktuální čísla stránek, což je pro tištěné dokumenty vhodnější.
$
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
Provozujete-li 64-bitový systém, ujistěte se, že jste patřičně nastavili MYSYSTEM
.
Po jejich stažení nainstalujte oba rpm následovně:
$
sudo sh
rpm -ivh wkhtmltopdf-qt*
rpm -ivh --nodeps wkhtmltopdf-0*
exit
Musíte použít volbu, kdy ignorujete závislosti druhého rpm kvůli výše popsaným problémům ghostscript-fonts
.
Nainstalujte Publican.
Závěrečnou fází je instalace Publicanu, i když testovací fáze měla pár podtestů, které selhaly.
$
sudo sh
./Build test
exit
Následující kroky jsou volitelné, ale vždy je dobrý nápad otestovat, zda vše funguje předtím, než strávíte čas na svých dokumentech.
Otestujte nainstalované sestavení Publicanu:
$
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
V době psaní vytváření souborů epub Publicanem 2.9 v OpenSuse vytvářelo následující chybu:
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
Nebyl vytvořen žádný epub. Jednotlivé pracovní soubory však ano, a chcete-li, lze je sestavit do knihy epub použitím Sigil.
Správcem souborů Dolphin můžete přejít do adresáře SourceCode/TestPublican/tmp/en-US/
a prohlédnout si různé výstupní formáty, které zde naleznete.
This installation procedure assumes you have already installed a working docker (see http://docker.io) environment.
Docker je odlehčené uzavřené prostředí (v současnosti využívá LXC), které vám umožní nainstalovat a spustit publican bez potřeby instalace hlavní instalace Linuxu se všemi svými závislostmi.
Otevřete terminál.
Download and install the svendowideit/publican container from https://index.docker.io/u/svendowideit/publican/:
$
docker pull svendowideit/publican
To bude trvat nějakou chvíli, neboť stáhne kontejner založený na Fedoře, a poté závislosti nutné pro publican
Přidejte bash alias pro publican, abyste si ulehčili používání:
$
echo 'alias publican="docker run -t -i -v $(pwd):/mnt svendowideit/publican"' >> ~/.bashrc
Tento alias předpokládá, že máte publican spuštěn v kořenovém adresáři dokumentace (adresář se souborem publican.cfg)
nyní můžete používat publican dle své dokumentace
$
publican --versionversion=3.2.1
It is possible to run publican from a GIT checkout, without installing it, if the dependencies are installed.
To checkout the source from GIT open a terminal.
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
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
Download the Publican installer from https://fedorahosted.org/releases/p/u/publican/.
Přejděte do adresáře, do kterého jste stáhli soubor Publican-Installer-verze.exe
.
Poklepejte na soubor Publican-Installer-version.exe
.
Instalační program vám zobrazí sadu licenčních smluv. Všechny soubory, které představují instalaci Publicanu, jsou k dispozici pod svobodnou licencí. Nicméně protože jsou různé licence vhodnější pro určité části Publicanu než jiné, soubory Publicanu nejsou k dispozici pod jednou svobodnou licencí. Každá licence vám dává různou sadu práv a odpovědností, pokud rozmnožujete nebo měníte soubory ve své instalaci Publicanu. Zvolili jsme tuto kombinaci licencí, abychom vám umožnili používat Publican jak nejsvobodněji lze a zvolit si jakoukoliv licenci, kterou upřednostňuje pro dokumenty, které Publicanem zveřejníte.
Přečtěte si ustanovení těchto různých licenčních smluv. Pokud s jejich zněním souhlasíte, stiskněte na každé tlačítko
, jinak stiskněte .
Instalační program vám nabídne instalaci několika součástí: samotný Publican (v okně instalace označený Hlavní
), několik grafických úprav (včetně RedHat
, JBoss
a fedora
) a dvě součásti DocBook (definici typu dokumentu (DTD) DocBook a styly rozšiřitelného stylového jazyka (XSL) DocBook). Tyto tři grafické úpravy jsou v okně instalace shromážděny pod rozbalovacím nadpisem Grafické úpravy
a součásti DocBook pod rozbalovacím nadpisem DocBook
. Vysvětlení grafických úprav v Publicanu viz 5 – „Branding“. Publican využívá DTD a styly XSL k renderování dokumentů XML do jiných prezentačních formátů (jako např. HTML a PDF). Vynecháte-li tyto součásti z instalace, Publican musí vždy při zpracovávání dokumentu tyto údaje stáhnout z Internetu, což vytváří velká zpoždění.
Všechny součásti jsou standardně zaškrtnuty. Klepněte na zaškrtávací pole, abyste odstranili kterékoliv součásti z výběru, které nevyžadujete a pro pokračování klepněte na .
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.
Jste-li spokojení s cílovým adresářem, klepněte na
.Instalační program, jak instaluje Publican, zobrazí ukazatel průběhu. Chcete-li zobrazit podrobnější informace z průběhu instalace, klepněte na .
Když tento proces skončí, instalační program vás upozorní zprávou Dokončeno
.
Klepněte na
, čímž ukončíte instalační program.Nainstalujte Xcode z obchodu Mac App Store.
Xcode má velikost asi 4GB, proto se obrňte trpělivostí. Nicméně obsahuje potřebné věci.
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.
Otevřete terminál.
Nainstalujte závislosti pro publican, které jsou k dispozici jako porty:
$
sudo port installdocbook-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
Nainstalujte moduly CPAN pro závislosti, které nemohou být vyřešeny porty. Poznámka: tento krok bude příčinou mnoha zpráv, včetně varování. Nedějte si však s nimi starosti.
$
sudo cpanLocale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables
Nainstalujte FOP, chcete-li, aby fungovaly PDF:
$
sudo port installfop
$
echo"FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc
Přejděte (checkout) do hlavní větve Publicanu. Tento příkaz by měl být spuštěn z vašeho domácího adresáře, na příklad /Uživatelé/vašeuživatelskéjméno
$
git clonegit://git.fedorahosted.org/publican.git
Změňte adresáře:
$
cdpublican/publican
Tento adresář by měl obsahovat soubor s názvem Build.pl
. Ověřte, zda se nacházíte ve správném adresáři, poté spusťte následující příkaz. Všechny vypsané zprávy ignorujte.
$
perl ./Build.PL
$
./Build
Spusťte následující příkaz, abyste nainstalovali Publican, a uložte všechny jeho části do adresáře /opt/local
:
$
sudo ./Build install
Postup 1.1. Vytvořte a sestavte knihu
$
publican create--name=testbook
$
cd testbook
$
publican build--formats=html --langs=en-US
Otevřete soubor tmp/en-US/html/index.html
v prohlížeči, abyste zjistili, zda se kniha sestavila bezchybně.
Postup 1.2. Nainstalujte grafickou úpravu
Opravte oprávnění grafické úpravy Commons Brand. To bude nutné pouze jednou. Jedná se o chybu, která bude příležitostně řešena.
$
find /opt/local/share/publican-type f
|xargs sudo chmod 644
Zkontrolujte SVN vámi vybrané grafické úpravy, nebo získejte předsestavenou grafickou úpravu od přítele.
The SVN location for the brands supplied by Red Hat is http://svn.fedorahosted.org/svn/publican
Použijete-li předsestavenou grafickou úpravu, rozbalte ji jak je třeba.
Získáte-li grafickou úpravu z SVN, sestavte ji.
$
cd publican/publican-jboss
$
publican build--formats=xml --langs=all --publish
Nainstalujte grafickou úpravu.
$
sudo publican install_brand--path=/opt/local/share/publican/Common_Content
Nyní můžete využívat grafickou úpravu ve svých knihách, úpravou souboru publican.cfg
své knihy nebo uvedením volby --brand
při vytváření knihy.
Uživatelé mohou nastavit pro Publican své vlastní výchozí hodnoty v souboru ~/.publican.cfg
. Publican podporuje v současnosti tyto hodnoty:
firstname (jméno)
surname (příjmení)
email (e-mail)
formats (formáty)
lang (jazyk)
langs (jazyky)
Tento soubor je zcela jiný než publican.cfg
, který se užívá k sestavení knihy. Ten stejné parametry nepřijímá.
Uživatelé mohou nastavit své standardní parametry pro sestavení pomocí formats, lang a langs.
Příklad 2.1. Nastavení formátů a jazyka
$
echo 'formats: "html,html-single,pdf,txt"' >> ~/.publican.cfg$
echo 'langs: "en-US"' >> ~/.publican.cfg$
publican buildSetting up en-US
[...]
Finished txt
Publican 3.0 umožňuje přidat položku historie revizí z příkazové řádky. Nastavit o sobě podrobnosti jako uživateli lze v ~/.publican.cfg
.
Příklad 2.2. Nastavení informací o uživateli
$
echo 'firstname: "Dude"' >> ~/.publican.cfg$
echo 'surname: "McPants"' >> ~/.publican.cfg$
echo 'email: "dude.mcpants@awesome.com"' >> ~/.publican.cfg$
publican add_revision --member "Updated examples in chapter 2." \ --member "Removed obsolete example in sect 4.1"
Publican je nástroj příkazového řádku. Chcete-li používat Publican na počítači s Linuxovým operačním systémem, musíte buď spustit program emulátoru terminálu (jako např. GNOME Terminál nebo Konsole), nebo se přepnout do virtuální konzole. Příkazovou řádku lze na počítači s operačním systémem Windows otevřít spuštěním příkazu cmd z .
Příkazy Publicanu mají jeden z těchto formátů:
$
publican volba_příkazu
The command_option is any of several options for the $
publican command itself. For a complete list of actions see 2 – „Command actions“
$
publican akce volby_akceAkce je akce, kterou má Publican provést, jako např. vytvoření souborů XML pro nový dokument nebo sestavení dokumentu HTML z jeho souborů XML. Volby_akce se uplatňují na akci, jako např. zadání jazyka dokumentu.
$
publican volba_příkazu akce volby_akceNěkteré volby_příkazu ovlivňují výstup akcí, na příklad zda by měl Publican ve svém výstupu použít barvy ANSI.
Tato kapitola popisuje tvorbu knih a článků: hlavní konfigurační soubory, ukázkové soubory dokumentu a jak sestavit dokument.
Chcete-li vytvořit nový dokument, včetně všech nezbytných souborů dokumentu, použijte příkaz $
publican create.
Příkaz $
publican create přijímá několik voleb, podrobně popsaných v této kapitole. Může-li volba přijmout hodnotu, oddělte volbu od hodnoty mezerou nebo rovnítkem, na příklad publican create --name Nova_Kniha nebo publican create --name=Nova_Kniha.
--help
vytiskne seznam všech voleb příkazu $
publican create.
--name Dok_Nazev
nastaví Dok_Nazev jako název knihy nebo článku. Tato proměnná nesmí obsahovat žádné mezery. Na příklad příkaz $
create_book --name Kniha_Test vytvoří knihu s názvem Kniha_Test
, se všemi nezbytnými soubory, které zajišťují sestavení knihy, a nastaví BOOKID
v souboru Test_Book.ent
.
--lang Kod_Jazyka
nastaví Kod_Jazyka jako kód jazyka, ve kterém je kniha nebo článek sepsán. Nezadáte-li kód jazyka, Publican použije standardně en-US
(Americká Angličtina). Volba --lang
nastaví parametr xml_lang
v souboru publican.cfg
a vytvoří stejně nazvaný adresář v adresáři dokumentu. Při počátečním vytvoření obsahuje tento adresář několik předpřipravených souborů XML. Více informací o parametrech souboru publican.cfg
viz 1.1 – „Soubor publican.cfg“ a více podrobností o kódech jazyků viz F – „Language codes“.
--version verze
nastaví verzi jako číslo verze produktu, který kniha popisuje. Na příklad byste pro Red Hat Enterprise Linux 5.1 použili 5.1
. Výchozí verze je 0.1
. Volba --version
nastaví v souboru Book_Info.xml
nebo Article_Info.xml
tag <productnumber>
. Více informací viz 1.2 – „Book_Info.xml“.
--edition vydani
nastaví vydani jako číslo vydání knihy. Toto číslo upozorňuje uživatele na nové vydání knihy. Úvodní veřejně dostupné (GA) vydání knihy by mělo být vydání 1.0
. Výchozí hodnotou je 0
. Volba --edition
nastaví v souboru Book_Info.xml
nebo Article_Info.xml
tag <edition>
. Více informací viz 1.2 – „Book_Info.xml“.
--product Nazev_Produktu
nastaví Nazev_Produktu jako název produktu, který kniha popisuje. Tato proměnná nesmí obsahovat žádné mezery. Nastavte ji na příklad na Fedora
v případě hlavní dokumentace Fedory, v případě jiného produktu na jiný název, jako např. Fedora_Directory_Server
. Výchozí hodnotou je Documentation
. Volba --product
nastaví v souboru Book_Info.xml
nebo Article_Info.xml
tag <product name>
a v souboru Dok_Nazev.ent
entitu PRODUCT
.
--type Article --name Nazev_Clanku
vytvoří článek, místo knihy. Místo Nazev_Clanku dosadte skutečný název článku. Tato proměnná nesmí obsahovat žádné mezery. Volba --type
nastaví v souboru publican.cfg
parametr type
. Více informací o parametrech publican.cfg
viz 1.1 – „Soubor publican.cfg“.
--type Set --name Nazev_Sady
vytvoří místo knihy sadu dokumentů. Místo Nazev_Sady dosaďte skutečný název sady. Tato proměnná nesmí obsahovat žádné mezery. Volba --type
nastaví v souboru publican.cfg
parametr type
. Více informací o parametrech publican.cfg
viz 1.1 – „Soubor publican.cfg“ a podrobnosti o používání sad viz 6 – „Using sets“.
--brand grafuprava
nastaví grafupravu jako grafickou úpravu, která se použije ke stylizaci výstupu tohoto dokumentu, na příklad RedHat
, fedora
, JBoss
, oVirt
nebo GIMP
. Výchozí hodnotou je common
, výchozí grafická úprava dodávaná s Publicanem. Volba --brand
nastaví v souboru publican.cfg
parametr brand
. Více informací o parametrech publican.cfg
viz 1.1 – „Soubor publican.cfg“. Tato volba vyžaduje nainstalovaný příslušný balíček grafické úpravy Publicanu. Na příklad přejete-li si sestavovat knihy s grafickou úpravou Red Hat, musíte nainstalovat balíček publican-redhat. Pokyny k instalaci balíčků grafických úprav pro Publican viz 1 – „Installing a brand“. Nezadáte-li grafickou úpravu, Publican použije svou vestavěnou, výchozí úpravu. Více informací viz 5 – „Branding“
Před spuštěním příkazu $
publican create přejděte pomocí příkazu cd do adresáře, ve kterém si přejete vytvořit knihu. Na příklad chcete-li vytvořit knihu s názvem Kniha_Test
v adresáři mé_knihy
, spusťte tyto příkazy:
$
cd mé_knihy/$
publican create --name Kniha_Test
Výsledky tohoto příkazu zobrazíte na počítači s operačním systémem Linux příkazem:
$
ls
Výstup by měl být podobný tomuto:
Kniha_Test/
Obsah nového adresáře Kniha_Test/
zobrazíte na počítači s operačním systémem Linux takto:
$
cd Kniha_Test/$
ls
Výstup by měl být podobný tomuto:
en-US/ publican.cfg
Spustíte-li příkaz $
publican create --name Kniha_Test --lang en-US, Publican vytvoří adresářovou strukturu a požadované soubory, podobné těmto:
publican.cfg
en-US
(adresář)
Kniha_Test.xml
Kniha_Test.ent
Revision_History.xml
Preface.xml
Chapter.xml
Book_Info.xml
Author_Group.xml
images
(adresář)
icon.svg
Udržujete-li několik verzí dokumentu, lze vytvořit konfigurační soubor pro každou z nich. Při sestavování nebo balení dokumentu lze pomocí --config
zadat jiný konfigurační soubor než publican.cfg
, a tak použít pro dané sestavení jinou sadu parametrů. Na příklad:
$
publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
Soubor publican.cfg
nastavuje volby sestavení a nachází se v kořenovém adresáři knihy. Následuje příklad souboru publican.cfg
, popis jeho parametrů je uveden pod ním:
# Config::Simple 4.59 # Wed Jul 18 13:00:40 2012 xml_lang: "en-US" type: Book brand: common \t\t \t\t
Základní parametry
xml_lang
určuje jazyk zdrojových souborů XML, na příklad en-US
, nastavený volbou --lang
v $
publican create.
type
určuje typ dokumentu — <article>
, <book>
nebo <set>
z DocBook, nastavený volbou --type
v $
publican create.
brand
stanoví grafickou úpravu dokumentu, na příklad RedHat
, fedora
, JBoss
, oVirt
nebo GIMP
, nastavenou volbou --brand
v $
publican create. Nezadáte-li grafickou úpravu, Publican použije svou výchozí. Více informací viz 5 – „Branding“.
Advanced parameters Delete me and reference appendix
arch
filtruje výstup dle počítačové architektury. Na příklad, nastavíte-li v souboru publican.cfg
arch: x86_64
, Publican zahrne pouze prvky XML opatřené stejným atributem, např. <para arch="x86_64">
.
Tak jako obecněji podmíněné tagování může arch
být velmi problematický z hlediska jazykových překladů dokumentů. Vysvětlení problematiky viz 9.1 – „Conditional tagging and translation“.
Je-li kořenový uzel souboru XML vyloučen atributem arch
, váš dokument se nesestaví, neboť prázdné soubory nejsou validním XML. Na příklad obsahuje-li Installation_and_configuration-PPC.xml
jedinou kapitolu:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_PowerPC" arch="PowerPC"> <title>Installation and configuration on PowerPC</title> [text of chapter] </chapter>
a tato kapitola je zahrnuta tagem <xi:include>
v User_Guide.xml
, dokument se nesestaví s podmínkou $
condition: x86 nastavenou v souboru publican.cfg
.
Chcete-li tuto kapitolu vyloučit, přidejte atribut arch
do tagu <xi:include>
v User_Guide.xml
, nikoliv do tagu <chapter>
v Installation_and_configuration-PPC.xml
.
Ukazuje-li <xref>
na obsah vyloučený ze sestavení kvůli atributu arch
, sestavení selže. Na příklad, s nastavenou arch: x86
v souboru publican.cfg
, $
publican build --formats=pdf --langs=en-US selže, obsahuje-li kniha tag <xref linkend="Itanium_installation">
ukazující na <section id="Itanium_installation" arch="IA64">
.
books
uvádí čárkou oddělený seznam knih používaných ve vzdálené sadě. Více informací o distribuovaných sadách viz 2 – „Distributed sets“
brew_dist
uvádí cíl sestavení, který se má použít v Brew, interním sestavovacím systému společnosti Red Hat, pro sestavení balíčku RPM pro stolní počítač. Výchozí hodnotou je docs-5E
. Více informací o sestavování balíčků RPM viz 8.2 – „The $
publican package command“ a 4 – „Packaging a brand“.
bridgehead_in_toc
stanoví, zda texty prvků <bridgehead>
(volně plující nadpisy) mají být zahrnuty k ostatním nadpisům v obsahu (jako např. nadpisům oddílů a kapitol). Chcete-li povolit tuto vlastnost, nastavte bridgehead_in_toc: 1
. V opačném případě tento parametr má výchozí hodnotu 0
a prvky <bridgehead>
nejsou do obsahu zahrnuty.
chunk_first
řídí, zda se má první oddíl při renderování v HTML umístit na novou stránku. Chcete-li umístit první oddíl na novou stránku HTML, nastavte tento parametr na chunk_first: 1
. Jinak tento parametr má výchozí hodnotu 0
a první oddíly se zobrazí na stejné stránce jako jejich kapitola.
chunk_section_depth
řídí hloubku, v které Publican při renderování HTML již neumisťuje pododdíly na nové stránky. Výchozí hodnota je nastavena na 4
.
Příklad 4.1. Řízení hloubky zanoření oddílů s chunk_section_depth
bez oddělení oddílů. Kapitola a všechny její oddíly, vč. pododdílů, se umístí na jednu stránku. Řazení stránek je kapitola 1, kapitola 2, kapitola 3, …
oddělení nastává na oddílu "úroveň 1". Každý oddíl první úrovně se umístí, se svými pododdíly, na novou stránku. Řazení stránek je kapitola 1, 1.2, 1.3, 1.4 … kapitola 2, 2.1, 2.2, 2.3 …
oddělení nastavá na oddílu "úroveň 2". Řazení stránek je kapitola 1, 1.2, 1.2.2, 1.2.3, 1.2.4 … 1.3, 1.3.2, 1.3.3 …
oddělení nastává na oddílu "úroveň 3". Řazení stránek je kapitola 1, 1.2, 1.2.2, 1.2.2.3, 1.2.2.4 … 1.3, 1.3.2, 1.3.2.2, 1.3.2.3 …
oddělení nastává na oddílu "úroveň 4". Řazení stránek je 1, 1.2, 1.2.2, 1.2.2.2, 1.2.2.2.2, 1.2.2.2.3, 1.2.2.2.4 … 1.2.3, 1.2.3.2, 1.2.3.2.2, 1.2.3.2.3 …
classpath
nastaví cestu k souborům Java archive (jar) pro aplikaci FOP. Publican spoléhá při renderování dokumentů do souborů PDF na Apache FOP - applikaci Java. Výchozí cesta pro soubory jar aplikace FOP na počítači s operačním systémem Linux je: /usr
/share
/java
/ant
/ant-trax-1.7.0.jar:
/usr
/share
/java
/xmlgraphics-commons.jar:
/usr
/share
/java
/batik-all.jar:
/usr
/share
/java
/xml-commons-apis.jar:
/usr
/share
/java
/xml-commons-apis-ext.jar
common_config
nastaví cestu k instalaci Publicanu. Výchozí umístění na počítači s operačním systémem Linux je /usr/share/publican
. Na počítači s operačním systémem Windows je výchozí umístění %SystemDrive%/%ProgramFiles%/publican
— nejčastěji tedy C:/Program Files/publican
.
common_content
nastaví cestu k souborům společného obsahu Publicanu. Tyto soubory poskytují výchozí formátování, plus některý předpřipravený text a obecnou grafiku. Výchozí umístění na počítači s operačním systémem Linux je /usr/share/publican/Common_Content
. Výchozí umístění na počítači s operačním systémem Windows je %SystemDrive%/%ProgramFiles%/publican/Common_Content
— obvykle tedy C:/Program Files/publican/Common_Content
.
condition
uvádí podmínky, za kterých se redukuje (prune) XML před transformací. Více informací viz 9 – „Conditional tagging“.
If the root node of an XML file is excluded with a conditional, your document will not build, because empty files are not valid XML. For example, if Installation_and_configuration_on_Fedora.xml
contains a single chapter:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora"> <title>Installation and configuration on Fedora</title> [text of chapter] </chapter>
and this chapter is included in User_Guide.xml
with an <xi:include>
tag, the document will not build with $
condition: Ubuntu set in the publican.cfg
file.
To exclude this chapter, add a condition to the <xi:include>
tag in User_Guide.xml
, not to the <chapter>
tag in Installation_and_configuration_on_Fedora.xml
.
If an <xref>
points to content not included in the build due to conditional tagging, the build will fail. For example, with $
condition: upstream set in the publican.cfg
file, $
publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection">
pointing to <section id="betasection" condition="beta">
.
confidential
označí dokument za utajovaný. Je-li tento parametr nastaven na 1
, přidá Publican do patičky každé stránky HTML a do hlavičky každé stránky v dokumentu PDF text uvedený v parametru confidential_text
(ve výchozím stavu CONFIDENTIAL
). Výchozí hodnotou je 0
(žádná hlavička ani patička).
confidential_text
určuje text, který se použije, je-li parametr confidential
nastaven na 1
. Výchozí text je CONFIDENTIAL
.
debug
řídí, zda má Publican zobrazovat ladící informace při své činnosti. Je-li nastaven na svou výchozí hodnotu 0
, Publican ladící informace nezobrazuje. Chcete-li tyto informace zobrazovat, změňte hodnotu na 1
.
def_lang
nastaví výchozí jazyk pro webové stránky řízené Publicanem. Obsahy pro jiné jazyky než je výchozí jazyk budou odkazovat na dokumenty ve výchozím jazyku, nejsou-li k dispozici překlady. Viz 8 – „Packaging a document“.
doc_url
poskytuje URL pro dokumentační tým tohoto balíčku. Ve výstupu HTML odkazuje Publican na toto URL vpravo nahoře každé stránky, pomocí obrázku image_right.png
v adresáři Common_Content/images
grafické úpravy. Výchozí hodnotou parametru je https://fedorahosted.org/publican
.
docname
určuje název dokumentu. Je-li nastaven, jeho hodnota při balení dokumentu potlačuje obsah tagu <title>
v souboru Book_Info.xml
. Hodnota musí obsahovat pouze velká a malá písmena bez diakritiky, číslice, podtržítka a mezery ((‘a–z’, ‘A–Z’, ‘0’–‘9’, ‘_’ a ‘ ’).
dt_obsoletes
balíček, který bude balíčkem pro stolní počítač označen za zastaralý.
dt_requires
balíček, který je vyžadován balíčkem pro stolní počítač, na příklad balíček dokumentační nabídky. Viz 8.1.3 – „Desktop menu entries for documents“.
dtdver
určuje verzi definici typu dokumentu (DTD) DocBook XML, na níž je projekt založen. Publican ve výchozím nastavení využívá verzi 4.5. Specifikace DocBook XML DTD verze 4.5 je dostupná na http://www.docbook.org/specs/docbook-4.5-spec.html.
Při instalaci Publicanu rovněž instalujete místní kopii DocBook XML DTD verze 4.5 a přidružený rozšiřitelný stylový jazyk (XSL). Nastavíte-li verzi DTD, pro kterou neexistuje místní podpora, Publican musí příslušnou DTD a XSL stáhnout z online zdroje pokaždé, kdy je dokument sestavován. Sestavení dokumentu je tak zpožděno, neboť probíhá toto stahování. Celková velikost požadovaných souborů se pohybuje kolem 70 MB.
dtd_type
Potlačuje Typ pro DocType. Musí mít formu celého řetězce.
Tento parametr je povolen pouze v grafické úpravě.
dtd_uri
Potlačuje URI pro DocType. Musí mít podobu celého řetězce.
Tento parametr je povolen pouze v grafické úpravě.
ec_id
nastavuje ID pro zásuvný modul nápovědy Eclipse. Každý zásuvný modul Eclipse musí mít jedinečné ID, a ty obecně odpovídají úmluvám o přidělování názvů balíčkům Java - viz http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html. Ve výchozím nastavení nastaví Publican ID na org.product.docname. ID, které zde nastavíte, určuje rovněž název adresáře pro tento zásuvný modul v adresáři plugin
.
ec_name
nastavuje název zásuvného modulu nápovědy Eclipse. Jedná se o člověkem čitelný název, který bude zobrazen v seznamu nápovědy v Eclipse. Název nemusí být jedinečný nebo odpovídat zvláštní úmluvě. Ve výchozím nastavení nastaví Publican název na product docname.
ec_provider
nastaví název poskytovatele zásuvného modulu nápovědy Eclipse. Zde by mělo být vaše jméno, nebo název vašeho projektu nebo organizace. Název je prezentován uživatelům a nemusí být jedinečný nebo odpovídat zvláštní úmluvě. Ve výchozím nastavení nastaví Publican název poskytovatele na Publican-verze Publicanu.
edition
určuje číslo vydání tohoto dokumentu.
Tag <edition>
byl vyžadován staršími verzemi Publicanu, než byla verze 2.0, které ho využívali k vygenerování verze dokumentačního balíčku. Tento tag je nyní zcela volitelný a neovlivňuje žádným způsobem balíčkování.
extras_dir
adresář, ze kterého bude Publican zpracovávat dodatečné soubory. (Výchozí: extras
footer
uvádí obsah, který bude vložen do dolní části každé stránky webových stránek.
generate_section_toc_level
řídí hloubku oddílů, u nichž Publican vygeneruje obsah. Při výchozí hodnotě 0
vygeneruje Publican obsah na začátku dokumentu a v částech, kapitolách a přílohách, nikoliv však v oddílech. Je-li na příklad hodnota nastavena na 1
, obsahy se objeví rovněž v každém oddílu "úroveň 1", tedy oddílech 1.1, 1.2, 2.1 a 2.2. Je-li nastavena na 2
, obsahy se budou rovněž nacházet v oddílech "úroveň 2", např. 1.1.1, 1.1.2 a 1.2.1.
Příklad 4.2. Nastavení hloubky oddílů, ve které se vytvoří obsah
Publican vytvoří obsahy na začátku dokumentu a v částech, kapitolách a přílohách, nikoliv však v oddílech.
Publican vytvoří obsahy také na začátku každého oddílu "úroveň 1", jako např. oddílu 1.1, 1.2 … 2.1, 2.2 …
Publican vytvoří obsahy také na začátku každého oddílu "úroveň 2", tedy např. 1.1.1, 1.1.2. 1.1.3 … 1.2.1., 1.2.2, 1.2.3 …
ignored_translations
uvádí překlady, v podobě čárkou oddělených XML kódů jazyků, které budou ignorovány, na příklad es-ES,it-IT
. Sestavíte-li nebo zabalíte-li knihu v jazyku filtrovaném tímto parametrem, Publican pro tento jazyk ignoruje všechny existující překlady a na místo toho sestaví nebo zabalí knihu v jazyku originálního XML. Viz 6 – „Překlad dokumentu“ a F – „Language codes“.
img_dir
adresář, ze kterého bude Publican zpracovávat obrazové soubory. (Výchozí: images
info_file
potlačí výchozí soubor Info. Uvádí, kde bude Publican hledat informační pole. Použijte celý název bez cesty.
license
uvádí licenci, kterou použije balíček. Ve výchozím nastavení Publican zvolí GNU Free Documentation License (GDFL). Viz 8 – „Packaging a document“.
mainfile
uvádí název souboru XML v dokumentu, který obsahuje kořenový uzel XML <article>
, <book>
nebo <set>
, a název příslušného souboru .ent
, který obsahuje entity dokumentu. Na příklad nastavíte-li mainfile: master
, Publican hledá kořenový uzel XML v master.xml
a entity dokumentu v master.ent
.
Není-li mainfile
nastaven, Publican hledá kořenový uzel XML v souboru, který odpovídá tagu <title>
dokumentu nastaveném v Article_Info.xml
, Book_Info.xml
nebo Set_Info.xml
, a entity v souboru s odpovídajícím názvem.
menu_category
kategorie nabídky pro stolní počítač (definovaná příslušným souborem .menu
), do které se umístí dokument, je-li nainstalován z balíčku RPM pro stolní počítač. Viz 8.1.3 – „Desktop menu entries for documents“.
os_ver
uvádí operační systém, pro který se sestaví balíček. Publican připojí hodnotu, kterou zde uvedete, k balíčkům RPM, které sestavuje. Na příklad .fc15
pro Fedoru 15. Výchozí hodnotou je .el5
, která označuje Red Hat Enterprise Linux 5 a z něho odvozené operační systémy. Viz 8 – „Packaging a document“ a 4 – „Packaging a brand“.
prod_url
poskytuje URL k produktu, ke kterému se dokument vztahuje. Ve výstupu HTML umístí Publican odkaz na toto URL do levé horní části každé stránky, prostřednictvím obrazového souboru image_left.png
v adresáři Common_Content/images
grafické úpravy. Výchozí hodnotou tohoto parametru je https://fedorahosted.org/publican
.
product
uvádí produkt, ke kterému se dokument vztahuje. Je-li nastaven, hodnota při balení dokumentu potlačuje obsah tagu <productname>
v souboru Book_Info.xml
. Hodnota musí obsahovat pouze malá a velká písmena bez diakritiky, číslice, podtržítka a mezery (‘a–z’, ‘A–Z’, ‘0’–‘9’, ‘_’ a ‘ ’).
release
uvádí číslo vydání balíčku. Je-li nastaven, hodnota při balení dokumentu potlačuje hodnotu <pubsnumber>
v souboru Book_Info.xml
. Hodnota smí obsahovat pouze číslice (‘0’–‘9’).
repo
uvádí repozitář, ze kterého stáhnout knihy, které tvoří součást distribuované sady, na dálku. Viz 2 – „Distributed sets“.
rev_dir
potlačuje výchozí směr řazení souboru Revision History (historie revizí). Ve výchozím nastavení předpokládá Publican, že Revision History je řazen sestupně, nové verze nejdříve, přejete-li si toto změnit a mít nejdříve nejstarší verze, nastavte pak tento parametr na asc
nebo ascending
.
rev_file
potlačuje výchozí soubor Revision History. Uvádí, kde má Publican hledat pole revizí. Použijte celý název bez cesty. Společně s akcí add_revision Publicanu vám umožňuje sestavit knihu bez Revision_History.xml
.
scm
uvádí systém pro správu verzí (též source code management) používaný v repozitáři, do kterého jsou ukládány vzdálené knihy v distribuované sadě. V současnosti dokáže Publican pracovat pouze se Subversion (SVN), a proto jako výchozí hodnotu používá SVN
. Viz 2 – „Distributed sets“.
show_remarks
řídí, zda se mají v převedeném výstupu zobrazit poznámky typu <remark>
DocBook. Jako výchozí je tato hodnota nastavena na 0
, která způsobí, že Publican poznámky nezobrazí. Chcete-li poznámky zobrazit, nastavte ji na 1
. V grafickém stylu common
Publicanu jsou poznámky zvýrazněny purpurovou barvou.
sort_order
potlačuje výchozí vážené řazení knih ve webové stránce Publicanu. Knihy jsou zobrazeny na webové stránce v sestupném pořadí. Na příklad kniha s vahou řazení 10 se zobrazí před knihou s vahou 5. Ve výchozím nastavení je tato hodnota nastavena na 50.
src_url
uvádí URL, na kterém lze nalézt tarové archivy zdrojových souborů. Tento parametr poskytuje pole Source:
v hlavičce souboru spec RPM. Viz 8 – „Packaging a document“.
tmp_dir
uvádí adresář pro výstup Publicanu. Ve výchozím nastavení má hodnotu tmp
, který vytvoří adresář s názvem tmp
uvnitř adresáře, ve kterém se nachází váš článek nebo kniha.
tmpl_path
uvádí cestu k šablonám Publicanu. Ve výchozím nastavení má hodnotu /usr/share/publican/templates
.
toc_js
umožňuje stránce potlačit šablonu využívanou pro stránky web_style=1 použitou při sestavování vestavěného obsahu. Šablona se musí nacházet ve stejném adresáři jako se nachází toc.tmpl
. Název šablony musí mít formát toc_typ+.tmpl
toc_type
uvádí název vlastní šablony pro obsah. Ve výchozím nastavení hledá Publican toc-$toc_type.tmpl
v /usr/share/publican/templates
. Toto nastavení lze potlačit zadáním alternativní cesty v tmpl_path
.
toc_section_depth
řídí hloubku oddílů, kterou Publican zahrne do hlavního obsahu. Ve výchozím nastavení je hodnota nastavena na 2
. S tímto výchozím nastavením se oddíly 1.1 a 1.1.1 zobrazí v hlavním obsahu, ale oddíl 1.1.1.1 již ne. (Všimněte si, že první číslo v tomto příkladu představuje kapitolu nikoliv oddíl.)
Příklad 4.3. Řízení hloubky oddílů v hlavním obsahu
Publican vygeneruje hlavní obsah pouze z kapitol.
Publican vygeneruje hlavní obsah pouze z kapitol a oddílů "úroveň 1", jako např. 1, 1.1, 1.2, 1.3 …, ale ne pro oddíly 1.1.1, 1.1.2 …
Publican vygeneruje obsah z kapitol a oddílů "úroveň 1" a "úroveň 2", jako např. 1, 1.1, 1.1.1, … 1,2, 1.2.1, 1.2.2 …, nikoliv však pro oddíly umístěné hlouběji x.x.x.x.
version
uvádí číslo verze produktu, na který se vztahuje tento dokument. Je-li nastavena, hodnota při balení dokumentu potlačuje obsah tagu <productnumber>
v souboru Book_Info.xml
. Hodnota musí obsahovat pouze číslice a tečky (‘0’–‘9’ and ‘.’).
web_brew_dist
uvádí cíl sestavení brew, který se má použít pro sestavení webových balíčků RPM. Brew je interní sestavovací systém používaný společností Red Hat. Ve výchozím nastavení je tato hodnota nastavena na docs-5E
, představuje dokumentační balíčky pro Red Hat Enterprise Linux 5.
web_formats
čárkou oddělený seznam formátů, které se mají zahrnout do webového balíčku RPM. Viz 8.2 – „The $
publican package command“.
web_home
konkretizuje, že dokument je domovská stránka webové stránky dokumentace, nikoliv standardní dokument. Viz 7 – „Building a website with Publican“.
web_home
je zastaralý
V Publicanu 2.2 je web_home
nahrazen web_type: home
. Podpora pro web_home
bude v některé příští verzi Publicanu odstraněna.
web_name_label
potlačuje název knihy, který se zobrazuje v nabídce webové stránky řízené Publicanem. Viz 7 – „Building a website with Publican“.
web_obsoletes
uvádí balíčky, které webový RPM označí za zastaralé. Viz 8 – „Packaging a document“.
web_product_label
potlačuje název produktu, který se zobrazuje v nabídce webové stránky řízené Publicanem. Viz 7 – „Building a website with Publican“.
web_style
nastaví styl webu, který určuje rozvržení a prezentaci webové stránky. Platnými hodnotami jsou 1
a 2
. Styl 1 používá navigační okno po levé straně obrazovky, které poskytuje přístup ke všem dokumentům na webové stránce.
web_type
konkretizuje, že dokument je pro webovou stránku řízenou Publicanem spíše popisným obsahem než dokumentací produktu. Tento obsah zahrnuje domovskou stránku webové stránky (web_type: home
), stránky popisující produkt (web_type: product
) a stránky popisující verzi (web_type: version
). Viz 7 – „Building a website with Publican“.
web_version_label
potlačuje číslo verze, které se zobrazuje v nabídce webové stránky řízené Publicanem. Pro obecnou dokumentaci, k níž se nevztahuje žádná konkrétní verze produktu, nastavte tuto hodnotu na UNUSED
. Viz 7 – „Building a website with Publican“.
wkhtmltopdf_opts
Zvláštní volby předávané wkhtmltopdf. Např. wkhtmltopdf_opts: "-O landscape -s A3"
Chcete-li získat shrnující informace k těmto parametrům, spusťte v kořenovém adresáři knihy příkaz $
publican help_config.
Article_Info.xml
a Set_Info.xml
Následující popis souboru Book_Info.xml
se rovněž vztahuje na soubory Article_Info.xml
a Set_Info.xml
. Nicméně v tomto oddílu se z důvodu zjednodušení používá pouze soubor Book_Info.xml
.
This section discusses packaging documents for distribution through the RPM Package Manager. However, when you use the $
publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
Soubor Book_Info.xml
obsahuje klíčová metadata, která se týkají knihy: ID knihy, název, podtitul, autor a číslo vydání. Obsahuje rovněž název a verzi produktu, který dokumentuje, a abstrakt.
Vedle těchto "obálkových" záležitostí jsou metadata také využívána pro sestavování knih do balíčků RPM. Obvykle, pokud šíříte knihu jako balíček RPM, musí mít několik tagů standardně obsažených v Book_Info.xml
v sobě uvedeny příslušné údaje a tyto údaje musí odpovídat požadavkům formátu RPM. Údaje v těchto tazích lze potlačit použitím rovnocenných polí v souboru publican.cfg
, diskutovaných v tomto oddílu.
Nejsou-li potlačeny v souboru publican.cfg
, vyžadují se k sestavení knihy jako RPM údaje ze sedmi výchozích tagů v Book_Info.xml
. Velmi stručně je název souboru knihy sestavené jako balíček RPM složen následovně:
productname-title-productnumber-language-edition-pubsnumber.src.rpm
Vše výše kromě language se získává z Book_Info.xml
— language uvádíte, když sestavujete knihu. A podobně <subtitle>
a <abstract>
se využívají v souboru spec RPM, poskytují pole Summary:
v hlavičce, respektive %description
.
Ukázkový příklad souboru Book_Info.xml
pro knihu Kniha_Test
lze shlédnout níže. Podrobnosti tohoto souboru a jaké požadavky na formát RPM jsou pro každý tag, následují.
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE info [ <!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent"> %BOOK_ENTITIES; <!ENTITY % sgml.features "IGNORE"> <!ENTITY % xml.features "INCLUDE"> <!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod"> %DOCBOOK_ENTS; ]> <info conformance="121" version="5.0" xml:id="info-Publican-Users_Guide-Users_Guide" xml:lang="cs-CZ" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Uživatelská příručka</title> <subtitle>Zveřejnění knih, článků, dokumentů a vícesvazkových sad s DocBook XML</subtitle> <productname>publican</productname> <productnumber>4.2</productnumber> <abstract> <para> Tato kniha vám poradí při instalaci <application>&PRODUCT;</application>. Také vám poskytne návody jak použít Publican pro tvorbu a zveřejnění knih, článků a sad knih založených na DocBook XML. Příručka předpokládá, že již máte znalosti DocBook XML. </para> </abstract> <keywordset> <keyword>publican</keyword> <keyword>docbook</keyword> <keyword>zveřejnění</keyword> </keywordset> <subjectset scheme="libraryofcongress"> <subject> <subjectterm>Electronic Publishing</subjectterm> </subject> <subject> <subjectterm>XML (Computer program language)</subjectterm> </subject> </subjectset> <mediaobject role="logo"> <imageobject> <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> </imageobject> <textobject> <phrase>Team Publican</phrase> </textobject> </mediaobject> <mediaobject role="cover"> <imageobject remap="lrg" role="front-large"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="s" role="front"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="xs" role="front-small"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="cs" role="thumbnail"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> </mediaobject> <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </info> \t\t \t\t
<bookinfo id="kniha_id">
, <articleinfo id="clanek_id">
, <setinfo id="sada_id">
ID dokumentu se využívá interně a čtenářům zůstává skryto při sestavování knihy. Spustíte-li příkaz $
publican clean_ids, kterékoliv ručně vložené ID, včetně tohoto jednoho, se změní na formát Nazev_Dok-Title, kde Title je název související knihy, článku, oddílu nebo kapitoly.
<productname>nazevproduktu</productname>
Název produktu nebo produktové řady, ke kterému se kniha, článek nebo sada vztahuje, na příklad: Red Hat Enterprise Linux
nebo JBoss Enterprise Application Platform
. Při sestavování knihy do balíčku RPM je údaj v tagu <productname>
použit jako součást názvu soboru balíčku.
Obsahuje-li váš produkt nelatinské znaky, latinské znaky s diakritikou nebo interpunkční znaménka jiná než podtržítko, potlačte tento tag proměnnou product
v souboru publican.cfg
.
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg
file. If you do not override this tag in the publican.cfg
file, this tag must only contain upper- and lower-case un-accented letters, digits, and the hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
<title>nazev</title>
Název dokumentu (na příklad <title>Server Configuration Guide</title>
). Název se zobrazuje pod názvem produktu jak ve vydáních HTML, tak PDF. Název se vyžaduje, jinak nelze sestavit balíček RPM. Název je při sestavování knihy do balíčku RPM použit jako část názvu souboru balíčku.
Názvy balíčků RPM mohou obsahovat pouze určité základní znaky ASCII. Obsahuje-li název dokumentu nelatinské znaky, latinské znaky s diakritikou nebo interpunkční znaménka jiná než podtržítko, použijte parametr docname
v souboru publican.cfg
k nastavení názvu dokumentu ve znacích ASCII. Při sestavení dokumentu se název zobrazí tak, jak jste ho nastavili s tagem <title>
, ale pokud dokument balíte, je pro název souboru balíčku RPM použita hodnota parametru docname
.
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg
file. If you do not override this tag in the publican.cfg
file, this tag must only contain upper- and lower-case un-accented letters, digits, and the hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
Ve výchozím nastavení používá Publican obsah z tagu <title>
také k nalezení souboru, kde se nachází kořenový uzel XML: <article>
, <book>
nebo <set>
. Na příklad nastavíte-li název na <title>Server Configuration Guide</title>
, Publican očekává kořenový uzel XML v souboru nazvaném Server_Configuration_Guide.xml
a entity dokumentu v souboru Server_Configuration_Guide.ent
. Chcete-li použít jiný název těchto souborů, nastavte v konfiguračním souboru dokumentu parametr mainfile
(ve výchozím nastavení se jedná o publican.cfg
). Viz 1.1 – „Soubor publican.cfg“.
<subtitle>podtitul</subtitle>
Podtitul knihy: alternativní a obecně popisný název knihy (na příklad: Server Configuration Guide: Preparing Red Hat Enterprise Linux for Production Use). Podtitul se zobrazuje pod názvem jak ve vydáních HTML, tak PDF. Podtitul se také vyžaduje pro vytvoření balíčku RPM z knihy. Při sestavování knihy do balíčku RPM se použije podtitul jako Summary
v souboru spec RPM. Příkaz rpm -qi vrací obsah několika polí souboru spec, včetně pole Summary
.
<productnumber>cisloproduktu</productnumber>
Číslo verze produktu, o němž pojednává kniha, na příklad ‘5.2’ pro Red Hat Enterprise Linux 5.2 a ‘4.3’ pro JBoss EAP 4.3.
Spuštění příkazu $
publican create --name Nazev_Dok --version verze nastaví správné číslo produktu.
Potlačte tento tag proměnnou version
v souboru publican.cfg
, je-li verze produktu cokoliv jiného než číslo.
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg
file. If you do not override this tag in the publican.cfg
file, this tag must only contain numbers and the period (‘0–9’ and ‘.’) if you plan to build packages with Publican.
<edition>vydani</edition>
Číslo vydání knihy. První vydání knihy by mělo být očíslováno 1.0 (pokud nepoužíváte číslování 0.x pro účely verzí knihy před veřejným vydáním). Následující vydání by měla mít oproti 1.x číslo vyšší, aby měli čtenáři možnost zjistit, že se jedná o nové vydání knihy. Vydání změní číslo verze v názvu souboru, sestavujete-li knihu příkazem $
publican package.
Na příklad nastavení vydání na 1.2
a sestavení knihy pomocí příkazu $
publican package --binary --lang=en-US vytvoří soubor RPM s názvem nazevproduktu-nazev-cisloproduktu-en-US-1.2-0.src.rpm
.
Spuštění příkazu $
publican create --name Nazev_Dok --edition x.y správně nastaví vydání.
Potlačte tento tag proměnnou edition
v souboru publican.cfg
, je-li vydání vašeho dokumentu identifikováno čímkoliv jiným než číslem.
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg
file. If you do not override this tag in the publican.cfg
file, this tag must only contain numbers and the period (‘0–9’ and ‘.’) if you plan to build packages with Publican.
<pubsnumber>pubsnumber</pubsnumber>
pubsnumber nastaví číslo vydání (release) (poslední číslici v názvu souboru) při sestavení knihy příkazem $
publican package. Na příklad nastavení pubsnumber na 1
a sestavení knihy použitím příkazu publican package --binary --lang=en-US vytvoří soubor RPM s názvem nazevproduktu-nazev-cisloproduktu-en-US-vydani-1.src.rpm
.
Potlačte tento tag proměnnou release
v souboru publican.cfg
, obsahuje-li číslo vydání vašeho dokumentu cokoliv jiného než celá čísla.
Publican uses data in this tag to generate part of the file name for RPM packages, unless overridden by data in the publican.cfg
file. If you do not override this tag in the publican.cfg
file, this tag must only contain numbers (‘0–9’) if you plan to build packages with Publican.
<abstract><para>abstrakt</para></abstract>
Krátký přehled a shrnutí předmětu knihy a jejího účelu, tradičně ne delší než jeden odstavec. Abstrakt se zobrazí před obsahem ve vydáních HTML a na druhé stránce vydáních PDF. Je-li kniha sestavena jako balíček RPM, abstrakt nastaví pole Description
v souboru spec RPM. To způsobí, že abstrakt je pro balíček dostupný pomocí příkazu rpm -qi.
Do souboru Book_Info.xml
dokumentu lze přidat další metadata, která podpoří zvláštní vlastnosti různých výstupních formátů:
<keywordset>
, <keyword>
Termíny označené tagem <keyword>
a umístěné uvnitř <keywordset>
jsou přidány do pole <meta name="keywords">
v hlavičce souborů HTML a pole Keywords
vlastností dokumentu PDF.
<subjectset>
, <subject>
Termíny označené tagem <subject>
a umístěné uvnitř <subjectset>
jsou přidány do pole Subject
vlastností dokumentu PDF a metadat e-knihy formátu EPUB.
Pro účely stanovení předmětu svého dokumentu zvažte použití řízeného slovníku, na příklad Předmětová hesla Kongresové knihovny (LCSH). Zvolený slovník identifikujte v tagu <subjectset>
atributem scheme
, na příklad <subjectset scheme="libraryofcongress">
. Vyhledávat v předmětových heslech LCSH lze na stránce Authorities & Vocabularies Kongresové knihovny: http://id.loc.gov/authorities/search/.
<mediaobject role="cover" id="epub_cover">
Použijte tag <mediaobject>
s atributy role="cover"
a id="epub_cover"
, abyste nastavili zpracování obálky pro e-knihu formátu EPUB. Na příklad:
<mediaobject role="cover" id="epub_cover"> \t<imageobject role="front-large" remap="lrg"> \t\t<imagedata width="600px" format="PNG" fileref="images/front_cover.png"/> \t</imageobject> \t<imageobject role="front" remap="s"> \t\t<imagedata format="PNG" fileref="images/front_cover.png"/> \t</imageobject> \t<imageobject role="front-small" remap="xs"> \t\t<imagedata format="PNG" fileref="images/front_cover.png"/> \t</imageobject> \t<imageobject role="thumbnail" remap="cs"> \t\t<imagedata format="PNG" fileref="images/front_cover_thumbnail.png"/> \t</imageobject> </mediaobject>
Tak jako v případě všech dalších obrázků ve vašem dokumentu umístěte obrázky určené pro obálku knihy v podadresáři images
.
Jak bylo poznamenáno výše, výchozí Book_Info.xml
používaný Publicanem obsahuje tag <edition>
.
Šíříte-li knihu jako balíček RPM, údaje umístěné v tomto tagu nastaví v názvu souboru RPM první dvě číslice čísla verze.
Proto se vydání (edition) '1.0' stává verzí '1.0'.
Book_Info.xml
obsahuje rovněž tag <pubsnumber>
. Jakékoliv údaje umístěné v tomto tagu změní číslo vydání (release) knih zabalených do RPM.
Kniha s vydáním (edition) 1.0 a pubsnumber 5 by měla být verzí 1.0 vydáním (release) 5, zkráceně 1.0-5.
Tagy edition a pubsnumber nejsou svázány s tagem <productnumber>
, který lze najít v Book_Info.xml
rovněž: <productnumber>
představuje číslo verze produktu, který se v knize dokumentuje nebo se o něm jinak píše.
Je zcela možné mít 2. vydání knihy vztahující se ke konkrétní verzi produktu.
V bibliografii jsou dvě kopie knihy stejné vydání, jsou-li vytištěny za použití podstatně stejných type-set master desek nebo stránek. ('Podstatně' nabízí určitou toleranci pro opravy překlepů a další nezávažné změny.)
Sběratelé knih běžně spojují 'první vydání' s 'prvním výtiskem', zatímco bibliografičtí pracovníci se zajímají o text běžně umístěný na obálce knihy, kteří označují 2. výtisk stejné (nebo podstatně stejné) desky za '1. vydání, 2. přetisk' nebo '1. vydání, 2. výtisk'.
Doporučujeme v této záležitosti dodržovat bibliografickou praxi. Používáte-li Publican k nové publikaci knihy z 'podstatně stejného XML', navyšte tag <pubsnumber>
, nikoliv tag <edition>
. Funguje totiž jako blízká obdoba přetisku nebo čísla výtisku v tradičním nakladatelství.
Ohledně změny čísla vydání (edition) doporučujeme ho měnit za stejných okolností, za kterých tradiční nakladatelé mění vydání díla: je-li revidováno nebo významně přepracováno. Co představuje významně, a jak vysoká musí být míra přepracování, aby se zvýšilo celé nebo jen desetinné číslo vydání (edition), se ponechává na uvážení redakce.
Author_Group.xml
není povinný, ale je standardním místem pro záznam o autorovi, redaktorovi, umělcovi a dalších podrobností uznání. Zde je ukázka souboru Author_Group.xml
:
<?xml version="1.0" encoding="utf-8"?> <authorgroup xmlns="http://docbook.org/ns/docbook" version="5.0"> <author> <orgname>FF0000 Headgear Documentation Group</orgname> </author> <author> <personname> <firstname>Dude</firstname> <surname>McDude</surname> </personname> <affiliation> <orgname>My Org</orgname> <orgdiv>Best Div in the place</orgdiv> </affiliation> <email>dude.mcdude@myorg.org</email> </author> </authorgroup> \t\t \t\t
Author_Group.xml
nemusí obsahovat všechny výše uvedené informace: uvěďte co nejvíce nebo co nejméně je potřeba.
Články DocBook nemohou obsahovat kapitoly (chapter). Použijete-li v $
publican create volbu --type=article
, Publican nevytvoří soubor Chapter.xml
. K organizaci obsahu svého článku použijte oddíly (section).
Podrobnosti o různých způsobech interakce sad, knih, článků, částí, kapitol a oddílů viz DocBook: The Definitive Guide od Norman Walsh a Leonard Muellner, dostupný na http://www.docbook.org/tdg/en/html/docbook.html. Zejména si všimněte, že články lze napsat jako samostatně stojící dokumenty, nebo je lze začlenit do knih.
Soubor Chapter.xml
je šablona pro vytváření souborů kapitol. Soubory kapitol obsahují obsah, který tvoří knihu. Následuje šablona kapitoly (Chapter.xml
) vytvořená příkazem $
publican create. Všimněte si, že DOCTYPE
je nastaven na chapter
:
<?xml version='1.0'?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="MYBOOK-Test"> <title>Test</title> <para> This is a test paragraph </para> <section id="MYBOOK-Test-Section_1_Test"> <title>Section 1 Test</title> <para> Test of a section </para> </section> <section id="MYBOOK-Test-Section_2_Test"> <title>Section 2 Test</title> <para> Test of a section </para> </section> </chapter>
Tato kapitola má dva oddíly, Section 1 Test
and Section 2 Test
. Další informace o kapitolách viz http://docbook.org/tdg/en/html/chapter.html
Soubor kapitoly by měl být přejmenován tak, aby odrážel předmět kapitoly. Na příklad kapitola o instalaci produktu by mohla nést název Instalace.xml
, zatímco kapitola o nastavení části softwaru by měla být nazvána Nastaveni.xml
nebo Konfigurace.xml
.
Soubor Nazev_Dok.xml
obsahuje direktivy xi:include
, které připojí další soubory XML nezbytné pro dokument, včetně kapitol nebo oddílů obsažených v jiných XML souborech. Na příklad soubor knihy Nazev_Dok.xml
shromažďuje kapitoly, které jsou obsaženy v oddělených souborech XML.
Níže je uveden příklad souboru Nazev_Dok.xml
, který popisuje knihu DocBook — všimněte si, že DOCTYPE
je nastaven na book
.
Příklad 4.4. Kniha DocBook
<?xml version='1.0'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <book> <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <index /> </book>
Tento příklad načítá soubory XML Book_Info.xml
, Preface.xml
, Chapter.xml
a Appendix.xml
.
Na pořadí, ve kterém jsou kapitoly seřazeny, záleží. Při sestavování této ukázkové knihy předchází Book_Info.xml
před Preface.xml
, který předchází před Chapter.xml
atd.
Soubor Nazev_Dok.xml
není nijak omezen, co se týče použití direktiv xi:include
. Lze vytvořit dokument jen s jedním souborem XML. Následuje příklad knihy vytvořené jediným souborem XML.
<book> <chapter> <title>Chapter 1</title> <para> \tA paragraph in Chapter 1. </para> <section id="section1"> <title>Chapter 1 Section 1</title> \t<para> \t\tA paragraph in Section 1. \t</para> </section> <section id="section2"> <title>Chapter 1 Section 2</title> \t<para> \t\tA paragraph in Section 2. \t</para> </section> </chapter> <chapter> <title>Chapter 2</title> <para> \tA paragraph in Chapter 2. </para> </chapter> </book>
This book contains two chapters. Chapter one contains two sections. Refer to http://docbook.org/tdg/en/html/section.html for further information about sections, and http://docbook.org/tdg/en/html/book.html for further information about books.
Soubor Nazev_Doc.ent
se využívá pro definici lokálních entit. Entity YEAR
a HOLDER
se využívají pro informace o autorských právech. Ve výchozím nastavení nastaví Publican YEAR
na současný rok a do HOLDER
vloží zprávu, která vám připomene, abyste nezapomněli pro dokument uvést držitele autorských práv. Chybí-li entity YEAR
a HOLDER
, dokument se nesestaví.
Další entity mohou být požadovány grafickou úpravou uplatňovanou na dokument. Na příklad grafická úprava Publicanu pro dokumenty Fedory používá entitu BOOKID
, která předepisuje, jak by měli čtenáři odkazovat na dokument, když zasílají o něm zpětnou vazbu.
<!ENTITY PRODUCT "MYPRODUCT"> <!ENTITY BOOKID "MYBOOK"> <!ENTITY YEAR "2008"> <!ENTITY HOLDER "YOUR NAME GOES HERE">
Entity nabízejí pohodlí, ale měly by být používány s velkou opatrností v dokumentech určených k překladu. Napsání (na příklad) &FDS;
místo Fedora Directory Server šetří autorovi čas, ale převedené entity se nezobrazí v souborech portable object (PO), které používají překladatelé. Úplné překlady dokumentů, jež obsahují entity, jsou tak v konečném důsledku nemožné.
Entity zavádějí zvláštní překážky pro překladatele a mohou vyloučit vytvoření vysoce kvalitního překladu. Základní povahou entity je skutečnost, že slovo nebo fráze zastoupená entitou se renderuje v dokumentu pokaždé zcela stejně, v každém jazyce. Tato nepřizpůsobivost znamená, že slovo nebo skupina slov zastoupená entitou může být pro cílový jazyk nečitelná nebo nesrozumitelná a že zastoupené slovo nebo skupina slov se nemohou změnit, pokud gramatická pravidla cílového jazyka vyžadují jejich změnu. Navíc protože entity nejsou převedeny, když je XML převáděn na PO, překladatelé nedokáží vybrat správná slova, která entitu obklopují, jak vyžadují gramatická pravidla cílového jazyka.
Definujete-li entitu — <!ENTITY LIFT "Liberty Installation and Formatting Tome">
— lze do XML vložit &LIFT;
a to se vždy, když je kniha sestavena do HTML, PDF nebo textového souboru, zobrazí jako Liberty Installation and Formatting Tome
.
Avšak entity nejsou při převádění XML do PO převedeny. Překladatelé proto nikdy neuvidí Liberty Installation and Formatting Tome
. Místo toho uvidí &LIFT;
, což nelze přeložit.
Zvažte něco tak jednoduchého, jako je následující část věty v angličtině přeložená do souvisejícího jazyka: němčiny.
As noted in the Liberty Installation and Formatting Tome, Chapter 3…
Její překlad může být následující:
Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…
Jelikož zde žádný text nechybí, název lze přeložit do elegantní němčiny. Rovněž si všimněte použití ‘dem’, v těchto gramatických souvislostech správného tvaru určitého členu ('the') ve vztahu k Wälzer ('tome').
Naproti tomu užívají-li se entity, položka v souboru PO praví:
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr ""
Překlad by pravděpodobně vypadal takto:
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr "Wie in <citetitle>&LIFT;</citetitle>, Kapitel 3, erwähnt…"
A výsledná podoba testu bude tato:
Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…
Název samozřejmě zůstane v angličtině, včetně slov jako 'Tome' a 'Formatting', kterým čtenáři nejspíš nebudou rozumět. Překladatel je také přinucen vynechat určitý člen ‘dem’, obecnější stavba připomínající hybrid angličtiny a němčiny, kterou němečtí mluvčí nazývají Denglisch nebo Angleutsch. Mnoho německých mluvčích považuje tento přístup za špatný a prakticky všichni ho považují za neelegantní.
Prakticky stejné problémy vznikají s úryvkem, jako je tento:
However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…
S textem, který není zakryt entitou, by německý překlad mohl vypadat takto:
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…
Kdyby byla použita entita, aby se ušetřil čas autora, překladatel by se musel poprat s tímto:
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr ""
A překlad by byl sice lehce, zato významně odlišný:
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle>&LIFT;</citetitle>, dass…"
Při prezentaci čtenářovi by se pak zobrazilo následující:
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…
Opět si všimněte chybějícího určitého členu (v této gramatické souvislosti den). Je to sice neelegantní, ale nezbytné, neboť překladatel jinak může pouze odhadovat, kterou podobu určitého členu (den, die or das) použít, což by mohlo vést nevyhnutelně k chybě.
A závěrem si uvědomte, že ačkoliv se v angličtině tvar určitého slova nikdy nemění, toto nutně neplatí v jiných jazycích, a to i když se u slova jedná o jméno vlastní, jako např. název produktu. V mnoha jazycích mění (skloňují se) podstatná jména svůj tvar dle jejich úlohy (mluvnického pádu) ve větě. Entita XML je nastavena tak, aby zastupovala slovo nebo slovní frázi anglickou, proto činí správný překlad v takovýchto jazycích nemožným.
Na příklad napíšete-li dokument, který se vztahuje na více než jeden produkt, bude vás lákat použití entity jako je např. &PRODUCT;
. Výhoda tohoto přístupu spočívá v tom, že jednoduchou změnou této hodnoty v souboru Doc_Name.ent
lze jednoduše přizpůsobit knihu pro zdokumentování (na příklad) Red Hat Enterprise Linuxu, Fedory nebo CentOS. Ovšem zatímco vlastní jméno Fedora
se v angličtině nikdy nemění, má několik tvarů v jiných jazycích. Na příklad v češtině má název Fedora
šest různých tvarů, v záležitosti na sedmi způsobech, ve kterých ho můžete ve větě použít:
Tabulka 4.1. 'Fedora' v češtině
Pád | Užití | Tvar |
---|---|---|
1. Nominativ | podmět věty | Fedora |
2. Genitiv | naznačuje vlastnictví | Fedory |
3. Dativ | nepřímý předmět věty | Fedoře |
4. Akuzativ | přímý předmět věty | Fedoru |
5. Vokativ | oslovení | Fedoro |
6. Lokál | plní funkci příslovečného určení (místa,...) | Fedoru |
7. Instrumentál | vztahuje se k metodě | Fedorou |
Na příklad:
Fedora je linuxová distribuce. — Fedora is a Linux distribution.
Instalace Fedory — Installation of Fedora
Přispějte Fedoře — Contribute to Fedora
Stáhnout Fedoru — Get Fedora
Ahoj, Fedoro! — Hello Fedora!
Ve Fedoře 10… — In Fedora 10…
S Fedorou získáváte nejnovější… — With Fedora, you get the latest…
Věta, která začíná S Fedora získáváte nejnovější…, zůstává českým čtenářům srozumitelná, ale výsledek je gramaticky chybný. Stejný efekt lze simulovat v angličtině, neboť ačkoliv anglická podstatná jména ztratila své pádové koncovky za dob středověku, anglická zájmena se stále skloňují. Věta 'Me see she' je pro anglické čtenáře zcela srozumitelná, ale není tím, co očekávají, neboť tvary zájmen me
a she
nejsou správné. Me
je tvar zájmena ve 4. pádu, ale protože je podmětem věty, zájmeno by mělo být ve tvaru 1. pádu, I
. Podobně she
je v 1. pádu, ale jako přímý předmět věty by mělo zájmeno být v pádu 4., her
.
Podstatná jména mají ve většině slovanských jazyků, jako ruština, ukrajinština, čeština, polština, srbština a chorvatština, sedm různých pádů. Podstatná jména v ugrofinských jazycích, jako je finština, maďarština a estonština, mají mezi patnácti až sedmnácti pády. Skandinávské jazyky na příklad skloňují podstatná jména, aby naznačili určitost — zda se podstatné jméno vztahuje na 'a thing' (nějakou věc) nebo 'the thing' (tu věc) — a některá nářečí těchto jazyků skloňují podstatná jména jak pro určitost, tak pro gramatické pády.
Nyní vynásobte tyto problémy více než 40 jazyky, jež Publican v současnosti podporuje. Kromě několika málo nepřekládaných řetězců, které Publican standardně uvádí v souboru Dok_Nazev.ent
, se entity mohou ukázat jako užitečné pro čísla verzí produktů. Cokoliv mimo tyto důvody užívání entit se rovná vědomému pokusu jak ztížit a omezit kvalitu překladů. Navíc čtenáři vašeho dokumentu v jazyce, který skloňuje podstatná jména (až již pro pády, určitost nebo jiné důvody), nebudou vědět, že špatná gramatike je výsledkem vámi nastavených entit XML — budou nejspíš předpokládat, že neschopným je zde překladatel.
Příkaz $
publican package vyhledá první soubor XML v adresáři XML dokumentu, který obsahuje tag <revhistory>
. Publican poté použije tento soubor k sestavení historie revizí RPM.
Obrázky ukládejte v adresáři se svými soubory XML do podadresáře images
. K vložení obrázků do knihy používejte ./images/nazev-obrazku
. Zde je příklad, který vloží soubor obrázku testimage.png
:
<mediaobject> <imageobject> \t<imagedata fileref="./images/testimage.png" /> </imageobject> <textobject><phrase>sem vložte náhradní text</phrase></textobject> </mediaobject>
Nezapomeňte zadat <textobject>
proto, aby váš obsah zůstal přístupný zrakově postiženým lidem. V některých právních řádech můžete za poskytnutí této přístupnosti dokonce právně zodpovídat — na příklad musíte-li nebo vaše organizace musí být v souladu se Section 508 of the United States Rehabilitation Act of 1973.[1]
Máte-li ve své knize obrázky, které je potřeba přeložit - na příklad snímky obrazovky s uživatelským rozhraním v jiném jazyce, než je originální jazyk knihy — umístěte tyto obrázky v adresáři images
do podadresářů rozdělených dle jednotlivých jazyků. Zajistěte, aby soubor obrázku v přeloženém jazyce měl stejný název jako soubor v jazyce originálním. Sestavíte-li přeloženou knihu, Publican použije soubor z podadresáře adresáře images/
přeloženého jazyka, namísto souboru z podadresáře originálního jazyka.
Publican používá pouze obrázky z podadresáře images
vašeho adresáře XML a odpovídající obrázky z jeho jazykových podadresářů. Obrázky uložené v ostatních adresářích nefungují.
Obsahuje-li vaše kniha příklady programových kódů, umístěte je do adresáře extras/
v adresáři svého zdrojového jazyka, a pro načtení souboru s kódem do struktury XML dokumentu používejte <xi:include>
. Publican neprovádí syntaktickou analýzu žádného souboru jako XML, který nalezne v adresáři extras/
.
Některé znaky jsou v XML rezervované, zejména &
a <
. Vložíte-li příklady kódu přímo do XML svého dokumentu, musíte tyto znaky escapovat buď jejich označením jako CDATA
, nebo nahrazením entitami (&, resp. <). [2] Umístíte-li tyto soubory do adresáře extras/
, není nutné tyto znaky escapovat. Tento přístup šetří čas, snižuje šanci na zavedení chyb jak do XML dokumentu, tak do kódu samotného, a zjednodušuje budoucí údržbu dokumentu i kódu.
Chcete-li vložit příklad kódu z adresáře extras/
do dokumentu, dodržujte tento postup:
Vytvořte adresář extras
$
mkdircs-CZ/extras
Zkopírujte soubor s kódem do adresáře extras
$
cp~/priklady/foo.c en-US/extras/.
vložte ukázkový soubor do svého souboru XML pomocí xi:include
<programlisting> <xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting>
Nyní můžete upravovat cs-CZ/extras/foo.c
ve svém oblíbeném editoru bez ohledu na to, jaký bude mít vliv na XML.
Stejný přístup funguje, chcete-li popsat svůj kód popisky. Na příklad:
<programlistingco> \t<areaspec> \t\t<area id="bublina-pro-parametr" coords='4 75'/> \t\t<area id="bublina-pro-magnitudu" coords='12 75'/> \t</areaspec> \t<programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for" \txmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> \t<calloutlist> \t\t<callout id="popisek-pro-parametr" arearefs="bublina-pro-parametr"> \t\t\t<para> \t\t\t\t<firstterm>Standardní gravitační parametr</firstterm> \t\t\t\t(μ) je veličina, která se rovná součinu univerzální gravitační \t\t\t\tkonstanty (G) a hmotnosti přirozeného kosmického tělesa. \t\t\t</para> \t\t</callout> \t\t<callout id="popisek-pro-magnitudu" arearefs="bublina-pro-magnitudu"> \t\t\t<para> \t\t\t\tJelikož hmotnost obíhajícího tělesa je o několik řádů \t\t\t\tmenší než hmotnost primárního tělesa, hmotnost \t\t\t\tobíhajícího tělesa není do výpočtu zahrnuta. \t\t\t</para> \t\t</callout> \t</calloutlist> </programlistingco>
Všimněte si, že elementy <area>
určují pozici popisků, které se zobrazí nad příkladem kódu. Atributy coords
uvádějí číslo řádku a sloupce oddělené mezerou. V této ukázce jsou popisky použity na řádky 4 a 12, zarovnané na sloupec 75. Ačkoliv tento přístup značí, že byste museli upravit atributy coords
, změnili-li byste někdy kód, na který se vztahují, zabraňuje mísení tagů <area>
XML do samotného kódu.
[2] Viz kap. 2.4 "Character Data and Markup" normy XML 1.0, dostupná on-line http://www.w3.org/TR/2008/REC-xml-20081126/.
Publican vám dovolí zkombinovat libovolné soubory společně s dokumenty. Tyto soubory jsou součástí balíčků RPM, které sestavíte Publicanem, a jsou nainstalovány na systémy uživatelů společně se samotným dokumentem. Na příklad můžete chtít zahrnout multimediální soubory vzdělávací povahy, které doplní dokument, nebo ukázkové příklady zdrojového kódu nebo jiných materiálů, které umožní uživatelům propracovat se skrze příklady nebo lekce v dokumentu.
Chcete-li přibalit libovolné soubory k dokumentu, vytvořte adresář s názvem files
v jazykovém adresáři originálního jazyka (např. cs-CZ
) knihy (např. Moje_Kniha
.
V adresáři Moje_Kniha
$
mkdir cs-CZ/files
Zkopírujte soubory do adresáře files
:
$
cp libovolne_soubory cs-CZ/files
Příkaz $
publican rename zjednoduší přejmenování dokumentu na nový název, nebo změnu názvu verze produktu, na který se dokument vztahuje. Příkaz přijímá až tři volby:
--name
novy_nazevzmění název dokumentu. Na příklad chcete-li přejmenovat dokument z Server Configuration Guide na Server Deployment Guide, přejděte do kořenového adresáře dokumentu a spusťte:
$
publican rename --name "Server Deployment Guide"
Konkrétně příkaz změní obsah tagu <title>
v souboru Article_Info.xml
, Book_Info.xml
nebo Set_Info.xml
a nastaví hodnotu parametru mainfile
v souboru publican.cfg
, aby Publican stále mohl nelézt kořenový uzel XML a entity dokumentu.
Všimněte si, že příkaz $
publican rename nezmění název žádného souboru. Proto jsou kořenový uzel XML a všechny entity dokumentu stále umístěny v souborech pojmenovaných dle původního názvu dokumentu — v předchozím příkladu tedy Server_Configuration_Guide
.
--product
novy_produktzmění název produktu, na který se dokument vztahuje. Na příklad byl-li předchozí název produktu ForceRivet, ale nyní se nazývá PendantFarm, přejděte do kořenového adresáře dokumentu a spusťte:
$
publican rename --product PendantFarm
Příkaz změní obsah tagu <productname>
v souboru Article_Info.xml
, Book_Info.xml
nebo Set_Info.xml
.
--version
nova_verzezmění verzi produktu, na kterou se dokument vztahuje. Byla-li na příklad předchozí verze produktu verze 1.0 a nyní je 2.0 , přejděte do kořenového adresáře dokumentu a spusťte:
$
publican rename --version 2.0
Příkaz změní obsah tagu <productnumber>
v souboru Article_Info.xml
, Book_Info.xml
nebo Set_Info.xml
.
Všechny tyto volby lze použít v jednom příkazu. Na příklad:
$
publican rename --name "Server Deployment Guide" --product PendantFarm --version 2.0
Podpora lokalizace dokumentů byla v návrhu Publican klíčovou otázkou. Obecné překladatelské workflow pro dokument vyvinuté v Publicanu je následující:
Dokončete XML dokumentu.
XML by se pro tuto verzi dokumentu nemělo považovat za ‘zmražené’. Máte-li svůj dokument uložen v repozitáři se správou verzí, měli byste tuto verzi umístit do odděleného adresáře nebo větve. To umožní autorům zahájit práci na následujících verzích dokumentu ve větvi jedné, zatímco se poskytne stabilní základna pro překlad ve větvi jiné.
Volitelné ale doporučené: pusťte, neboli dropněte, dokument pro překlad. Spusťte:
$
publican trans_drop
Publican vytvoří nový podadresář, nazvaný trans_drop/
. Podadresář trans_drop/
obsahuje momentální snímek zdrojových souborů dokument. Když se adresář trans_drop/
nachází v dokumentačním projektu, Publican používá jeho obsah jako základnu pro příkazy zdokumentované dále v tomto postupu.
Generate portable object template (POT) files from the XML files:
$
publican update_pot
If this is the first time that POT files have been created for this document, Publican creates a new subdirectory, named pot
. The pot
subdirectory holds a POT file for each XML file in the document. If Publican has created POT files for this document previously, Publican updates the existing POT files to reflect any changes in the XML since the POT files were last updated.
Publican generates a POT file for every XML file in the XML directory, whether the XML file is used in the document or not. If you transform unused XML files into POT files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
Use the $
publican print_unused command to generate a list of XML files that are not used in your document.
Generate portable object (PO) files from the POT files to begin translation into a particular language:
$
publican update_po --langs=language_code
where language_code is the code for the target language. Refer to F – „Language codes“ for more information about language codes. You can provide multiple language codes, separated by commas, to generate PO files for more than one language at a time. For example:
$
publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN
If this is the first time that PO files have been created for a particular language, Publican creates a new subdirectory, named with the language code that you specified with the --langs=
option. This subdirectory holds a PO file for each POT file in pot
subdirectory, plus a Revision_History.xml
file that tracks the history of this particular translation. When created for the first time, the Revision_History.xml
file records the date on which the PO files for this translation were created, and the version of the source language XML (taken from the source language's Revision_History.xml
file) on which this translation is therefore based.
If Publican has created PO files for this language previously, Publican updates the existing PO files to reflect any changes in the POT files since the PO files were last updated, and adds a new entry to the translation's Revision_History.xml
file to record the date on which the PO files for this translation were refreshed, and the version of the source language XML on which the revision is based. You can update existing PO files in every subdirectory with the --langs=all
option:
$
publican update_po --langs=all
Publican generates a PO file for every POT file in the pot
directory, whether the POT file is based on a corresponding XML file that is used in the document or not, or whether a corresponding XML file even exists. If you transform POT files for unused or deleted XML files into PO files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
When you generate PO files, Publican presents you with a warning for any POT files that do not have corresponding XML files, but will generate the PO file nevertheless. However, Publican will not warn you if a POT file exists for an XML file that is not used in the document.
Translate the strings contained in the PO files.
If you are updating a previously published translation of this revision in the source language, use Publican's publican add_revision command to describe your changes or corrections. Publican updates the Revision_History.xml
file for you.
If the document has changed in its original language, use the publican trans_drop, publican update_pot, and publican update_po commands as described earlier in this procedure instead.
Build the document in the target language, for example:
$
publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
or package it in the target language, for example:
$
publican package --lang=is-IS
You can build the document in all languages for which you have translations with the --langs=all
option, but note that you must package each language individually. Refer to 7 – „Sestavení dokumentu“ for more information on building a document, and 8 – „Packaging a document“ on packaging a document.
Translation takes place after a book has been finalized. You do not need to know who will translate your book in order to give them credit. Create $translation/Author_Group.xml
and add a valid DocBook authorgroup. The translator can add their details to this file and Publican will append it to $source_lang/Author_Group.xml
when the book is build. This allows authors to finalize the original text without needing to know who will translate the book.
DocBook automatically collates and sorts <glossentry>
elements into a book's glossary; and <primary>
, <secondary>
, and <tertiary>
<indexterm>
elements into a book's index. Entries are sorted automatically, and although this system works well for languages written with an alphabet, abugida, or syllabic script, languages written with logograms sort less well.
To manually adjust the sort order of a glossary entry or index entry, manually add DocBook's sortas
attribute to the XML element. For example, to ensure that the Japanese word 暗号化 sorts correctly in an index, specify:
#. Tag: indexterm #, no-c-format msgid "<primary>encryption</primary>" msgstr "<primary sortas="あんごうか">暗号化</primary>"
Similarly, to ensure that the Japanese word 暗号化 sorts correctly in a glossary, specify:
#. Tag: glossentry #, no-c-format msgid "<glossterm>encryption</glossterm>" msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"
Parametry nastavené v konfiguračním souboru dokumentu (ve výchozím stavu se jedná o publican.cfg
) vám umožní ovládat mnoho aspektů způsobu prezentace dokumentu - viz 1.1 – „Soubor publican.cfg“.
Udržujete-li několik verzí dokumentu, lze vytvořit konfigurační soubor pro každou z nich. Při sestavování dokumentu lze k zadání, který konfigurační soubor se má pro dané sestavení použít, využít --config
, na příklad:
$
publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
Pro účely sestavení dokumentu:
Si potvrďte, že v souboru Dok_Nazev.ent
jsou nastaveny entity YEAR
a HOLDER
, jak je popsáno v 1.6 – „Nazev_Dok.ent“.
Přejděte do kořenového adresáře dokumentu. Na příklad je-li dokument pojmenován Kniha_Test
a umístěn v adresáři ~/knihy/
, spusťte tento příkaz:
$
cd ~/knihy/Kniha_Test
Spusťte test pro kontrolu všech chyb, které by mohly zastavit sestavování knihy ve vybraném jazyce, na příklad:
$
publican build --formats=test --langs=en-US
Spusťte tento příkaz pro sestavení knihy:
$
publican build --formats=formaty --langs=jazyky
Nahraďte formaty čárkou odděleným seznamem formátů, které chcete sestavit, na příklad html,html-single,pdf
. Nahraďte jazyky čárkou odděleným seznamem jazyků, které chcete sestavit, na příklad en-US,sv-SE,uk-UA,ko-KR
.
Formáty pro akci build
html
Publican sestaví dokument do podoby mnohostránkového HTML, s každou kapitolou nebo hlavním oddílem na samostatné stránce. Publican umístí na začátek dokumentu rejstřík a navigační prvky do každé stránky.
V souboru publican.cfg
použijte parametry chunk_first
a chunk_section depth
, abyste řídili, do jaké hloubky má Publican v tomto formátu zanořovat (seskupovat) oddíly.
html-single
Publican sestaví dokument do podoby jednostránkového HTML s obsahem blízko začátku stránky.
html-desktop
Publican sestaví dokument do podoby jednostránkového HTML s obsahem v samostatném okně po levé straně dokumentu.
man
Publican sestaví dokument do podoby manuálové stránky ("man page"), které se používají v Linuxu, UNIXu a podobných operačních systémech.
pdf
Publican sestaví dokument do podoby souboru PDF.
test
Publican ověří validitu struktury XML knihy, ale nepřevede XML do jiného formátu.
txt
Publican sestaví dokument do podoby jediného textového souboru.
epub
Publican sestaví dokument do podoby elektronické knihy ve formátu EPUB.
eclipse
Publican sestaví dokument do podoby zásuvného modulu nápovědy Eclipse. Podrobnosti o zadávání parametrů id
, name
a provider-name
pro Eclipse parametry Publicanu ec_id
, ec_name
a ec_provider
viz 1.1 – „Soubor publican.cfg“.
Následující příklady ukazují běžně užívané příkazy $
publican build:
$
publican build --help
Nebo-li zobrazit dostupné volby $
publican build pro sestavení knihy.
$
publican build --formats=test --langs=jazyky
Zkontrolovat, zda se kniha sestaví bezchybně. Sestavte --formats=test před spuštěním kteréhokoliv jiného příkazu $
publican build, a před odesláním knihy zpět do repozitáře se správou verzí, z kterého ji mohou stáhnout ostatní přispěvatelé.
$
publican build --formats=html --langs=jazyky
Sestavit knihu do formátu vícestránkového HTML. Výstup HTML bude umístěn v adresáři Dok_Nazev/tmp/jazyk/html/
. Každá kapitola a hlavní oddíl je umístěn do svého souboru HTML. Hloubku, do které Publican umisťuje pododdíly do samostatných souborů HTML, lze řídit pomocí parametru chunk-section-depth
v publican.cfg
— viz 1.1 – „Soubor publican.cfg“.
$
publican build --formats=html-single --langs=jazyky
Sestavit knihu do formátu jednostránkového HTML. Výstupem bude jediný HTML soubor umístěný v adresáři Dok_Nazev/tmp/jazyk/html-single/
$
publican build --formats=pdf --langs=jazyky
Sestavit knihu do souboru PDF. Publican pro renderování PDF spoléhá na externí aplikaci, FOP. Proto nemusí být sestavování do PDF k dispozici na všech systémech, vše závisí na dostupnosti FOP. Výstupem bude jediný soubor PDF umístěný v adresáři Dok_Nazev/tmp/jazyk/pdf/
.
$
publican build --formats=html,html-single,pdf --langs=jazykySestavit knihu do formátu vícestránkového HTML, jednostránkového HTML i PDF.
Publican provádí validaci XML proti definici typu dokumentu (DTD) DocBook předtím, než provede sestavení obsahu. Ačkoliv, je-li dokument ve vývoji, někdy můžete chtít validaci při sestavení přeskočit, zejména pokud dokument obsahuje křížové odkazy (<xref>
s) na oddíly dokumentu, které ještě neexistují. Přeskočit validaci lze spuštěním $
publican build s volbou --novalid
. Křížové odkazy na neexistující obsah se v sestaveném dokumentu zobrazí jako tři otazníky: ???
.
Jelikož nebyl dokument validován proti DTD, kvalita výstupu, provedete-li sestavení s volbou --novalid
, je vysoce pochybná. Nezveřejňujte dokumentaci, kterou jste sestavili s volbou --novalid
.
This section discusses packaging documents for distribution through the RPM Package Manager. However, when you use the $
publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
The parameters set in the document configuration file (by default, publican.cfg
) allow you to control many aspects of the way in which a document is presented and packaged — refer to 1.1 – „Soubor publican.cfg“.
If you maintain multiple versions of a document, you can create a configuration file for each version. When packaging the document, you can use the --config
to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
$
publican package --lang hi-IN --config community.cfg
Publican not only builds documentation, but it can package built content for distribution to individual workstations and to web servers as RPM packages. RPM packages are used to distribute software to computers with Linux operating systems that use the RPM Package Manager. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
Publican can produce both source RPM packages (SRPM packages) and binary RPM packages. Furthermore, both SRPM packages and binary RPM packages can be configured to deploy to workstations or web servers.
SRPM packages contain the source code used to generate software rather than the software itself. To use an SRPM package, a computer must compile the source code into software — or in this case, into documents. SRPM packages of Publican documents contain XML files and a spec file rather than finished documents in formats such as HTML and PDF. You cannot install documentation directly from SRPM packages with current versions of the RPM Package Manager.
Conversely, binary RPM packages contain software — or in this case, a document — that is ready to copy to a location in the computer's file system and use immediately. The contents of the binary RPM package do not need to be compiled by the computer onto which they are installed. Therefore, when installing documentation solely for local use the computer does not need to have Publican installed. Installing Publican-generated documentation on a webserver does requires Publican to be installed, but for reasons other than compiling the source code. Refer to 8.1.2 – „Desktop packages and web packages“ for a description of the differences between documentation installed for local use (desktop RPMs) and documentation installed to serve as web content (web RPMs).
Publican can package documents for reading on a computer workstation (a desktop RPM package) or to install on a web server and publish on the World Wide Web (a web RPM package). The desktop RPM package of a Publican document and the web RPM package of the same document differ in that the desktop RPM package installs documentation only for local use on a computer, while the web RPM installs documentation for local use, but also to be served to the World Wide Web.
Desktop (binary) RPM packages of Publican documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of /usr/share/doc/
, the location specified by the Filesystem Hierarchy Standard (FHS) for ‘Miscellaneous documentation’.[3] The desktop RPM package also contains a desktop file, to be placed in /usr/share/applications/
. This file enables desktop environments to add the installed document to their menus for ease of reference by users. By default, the menu item appears under → on the GNOME desktop. To customize the placement of the menu item, create a documentation menu package to supply .directory
and .menu
files and set the dt_requires
and menu_category
parameters in the publican.cfg
file to require this package and supply the appropriate menu category. Refer to 8.1.3 – „Desktop menu entries for documents“
By default, web RPM packages of Publican documents contain the documentation in single-page HTML, multi-page HTML, EPUB, and PDF formats. The formats included vary if:
you publish documentation in a language in which PDF output is not currently supported. Publican relies on FOP to generate PDF output. FOP does not presently support right-to-left text (for example, Arabic, Persian, or Hebrew). Furthermore, because FOP cannot presently specify fonts on a character-by-character basis, a lack of available fonts in Indic scripts that also include Latin glyphs prevents Publican from reliably generating PDF output in Indic languages. By default, Publican does not include PDF files in web RPM packages generated in Arabic, Persian, Hebrew, or any Indic language.
your book or your brand contains the web_formats
parameter. The value of this parameter overrides the default formats that Publican packages. For example, to publish the document only as single-page HTML, PDF, and text, set web_formats: "html-single,pdf,txt"
Built content is installed in subdirectories of /var/www/html/
, a common document root for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.
$
publican package command
Use the $
publican package --lang=Language_Code command to package documents for distribution in the language that you specify with the --lang
option. Refer to F – „Language codes“ for more information about language codes.
If you run $
publican package with no options other than the mandatory --lang
option, Publican produces a web SRPM package. The full range of options for publican package is as follows:
--lang
languagespecifies the language in which to package the documentation.
If translation in a particular language is not complete by the scheduled release date, consider marking the language with the ignored_translations
parameter in the document's publican.cfg
file. The package will be named appropriately for the language, but will contain documentation in the original language of the XML rather than a partial translation. When translation is complete, remove the ignored_translations
parameter, increase the release number in the Project-Id-Version
field in the Book_Info.po
file for that language, and generate the package again. When you distribute the revised package, it becomes available to replace the original untranslated package.
--config
filename
specifies that Publican should use a configuration file other than the default publican.cfg
file.
--desktop
specifies that Publican should create a desktop RPM package rather than a web RPM package.
--brew
specifies that Publican should push the completed package to Brew. Brew is the build system used internally by Red Hat; this option is meaningless outside Red Hat.
--scratch
when used together with the --brew
and --desktop
options, specifies that an SRPM package should be built as a scratch build when sent to Brew. Scratch builds are used to verify that an SRPM package is structured correctly, without updating the package database to use the resulting package.
--short_sighted
specifies that Publican should build the package without including the version number of the software (version
in the publican.cfg
file) in the package name.
Much software documentation is version-specific. At best, the procedures described in the documentation for one version of a product might not help you to install, configure, or use a different version of the product. At worst, the procedures described in the documentation for one version might be misleading or even harmful when applied to a different version.
If you distribute documentation as RPM packages without version numbers in the package names, the RPM Package Manager on users' computers will automatically replace any existing documentation with the documentation for the latest version; users will not have access to documentation for more than one version of the software at a time. Be certain you want this outcome.
--binary
specifies that Publican should build the package as a binary RPM package.
After you run the $
publican package command, Publican outputs completed SRPM packages to the document's tmp/rpm
directory, and completed binary RPM packages to the document's tmp/rpm/noarch
directory.
By default, Publican documentation packages are named:
productname-title-productnumber-[web]-language-edition-pubsnumber. [.[build_target].noarch].file_extension
.
Publican uses the information in the document's configuration file (by default, publican.cfg
) to supply the various parameters in the file name, and then information in the Book_Info.xml
file for any parameters missing from the configuration file. Refer to 1 – „Soubory v adresáři knihy“ for details of the parameters used in these files. Additionally, note that:
web RPM packages include the element -web-
between the product version and the language code.
SRPM packages have the file extension .src.rpm
but binary RPM packages have the file extension .rpm
binary RPM packages include build_target.noarch
before the file extension, where build_target represents the operating system and version that the package is built for as set by the os_ver
parameter in the publican.cfg
file. The noarch
element specifies that the package can be installed on any system, regardless of the system architecture.
use of the --short_sighted
option removes the -productnumber-
from the package name.
packages of translated documents take their release numbers from the Project-Id-Version
parameter in the Article_Info.po
or Book_Info.po
file. This release number is specific to a particular language and bears no relationship to the release numbers of the same document in the original language or any other language.
$
publican package command — Example usageThe following examples illustrate some common options, illustrated with the Foomaster 9 Configuration Guide, edition 2, revision 6.
$
publican package --lang=cs-CZproduces a web SRPM package named Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.src.rpm that contains XML source files in Czech, together with a spec file.
$
publican package --desktop --lang=cs-CZproduces a desktop SRPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.src.rpm that contains XML source files in Czech, together with a spec file.
$
publican package --binary --lang=cs-CZproduces both a web binary RPM package named Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.el5.noarch.rpm and a desktop binary RPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm that contain documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
$
publican package --desktop --binary --lang=cs-CZproduces a desktop binary RPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm that contains documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
$
publican package --desktop --short_sighted --lang=cs-CZproduces a desktop SRPM package named Foomaster-Configuration_Guide-cs-CZ-2-6.src.rpm that contains documentation in Czech. This package will replace any Configuration Guides for previous versions of Foomaster that exists on a system. Users cannot have access to both the Foomaster 8 Configuration Guide and the Foomaster 9 Configuration Guide.
In some cases you may need to maintain multiple versions of a book; for example, a HOWTO guide for product FOO can have an upstream version and an enterprise version, with very subtle differences between them.
Publican makes it easy to manage differences between multiple versions of a book by allowing you to use a single source for all versions. Conditional tagging allows you to make sure that version-specific content only appears in the correct version; that is, you conditionalize the content.
To conditionalize content in a book, use the tag attribute condition. For example, let's say the book How To Use Product Foo has an "upstream", "enterprise", and "beta" version:
<para condition="upstream"> <application>Foo</application> starts automatically when you boot the system. </para> <para condition="enterprise"> <application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>. </para> <para condition="beta"> <application>Foo</application> does not start automatically when you boot the system. </para> <para condition="beta,enterprise"> To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file. </para>
To build a specific version (and thereby capture all content conditionalized for that version), add the condition: version parameter to the publican.cfg
file and run the $
publican build command as normal. For example, if you add condition: upstream
to the publican.cfg
file of How To Use Product Foo and run:
$
publican build --formats=pdf --langs=en-US
Publican filters out all tags with condition attributes other than condition="upstream"
and builds How To Use Product Foo in as a PDF file in American English.
If the root node of an XML file is excluded with a conditional, your document will not build, because empty files are not valid XML. For example, if Installation_and_configuration_on_Fedora.xml
contains a single chapter:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora"> <title>Installation and configuration on Fedora</title> [text of chapter] </chapter>
and this chapter is included in User_Guide.xml
with an <xi:include>
tag, the document will not build with $
condition: Ubuntu set in the publican.cfg
file.
To exclude this chapter, add a condition to the <xi:include>
tag in User_Guide.xml
, not to the <chapter>
tag in Installation_and_configuration_on_Fedora.xml
.
If an <xref>
points to content not included in the build due to conditional tagging, the build will fail. For example, with $
condition: upstream set in the publican.cfg
file, $
publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection">
pointing to <section id="betasection" condition="beta">
.
Use conditional tagging only with great caution in books that you expect to be translated, as conditional tagging creates extra difficulties for translators.
Conditional tagging creates difficulty for translators in two ways: it obscures context in the portable object (PO) files through which translators work, and it makes proofreading more difficult for translators who are not deeply familiar with your book and all the conditions that you have set.
The PO files for the document contain the full set of tags from the XML files, regardless of any conditions set. When translators open the PO file for the example from How To Use Product Foo in 9 – „Conditional tagging“, they see:
#. Tag: para #, no-c-format msgid "<application>Foo</application> starts automatically when you boot the system." msgstr "" #. Tag: para #, no-c-format msgid "<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>." msgstr "" #. Tag: para #, no-c-format msgid "<application>Foo</application> does not start automatically when you boot the system." msgstr "" #. Tag: para #, no-c-format msgid "To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file." msgstr ""
Because PO files include do not include attributes from tags, there is nothing obvious here to show translators that these paragraphs are alternatives to each other and that the writer does not intend that meaning should flow from one paragraph to the next.
In this example, the only paragraphs where the meaning flows logically from one to the next is between paragraphs three and four. Because both of these paragraphs appear in the book for the beta version of the product, they (hopefully) make sense together. Beyond that, the use of conditionals here requires translators to translate individual small chunks of content without the ability to follow the context from one paragraph to the next. When translators must work under these conditions, the quality of the translation will suffer, or the time required — and therefore the cost of translation — will increase.
Furthermore, unless the translators who work on your book know how to configure Publican's publican.cfg
file and are aware of the valid conditions for your book, they cannot proofread their work. Without that knowledge, when translators proofread a document, they will wonder why they cannot find text that they know they translated and can find easily in the PO file. If you must use conditionals in your book, you must be prepared to provide a greater degree of support to your translators than you would otherwise provide.
As an alternative to conditionals, consider maintaining separate versions of your book in separate branches of a version-controlled repository. You can still share XML files and even PO files between the various branches as necessary, and some version control systems allow you to share changes readily among branches.
If you maintain two versions of a book in the same repository, we recommend using a separate config file for each version. For example, the upstream.cfg
file might contain the condition condition: upstream
and the enterprise.cfg
file might contain the condition condition: enterprise
. You could then specify the version of the document to build or package with the --config
; for example, $
publican package --lang en-US --config upstream.cfg. Using two separate config files saves you from having to edit the one config file each time you build or package a document.
Completed documentation for pre-release software is not the same thing as draft documentation.
Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.
In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.
Documentation for pre-release software, especially pre-release software being distributed to testers, customers and partners, should carry a clear mark denoting the beta-status of the software.
To create that mark do the following:
Add the software's pre-release version number, or equivalent state information, to the <subtitle>
tag in your Book_Info.xml
file. Place this additional text in <remark>
tags. For example:
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
add show_remarks
to the publican.cfg
file and set it to '1':
show_remarks: 1
When you build your book with this <remark>
tag and the show_remarks
setting in place, the pre-release nature of the software is displayed clearly and unmistakably. PDF builds display the remark on their cover and title pages. HTML builds (both single-page HTML and multiple-page HTML) display the remark near the beginning of index.html
.
Because this approach makes no changes to the information in Book_Info.xml
used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.
Příklad 4.7. An example of an inline remark
Here is an example of an inline remark.
It is the writer's responsibility to remove the <remark>
tag and its contents and remove or turn off show_remarks
when documentation is updated for use with the release version of the software.
Unfinished documentation made available to others for review should be labeled clearly as such.
To add the draft watermark to your documentation add the status="draft"
attribute to the <article>
, <book>
or <set>
tag in your document's root node. For example:
<book status="draft">
By default, your root node is the <book>
tag in your Doc_Name.xml
file.
If you are working on an article or set, the root node is the <article>
or <set>
tag in Doc_Name.xml
.
Adding the status="draft"
attribute causes each page of the document to show the draft watermark. This is by design.
Even if you change only a portion of a work before sending it out for review, marking every page as draft will encourage reviewers to report errors or typos they spot in passing. It will also ensure non-reviewers who encounter the work do not mistake a draft for a finished version.
Příklad 4.8. An example of a block marked up as draft
This is an example of a block that is marked as draft
Isn't it pretty!
To denote unfinished documentation of pre-release software properly, do both previously noted procedures.
DocBook allows setting the revisionflag
on many elements to allow easier reviewing on changed documents. Publican, as of version 4.1, will add highlighting to these elements if the book is in draft mode. e.g. revisionflag="added"
This is how an element that has been added to a new revision is marked-up.
This is how an element that has been changed in a new revision is marked-up.
This is how an element that has been marked for deletion from a new revision is marked-up. Publican will not automatically delete or hide this content, you have to ensure this is done before publication.
Brands are collections of files that Publican uses to apply a consistent look and style to HTML and PDF output. They provide boilerplate text that appears at the beginning of documents, images such as logos, and stylistic elements such as color schemes. Publican ships with one brand, common/
. Documentation projects can produce and distribute brands to their contributors, either as a package (for example, an RPM package) or as an archive (for example, a tarball or ZIP file).
Publican brands for Fedora, Genome, and oVirt documents are available as RPM packages in Fedora. Similarly, Red Hat internally distributes RPM packages containing Publican brands for GIMP, JBoss, and Red Hat documents. Providing that you have access to the relevant repositories, you can install these brands on a computer that runs Red Hat Enterprise Linux or Fedora — or an operating system derived from either — with the command yum install publican-brand or with a graphical package manager such as PackageKit.
If you use Publican on an operating system that does not use RPM packages, your documentation project might provide its brand in another format. Whatever the format in which the brand is supplied, you must place the brand files in a subdirectory of the Publican Common_Content
directory. By default, this directory is located at /usr/share/publican/Common_Content
on Linux operating systems and at %SystemDrive%/%ProgramFiles%/Publican/Common_Content
on Windows operating systems — typically, C:/Program Files/Publican/Common_Content
Each currently available brand is distributed under a brand-specific license as follows:
To install the brand:
If the brand was supplied to you in an archive of some kind, for example, a tarball or ZIP file, unpack the brand into a new directory on your system.
Change into the directory in which you created or unpacked the brand:
$
cd publican-brand
where brand is the name of the brand.
Build the brand:
$
publican build --formats xml --langs all --publish
Install the brand:
$
sudo publican install_brand --path path
where path is the path to the Publican Common Content files. For example, on a Linux system, run:
$
sudo publican install_brand --path /usr/share/publican/Common_Content
or on a Windows system, run
$
publican install_brand --path "C:/Program Files/Publican/Common_Content"
Tabulka 5.1. Current Brands and their packages
Brand | License of Common Content files | Default license for documents | Package | Comment |
---|---|---|---|---|
common | CC0 1.0 | GFDL Version 1.2 | publican | GPL compatible license. No options. |
RedHat | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-redhat | |
Fedora | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-fedora | |
JBoss | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-jboss | No Options. |
oVirt | OPL 1.0 | OPL 1.0 | publican-ovirt | No Options. |
GIMP | GFDL Version 1.2 | GFDL Version 1.2 | publican-gimp | Matches the license for existing GIMP documentation. |
Genome | OPL 1.0 | OPL 1.0 | publican-genome | No Options. |
Note the difference in licensing between the common content files provided in the common brand (CC0) and the default license set for books generated with the common brand (GFDL). The CC0 license allows you to redistribute and relicense the files that make up the common brand (including the CSS and image files) to suit your project. Publican suggests the GFDL for documentation by default because Publican is developed primarily to build documentation for software. The GFDL is compatible with the GPL, which is the most commonly used license for open-source software.
Use the $
create_brand action to create a new brand. When you create a new brand, you must give it a name and specify the original language for the brand's XML files. The --name
option provides the name, and the --lang
option specifies the language. The complete command is therefore:
$
publican create_brand --name=brand --lang=language_code
Publican creates a new subdirectory named publican-brand
, where brand is the brand that you specified with the --name
option.
For example, to create a brand called Acme
, which will have its Common Content XML files written originally in American English, run:
$
publican create_brand --name=Acme --lang=en-US
Publican creates the brand in a subdirectory named publican-Acme
.
To configure your new brand, search for the word SETUP
in the default files that Publican creates and edit the files to provide the missing details. On Linux operating systems, you can search for the word SETUP
in these files with the command:
$
grep -r 'SETUP' *
Running the $
publican create_brand --name=brand --lang=language_code command creates a directory structure and the required files. The brand directory initially contains:
COPYING
defaults.cfg
overrides.cfg
publican.cfg
publican-brand.spec
, where brand is the name of the brand.
README
a subdirectory for the brand's XML files, CSS stylesheets, and default images. The subdirectory is named with the language code of the original language of the brand (for example, en-US
). These files are:
Feedback.xml
Legal_Notice.xml
the css
subdirectory, which contains:
overrides.css
the images
subdirectory, which contains 43 images in both raster (PNG) and vector (SVG) formats.
The publican.cfg
file in a brand serves a similar purpose to the publican.cfg
file in a document — it configures a number of basic options that define your brand.
version
specifies the version number for the brand. When you create the brand with $
publican create_brand, the version number is set to 0.1
. Update the version number here in the brand publican.cfg
file and in the publican-brand.spec
file when you prepare a new version of the brand.
Note that this parameter is unrelated to the version number of documents built with this brand. For example, the Fedora 12 Installation Guide has its version set as 12
in its publican.cfg
file, but might be built with version 1.0 of the publican-fedora brand.
xml_lang
specifies the language of the source XML files for the brand's Common Content, for example, en-US
, as set by the --lang
option for $
publican create_brand.
release
specifies the release number for the brand. When you create the brand with $
publican create_brand, the release number is set to 0
. Update the version number here in the brand publican.cfg
file and in the publican-brand.spec
file when you prepare a new release of an existing version of the brand.
type
when set to type: brand
, this parameter identifies the contents of this directory as a brand, rather than a book, article, or set.
brand
specifies the name of the brand, as set by the --name
option for $
publican create_brand.
web_cfg
the full path for the Publican site configuration file for non standard RPM websites.
web_dir
the full path to where files will be installed. You must also set wwwdir in publican-brand.spec
.
web_req
the name of the RPM package that will supply the Publican site config file.
Every document built in Publican has a publican.cfg
file in its root directory, which configures build options for the document. Refer to 1.1 – „Soubor publican.cfg“ for a full description of these options. The defaults.cfg
file and overrides.cfg
file in a brand supply default values for any of the parameters that you can otherwise set with a document's publican.cfg
file.
When you build a document with a particular brand, Publican first applies the values in the brand's defaults.cfg
file before it applies the values in the document's publican.cfg
file. Values in the document's publican.cfg
file therefore override those in the brand's defaults.cfg
file.
Publican next applies the values in the brand's overrides.cfg
file, which therefore override any values in the brand's defaults.cfg
file and the document's publican.cfg
file.
Use the defaults.cfg
file to set values that you routinely apply to your brand but want to allow writers to change in particular books; use the overrides.cfg
file for values that you do not want to allow writers to change.
You can add a list of banned tags or attributes using banned_tags and banned_attrs respectively to either defaults.cfg
or overrides.cfg
. These will be listed by the Publican action print_banned.
Some Linux operating systems use the RPM Package Manager to distribute software, in the form of RPM packages. In general terms, an RPM package contains software files compressed into an archive, accompanied by a spec file that tells the RPM Package Manager how and where to install those files.
When you create a brand, Publican generates the outline of an RPM spec file for the brand. The automatically generated spec file provides you with a starting point from which to create an RPM package to distribute your brand. Refer to 4 – „Packaging a brand“ to learn how to configure the spec file and use it to produce an RPM package.
The README
file contains a brief description of the brand package.
The COPYING
file contains details of the copyright license for the package and perhaps the text of the license itself.
Inside the brand directory is a subdirectory named after the default XML language for brand, as set with the --lang
option when you created the brand. This subdirectory contains XML and image files that override the default Common Content provided with Publican. Customizing these files provides your brand with its distinctive appearance, including its color scheme and logos.
Feedback.xml
The Feedback.xml
file is included by default in the preface of every book produced in Publican. It invites readers to leave feedback about the document. Customize this file with the contact details of your project. If your project uses a bug tracking system such as Bugzilla, JIRA, or Trac, you could include this information here.
Legal_Notice.xml
The Legal_Notice.xml
file contains the legal notice that appears at the beginning of every document produced by Publican. Insert the details of your chosen copyright license into this file. Typically, this might include the name of the license, a short summary of the license, and a link to the full details of the license.
css
subdirectory
The css
subdirectory contains a single file: overrides.css
.
The overrides.css
file sets the visual style for your brand. Values in this file override those in Publican's Common_Content/common/xml_lang/css/common.css
file.
images
subdirectory
The images
subdirectory contains 43 images in both portable network graphics (PNG) and scalable vector graphics (SVG) format. These images are placeholders for various navigation icons, admonition graphics, and brand logos. They include:
image_left
is a logo for the product to which this document applies. It appears at the top left corner of HTML pages, where it contains a hyperlink to a web page for the product, as defined by prod_url
in the publican.cfg
file for the document. Consider setting prod_url
in the brand's defaults.cfg
or overrides.cfg
file.
image_right
is a logo for the team that produced this documentation. It appears at the top right corner of HTML pages, where it contains a hyperlink to a web page for the documentation team, as defined by doc_url
in the publican.cfg
file for the document. If all the documentation for this brand is produced by the same team, consider setting doc_url
in the brand's defaults.cfg
or overrides.cfg
file.
title_logo
is a larger version of your product logo, which appears on the title page of PDF documents and at the start of HTML documents.
note
, important
, warning
are icons that accompany the XML admonitions <note>
, <important>
, and <warning>
.
dot
, dot2
are bullets used for <listitem>
s in <itemizedlist>
s.
stock-go-back
, stock-go-forward
, stock-go-up
, stock-home
are navigation icons for HTML pages.
h1-bg
is a background for the heading that contains the name of your product, as it appears at the very beginning of a HTML document.
watermark_draft
is a watermark that appears on pages of draft documentation. Refer to 10.2 – „Denoting draft documentation“.
The Publican build option brand_dir allows you to specify the location of brand files. These files do not have to be part of an installed brand.
You can ship custom XSL in a folder named xsl
in your brand: it sits at the same level as the various language files for your brand. Publican uses any XSL that it finds in that directory to override the XSL templates that we ship in the common brand (which in turn override the XSL templates that the DocBook project ships).
Brands with custom XSLT need to change the relative path of referencing XSL templates to a URI.
This section discusses packaging documents for distribution through the RPM Package Manager. However, when you use the $
publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
After you create a brand (as described in 2 – „Creating a brand“), Publican can help you to distribute the brand to members of your documentation project as RPM packages. RPM packages are used to distribute software to computers with Linux operating systems that use the RPM Package Manager. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
Publican can produce both source RPM packages (SRPM packages) and binary RPM packages. As part of this process, it also creates the spec file — the file that contains the details of how a package is configured and installed.
SRPM packages contain the source code used to generate software rather than the software itself. To use an SRPM package, a computer must compile the source code into software. SRPM packages of Publican brands contain the configuration files, XML files, and image files that define the brand in its original language, plus the PO files that generate the Common Content files in translated languages. You cannot install documentation directly from SRPM packages with current versions of the RPM Package Manager.
Conversely, binary RPM packages contain software — in this case, a Publican brand — that is ready to copy to a location in the computer's file system and use immediately. The contents of the binary RPM package do not need to be compiled by the computer onto which they are installed, and therefore, the computer does not need to have Publican installed.
To package a brand, use the $
publican package command in the brand directory. When used without any further options, Publican produces an SRPM package. The options for packaging a brand are as follows:
--binary
specifies that Publican should build the package as a binary RPM package.
--brew
specifies that Publican should push the completed package to Brew. Brew is the build system used internally by Red Hat; this option is meaningless outside Red Hat.
--scratch
when used together with the --brew
option, specifies that a SRPM package should be built as a scratch build when sent to Brew. Scratch builds are used to verify that a SRPM package is structured correctly, without updating the package database to use the resulting package.
The --lang
, --desktop
and --short_sighted
options that apply when you package books (described in 8 – „Packaging a document“) are meaningless when you package brands. In particular, note that although the --lang
option is mandatory when you package a book, you do not need to use it when you package a brand.
By default, Publican brand packages are named:
publican-brand-version-release.build_target.noarch.file_extension
.
Publican uses the information in the publican.cfg
file to supply the various parameters in the file name. Refer to 3.1 – „The publican.cfg file“ for details of configuring this file. Additionally:
SRPM packages have the file extension .src.rpm
but binary RPM packages have the file extension .rpm
binary RPM packages include build_target.noarch
before the file extension, where [build_target] represents the operating system and version that the package is built for as set by the os_ver
parameter in the publican.cfg
file. The noarch
element specifies that the package can be installed on any system, regardless of the system architecture.
A set is a collection of books, published as a single output. The Services Plan for example is a set comprised of many books such as the Developer Guide, Engineering Content Services Guide and the Engineering Operations Guide to name just a few. The $
create_book command creates a template for a set by setting the type
parameter to Set
.
There are two types of set:
stand-alone sets
distributed sets
A stand-alone set contains the XML files for each book, all of which are located inside the directory of the set. Stand-alone sets are always built as a set; you cannot build the individual books on their own without modification.
The procedure that follows will guide you through the process of creating a stand-alone set named My Set located in a directory called books/My_Set/
. The set will contain Book A and Book B both of which will be manually created inside the books/My_Set/en-US
directory.
Postup 6.1. Creating a stand-alone set
Run the following command in a shell in the books/
directory to create a set named My_Set
branded in the Red Hat style and in which the XML will be written in American English.
publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US
$
cd into the My_Set/en-US
directory and create two directories (not books) called Book_A
and Book_B
.
$
cdMy_Set/en-US
$
mkdirBook_A
Book_B
$
cd into the books/My_Set/en-US/Book_A
directory. Create and edit the Book_A.xml
, Book_Info.xml
, and any other xml files required for your book such as those required for individual chapters. Ensure that Book_A.xml
contains the correct xi:include
references to all of your xml files in the directory. For example, if Book A contained Book_Info.xml
and Chapter_1.xml
, the Book_A.xml
file would look like this:
<?xml version='1.0'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <book> <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> </book>
Use the same process for Book_B, located in the books/My_Set/en-US/Book_B
directory, as per the step above.
Open the books/My_Set/en-US/My_Set.xml
file in an editor. For each book in the set, add an xi:include
reference to the primary xml file from the book. The primary xml file for Book A will be Book_A.xml
and for Book B, Book_B.xml
. The My_Set.xml
file should now look like this:
<?xml version="1.0"?> <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <set> <xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </set>
To make your set XML valid, you will need to change the following:
In My_Set.xml
, comment out the following lines:
<remark>NOTE: the href does not contain a language! This is CORRECT!</remark> <remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark> <setindex></setindex>
In the Preface.xml
and Book_Info.xml
for each book you are using, add ../../ to the front of every Common_Content string you see. For example:
<xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
This will need to become:
<xi:include href="../../Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
This is because in a standalone set, the Common Content folder is two directories further away from where Publican usually looks for it, so it has to be told manually. To build your book individually, without building the entire set, undo this step.
Test your set by running the publican build --formats=test --langs=en-US command.
If you are using pre-existing books, you will need to rearrange them so the XML files are at the level of the set and all images are inside the images directory at the same level. For example:
-- My_Set |-- en-US | |-- Author_Group.xml | |-- Book_A.ent | |-- Book_A.xml | |-- Book_B.ent | |-- Book_B.xml | |-- Book_Info_A.xml | |-- Book_Info_B.xml | |-- chapter_A.xml | |-- chapter_B.xml | |-- images | | |-- icon.svg | | `-- image1.png | |-- My_Set.ent | |-- My_Set.xml | |-- Preface.xml | |-- Revision_History.xml | `-- Set_Info.xml `-- publican.cfg
The XML files can also be within sub-folders to keep them separate. This is true within the images directory, as well. For example:
-- My_Set |-- en-US | |-- Author_Group.xml | |-- Book_A | | |-- Book_A.ent | | |-- Book_A.xml | | |-- Book_Info.xml | | `-- chapter.xml | |-- Book_B | | |-- Book_B.ent | | |-- Book_B.xml | | |-- Book_Info.xml | | `-- chapter.xml | |-- images | | |-- icon.svg | | `-- image1.png | |-- My_Set.ent | |-- My_Set.xml | |-- Preface.xml | |-- Revision_History.xml | `-- Set_Info.xml `-- publican.cfg
A distributed set contains books that are located in a version-controlled repository. Although several version control systems exist, this version of Publican supports only one: Subversion (SVN). By setting the repository location and titles of the included books in the publican.cfg
file, each book can be exported to build the entire set. The procedure that follows will guide you through the process of creating a set named My Set containing Book A and Book B.
The following procedure assumes that Book A and Book B already exist and are available in your SVN repository. Currently Publican only supports SVN.
Postup 6.2. Creating a set
Run the following command in a shell to create a set named My_Set
branded in the Red Hat style and in which the XML will be written in American English.
$ publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US
Add the following lines to the publican.cfg
file:
books: Book_A Book_B repo: http://PATH-TO-YOUR-SVN-REPOSITORY scm: SVN
Your repository path should end in the directory before the book you need.
Open the My_Set.xml
file in an editor. For each book in the set, add an xi:include
reference to the primary XML file from the book. The primary XML file for Book A will be Book_A.xml
and for Book B, Book_B.xml
. The My_Set.xml
file should now look like this:
<?xml version="1.0"?> <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <set> <xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </set>
To make your set XML valid, you will need to comment out the following lines in My_Set.xml
<remark>NOTE: the href does not contain a language! This is CORRECT!</remark> <remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark> <setindex></setindex>
Test your set by running the publican build --formats=test --langs=en-US command.
When building a set, the publican clean_ids command will be run over each book because of the constraint that IDs must be unique across all books. Be careful of creating IDs that rely on content that may not be available when building books independently of the set.
Publican not only builds documents for publication but can build and manage a documentation website as well. For a suite of documents that you maintain by yourself, you can use Publican to build a site on your local system; you can then upload the site to a webserver by whatever means you choose. This approach does not scale well, however, so for team-based documentation projects, Publican can generate RPM packages of documentation to install on the webserver. To install Publican-generated RPM packages on a webserver, Publican (version 2.1 or higher) and rpm must be installed on the server. If you build and maintain the website on a workstation and upload it to a webserver for publication, Publican and rpm do not need to be installed on the webserver.
The websites that Publican creates consist of four parts: the website structure, a home page, product and version description pages, and the documents published on the site. The website structure itself consists of:
a configuration file.
an SQLite database file.
a subdirectory for the published documents, which contains:
index.html
— an index page that redirects to localized versions of a home page for the site.
interactive.css
— a CSS stylesheet that contains styles for the navigation menu.
opds.xml
— an Open Publication Distribution System (OPDS) catalog to allow compliant eBook readers to find EPUB documents on your site easily.
Sitemap
— A Sitemap is a list of the URLs from your website and metadata about them, like update history, change frequency, and importance relative to other URLs in the site. A Sitemap can be supplied to many major search engines, where it is used to help their crawlers index your site more intelligently. A Sitemap does not guarantee that your site will be ranked higher in search results. However, it does help search engines to return the most relevant results from your website in response to user queries. For more information on Sitemaps, visit sitemaps.org.
site_overrides.css
— a CSS stylesheet that overrides the styles contained in interactive.css
to provide site-specific styles. This file is not created by the site creation process, but must be added manually later, or supplied by the site home page.
default.js
— a JavaScript script that directs visitors to localized content based on the locale set in their browser and which controls the presentation of the navigation menu.
subdirectories for each language in which you publish. Initially, this contains opds.xml
and toc.html
. Later it also contains opds-product.xml
:
opds.xml
— an OPDS catalog of EPUB documents in this language.
opds-product.xml
— an OPDS catalog of EPUB documents for each product for which you publish documentation in this language. Within each product catalog, documentation is divided into <category>
s for different versions of the same product.
toc.html
— the table of contents for that language, initially without links to any documents.
A subdirectory for each product for which you publish documentation in this language.
Optionally, the site structure might also include a dump file — an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The site structure might also contain a zipped version of the dump file. Refer to 1.1 – „Creating the website structure“ and 1.1 – „Creating the website structure“ for details of creating a dump file, and to D – „Contents of the website dump file“ for a description of the dump file contents.
To build the website structure:
On your workstation, create a new directory and change into it. For example, on a Linux system, run:
$
mkdir ~/docsite$
cd ~/docsite
Run publican create_site, specifying the following parameters:
--site_config
— the name of the configuration file for your site, with the filename extension .cfg
--db_file
— the name of the SQLite database file for your site, with the filename extension .db
--toc_path
— the path to the directory in which you will place your documents
On a computer with an operating system other than Linux, also set:
--tmpl_path
— the path to the templates/
directory of your Publican installation. On computers with Windows operating systems, this is typically %SystemDrive%\%ProgramFiles%\Publican\templates
.
For example:
$
publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
You might give names to the site configuration file and database file that help you to recognize the site to which they belong. For example, for the FooMaster documentation site, you might call these files foomaster.cfg
and foomaster.db
. You can set --toc_path
to whatever you choose.
Edit the site configuration file to specify the name of the site, the web host, and optionally, search parameters, default language, dump file settings, and update settings for the site:
Specify the title with the title
parameter, for example:
title: "Foomaster Documentation"
Normally, visitors to your website do not see this title because the site's JavaScript redirects them to a homepage. However, this title is likely to be found and indexed by search engines.
Specify the web host with the host
parameter as a full URL, including the protocol (for example, http://
). For example:
host: http://docs.example.com
Publican uses the value set for host
to construct the URLs in the XML Sitemap
that it creates for search engine crawlers, and to limit searches submitted through the search box in the navigation menu to results on your site only.
Optionally, construct a search engine query to use with the search box in the navigation menu and specify the entire content of a HTML <form>
with the search
parameter. If you do not specify a custom web search, Publican creates a Google search limited to the host that you specified in the host
parameter.
For example, to construct a Yahoo! search limited to docs.example.com
, set:
search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'
Refer to the documentation of your chosen search engine for details of how to construct custom searches.
If you set value="###Search###"
in the code for a submit button, Publican uses the word Search
on the button, localized into any language that Publican supports.
Publican does not validate the search
parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.
Optionally, set the default language of the website. Publican creates a separate, translatable navigation menu for each language in which you publish documentation. However, if a document is not available in a particular language, Publican links visitors to the untranslated version of that document. To specify the default, untranslated language for the site, set def_lang
with a language code. For example:
def_lang: fr-FR
With def_lang
set to fr-FR
, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.
Optionally, configure a dump file for the website. Publican can output an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The file is updated whenever a book is installed or removed from the site, or the $
publican update_site command is run. Configure the dump
, dump_file
, and zip_dump
parameters as follows:
dump
Set dump: 1
to enable the dump file function. This parameter defaults to 0
(off).
dump_file
Set dump_file: name
to specify the name of the dump file and the directory in which Publican stores it. This parameter defaults to /var/www/html/DUMP.xml
.
zip_dump
Set zip_dump: 1
to specify that Publican should create a zipped version of the XML file together with the XML version. This parameter defaults to 0
(off).
Refer to D – „Contents of the website dump file“ for a description of the contents of the dump file.
Optionally, specify the web style with the web_style
.
The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)
The website includes a breadcrumb-like navigation bar across the top of the documentation.
The web style set for your site must match the web style set for your content. For example, if you set web_style: 2
for your website, you need to have web_style: 2
set in each of the books that you want to install on the site. Consider setting this parameter in the defaults.cfg
or overrides.cfg
files of the brands that you intend to use with this site.
Optionally, specify that the site tables of contents will be updated manually with the manual_toc_update
parameter, for example:
manual_toc_update: 1
Normally, Publican updates the site's tables of contents every time a documentation package is added or removed. On a site with a large number of documents on it (more than a few hundred), or where documents are updated very frequently (dozens of updates per week), this process is very demanding on a server. On a large or busy site, we recommend that you set this parameter and then periodically update the tables of contents with the $
publican update_site command.
Optionally, override the default JavaScript for the site with the toc_js
parameter, for example:
toc_js: "mybrand/scripts/megafoo.js"
This file will be symlinked as toc_path
/toc.js with the $
publican update_site command. This path should be relative to the toc_path
parameter.
Create an empty file named site_overrides.css
in the directory that you specified with doc_path
(the directory that contains interactive.css
and the various language directories). If you want to use site-specific styles to override those provided by interactive.css
, you can add a site_overrides.css
to the document that provides the site home page — refer to 1.2 – „Creating, installing, and updating the home page“. If you do not want to use site-specific styles, the empty file you add here will prevent 404 errors on your server. On a Linux system, change into the directory that you specified with doc_path
and run:
$
touch site_overrides.css
Build and install each brand, including the Publican common
brand.
Change into the directory that holds the source for the brand.
$
cd brandsrc_dir
Build the brand.
$
publican build --formats=xml --langs=all --publish
Install the brand on your website.
$
publican install_brand --web --path=path_to_site_root_dir
Perform these steps for all brands.
Update the site.
$
publican update_site
To make Publican refresh the site structure at any time, run:
$
publican update_site --site_config path_to_site_configuration_file.cfg
The Publican-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook <article>
with an extra web_type: home
parameter in its publican.cfg
file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican. To create the home page:
Change into a convenient directory and run the following $
publican create command:
$
publican create --type Article --name page_name
For example:
$
publican create --type Article --name Home_Page
Most brands (including the common
brand) present the name of the document in large, coloured letters close to the top of the page, underneath the banner that contains the product name (the --name
option sets the <title>
tag). Therefore, by default, the value that you set with the --name
option is presented prominently to visitors to your site; in the above example, visitors are greeted with the words Home Page
underneath the product banner.
Change into the article directory:
$
cd page_name
For example:
$
cd Home_Page
Unlink the Article_Info.xml
file from your root XML file.
Little of the content of the Article_Info.xml
file is likely to be useful for the home page of your website. Therefore, edit the root XML file of your home page to remove the <xi:include>
tag that links to Article_Info.xml
. Publican still uses the information in Article_Info.xml
for packaging, but does not include it on the page itself.
Edit the publican.cfg
file.
At the very least, you must add the web_type
parameter and set it to home
:
web_type: home
The web_type: home
parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg
file. Other optional changes to the publican.cfg
file that are frequently useful for Publican-generated websites include:
brand
To style your home page to match your documents, add:
brand: name_of_brand
docname
, product
If the <title>
or the <product>
that you set in the Article_Info
file included anything other than basic, unaccented Latin characters, set the docname
and product
as necessary.
Edit the content of the page_name.xml
file (for example, Home_Page.xml
) as you would any other DocBook document.
If you remove the <xi:include>
that links to Article_Info.xml
, specify a title for your page in the following format:
<title role="producttitle">FooMaster Documentation</title>
If you publish documentation in more than one language, create a set of POT files and a set of PO files for each language with the $
publican update_pot and publican update_po commands.
To customize the logo at the top of the navigation menu that provides a link back to the home page, create a PNG image 290 px × 100 px and name it web_logo.png
. Place this image in the images/
directory in the document's XML directory, for example en-US/images/
.
To specify site-specific styles to override the styles set in the website's interactive.css
file, add styles to a file named site_overrides.css
and place it in the root of your document source (the same directory that contains publican.cfg
and the language directories).
Build the home page in single-page HTML format with the --embedtoc
option and install it in your website structure. For example:
$
publican build --publish --formats html-single --embedtoc --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Language_Code
Note that you can build all languages at the same time, but must install the home page for each language with a separate $
publican install_book command.
Publican-generated product pages and version pages are the localizable pages that provide a general overview of a product or version respectively. Visitors access these pages by clicking on a product or version in the navigation menu. The pages are structured as DocBook <article>
s with an extra web_type: product
or web_type: version
parameter in their publican.cfg
files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican. To create a product page or version page:
Change into a convenient directory and run the following $
publican create command:
$
publican create --type Article --name page_name
For example, a product page might be:
$
publican create --type Article --name FooMaster
or a version page might be:
$
publican create --type Article --name FooMaster_3
Change into the article directory:
$
cd page_name
For example:
$
cd FooMaster
Unlink the Article_Info.xml
file from your root XML file.
Little of the content of the Article_Info.xml
file is likely to be useful for product pages or version pages. Therefore, edit the root XML file of your page to remove the <xi:include>
tag that links to Article_Info.xml
. Publican still uses the information in Article_Info.xml
for packaging, but does not include it on the page itself.
Edit the publican.cfg
file.
At the very least, you must add the web_type
parameter and set it to product
or version
:
web_type: product
or
web_type: version
The web_type
parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg
file. Other optional changes to the publican.cfg
file that are frequently useful for product pages or version pages include:
brand
To style your home page to match your documents, add:
brand: name_of_brand
docname
, product
If the <title>
or the <product>
that you set in the Article_Info
file included anything other than basic, unaccented Latin characters, set the docname
and product
as necessary.
Edit the content of the page_name.xml
file (for example, FooMaster.xml
) as you would any other DocBook document.
If you remove the <xi:include>
that links to Article_Info.xml
, specify a title for your page in the following format:
<title role="producttitle">FooMaster Documentation</title>
If you publish documentation in more than one language, create a set of POT files and a set of PO files for each language with the $
publican update_pot and publican update_po commands.
Build the product page or version page in single-page HTML format with the --embedtoc
option and install it in your website structure. For example:
$
publican build --publish --formats html-single --embedtoc --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Language_Code
Note that you can build all languages at the same time, but must install the product page or version page for each language with a separate $
publican install_book command.
To install a document on a website that you are building manually, change into the directory that contains the source for the document and run:
$
publican build --embedtoc --formats=list_of_formats --langs=language_codes --publish$
publican install_book --site_config path_to_site_configuration_file.cfg --lang language_code
Note that you can run a single $
publican build command for all languages that you want to publish, but must run a separate publican install_book for each language. You must include html
as one of the formats in the publican build command; optionally, include any or all of the following formats in a comma-separated list: html-single
, pdf
, and epub
.
To update a document, change into the directory that contains the updated source for the document and run the same commands as if you were installing the document for the first time. Publican replaces the old version with the new version.
To remove a document, change into the directory that contains the source for the document and run:
$
publican remove_book --site_config path_to_site_configuration_file.cfg --lang language_code
When you have installed the documents, the website is ready to upload to your webserver by whatever process you usually use, for example scp, rsync, or an FTP client.
When you create the website structure, Publican places files in the /var/www/html/docs
directory. Existing files in this directory might be overwritten by this procedure.
Perform the following steps on your webserver.
Log into the webserver.
Install Publican and its web components package. For example, on a webserver with a Fedora operating system, run:
$
sudo yum install publican publican-common-web
With root privileges, edit the /etc/publican-website.cfg
file to specify the name of the site, the web host, and optionally, search parameters, default language, dump file settings, and web style for the site:
Specify the title with the title
parameter, for example:
title: "Foomaster Documentation"
Normally, visitors to your website do not see this title because the site's JavaScript redirects them to a homepage. However, this title is likely to be found and indexed by search engines.
Specify the web host with the host
parameter as a full URL, including the protocol (for example, http://
). For example:
host: http://docs.example.com
Publican uses the value set for host
to construct the URLs in the XML Sitemap
that it creates for search engine crawlers, and to limit searches submitted through the search box in the navigation menu to results on your site only.
Optionally, construct a search engine query to use with the search box in the navigation menu and specify the entire content of a HTML <form>
with the search
parameter. If you do not specify a custom web search, Publican creates a Google search limited to the host that you specified in the host
parameter.
For example, to construct a Yahoo! search limited to docs.example.com
, set:
search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'
Refer to the documentation of your chosen search engine for details of how to construct custom searches.
If you set value="###Search###"
in the code for a submit button, Publican uses the word Search
on the button, localized into any language that Publican supports.
Publican does not validate the search
parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.
Optionally, set the default language of the website. Publican creates a separate, translatable navigation menu for each language in which you publish documentation. However, if a document is not available in a particular language, Publican links visitors to the untranslated version of that document. To specify the default, untranslated language for the site, set def_lang
with a language code. For example:
def_lang: fr-FR
With def_lang
set to fr-FR
, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.
Optionally, configure a dump file for the website. Publican can output an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The file is updated whenever a book is installed or removed from the site, or the $
publican update_site command is run. Configure the dump
, dump_file
, and zip_dump
parameters as follows:
dump
Set dump: 1
to enable the dump file function. This parameter defaults to 0
(off).
dump_file
Set dump_file: name
to specify the name of the dump file and the directory in which Publican stores it. This parameter defaults to /var/www/html/DUMP.xml
.
zip_dump
Set zip_dump: 1
to specify that Publican should create a zipped version of the XML file together with the XML version. This parameter defaults to 0
(off).
Refer to D – „Contents of the website dump file“ for a description of the contents of the dump file.
Optionally, specify the web style with the web_style
.
The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)
The website includes a breadcrumb-like navigation bar across the top of the documentation.
The web style set for your site must match the web style set for your content. For example, if you set web_style: 2
for your website, you need to have web_style: 2
set in each of the books that you want to install on the site. Consider setting this parameter in the defaults.cfg
or overrides.cfg
files of the brands that you intend to use with this site.
Optionally, specify that the site tables of contents will be updated manually with the manual_toc_update
parameter, for example:
manual_toc_update: 1
Normally, Publican updates the site's tables of contents every time a documentation package is added or removed. On a site with a large number of documents on it (more than a few hundred), or where documents are updated very frequently (dozens of updates per week), this process is very demanding on a server. On a large or busy site, we recommend that you set this parameter and then periodically update the tables of contents with the $
publican update_site command.
Optionally, override the default JavaScript for the site with the toc_js
parameter, for example:
toc_js: "mybrand/scripts/megafoo.js"
This file will be symlinked as toc_path
/toc.js with the $
publican update_site command. This path should be relative to the toc_path
parameter.
Create an empty file named site_overrides.css
. If you want to use site-specific styles to override those provided by interactive.css
, you can add a site_overrides.css
to the document that provides the site home page — refer to 1.2 – „Creating, installing, and updating the home page“. If you do not want to use site-specific styles, the empty file you add here will prevent 404 errors on your server. On a Linux system, run:
#
touch /var/www/html/docs/site_overrides.css
To make Publican refresh the site structure at any time, run:
$
publican update_site
The Publican-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook <article>
with an extra web_type: home
parameter in its publican.cfg
file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican and is packaged the same way.
On a workstation, create a home page using the procedure described in 1.2 – „Creating, installing, and updating the home page“.
In the directory in which you created the home page, run:
$
publican package --binary
Publican builds an RPM package and places it in the /tmp/rpms/noarch/
directory of the home page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver
parameter in the home page's publican.cfg
file.
Either upload the home page package to the webserver and install it with the rpm -i or yum localinstall command, or place the package in a repository and configure the webserver to install from that repository when you run yum install.
To update the home page, build a new package with a higher <edition>
number or <pubsnumber>
in the Article_Info.xml
. Publican uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, yum can replace the old version with the new when you run yum localinstall for a local package, or yum update for a package fetched from a repository.
Publican-generated product pages and version pages are the localizable pages that provide a general overview of a product or version respectively. Visitors access these pages by clicking on a product or version in the navigation menu. The pages are structured as DocBook <article>
s with an extra web_type: product
or web_type: version
parameter in their publican.cfg
files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican and are packaged the same way.
On a workstation, create a product or version page using the procedure described in 1.3 – „Creating, installing, and updating product pages and version pages“.
In the directory in which you created the product page or version page, run:
$
publican package --binary
Publican builds an RPM package and places it in the /tmp/rpms/noarch/
directory of the product page or version page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver
parameter in the publican.cfg
file of the product page or version page.
Either upload the package to the webserver and install it with the rpm -i or yum localinstall command, or place the package in a repository and configure the webserver to install from that repository when you run yum install.
To update the product page or version page, build a new package with a higher <edition>
number or <pubsnumber>
in the Article_Info.xml
. Publican uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, yum can replace the old version with the new when you run yum localinstall for a local package, or yum update for a package fetched from a repository.
On your workstation, change into the directory that contains the source for the document and run:
$
publican package --binary --lang language_code
Publican builds an RPM package and places it in the /tmp/rpms/noarch/
directory of the document. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver
parameter in the document's publican.cfg
file.
Either upload the document packages to the webserver and install them with the rpm -i or yum localinstall command, or place the packages in a repository and configure the webserver to install from that repository when you run yum install.
To update a document, build a new package with a higher <edition>
number or <pubsnumber>
in the Book_Info.xml
or Article_Info.xml
. Publican uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, yum can replace the old version with the new when you run yum localinstall for a local package, or yum update for a package fetched from a repository.
Remove a document from the webserver with the rpm -e or yum erase command.
On large or busy sites, we recommend that you set the manual_toc_update
parameter in the site's configuration file. With this parameter set, you must run the $
publican update_site command after installing, updating, or removing documents. Refer to 1.1 – „Creating the website structure“ for more information.
A Publican website includes an XML Sitemap file. The Sitemap can be submitted to many major search engines, in order to help them index your website more intelligently and thoroughly. Each search engine has its own submission procedure. This section includes documentation on how to submit a Sitemap to Google and Bing.
Postup 7.1. To Submit Your Sitemap to Google:
Sign up for a Google account at Google Webmaster Tools. If you already have a Google account, you can use it.
Sign in to your Google Webmaster Tools account at this URL: http://www.google.com/webmasters/tools/home.
First you must verify you are the owner of your Publican site. Click the
button.A dialog box is displayed for you to Add a site with. Enter the URL of your Publican site in the text entry field and click .
Follow the instructions that display and upload the HTML file that Google provides to the document root of your website.
When you have confirmed that the provided HTML file has been uploaded to the required location by accessing it in a web browser, click the
button.When you have successfully verified the ownership of your Publican website to Google, return to the Webmaster Tools home page. Your Publican site is listed. Click on it.
You are taken to the Webmaster Tools configuration page for your Publican site. On the left side of the page there is a menu. Click on the Site configuration menu entry to expand it. Its expanded contents includes a Sitemaps entry. Click it.
You are taken to a Sitemap submission page. Click the
button.A text entry field displays, including the base URL of your Publican site, with room to enter the URL of your Sitemap XML file. Enter its location and click the
button. The details of the Sitemap are displayed in a table.Result. The Sitemap for your Publican site has been successfully submitted to Google.
Postup 7.2. To Submit Your Sitemap to Bing:
Sign up for a Bing Webmaster Tools account at Bing Webmaster Tools. If you already have a Windows LiveID account, you can use it.
Sign in to your Bing Webmaster Tools account at this URL: http://www.bing.com/toolbox/webmaster/.
Click the
button.The Add Site dialog box is displayed. Enter the URL of your Publican site in the text entry field and click .
The Verify Ownership dialog displays, with three options. Follow the instructions given when the Option 1: Place an XML file on your web server has been expanded. Upload the BingSiteAuth.xml
file that Bing provides to the document root of your website.
When you have confirmed that the provided BingSiteAuth.xml
file has been uploaded to the required location by accessing it in a web browser, click the button.
When you have successfully verified your ownership of your Publican website to Bing, return to the Bing Webmaster Tools home page. Your Publican site is listed. Click on it.
Select the
tab.Select Sitemaps and then Add Feed.
The Add Feed dialog displays. Enter the URL of your Sitemap file and click . The details of the Sitemap are displayed.
Result: The Sitemap for your Publican site has been successfully submitted to Bing.
Publican 3.1 has a new functionality which allow user to create and import a book into Drupal. All xml files in a book are transformed into a single CSV file which will later be used to import into Drupal.
The CSV File consists of information that tells Drupal how to import the book. Each row in the CSV file represents a html page.
Use the $
publican build command to create the CSV file for Drupal import. Before running the command, use the cd command to change into the directory where your book is located. For example, if you have a book call "User_Guide" in your home directory, then run the following command.
$
cd User_Guide/$
publican build --langs en-US --formats=drupal-book
After running the command, you will see CSV file is created in the tmp/en-US/drupal-book/
directory.
Publican stores all the output files in /tmp/en-US/drupal-book/
directory. This directory contains the following files:
CSV file - The naming convention of the file is $product-$version-$docname-$lang-$edition.csv
en-US directory - contains all the html images.
tar.gz file - the archive of both CSV file and en-US directory.
After running the $
publican build --langs en-US --formats=drupal-book command, you will notice that the xml files in the en-US
directory had been changed. This is because Publican added a 'Conformance'
attribute for every xml tag that has id. This attribute contains a number which is unique across xml files in the book. If you are using a version control system like git for your xml files, then you need to commit the changes so that the number won't get reset when other users run it. These unique numbers are very important, because they are use as the url path in drupal. Besides, Publican also created a database file name max_unique_id.db
in the en-US
directory. This database file is use to track the current maximum unique number in the book, so that Publican can know where you are up to and add a new unique number for your newly created Chapter or Section. Therefore, it is very important to add the database file to the version control and commit it if there is any change. If you add a new section in the xml, don't set the 'Comformance'
attribute yourself as that will make the database outdated. Just leave it for publican to set it.
Below are some parameters that can be configure in the publican.cfg file for Drupal import:
drupal_author
specfies the author who should be shown in drupal book page. The name must be a valid Drupal username. 'Redhat' is the default author. Set this parameter in the publican.cfg
file to override it.
The author must have permission to manage (create, update, delete) nodes in Drupal. If the default author is used, make sure you had created an account with username 'Redhat' in Drupal.
drupal_menu_title
override the bookname that will be shown in the Drupal menu. If nothing is set, publican will use the default value which is "$product $version $docname". For example, Publican 3.1 User_Guide.
drupal_menu_block
specfies which menu block the book should show in Drupal. The default value is "user-guide"
.
The menu block must exist in Drupal. For more information about adding a menu block in Drupal. Please refer to 3.1 – „How to add a menu block“.
drupal_image_path
specfies the directory where the images should be stored in drupal server. The default value is "sites/default/files/"
.
Before you can import a book, you need to install a module call 'Node Import' in Drupal. This module allows Drupal to import and update content from CSV or TSV files. To install this module, simply go to drupal site and follow the instructions on the website to download it. Once this is done, then you need to copy the downloaded module to the 'modules' directory on the Drupal server. For example if your Drupal is located in /var/www/html/drupal/
directory, then you should copy the module to /var/www/html/drupal/sites/all/modules/
directory. To enable the installed module, login to the Drupal site and go to Administer -> Site building -> Modules . In the Development section, tick the and click button to activate the Node Import Module.
You also need to enable the following Drupal core modules:
Book
Menu
Path
Please consult your web adminstrator if you don't have permission to install module in drupal.
Import directory - Where the CSV files to be imported are stored. The default path is sites/default/files/imports/
.
FTP settings
Allow FTP uploads - Make sure the checkbox is checked, so that the new CSV file can be auto-detected when it is uploaded into the import directory
.
File owner - The CSV file that you uploaded to the import directory
will be assigned ownership to this user.
Users will only be allowed to use files they have uploaded themselves and files owned by anonymous. If you leave this field blank, all files uploaded by FTP will be owned by anonymous and so all users will see those files as being available for them. If you enter a username here, files that are uploaded using FTP will be owned by that user and only that user will be able to see those uploaded files. It is recommended to leave this field blank.
Allowed extensions - The allowed import file's extension. Other extensions will be ignore by the module.
Default settings
Content type - The default content type that will be used for quick import. Make sure the Book Page content type
is checked.
First row contains column names - This tells the node import module that the first row of the csv file is the headers.
To import book into Drupal:
Follow the steps in 1 – „How to build a CSV file for Drupal import“
Upload the CSV file to import Directory
in the Drupal Server
Upload en-US
directory to the "sites/default/files/"
directory in the Drupal server. This value can be overriden in the publican.cfg
. For more details, please read 2 – „The publican.cfg file“
Login to the Drupal website, and go to Administer -> Content management -> Import content. You will see the CSV file that you just uploaded is showing in the 'Pending Tasks" table and it is ready to import.
Click
to start importing book. You will be redirect to the next page which is showing the import progress. When the progress bar hit 100%, that means the import is done!The book link should be showing in the specified menu block now.
Simply repeat the steps in 3.3 – „How to import book“ to update the book.
If you update the book with smaller chunks, than the missing chunks will be deleted by Drupal and the URL path for the deleted chunks will be deleted as well.
How do I add a language to my book?
Run $
publican update_po --langs=language, where language is the code for the new language that you want to add. You can add more than one language at a time, with the language codes separated by commas. For example, publican update_po --langs=ja-JP creates the Japanese language directory and Japanese PO files, and publican update_po --langs=ja-JP,ko-KR creates directories and PO files for both Japanese and Korean.
What if I do not want to use the country code? For example, can I run $
publican update_po --langs=es,de,fr?
Yes — this command works. However, if you omit the country code, the output might be unpredictable when Publican or a brand has definitions for more than one regional variety of a language — for example, zh-CN
(Simplified Chinese as used in the People's Republic of China) and zh-TW
(Traditional Chinese as used in the Republic of China, on Taiwan). Even when only one variety is currently defined, it is always safest to include the country code so that, for example, a future update of Publican does not suddenly cause your German (de-DE
) documents to switch to Schweizerdeutsch (Swiss German, de-CH
) Common Content and headings.
How do I update all po files?
Run the $
publican update_po --langs=all command.
Where can I get a complete list of Publican's build options?
Run the $
publican build --help command.
Where can I get a complete list of parameters that can be set in the publican.cfg
?
Run the $
publican help_config command in a directory that holds any Publican document.
Where are the Publican common files located?
By default, they are in /usr/share/publican/
on Linux operating systems and in %SystemDrive%/%ProgramFiles%/publican/Common_Content
on Windows operating systems — typically, C:/Program Files/publican/Common_Content
.
Is it possible to include arbitrary files in tarballs and RPM packages?
Yes. If you make a directory named files
in your source language directory it will be included in any tarballs or SRPM packages that Publican creates.
The files
directory will not be available during the validation process so you can not xi:include
or otherwise embed any files in this directory in your XML.
Why does Publican give me warnings about unknown tags?
This warning informs you that you are using a tag whose output has not been tested for attractiveness, XHTML 1.0 Strict compliance, or Section 508 (Accessibility) compliance.
I can build HTML documents fine, but when I try to build PDF documents, I get errors like java.lang.NullPointerException
and no PDF file is produced. What is wrong?
Try building a PDF version of a different document — perhaps a fresh one that you create with the $
publican create command. If the problem is not just with one particular document, you probably have a mismatch between the Java Runtime Environment (JRE) and the Java Development Kit (JDK) in use on your system. If you have a JDK installed, FOP requires that the JDK is of the same version as the JRE. Furthermore, FOP cannot use the GNU Compiler for Java (GCJ).
Run alternatives --config java and alternatives --config javac to determine which JRE and JDK are in use, then select versions that match and which do not have gcj
in their name. For example, the following Java configuration shows a matching JRE and JDK that allow PDFs to build:
$
alternatives --config java
There are 3 programs which provide 'java'.
Selection Command
-----------------------------------------------
1 /usr/lib/jvm/jre-1.5.0-gcj/bin/java
* 2 /usr/lib/jvm/jre-1.6.0-openjdk/bin/java
+ 3 /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/java
Enter to keep the current selection[+], or type selection number:
$
alternatives --config javac
There are 3 programs which provide 'javac'.
Selection Command
-----------------------------------------------
*+ 1 /usr/lib/jvm/java-1.6.0-openjdk.x86_64/bin/javac
2 /usr/lib/jvm/java-1.6.0-openjdk/bin/javac
3 /usr/lib/jvm/java-1.5.0-gcj/bin/javac
Enter to keep the current selection[+], or type selection number:
You might need to install an extra JDK if you do not have a JDK on your system that matches any of the JREs.
Some Java installations do not set up the alternatives environment correctly. No fix has been determined for this situation.
I get an error saying Batik is not in the classpath but Batik is installed! What is wrong?
We believe this is due to classpath issues caused by having different JRE and JDK versions in use. Refer to the previous question in this FAQ about java.lang.NullPointerException
errors and using the alternatives command to ensure that the JRE and JDK match.
I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
when trying to build PDF. What is wrong?
The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to FOP. Before running $
publican build run echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc. This sets the initial heap space to 50 MB and allows it to grow to a maximum of 700 MB.
Previous versions of Publican removed empty <para>
tags. Does Publican still do this?
No. Publican previously removed empty <para>
tags while it transformed XML because empty <para>
tags broke earlier translation toolchains used within Red Hat and the Fedora Project. Empty <para>
tags are valid DocBook XML, and Publican no longer removes them.
What happened to the spell check?
Early versions of Publican (up to and including 0.45) ran a spell check while transforming a document's XML. Due to negative feedback from users, this feature was dropped.
Run the following bash script in the root directory of your document to check spellings in your XML files with the aspell command-line spell checker.
#!/bin/sh # Jeff Fearn 2010 ASPELL_EXCLUDES=programlisting,userinput,screen,filename,command,computeroutput,abbrev,accel,orgname,surname,foreignphrase,acronym,hardware for file in `find en-US -wholename '*/extras/*' -prune -o -name \*.xml -print`; do echo "Processing $file"; aspell --list --lang=en-US --mode=sgml --add-sgml-skip={$ASPELL_EXCLUDES} < $file | sort -u; echo; done
Why don't <segmentedlist>
s work when I build PDFs?
Check the number of columns in your <segmentedlist>
s. When <segmentedlist>
s are formatted as tables, the DocBook XSL limits the number of columns to two, and Publican formats <segmentedlist>
s as tables.
What happened to the colors in my images in this PDF?
This is the result of a bug in FOP that distorts colors in 24-bit PNG images. Convert your images to 32-bit PNG images to work around the problem.
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
Code highlighting in Publican is generated with the Syntax::Highlight::Engine::Kate Perl module. If you specify a language in a <programlisting>
tag that Syntax::Highlight::Engine::Kate does not recognize, you receive an error when you build your book. The first lines of the error message are similar to:
undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pm
line 615.
cannot create plugin for language 'JAVA'
Note that Syntax::Highlight::Engine::Kate is very strict about names of languages and is case sensitive. Therefore, <programlisting language="Java">
works, but <programlisting language="java">
and <programlisting language="JAVA">
do not. The error message that you receive identifies the problematic language attribute.
Refer to http://search.cpan.org/dist/Syntax-Highlight-Engine-Kate/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS for the full list of languages that Syntax::Highlight::Engine::Kate supports, including their expected capitalization and punctuation.
How do I enable bash command-line completion for Publican?
Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:
Install the package or packages that provide bash completion for your operating system. For example, on Fedora, run sudo yum install bash-completion.
Add the following to your ~/.bashrc
file:
# Use bash-completion, if available if [ -f /etc/bash_completion ]; then . /etc/bash_completion fi
Restart your terminal or run source ~/.bashrc.
Why am I having trouble building my large book?
Probably because the kernel can deal with only a certain number of file handles at a time, and you have exceeded that number. On some linuxes you can run ulimit -n 8192 to change the limit for the current shell.
To make this permanent, open /etc/security/limits.conf
and add these two lines:
* soft nofile 8192 * hard nofile 8192
Then save, and log in again for the changes to take effect.
Why does Jeff call Isaac ‘Ivan’?
Because Jeff's memory is pants!
Not every element (tag) and attribute that works with Publican is supported. Specifically, not every tag has been tested with regards its effect on the presentation of a document once it has been built in HTML or PDF.
Publican works with almost all DocBook elements and their attributes, and most of these elements are supported. Supported elements and attributes are those whose presentation in Publican HTML and PDF output has been tested and is of an acceptable quality.
Other elements and attributes that are not known to be harmful or redundant but which have not been tested for quality are unsupported. If material within a particular DocBook tag does not look correct when you build a document in HTML or PDF, the problem could be that the transformation logic for that tag has not yet been tested. Build the document again and examine Publican's output as the document builds. Publican presents warnings about unsupported tags that it encounters in your XML files.
Finally, a small group of elements and attributes are discouraged. These elements and attributes are set out below, each accompanied by rationale explaining why it is discouraged.
Use the command $
publican print_known to print a list of tags that Publican supports, and the command publican print_banned to print a list of tags that are banned in Publican.
<glossdiv>
This tag set presents terms in glossaries in alphabetical order; however, the terms are sorted according to the original language of the XML, regardless of how these terms are translated into any other language. For example, a glossary produced with <glossdiv>
s that looks like this in English:
Apple
— an apple is…
Grapes
— grapes are…
Orange
— an orange is…
Peach
— a peach is…
looks like this in Spanish:
Manzana
— la manzana es…
Uva
— la uva es…
Naranja
— la naranja es…
Melocotonero
— el melocotonero es…
In a translated language that does not share the same writing system with the original language in which the XML was written, the result is even more nonsensical.
<inlinegraphic>
This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This tag therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this tag will not satisfy those requirements. Section 508 of the Rehabilitation Act of 1973[4] is an example of such a requirement for federal agencies in the United States.
Note that <inlinegraphic>
is not valid in DocBook version 5.
<olink>
The <olink>
tag provides cross-references between XML documents. For <olink>
s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <olink>
s, these URLs can be supplied either as an XML entity or with a server-side script. Publican does not provide any way to build or use a database for these links.
<[element] xreflabel="[any_string_here]">
The presence of an <xreflabel>
attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.
For example, if you have the following:
<chapter id="ch03" xreflabel="Chapter Three"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
when your XML is built to HTML, the <xref>
tag becomes an HTML anchor tag as follows:
…see <a href="#ch03">Chapter Three</a> for details.
The text contained by the anchor tag is the same as the data in the <xreflabel>
attribute. In this case, it means that readers of printed copies have less information available to them.
You could work around this if you make the value of the <xreflabel>
attribute the same as the text within the <title>
</title>
element tags. However, this duplication increases the risk of typo-level errors and otherwise offers no underlying improvement. And it still reduces the amount of information presented to readers of printed copies.
The following XML:
<chapter id="ch03" xreflabel="The Secret to Eternal Life"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see >xref linkend="ch03"> for details.
Will result in an HTML anchor tag as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
This isn't as informative as the text presented to a reader if you do not use an <xreflabel>
attribute. The following:
<chapter id="ch03"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
transforms the <xref>
element as follows when built to HTML:
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
More important, however, are the translation problems that <xreflabel>
tags cause. Attribute values are not seen by translators. Consequently, they are not translated. Consider the second example above again:
<chapter id="ch03" xreflabel="The Secret to Eternal Life"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
In English, the <xref>
is still transformed into an anchor tag as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
Someone reading the German version, however, will have this as their underlying HTML:
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
If the <xreflabel>
attribute is not used, the title and chapter indicator, both properly translated, appear to the reader. That is, the following:
<chapter id="ch03"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
will, after translation, present thus to a German-speaking reader:
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
This is, not surprisingly, what we want.
The xreflabel
attribute is therefore discouraged.
<[element] endterm="[any_string_here]">
The endterm
attribute allows you to present hyperlinked text other than the name of the section or chapter to which the hyperlink points. As such, it decreases the usability of printed versions of documents, and causes difficulty for translators.
The text presented in an element (such as an <xref>
) that contains the endterm
attribute is taken from a <titleabbrev>
tag in the target chapter or section. Although the content of the <titleabbrev>
tag is available to translators in the document's PO files, it is removed from the context of the <xref>
. The absence of this context makes reliable translation impossible in languages that mark prepositions or articles for grammatical number and grammatical gender.
For example, if you have the following:
<chapter id="The_Secret"> <title>The Secret to Eternal Life</title> <titleabbrev id="final">the final chapter</titleabbrev> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] The solution is in <xref linkend="The_Secret" endterm="final"/>.
The text surrounding the <xref>
presents in the English version of the document as:
The solution is in
the final chapter
.
A translator sees the <titleabbrev>
in a PO file as:
#. Tag: titleabbrev #, no-c-format msgid "the final chapter" msgstr ""
and sees the text that contains the <xref>
elsewhere in the PO file (or, more likely, in a completely different PO file) as:
#. Tag: para #, no-c-format msgid "The solution is in <xref linkend=\"The_Secret\" endterm=\"final\"/>." msgstr ""
The translator has no way of telling what will be substituted for <xref linkend="The_Secret" endterm="final"/>
when the document builds, so a translation in Italian might read:
#. Tag: para #, no-c-format msgid "The solution is in <xref linkend=\"The_Secret\" endterm=\"final\"/>." msgstr "La soluzione è in <xref linkend=\"The_Secret\" endterm=\"final\"/>."
Note the preposition in
.
If the translator rendered the final chapter
in Italian as l'ultimo capitolo
, the result when the document builds will read:
La soluzione è in
l'ultimo capitolo
.
This result is comprehensible, but inelegant, because Italian combines some of its prepositions with its definite articles. More elegant Italian would be:
La soluzione è nell'
ultimo capitolo
.
Without knowing what text will appear in place of <xref linkend="The_Secret" endterm="final"/>, the translator into Italian cannot know whether to leave the preposition in
to stand by itself, or which of seven different possible combinations with the definite article to use: nel
, nei
, nello
, nell'
, negli
, nella
, or nelle
.
Furthermore, note that the combined preposition and article also poses a problem with regard to whether this word should be placed in the text surrounding the <xref>
, or in the <titleabbrev>
. Whichever of these two solutions the translator selects will cause problems when the endterm
appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.
Due to the problems that endterm
presents for translation, Publican discourages this attribute.
Allow the XML and XSLT processing to access the network. Defaults off.
Directory to source brand files from.
Override path to Common_Config directory
Override path to Common_Content directory
Use a nonstandard config file
Display help message
Disable ANSI colourisation of logging.
Disable all logging.
$
publican add_revisionAdd an entry to the revision history
Date to use for a revision.
email to use for a revision.
firstname to use for a revision.
The language the XML will be written in
An entry to be added to the revision. Can be specified multiple times.
Revision number to use for a revision.
surname to use for a revision.
$
publican buildTransform XML to other formats (pdf, html, html-single, drupal-book, etc)
This flag tells publican the data being processed is a distributed set. Note: do not use distributed_set on the command line. Publican uses this flag when calling itself to process distributed sets. This is the only safe way this flag can be used.
Embed the web site TOC object in the generated HTML
Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub
Comma-separated list of languages, for example: en-US,de-DE,all
Do not run the DTD validation
Override the tool to use when creating PDFs. Valid options are wkhtmltopdf and fop.
Directory to publish files to. Defaults to publish.
Set up built content for publishing
Show fuzzy translation entries in output. Defaults off.
Directory to source publican files from.
$
publican cleanRemove all temporary files and directories
Directory to publish files to. Defaults to publish.
$
publican clean_idsRun clean ids for source XML
$
publican clean_setRemove local copies of remote set books
$
publican copy_web_brandCopy a brand's installed web content to another site
The brand to use
WebSite configuration file to use when copying content between sites.
WebSite configuration file to use or create.
$
publican createCreate a new book, set, or article
The brand to use
The version of the DocBook DTD to use
The edition of the book, article, or set
The language the XML will be written in
The name of the book, article, set, or brand
The name of the product
The type (book, article, or set)
The version of the product
$
publican create_brandCreate a new brand
The language the XML will be written in
The name of the book, article, set, or brand
$
publican create_siteCreate a new WebSite in the supplied location.
Override default database file.
The language the XML will be written in
WebSite configuration file to use or create.
Override the default template path.
Override the default TOC path.
$
publican help_configDisplay help text for the configuration file
$
publican install_bookInstall a book in to a WebSite.
The language the XML will be written in
WebSite configuration file to use or create.
$
publican install_brandInstall a brand to the supplied location
/path/to/install/to
Directory to publish files to. Defaults to publish.
Install the web content for a brand.
$
publican lang_statsreport PO statistics
The language the XML will be written in
$
publican migrate_siteMigrate a website DataBase from Publican < 3 to Publican 3.
WebSite configuration file to use or create.
$
publican packagePackage a language for shipping
Build binary rpm when running package
Push SRPM to brew
Create desktop instead of web package
The language the XML will be written in
Directory to publish files to. Defaults to publish.
Use scratch instead of tag build
Create package without using version in package name
Wait for brew to finish building
$
publican print_bannedPrint a list of banned DocBook tags
$
publican print_knownPrint a list of QA'd DocBook tags
$
publican print_treePrint a tree of the xi:includes
$
publican print_unusedPrint a list of unused XML files
$
publican print_unused_imagesPrint a list of unused Image files
$
publican remove_bookRemove a book from a WebSite.
The language the XML will be written in
WebSite configuration file to use or create.
$
publican renameRename a publican book
The name of the book, article, set, or brand
The name of the product
The version of the product
$
publican reportPrint a readability report for the source text.
$
publican site_statsReport on the contents of a WebSite
WebSite configuration file to use or create.
$
publican trans_dropSnapshot the source language for use in translation.
$
publican update_dbAdd or remove database entries. Used for processing pre-build books, such as when building packages.
Abstract for a book
Add a database entry
The language this translation is based on.
The version number of the book being installed.
Delete a database entry
Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub
The language the XML will be written in
The name of the book, article, set, or brand
name label for a book
The name of the product
product label for a book
WebSite configuration file to use or create.
Order to sort a book
Sub title for a book
The version of the product
version label for a book
$
publican update_poUpdate the PO files
email to use for a revision.
firstname to use for a revision.
Comma-separated list of languages, for example: en-US,de-DE,all
Use gettext's msgmerge for POT/PO merging.
Keep previous msgid when fuzzy matches are detected in PO updates.
surname to use for a revision.
$
publican update_potUpdate the POT files
$
publican update_siteUpdate an existing sites templates.
WebSite configuration file to use or create.
$
publican zt_pullPull translations from Zanata.
$
publican zt_pushPush translations to Zanata.
These are set in the books or brands configuration files.
Arch to filter output on.
audience to filter output on.
A space-separated list of books used in this remote set.
The brand to use when building this package.
The default value for this parameter is: common
The brew dist to use for building the standalone desktop rpm.
The default value for this parameter is: docs-5E
This field is deprecated and will be removed from Publican in the future.
Display bridge head elements in the TOCs?
The default value for this parameter is: 0
For HTML, should the first section be on the same page as its parent?
The default value for this parameter is: 0
For HTML, what is the deepest level of nesting at which a section should be split onto its own page?
The default value for this parameter is: 4
Path to jar files for FOP.
The default value for this parameter is: /usr/share/java/ant/ant-trax-1.7.0.jar:/usr/share/java/xmlgraphics-commons.jar:/usr/share/java/batik-all.jar:/usr/share/java/xml-commons-apis.jar:/usr/share/java/xml-commons-apis-ext.jar
Path to publican content.
The default value for this parameter is: /usr/share/publican
Path to publican common content.
The default value for this parameter is: /usr/share/publican/Common_Content
Conditions on which to prune XML before transformation.
Is the content confidential?
The default value for this parameter is: 0
The text used to indicate content is confidential.
The default value for this parameter is: CONFIDENTIAL
conformance to filter output on.
Print out extra messages?
The default value for this parameter is: 0
URL for the documentation team for this package. Used for top right URL on HTML.
The default value for this parameter is: https://fedorahosted.org/publican
Name of this document. Fetched from title tag in xml_lang/TYPE_Info.xml if not set in cfg file.
This parameter is constrained with the following regular expression: ^[0-9a-zA-Z_\-\.\+]+$
This field is not supported for: brand.
The author name to be shown in drupal book page. It must be a valid drupal username.
The default value for this parameter is: Publican
The directory where the image should be stored in drupal server.
The default value for this parameter is: /sites/default/files/documentation/
The menu where we can find the book.
The default value for this parameter is: user-guide
Override the bookname that will be shown in the drupal menu.
The format to use for the desktop output.
The default value for this parameter is: html-desktop
Space-separated list of packages the desktop RPM obsoletes.
Space-separated list of packages the desktop RPM requires.
Version of the DocBook DTD on which this project is based.
The default value for this parameter is: 4.5
Eclipse plugin ID. Defaults to "$product.$docname"
Eclipse plugin name. Defaults to "$product $docname"
Eclipse plugin provider. Defaults to "Publican-v4.2.2"
Directory where images are located.
The default value for this parameter is: extras
Generate table of contents down to the given section depth.
The default value for this parameter is: 0
Languages to replace with xml_lang regardless of translation status.
Directory where images are located.
The default value for this parameter is: images
Override the default Info file.
lang to filter output on.
License this package uses.
The default value for this parameter is: GFDL
The name of the main xml and ent files for this book, sans file extension and language. Fetched from docname if not set.
Semicolon-separated list of menu categories for the desktop package.
os to filter output on.
The OS for which to build packages.
The font to use for body text in PDFs.
The default value for this parameter is: Liberation Sans
The font to use for mono text in PDFs.
The default value for this parameter is: Liberation Mono
URL for the product. Used in top left URL in HTML.
The default value for this parameter is: https://fedorahosted.org/publican
Product this package covers. Fetched from productname tag in xml_lang/TYPE_Info.xml
This parameter is constrained with the following regular expression: ^[0-9a-zA-Z_\-\.\+]+$
This field is not supported for: brand.
Repository from which to fetch remote set books.
By default Revision History is sorted in descending order. Set this to 'asc' or 'ascending' to reverse the sort.
Override the default Revision History file.
revision to filter output on.
revisionflag to filter output on.
role to filter output on.
Type of repository in which books that form part of a remote set are stored. Supported types: SVN, GIT.
security to filter output on.
Display remarks in transformed output.
The default value for this parameter is: 0
Override the default sort weighting. Defaults to 50.
URL to find tar of source files. Used in RPM Spec files.
status to filter output on.
Directory to use for building.
The default value for this parameter is: tmp
Depth of sections to include in the main table of contents.
The default value for this parameter is: 2
Choose the formatter to use when creating txt output.
The default value for this parameter is: default
This parameter is constrained with the following regular expression: ^(links{1}|tables{1}|default)$
Type of content this package contains. Supported: set, book, article, brand
The default value for this parameter is: Book
userlevel to filter output on.
vendor to filter output on.
Version of this package. Fetched from productnumber tag in xml_lang/TYPE_Info.xml
This parameter is constrained with the following regular expression: ^[0-9][^\p{IsSpace}]*$
The brew dist to use for building the web rpm.
The default value for this parameter is: docs-5E
A comma-separated list of the formats to use for the web packages.
The default value for this parameter is: html,html-single,pdf,epub
This is a home page for a Publican-generated website, not a standard book.
web_home is deprecated and will be removed from Publican in the future. Use "web_type: home" instead.
This is a host name for a Publican-generated website, used for searches and the Sitemap. Be sure to include the full path to your document tree. E.g. if your documents are in the docs directory: http://www.example.com/docs
web_host is deprecated and will be removed from Publican in the future. Use "host" in the web site configuration file instead.
Override the book name, bottom level, menu label on a Publican website.
Packages to obsolete in web RPM.
Override the product, top level, menu label on a Publican website.
Override the default search form for a Publican website. By default this will use Google search and do a site search if web_host is set.
web_search is deprecated and will be removed from Publican in the future. Use "search" in the web site configuration file instead.
This is a special page for a Publican-generated website, not a standard book. Valid types are home, product, and version.
This parameter is constrained with the following regular expression: ^(home|product|version)$
Override the version, middle level, menu label on a Publican website. To hide this menu item set this to: UNUSED
Extra options to pass to wkhtmltopdf. e.g. wkhtmltopdf_opts: "-O landscape -s A3"
wordsize to filter output on.
Language in which XML is authored.
The default value for this parameter is: en-US
These are set in the brands configuration files.
A comma-separated list of XML attributes that are not permitted in the source.
A comma-separated list of XML tags that are not permitted in the source.
The base brand to use for this brand.
The default value for this parameter is: common
Override Type for DocType. Must be a complete string.
Override URI for DocType. Must be a complete string.
Brand option to disable embedding the navigational toc in web packages
Full path for the publican site configuration file for non standard RPM websites.
Install path for non standard RPM websites.
Name of site package for non standard RPM websites. Required to ensure the site is installed.
These are set in the sites configuration file.
The name of the SQLite database file for your site, with the filename extension .db
Output extra messages when running publican.
The default value for this parameter is: 0
The default language for this website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available.
The default value for this parameter is: en-US
Dump the publican database to an XML file.
The name of the file to dump the publican database to.
The default value for this parameter is: /var/www/html/DUMP.xml
HTML to inject in to the footer of every page on the website.
The default value for this parameter is:
The web host, may be a full URI or a relative path.
The default value for this parameter is: /docs
Stop publican from automatically rebuilding teh web site everytime a book is installed, updated or removed.
The default value for this parameter is: 0
The HTML to inject in as the site serach.
The default value for this parameter is: Google site search
Title used for all site navigation pages.
The default value for this parameter is: Documentation
Full path to the template directory.
The default value for this parameter is: /usr/share/publican/templates
The source file to use for JavaScript functionality.
The default value for this parameter is: default.js
The path to the directory in which to create the top-level index.html file.
Template to use for generagting the web style 1 toc file.
The default value for this parameter is: toc
This field is deprecated and will be removed from Publican in the future.
Publican supports mutliple base styles for websites, this picks one.
The default value for this parameter is: 1
This parameter is constrained with the following regular expression: [1-2]
This field is deprecated and will be removed from Publican in the future.
Zip up the dump file after dumping it
The default value for this parameter is: 0
The dump file for a Publican-generated website contains some basic site configuration details, together with details of every document published on the site. The site configuration details are:
<host>
The URL to the root of the documentation site, as set by the host
parameter in the site configuration file.
<def_lang>
The default language of the documentation on the website, as set by the def_lang
parameter in the site configuration file.
Each document, in each language, in each format has a separate record. These records contain the following data:
<name>
The title of the document, generated from the <title>
tag in the Book_Info.xml
, Article_Info.xml
, or Set_Info.xml
file unless overridden by the docname
parameter in the publican.cfg
file. Any spaces in the title are replaced by underscores.
<ID>
A unique ID number for this document, in this format, in this language.
<abstract>
A brief summary of the content of the document, generated from the <abstract>
tag in the Book_Info.xml
, Article_Info.xml
, or Set_Info.xml
file. Publican uses this same content to generate the %description
section of the spec file when it packages a document. If the <abstract>
is translated, this field contains the translated text.
<format>
The format in which the document is produced — html
for multi-page html, html-single
for single-page html, pdf
for PDF, and epub
for EPUB.
<language>
The language code for the document. Refer to F – „Language codes“ for more information about language codes in XML.
<name_label>
The name of the document as it appears in the site table of contents. This label can be set with the web_name_label
parameter in the document's publican.cfg
file. Otherwise, the field is empty for a document in its original language, or uses the translated title of the document in a translated language. Any spaces in the name label are replaced by underscores.
<product>
The product that the document describes, generated from the <productname>
tag in the Book_Info.xml
, Article_Info.xml
, or Set_Info.xml
file unless overridden by the product
parameter in the publican.cfg
file. Any spaces in the product name are replaced by underscores.
<product_label>
The name of the product as it appears in the site table of contents. This label can be set with the web_product_label
parameter in the document's publican.cfg
file. Otherwise, the field is empty for a document in its original language, or uses the translated title of the document in a translated language. Any spaces in the name label are replaced by underscores.
If the product label is set to UNUSED
, no heading for this product appears in the website tables of contents.
<subtitle>
A one-line description of the content of the document, generated from the <subtitle>
tag in the Book_Info.xml
, Article_Info.xml
, or Set_Info.xml
file. Publican uses this same content to generate the Summary
section of the spec file when it packages a document. If the <subtitle>
is translated, this field contains the translated text.
<update_date>
The date that the document was most recently installed on the site, in the format YYYY-MM-DD.
<version>
The version of the product that the document describes (not the version of the document itself), generated from the <productnumber>
tag in the Book_Info.xml
, Article_Info.xml
, or Set_Info.xml
file unless overridden by the version
parameter in the publican.cfg
file.
<version_label>
The version of the product as it appears in the site table of contents. This label can be set with the web_version_label
parameter in the document's publican.cfg
file.
If the version label is set to UNUSED
, no heading for this version of the product appears in the website tables of contents.
Příklad D.1. Sample records from a DUMP.xml
file
These two records from a DUMP.xml
file show the same book, the Red Hat Enterprise Linux 5 Installation Guide, in two different formats and two different languages — an English PDF version and a French multi-page HTML version.
<record> <name>Installation_Guide</name> <ID>22</ID> <abstract>This manual explains how to boot the Red Hat Enterprise Linux 5 installation program (anaconda) and to install Red Hat Enterprise Linux 5 on 32-bit and 64-bit x86 systems, 64-bit POWER systems, and IBM System z. It also covers advanced installation methods such as kickstart installations, PXE installations, and installations over VNC. Finally, it describes common post-installation tasks and explains how to troubleshoot installation problems.</abstract> <format>pdf</format> <language>en-US</language> <name_label>Installation_Guide</name_label> <product>Red_Hat_Enterprise_Linux</product> <product_label>Red_Hat_Enterprise_Linux</product_label> <subtitle>Installing Red Hat Enterprise Linux 5 for all architectures</subtitle> <update_date>2010-10-07</update_date> <version>5</version> <version_label></version_label> </record> <record> <name>Installation_Guide</name> <ID>149</ID> <abstract>Ce manuel explique comment lancer le programme d'installation Red Hat Enterprise Linux 5 et comment installer Red Hat Enterprise Linux 5 sur les systèmes x86 32-bit et 64-bit, sur les systèmes POWER 64-bit, et sur les systèmes IBM System z. Il couvre aussi des méthodes d'installation avancées telles que les installations kickstart, PXE, et les installations au moyen de VNC. Finalement, ce manuel décrit les tâches communes post-installation et explique comment résoudre les problèmes liés à une installation.</abstract> <format>html</format> <language>fr-FR</language> <name_label>Guide_d'installation</name_label> <product>Red_Hat_Enterprise_Linux</product> <product_label>Red_Hat_Enterprise_Linux</product_label> <subtitle>Installation de Red Hat Enterprise Linux 5 pour toutes les architectures</subtitle> <update_date>2010-10-19</update_date> <version>5</version> <version_label></version_label> </record>
Using the following fields, you can compute the URL of any document on the site:
<host>
<name>
<format>
<language>
<product>
<version>
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
For example, http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
For example, http://docs.fedoraproject.org/en-US/Fedora/14/html-single/Accessibility_Guide/index.html
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/<product>
-<version>
-<name>
-<language>
.pdf
For example, http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.pdf
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/<product>
-<version>
-<name>
-<language>
.epub
For example, http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.epub
Note that the <product_label>
, <version_label>
, and <name_label>
fields have no significance for URLs, even when these fields are suppressed in tables of contents by the UNUSED
setting.
The only part of the XML language tag that is mandatory in Publican is the language subtag. However, Publican is designed with the assumption that you will routinely include the region subtag when you identify languages. In many languages, spelling and vocabulary vary significantly from region to region. If you do not specify the regional variety of a language in which your document is authored or into which it is translated, you might obtain unexpected results when you build the document in Publican.
The system of codes used to identify languages in the XML standard is not the only system of languages codes in use in the world today. However, because Publican strives to comply with the XML standard, these are the only codes that Publican supports. In particular, note that the codes used in the GNU tools (identified by their use of underscores and the @
symbol to separate elements — for example, en_GB
or sr_RS@latin
) do not comply with the XML standard and therefore do not work with Publican.
Publican is an XML publication tool and therefore is designed to use the language codes — or tags — that the World Wide Web Consortium (W3C) designated in the XML specification.[5] These codes are defined in the Internet Engineering Task Force (IETF) document BCP 47: Tags for Identifying Languages.[6]
Language tags are built from one of more subtags, separated from one another by hyphens. In order of appearance within a language tag, these subtags are:
language-script-region-variant
BCP 47 also allows for considerable customization of language tags for special purposes through the use of extension subtags and private-use subtags. Extension subtags allow for finer-tuning of existing subtags, but must be registered with the IETF (none are currently registered). Private-use subtags are introduced by x-
and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).[7] Although Publican will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form language-region
. A brief description of subtags follows:
The language subtag comprises two or more lower-case letters and is the only mandatory part of the language tag. For most widely spoken languages, the language subtag is a two-letter code identical with the language codes specified in ISO 639-1, [8] for example, zh
(Chinese), hi
(Hindi), es
(Spanish), and en
(English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,[9] for example, bal
(Balochi), apk
(Kiowa Apache), and tpi
(Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or ISO 639-2 equivalent, such as subtags for the constructed languages qya
(Quenya) and tlh
(Klingon), and for the occult language i-enochian
(Enochian). This last example also illustrates a small number of language subtags grandfathered into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.
RFC 5646: Tags for Identifying Languages[10] issued in September 2009 allows for extended language subtags to follow the language subtag. Extended language subtags are three-letter codes that represent languages that share a close relationship with a language already represented by a language subtag. For example, yue
represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: zh-yue
. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.
The script subtag comprises four letters — the first one in upper case, the other three in lower case — and defines a writing system. These codes are identical with the four-letter codes specified in ISO 15924.[11] The script subtag is used to identify languages that are commonly written with more than one writing system; the subtag is omitted when it adds no distinguishing value to the language tag overall. For example, sr-Latn
represents Serbian written with the Latin alphabet and sr-Cyrl
represents Serbian written with the Cyrillic alphabet; az-Arab
represents Azerbaijani written in Arabic script and az-Cyrl
represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as fr-Latn
, because French is not commonly written in any script other than the Latin alphabet anywhere in the world.
The region subtag comprises either two upper-case letters (for regions that conform to national boundaries) or three digits (for other areas, such as trans-national regions). The two-letter subtags are identical with those from ISO 3166-1[12], for example, AT
(Austria), TZ
(Tanzania), and VE
(Venezuela). The three-digit region subtags are based on those in UN M.49, [13] for example, 015
(Northern Africa), 061
(Polynesia), and 419
(Latin America and the Caribbean).
Variant subtags identify well-defined, recognizable variants of a language or script and can include upper-case letters, lower-case letters, and numerals. Variant subtags that start with a letter must be at least five characters long, and those that start with a numeral must be at least four characters long. Most variant subtags can only be used in combination with specific subtags or combinations of subtags. Variant subtags do not harmonize with any other standard; they are each the result of a separate registration with the IETF by an interested person or group.
Under the present standard, dialects of several languages are designated with variant subtags, for example, nedis
denotes Nadiza (also known as Natisone), a dialect of Slovenian. This tag must be used in conjunction with the language subtag for Slovenian, thus: sl-nedis
. In September 2009, the IETF issued a Request for Comments (RFC) that (amongst other things) proposes that dialects be represented by language extension subtags attached to language subtags.[14]
Most variant subtags mark a particular orthography, most usually as a result of an official spelling reform or a significant work documenting the language. Examples (with their required language subtags) include: fr-1606nicot
(French as documented by Jean Nicot in 1606), de-1901
(German spelling codified by the 2nd Orthographic Conference in 1901) and be-1959acad
(Belarusian as codified by the Orthography Commission in 1959).
Finally, some variant subtags denote a particular variant of a system of writing or transliteration. For example, zh-Latn-wadegile
is Chinese written in the Latin alphabet, according to the transliteration system developed by Thomas Wade and Herbert Giles; ja-Latn-hepburn
is Japanese written in the Latin alphabet using the transliteration system of James Curtis Hepburn.
Publican includes support for the following languages:
ar-SA — Arabic
as-IN — Assamese
ast-ES — Asturian
bg-BG — Bulgarian
bn-IN — Bengali (India)
bs-BA — Bosnian
ca-ES — Catalan
cs-CZ — Czech
da-DK — Danish
de-CH — German (Switzerland)
de-DE — German (Germany)
el-GR — Greek
es-ES — Spanish
fa-IR — Persian
fi-FI — Finnish
fr-FR — French
gu-IN — Gujarati
he-IL — Hebrew
hi-IN — Hindi
hr-HR — Croatian
hu-HU — Hungarian
id-ID — Indonesian
is-IS — Icelandic
it-IT — Italian
ja-JP — Japanese
kn-IN — Kannada
ko-KR — Korean
lv-LV — Latvian
ml-IN — Malayalam
mr-IN — Marathi
nb-NO — Norwegian (Bokmål orthography)
nl-NL — Dutch
or-IN — Oriya
pa-IN — Punjabi
pl-PL — Polish
pt-BR — Portuguese (Brazil)
pt-PT — Portuguese (Portugal)
ru-RU — Russian
si-LK — Sinhalese
sk-SK — Slovak
sr-Cyrl-RS — Serbian (Cyrillic script)
sr-Latn-RS — Serbian (Latin script)
sv-SE — Swedish
ta-IN — Tamil
te-IN — Telugu
th-TH — Thai
uk-UA — Ukrainian
zh-CN — Chinese (People's Republic of China, implicitly simplified Han script)
zh-TW — Chinese (Republic of China, implicitly traditional Han script)
Přehled revizí | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Revize 4.2-0.3 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Revize 4.2-0.2 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Revize 4.2-0.1 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Revize 4.2-0 | Mon May 12 2014 | ||||||||||
| |||||||||||
Revize 4.0-5 | Thu Mar 27 2014 | ||||||||||
| |||||||||||
Revize 4.0-4 | Mon Nov 25 2013 | ||||||||||
| |||||||||||
Revize 4.0-3 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Revize 4.0-2 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Revize 4.0-1 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Revize 3.2-1 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
Revize 3.2-0 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
Revize 3.1-0 | Tue Jan 8 2013 | ||||||||||
| |||||||||||
Revize 3.0-0 | Mon Feb 20 2012 | ||||||||||
| |||||||||||
Revize 2.7-1 | Tue Sep 6 2011 | ||||||||||
| |||||||||||
Revize 2.6-1 | Mon Jul 18 2011 | ||||||||||
| |||||||||||
Revize 2.4-1 | Wed Dec 1 2010 | ||||||||||
| |||||||||||
Revize 2.3-0 | Mon Oct 25 2010 | ||||||||||
| |||||||||||
Revize 2.3-0 | Tue Oct 5 2010 | ||||||||||
| |||||||||||
Revize 2.2-0 | Thu Aug 19 2010 | ||||||||||
| |||||||||||
Revize 2.1-1 | Fri Jul 16 2010 | ||||||||||
| |||||||||||
Revize 1.6-1 | Mon May 24 2010 | ||||||||||
| |||||||||||
Revize 1.6-0 | Fri May 7 2010 | ||||||||||
| |||||||||||
Revize 1.5-0 | Fri Feb 26 2010 | ||||||||||
| |||||||||||
Revize 1.4-0 | Wed Feb 17 2010 | ||||||||||
| |||||||||||
Revize 1.3-0 | Mon Dec 7 2009 | ||||||||||
| |||||||||||
Revize 1.2-0 | Fri Nov 27 2009 | ||||||||||
| |||||||||||
Revize 1.1-1 | Thu Nov 26 2009 | ||||||||||
| |||||||||||
Revize 1.1-0 | Thu Oct 22 2009 | ||||||||||
| |||||||||||
Revize 1.0-0 | Tue Oct 13 2009 | ||||||||||
| |||||||||||
Revize 0.5-0 | Thu Dec 18 2008 | ||||||||||
| |||||||||||
Revize 0.4-0 | Tue Nov 25 2008 | ||||||||||
| |||||||||||
Revize 0.3-0 | Fri Oct 10 2008 | ||||||||||
| |||||||||||
Revize 0.2-0 | Fri Sep 05 2008 | ||||||||||
| |||||||||||
Revize 0.1-1 | Fri Jun 06 2008 | ||||||||||
| |||||||||||
Revize 0.1-0 | Fri May 16 2008 | ||||||||||
| |||||||||||
Revize 0.0-0 | Thu Dec 13 2007 | ||||||||||
|