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.
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
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.
Naleznete-li v tomto manuálu typografickou chybu nebo přemýšlíte-li nad způsobem jak jej učinit lepším, velmi rádi si vás vyslechneme! Prosíme, podejte hlášení do Bugzilly: 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 je nástroj pro zveřejňování materiálu napsaného v DocBook XML. Tato příručka vysvětluje, jak pomocí Publicanu vytvořit a sestavit knihy a články. Nejedná se o obecnou učebnici DocBook XML; pro pomoc s DocBook XML využijte knihu DocBook: The Definitive Guide od Normana Walshe a Leonarda Muellnera, dostupné online: http://www.docbook.org/tdg/en/html/docbook.html.
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 4.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 4.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.
#!/usr/bin/perl use strict; use warnings; print "Hello, World!\n";
#include <iostream> int main() { std::cout << "Hello World!"; &lies; }
[Show All][Hide]$
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
Test a programlisting with a calloutlist
Příklad 1. "Hello world!" in C++
#include <qpid/messaging/Connection.h> #include <qpid/messaging/Message.h> #include <qpid/messaging/Receiver.h> #include <qpid/messaging/Sender.h> #include <qpid/messaging/Session.h> &BZ1101050; #include <iostream> using namespace qpid::messaging; int main(int argc, char** argv) { std::string broker = argc > 1 ? argv[1] : "localhost:5672"; std::string address = argc > 2 ? argv[2] : "amq.topic"; Connection connection(broker); try { connection.open(); 1 Session session = connection.createSession(); 2 Receiver receiver = session.createReceiver(address); 3 Sender sender = session.createSender(address); 4 sender.send(Message("Hello world!")); Message message = receiver.fetch(Duration::SECOND * 1); 5 std::cout << message.getContent() << std::endl; session.acknowledge(); 6 connection.close(); 7 return 0; } catch(const std::exception& error) { std::cerr << error.what() << std::endl; connection.close(); return 1; } }
Navazuje spojení s messaging broker.
Vytváří objekt relace, který udržuje stav všech interakcí s messaging broker a řídí vysílače a příjímače.
Vytváří příjímač, který čte z dané adresy.
Vytváří vysílač, kterí odesílá na danou adresu.
Čte další zprávu. Doba trvání je nepovinná, není-li zadána, bude čekat na příští zprávu nekonečně.
Potvrzuje přečtené zprávy. Aby se zaručilo doručení, zpráva zůstává v messaging brokeru dokud není potvrzena klientem. session.acknowledge() potvrzuje všechny nepotvrzené zprávy pro danou relaci—umožňuje dávkování potvrzení, které je uspornější než potvrzování jednotlivých zpráv.
Ruší spojení, všechny relace řízené spojením a všechny vysílače a přijímače řízené každou relací.
A nyní testujeme programlistingco s areaspec
<list-index
column="column_name" 1
base="0|1|..."/>
2
column_name
(povinný): název sloupce se sadou hodnot indexu.
base
(nepovinný - výchozí 0
): hodnota sloupce s indexy, která odpovídá prvnímu prvku seznamu nebo pole.
Je vložen nový řádek po tomto CDATA
?
=, >, >=, <, <=, <>
!=
<>
package com.sample; import org.kie.api.runtime.process.WorkItem; import org.kie.api.runtime.process.WorkItemHandler; import org.kie.api.runtime.process.WorkItemManager; public class NotificationWorkItemHandler implements WorkItemHandler { public void executeWorkItem(WorkItem workItem, WorkItemManager manager) { String from = (String) workItem.getParameter("From"); String to = (String) workItem.getParameter("To"); String message = (String) workItem.getParameter("Message"); String priority = (String) workItem.getParameter("Priority"); // send email EmailService service = ServiceRegistry.getInstance().getEmailService(); service.sendEmail(from, to, "Notification", message); 1 // notify manager that work item has been completed manager.completeWorkItem(workItem.getId(), null); } 2 public void abortWorkItem(WorkItem workItem, WorkItemManager manager) { // Do nothing, notifications cannot be aborted } }
Třída ServiceRegistry
je názorná třída implementující obchodní logiku úlohy.
Volání completeWorkItem()
dokončuje vykonání pracovní položky.
<?xml version="1.0" encoding="UTF-8"?><test></test>
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 – „Grafická úprava“.
Otevřete terminál.
Spusťte následující příkaz, abyste nainstalovali balíček publican:
$
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.
V současnosti není pro publican dostupný žádný zpětný port (http://backports.debian.org/Instructions/), proto je potřeba použít 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.
Postup instalace předpokládá, že již máte nainstalováno fungující prostředí docker (viz http://docker.io).
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.
Stáhněte a nainstalujte kontejner svendowideit/publican z adresy 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
Je možné spustit publican z GIT checkout, bez nutnosti jeho instalace, jsou-li nainstalovány závislosti.
Chcete-li stáhnout, nebo přesněji zkontrolovat (checkout), zdroj z GIT, otevřete terminál.
Pro zkontrolování zdrojových souborů publicanu z GITu spusťte následující příkazy:
$
cd CESTA KAM ULOŽIT ZDROJOVÉ SOUBORY$
git clone git://git.fedorahosted.org/publican.git publican
Chcete-li spustit publican z této kontroly, spusťte tyto příkazy:
$
PUBLICAN_PATH="CESTA, KDE JSOU ULOŽENY ZDROJOVÉ SOUBORY/publican"$
perl -CDAS -I $PUBLICAN_PATH/lib $PUBLICAN_PATH/bin/publican build --brand_dir $PUBLICAN_PATH/datadir/Common_Content/common --formats html
Stáhněte instalační soubor Publicanu ze stránky 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 – „Grafická úprava“. 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 .
Software instalačního programu standardně vytvoří ve vašem počítači adresář nazvaný Publican
v adresáři%ProgramFiles%
— nejčastěji C:\Program Files\Publican
. Ručně lze tuto cestu upravit v okně Cílový adresář, abyste zvolili jiný adresář.
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.
Ze stránky http://guide.macports.org/chunked/installing.macports.html nainstalujte Macports. Vše, co nainstalujete bude umístěno v /opt/local
, tedy dostatečně daleko od vašich normálních souborů.
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.
Umístění SVN pro grafické úpravy poskytované společností Red Hat je na adrese 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_prikazu
volba_prikazu je jedna z několika voleb pro samotný příkaz $
publican. Úplný seznam akcí je k dispozici v B.2 – „Akce příkazu“
$
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 těchto souborů. Volby_akce se uplatňují na akci, jako např. zadání jazyka dokumentu. Úplný seznam akcí je k dispozici v B.2 – „Akce příkazu“
$
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. Úplný seznam akcí a voleb je k dispozici v B.2 – „Akce příkazu“
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 4.1.1 – „Soubor publican.cfg“ a více podrobností o kódech jazyků viz F – „Jazykové kódy“.
--version verze
set version as the version number of the product that the book describes. For example, for Red Hat Enterprise Linux 5.1 you would use 5.1
. The default version is 0.1
. The --version
option sets the <productnumber>
tag in the Book_Info.xml
or Article_Info.xml
file. For more information refer to 4.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 4.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 4.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 4.1.1 – „Soubor publican.cfg“ a podrobnosti o používání sad viz 6 – „Užití sad“.
--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 4.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 5.1 – „Instalace grafické úpravy“. Nezadáte-li grafickou úpravu, Publican použije svou vestavěnou, výchozí úpravu. Více informací viz 5 – „Grafická úprava“
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 – „Grafická úprava“.
Pokročilé parametry Odstraňte mě a odkazovanou přílohu
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 4.9.1 – „Podmíněné tagování a překlady“.
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 6.2 – „Distribuované sady“
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 4.8.2 – „Příkaz $
publican package“ a 5.4 – „Balení grafické úpravy“.
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 4.9 – „Podmíněné tagování“.
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 4.8 – „Balení dokumentu“.
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
specifies the document name. If set, this value overrides the content of the <title>
tag in the Book_Info.xml
file when you package a document. This value must contain only upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
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 4.8.1.3 – „Položky nabídky pracovní plochy pro dokumenty“.
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.
When you install Publican, you also install a local copy of the DocBook XML DTD version 4.5 and accompanying Extensible Stylesheet Language (XSL). If you set a version of the DTD for which there is no local support, Publican must download the appropriate DTD and XSL from an online source every time that it builds the document. Building your document is delayed while this download takes place. The combined size of the required files is around 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 4.6 – „Překlad dokumentu“ a F – „Jazykové kódy“.
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 4.8 – „Balení dokumentu“.
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 4.8.1.3 – „Položky nabídky pracovní plochy pro dokumenty“.
os_ver
specifies the operating system for which to build packages. Publican appends the value that you provide here to the RPM packages that it builds. For example, .fc15
for Fedora 15. The default value is .el5
, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to 4.8 – „Balení dokumentu“ and 5.4 – „Balení grafické úpravy“.
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
specifies the product to which this documentation applies. If set, this value overrides the content of the <productname>
tag in the Book_Info.xml
file when you package a document. This value must include only contain upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
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 6.2 – „Distribuované sady“.
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 6.2 – „Distribuované sady“.
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 4.8 – „Balení dokumentu“.
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 zákaznicky upravené š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 4.8.2 – „Příkaz $
publican package“.
web_home
konkretizuje, že dokument je domovská stránka webové stránky dokumentace, nikoliv standardní dokument. Viz 7 – „Sestavování webových stránek Publicanem“.
web_home
je zastaralý
In Publican 2.2, web_home
is replaced by web_type: home
. Support for web_home
will be removed in a future version of Publican.
web_name_label
potlačuje název knihy, který se zobrazuje v nabídce webové stránky řízené Publicanem. Viz 7 – „Sestavování webových stránek Publicanem“.
web_obsoletes
uvádí balíčky, které webový RPM označí za zastaralé. Viz 4.8 – „Balení dokumentu“.
web_product_label
potlačuje název produktu, který se zobrazuje v nabídce webové stránky řízené Publicanem. Viz 7 – „Sestavování webových stránek Publicanem“.
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
specifies that the document is descriptive content for a Publican-managed website rather than product documentation. This content includes the home page of the website (web_type: home
), product description pages (web_type: product
), and version description pages (web_type: version
). Refer to 7 – „Sestavování webových stránek Publicanem“.
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 – „Sestavování webových stránek Publicanem“.
wkhtmltopdf_opts
Extra options to pass to wkhtmltopdf. e.g. 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
.
Tento oddíl rozebírá tvorbu balíčků dokumentů, které se distribuují pomocí Správce balíčků RPM. Ačkoliv příkazem $
publican package vygeneruje Publican balíček s archivem, tarball, který lze použít k sestavení balíčku pro distribuci pomocí různého softwaru pro správu balíčků. Spustíte-li příkaz publican package na počítači, na kterém není nainstalován rpmbuild, Publican přesto vygeneruje tento tarball, i když pak z něj nemůže vygenerovat balíček RPM.
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: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 4.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"> <imageobject role="front-large" remap="lrg"> <imagedata width="600px" format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="front" remap="s"> <imagedata format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="front-small" remap="xs"> <imagedata format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="thumbnail" remap="cs"> <imagedata format="PNG" fileref="images/front_cover_thumbnail.png"/> </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> A paragraph in Chapter 1. </para> <section id="section1"> <title>Chapter 1 Section 1</title> <para> A paragraph in Section 1. </para> </section> <section id="section2"> <title>Chapter 1 Section 2</title> <para> A paragraph in Section 2. </para> </section> </chapter> <chapter> <title>Chapter 2</title> <para> A paragraph in Chapter 2. </para> </chapter> </book>
Tato kniha obsahuje dvě kapitoly. První kapitola obsahuje dva oddíly. Více informací o oddílech viz http://docbook.org/tdg/en/html/section.html a knihách viz http://docbook.org/tdg/en/html/book.html.
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> <imagedata fileref="./images/testimage.png" /> </imageobject> <textobject><phrase>alternate text goes here</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/
.
Certain characters are reserved in XML, in particular, &
and <
. If you insert code samples directly into the XML of your document, you must escape these characters, either by marking them as CDATA
or by replacing them with entities (& and < respectively).[2] If you place these files in the extras/
directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.
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> <areaspec> <area id="orbit-for-parameter" coords='4 75'/> <area id="orbit-for-magnitude" coords='12 75'/> </areaspec> <programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <calloutlist> <callout id="callout-for-parameter" arearefs="orbit-for-parameter"> <para> The <firstterm>standard gravitational parameter</firstterm> (μ) is a derived value, the product of Newton's gravitational constant (G) and the mass of the primary body. </para> </callout> <callout id="callout-for-magnitude" arearefs="orbit-for-magnitude"> <para> Since the mass of the orbiting body is many orders of magnitude smaller than the mass of the primary body, the mass of the orbiting body is ignored in this calculation. </para> </callout> </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] Refer to section 2.4 "Character Data and Markup" in the XML 1.0 standard, available from 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 Publicanu klíčovou otázkou. Obecné překladatelské workflow pro dokument vyvinuté v Publicanu je následující:
Dokončete dokument v XML.
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ů dokumentu. 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.
Vygenerujte soubory šablon portable object (POT) ze souborů XML:
$
publican update_pot
Jsou-li sobory POT pro tento dokument vytvořeny poprvé, Publican vytvoří nový podadresář nazvaný pot
. Ten obsahuje soubor POT pro každý soubor XML v dokumentu. Vytvořil-li Publican soubory POT pro tento dokument již dříve, zaktualizuje existující soubory POT, aby promítl změny v XML od poslední aktualizace souborů POT.
Publican vygeneruje soubor POT pro každý soubor XML v adresáři XML, ať je daný soubor XML v dokumentu použit či nikoliv. Převedete-li napoužívané soubory XML na soubory POT, ztrácíte čas a úsilí dobrovolných překladatelů, a zbytečně utrácíte peníze, pokud překladatele platíte.
Použijte příkaz $
publican print_unused, abyste vytvořili seznam souborů XML, jež nejsou v dokumentu použity.
Vygenerujte soubory portable object (PO) ze souborů POT, abyste zahájili předkla do určitého jazyka:
$
publican update_po --langs=kod_jazyka
kde kod_jazyka je kód cílového jazyka. Více inforamací o kódech jazyků viz F – „Jazykové kódy“. Můžete poskytnout několik kódů, oddělených čárkou, abyste vygenerovali soubory PO pro více než jeden jazyk. Na příklad:
$
publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN
Jsou-li soubory PO vytvořeny pro daný jazyk poprvé, Publican vytvoří nový podadresář nazvaný kódem jazyka, který jste uvedli ve volbě --langs=
. Ten obsahuje soubor PO pro každý soubor POT v podadresáři pot
, plus soubor Revision_History.xml
, který sleduje historii tohoto konkrétního překladu. Je-li vytvořen poprvé, soubor Revision_History.xml
zaznamená datum, kdy byly pro tento překlad vytvořeny soubory PO, a verzi zdrojového jazyka XML (získaný ze souboru Revision_History.xml
zdrojového jazyka), na níž je tento překlad proto založen.
Vytvořil-li Publican soubory PO pro tento jazyk již dříve, dosavadní soubory PO zaktualizuje, aby promítl všechny změny v souborech POT od poslední aktualizace souborů PO a přidá novou položku do souboru Revision_History.xml
překladu, aby se zaznamenal datum, v kterém byly soubory PO pro tento překlad zaktualizovány, a verzi zdrojového jazyka XML, na níž je revize založena. Volbou --langs=all
lze zaktualizovat dosavadní soubory PO v každém podadresáři:
$
publican update_po --langs=all
Publican vygeneruje soubor PO pro každý soubor POT v adresáři pot
, ať se soubor POT zakládá na příslušném souboru XML použitém v dokumentu či nikoliv, nebo zda vůbec příslušný soubor XML existuje. Převedete-li soubory POT nepoužívaných nebo odstraněných souborů XML na soubory PO, ztrácíte čas a úsilí dobrovolných překladatelů, a zbytečně utrácíte peníze, pokud překladatele platíte.
Při vytváření souborů PO zobrazí Publican varování pro každý soubor POT, který nemá příslušný soubor XML, přesto však soubor PO vygeneruje. Avšak Publican vás neupozorní, pokud existuje soubor POT pro soubor XML, který se v dokumentu nepoužívá.
Přeložte řetězce nacházející se v souborech PO.
Aktualizujete-li dříve uveřejněný překlad této revize v zdrojovém jazyce, použijte příkaz Publicanu publican add_revision a popište své změny či opravy. Publican pro vás zaktualizuje soubor Revision_History.xml
.
Změnil-li se dokument ve svém původním jazyce, použijte příkazy publican trans_drop, publican update_pot a publican update_po, jak bylo popsáno v tomto postupu dříve.
Sestavte dokument v cílovém jazyce, na příklad:
$
publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
nebo ho zabalte do cíloveho jazyka, na příklad:
$
publican package --lang=is-IS
Dokument lze sestavit pro všechny jazyky, pro něž máte překlady, volbou --langs=all
, ale uvědomte si, že zabalit ho musíte pro každý jazyk samostatně. Více informací o sestavování dokumentu viz 4.7 – „Sestavení dokumentu“ a balení dokumentu viz 4.8 – „Balení dokumentu“
Překlad probíhá poté, kdy je kniha dokončena. Není nutné znát předem, kdo knihu bude překládat z důvodu věnovat jim poděkování. Vytvořte $translation/Author_Group.xml
a přidejte validní DocBook authorgroup. Překladatelé mohou přidat informace o sobě do tohoto souboru a Publican ho přiloží do $source_lang/Author_Group.xml
, když se kniha sestavuje. To umožní autorům zcela dokončit původní text bez potřeby znát, kdo bude knihu překládat.
Docbook automaticky shromažďuje a třídí prvky <glossentry>
do slovníku knihy; a prvky <primary>
, <secondary>
a <tertiary>
<indexterm>
do rejstříku knihy. Položky jsou tříděny automaticky, a ačkoliv tento systém funguje dobře pro jazyky zapisované v abecedě, abigudě či sylabickém skriptu, jazyky psané v logogramech se třídí méně dobře.
Chcete-li přizpůsobit pořadí třídění položky slovníku nebo rejstříku, přidejte ručně atribut DocBook sortas
. Na příklad, abyste zajistili, že japonské slovo 暗号化 bude zařazeno správně v rejstříku, uveďte:
#. Tag: indexterm #, no-c-format msgid "<primary>encryption</primary>" msgstr "<primary sortas="あんごうか">暗号化</primary>"
Obdobně, abyste zajistili, aby japonské slovo 暗号化 bylo zařazeno správně ve slovníku, uveďte:
#. 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 4.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 4.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 4.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 4.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
.
Tento oddíl rozebírá tvorbu balíčků dokumentů, které se distribuují pomocí Správce balíčků RPM. Ačkoliv příkazem $
publican package vygeneruje Publican balíček s archivem, tarball, který lze použít k sestavení balíčku pro distribuci pomocí různého softwaru pro správu balíčků. Spustíte-li příkaz publican package na počítači, na kterém není nainstalován rpmbuild, Publican přesto vygeneruje tento tarball, i když pak z něj nemůže vygenerovat balíček RPM.
Parametry nastavené v konfiguračním souboru dokumentu (ve výchozím stavu se jedná o publican.cfg
) vám umožní kontrolovat mnoho aspektů způsobu, ve kterém je dokument prezentován a zpracován v balíčku - viz 4.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 balení dokumentu lze pro uvedení konfiguračního souboru (a tedy které sady parametrů), který se má v daném sestavení použít, použít volbu --config
, na příklad:
$
publican package --lang hi-IN --config community.cfg
Publican nevytváří jen dokumentaci, může připravit balíčky sestaveného obsahu pro jeho distribuci na jednotlivé pracovní stanice nebo webové servery jako balíčky RPM. Balíčky RPM jsou používány pro šíření softwaru na počítače s operačním systémem Linux, které používají Správce balíčků RPM. Takovými operačními systémy jsou Red Hat Enterprise Linux , Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, Yellow Dog Linux, a další.
Publican může vytvářet jak zdrojové balíčky RPM (balíčky SRPM), tak binární balíčky RPM.
Balíčky SRPM obsahují zdrojový kód používaný k vytvoření softwaru, než samotný software. Aby bylo možné balíček SRPM použít, počítač musí zdrojový kód přeložit do softwaru — nebo v tomto případě do dokumentů. Balíčky SRPM dokumentů Publicanu obsahují soubory XML a soubor spec, než dokončené dokumenty ve formátu jako je HTML či PDF. Nelze nainstalovat dokumentaci přímo z balíčků SRPM v současných verzích Správce balíčků RPM.
Naopak binární balíčky RPM obsahují software — nebo v tomto případě dokument — který je připraven ke zkopírování do místa v souborovém systému počítače a okamžitému používání. Obsah binárního balíčku RPM nepotřebuje být přeložen počítačem, na kterém je nainstalován. Proto není nutné mít na počítači nainstalován Publican, pokud instalujete dokumentaci pouze pro místní užití. Pro instalaci dokumentace vygenerované Publicanem na webový server je nutné mít Publican nainstalován, ale z jiných důvodů než je překlad zdrojového kódu. Popis rozdílů mezi dokumentací instalované pro místní užití (desktopové RPM) a dokumentací instalované jako webový obsah (webové RPM) viz 4.8.1.2 – „Desktopové balíčky a webové balíčky“.
Publican může sbalit dokumenty pro čtení na počítačových pracovních stanicích (desktopový balíček RPM, nebo pro instalaci na webový server a zveřejnění na World Wide Web (webový balíček RPM). Desktopový balíček RPM dokumentu vytvořeného Publicanem a webový balíček RPM stejného dokumentu se liší tak, že desktopový balíček RPM nainstaluje dokumentaci pouze pro místní užití na počítači, zatímco webový RPM nainstaluje dokumentaci pro místní užití, ale rovněž ji lze použít pro World Wide Web.
Desktopový (binární) balíček RPM dokumentů vytvořených v Publicanu obsahují dokumentaci ve formátu jednostránkového HTML. Dokumenty šířené v tétho balíčcích jsou instalovány do podadresáře /usr/share/doc/
, umístění uváděné ve Filesystem Hierarchy Standard (FHS) pro ‘Různou dokumentaci’.[3] Desktopový balíček RPM obsahuje rovněž soubor desktop, který se ukládá do /usr/share/applications/
. Tento soubor umožňuje prostředím pracovní plochy přidat instalovaný dokument do svých nabídek pro snadné nalezení uživateli. Ve výchozím nastavení se položka nabídky v prostředí GNOME zobrazí pod → . Vlastní (zákaznickou) úpravu umístění položky nabídky lze provést vytvořením balíčku nabídky dokumentace, který poskytne soubory .directory
a .menu
a nastavte parametry dt_requires
a menu_category
v souboru publican.cfg
, aby si vyžádal tento balíček a poskytl příslušnou kategorii nabídky. Viz 4.8.1.3 – „Položky nabídky pracovní plochy pro dokumenty“
Standardně obsahují webové balíčky RPM dokumentů vytvořených v Publicanu dokumentaci ve formátu jednostránkového HTML, vícestránkového HTML, EPUB a PDF. Obsažené formáty se mohou měnit, pokud:
zveřejníte dokumentaci v jazyce, u něhož není v současnosti výstup PDF podporován. Publican se pro vytváření výstupu PDF spoléhá na FOP. FOP v současnosti nepodporuje texty psané/čtené zprava doleva (na příklad arabštinu, perštinu či hebrejštinu). Navíc jelikož FOP nemůže v současnosti specifikovat fonty na základě znak-za-znakem, nedostatek dostupných fontů pro indické skripty, které rovněž obsahují latinské glyfy, znemožňují Publicanu spolehlivou generaci výstupu PDF v indických jazycích. Standardně Publican nezahrnuje soubory PDF do webových balíčků RPM generované z arabského, perského, hebrejského nebo indického jazyka.
vaše kniha nebo grafická úprava obsahuje parametr web_formats
. Hodnota tohoto parametru potlačuje výchozí formáty, které se balí v Publicanu. Na příklad chcete-li zveřejnit dokument pouze jako jednostránkové HTML, PDF a text, nastavte web_formats: "html-single,pdf,txt"
Sestavený obsah je instalován do podadresáře /var/www/html/
, obvyklý dokumentační kořen (document root) pro webové servery. Všimněte si, že webové balíčky SRPM generují jak webové binární balíčky RPM, tak desktopové binární balíčky RPM.
$
publican package
Použijte příkaz $
publican package --lang=Kod_Jazyka, abyste sbalili dokumenty pro šíření v jazyku, který jste uvedli ve volbě --lang
. Více informací o kódech jazyků viz F – „Jazykové kódy“.
Spustíte-li příkaz $
publican package bez ostatních voleb, než je povinná --lang
, Publican zpracuje webový balíček SRPM. Úplný rozsah voleb pro publican package je následující:
--lang
jazykuvádí jazyk, pro který se připraví balíček dokumentace.
Není-li překlad do určitého jazyka dokončen v termínu vydání, zvažte jeho označení parametrem ignored_translations
v souboru publican.cfg
dokumentu. Balíček bude pojmenován dle jazyka, ale bude raději než částečný překlad obsahovat dokumentaci v originálním jazyce dokumentu XML. Je-li překlad dokončen, odstraňte parametr ignored_translations
, zvyšte číslo vydání v poli Project-Id-Version
v souboru Book_Info.po
pro tento jazyk a opět vygenerujte balíček. Jakmile revidovaný balíček rozšíříte, bude k dispozici za originální nepřeložený balíček.
--config
nazevsouboru
stanoví, že by Publican měl použít jiný konfigurační soubor, než je výchozí soubor publican.cfg
.
--desktop
stanoví, že by Publican měl vytvořit raději desktopový balíček RPM než webový.
--brew
stanoví, že by Publican měl nahrát celý balíček do Brew. Brew je interní sestavovací systém používaný společností Red Hat; tato volba nemá vně Red Hat význam.
--scratch
při použití spolu s volbami --brew
a --desktop
stanoví, že balíček SRPM by měl být po odeslání do Brew sestaven jako náčrt sestavení. Náčrty (scratch) sestavení se využívají k ověření, zda je balíček SRPM správně strukturován, bez oznámení databázi balíčků, aby výsledný balíček používala.
--short_sighted
stanoví, aby Publican sestavil balíček bez uvedení čísla verze softwaru (version
v souboru publican.cfg
) v názvu balíčku.
Mnoho dokumentace softwaru se týká pouze dané verze. V nejlepším případě postupy popsané v dokumentaci pro jednu verzi produktu vám nepomohou s instalací, nastavením nebo užíváním jiné verze produktu. V horším případě popsané postupy v dokumentaci pro jednu verzi mohou být zmatečné nebo dokonce škodlivé, pokud se použijí u jiné verze.
Šíříte-li dokumentaci jako balíčky RPM bez čísel verzí v jejich názvech, Správce balíčků RPM na uživatelově počítači automaticky nahradí existující dokumentaci dokumentací nejnovější verze; uživatelé nebudou mít přístup k dokumentaci pro více než jednu verzi softwaru najednou. Velmi dobře se ujistěte, že toto skutečně chcete.
--binary
stanoví, že Publican sestaví balíček jako binární balíček RPM.
Po spuštění příkazu $
publican package zapíše Publican dokončené balíčky SRPM do adresáře dokumentu tmp/rpm
a dokončené binární balíčky RPM do adresáře tmp/rpm/noarch
.
Standardně je název balíčku dokumentace vytvořený v Publicanu složen následovně:
productname-title-productnumber-[web]-language-edition-pubsnumber. [.[build_target].noarch].pripona_souboru
.
Publican používá pro získání různých parametrů do názvu souboru informace z konfiguračního souboru dokumentu (standardně publican.cfg
), až poté informace ze souboru Book_Info.xml
pro kterékoliv chybějící parametry v konfiguračním souboru. Podrobnosti o parametrech používaných v těchto souborech viz 4.1 – „Soubory v adresáři knihy“. Navíc si všimněte, že:
webové balíčky RPM obsahují prvek -web-
mezi verzí produktu a kódem jazyka.
balíčky SRPM mají příponu souboru .src.rpm
, ale binární balíčky RPM ji mají .rpm
binární balíčky RPM obsahují před příponou souboru build_target.noarch
, kde build_target představuje operační systém a verzi, pro níž je balíček sestaven dle nastavení parametru os_ver
v souboru publican.cfg
. Prvek noarch
stanoví, že balíček lze instalovat na kterýkoliv systém, bez ohledu na jeho architekturu.
použití volby --short_sighted
odstraní z názvu balíčku -productnumber-
balíčky přeložených dokumentů získávají svá čísla vydání z parametru Project-Id-Version
v souboru Article_Info.po
nebo Book_Info.po
. Toto číslo vydání je specifické pro příslušný jazyk a nemá žádný vztah k číslům vydání toho samého dokumentu v originálním jazyce nebo kteréhokoliv jiného jazyka.
$
publican package — Ukázka použitíNásledující příklady ukazují některé časté volby, pro příklady je použito Foomaster 9 Configuration Guide, edition 2, revision 6.
$
publican package --lang=cs-CZvytvoří webový balíček SRPM nazvaný Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.src.rpm, který obsahuje zdrojové soubory XML v češtině, spolu se souborem spec.
$
publican package --desktop --lang=cs-CZvytvoří desktopový balíček SRPM nazvaný Foomaster-Configuration_Guide-9-cs-CZ-2-6.src.rpm, který obsahuje zdrojové soubory XML v češtině, spolu se souborem spec.
$
publican package --binary --lang=cs-CZvytvoří jak webový binární balíček RPM nazvaný Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.el5.noarch.rpm, tak desktopový binární balíček RPM nazvaný Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm, které obsahují dokumentaci v češtině, sestavené pro operační systém Red Hat Enterprise Linux 5.
$
publican package --desktop --binary --lang=cs-CZvytvoří desktopový binární balíček RPM nazvaný Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm, který obsahuje dokumentaci v češtině, sestavený pro operační systém Red Hat Enterprise Linux 5.
$
publican package --desktop --short_sighted --lang=cs-CZvytvoří desktopový balíček SRPM nazvaný Foomaster-Configuration_Guide-cs-CZ-2-6.src.rpm, který obsahuje dokumentaci v češtině. Tento balíček nahradí příručku nastavení pro kterékoliv předchozí verze aplikace Foomaster, které se nachází na systému. Uživatelé mají přístup k Foomaster 9 Configuration Guide, nikoliv však Foomaster 8 Configuration Guide.
Někdy můžete chtít udržovat několik verzí knihy; na příklad příručka JAK NA TO pro produkt TOTO může mít dodavatelskou (upstream) verzi a prodejní (enterprise) verzi, s velmi nepatrnými rozdíly mezi sebou.
Publican vám jednoduše umožní řídit rozdíly mezi několika verzemi knihy s využitím jediného zdroje pro všechny verze. Podmíněné tagování vám pomůže zajistit, aby se obsah, který se týká pouze jedné verze, objevil pouze v té správné verzi; to znamená, že obsah zapodmínkujete.
Abyste zapodmínkovali obsah v knize, použijte u tagu atribut condition. Na příklad řekněme, že kniha Jak používat produkt Toto má "dodavatelskou", "prodejní" a "beta" verzi:
<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>
Příslušnou verzi sestavíte (a proto zachytíte všechen obsah, který je opatřen podmínkou této verze) přidáním parametru condition: verze do souboru publican.cfg
a spuštěním běžného příkazu $
publican build. Na příklad přidáte-li do souboru publican.cfg
knihy Jak používat produkt Něco condition: dodavatelska
a spustíte:
$
publican build --formats=pdf --langs=en-US
Publican odfiltruje všechny tagy s jiným podmíněným atributem než condition="dodavatelska"
a sestaví soubor PDF knihy Jak používat produkt Něco v americké angličtině.
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">
.
Podmíněné tagování používejte v knihách, které budou překládány, pouze s velkou opatrností, neboť podmíněné tagování vytváří pro překladatele další překážky.
Podmíněné tagování vytváří nesnáze pro překladatele dvěma způsoby: činí obsah v souborech portable object (PO), se kterými pracují překladatelé, nejasný a kontrolu správnosti překladu činí obtížnější pro překladatele, kteří nejsou příliš seznámeni s knihou a všemi vámi nastavenými podmínkami.
Soubory PO dokumentu obsahují úplnou sadu tagů ze souborů XML, bez ohledu na nastavené podmínky. Otevřou-li překladatelé soubor PO na příklad z ukázky Jak používat produkt Něco v 4.9 – „Podmíněné tagování“, uvidí:
#. Tag: para #, no-c-format msgid "<application>Toto</application> se při spuštění systému spustí automaticky." msgstr "" #. Tag: para #, no-c-format msgid "<application>Toto</application> se spustí při spuštění systému automaticky pouze, pokud je také nainstalováno <application>Tamto</application>." msgstr "" #. Tag: para #, no-c-format msgid "<application>Toto</application> se při spuštění systému automaticky nespustí." msgstr "" #. Tag: para #, no-c-format msgid "Chcete-li, aby se <application>Toto</application> spustilo při spuštění systému automaticky, upravte soubor <filename>/etc/init.d/toto</filename>." msgstr ""
Protože vkládání (include) souborů PO nezahrnuje do sebe atributy tagů, není zde nic patrného, co by naznačovalo překladatelům, že tyto odstavce jsou si vzájemnými alternativami a že autor nezamýšlí, aby text postupně po odstavcích dával smysl.
V této ukázce dává posloupnost textu logický smysl pouze mezi odstavcem tři a čtyři. Neboť oba tyto odstavce patří do knihy v beta verzi produktu, dávají (doufejme) dohromady smysl. Navíc použití podmínek v tomto místě vyžaduje, aby překladatelé překládali jednotlivé malé úryvky obsahu bez schopnosti sledovat kontext od jednoho odstavce k dalšímu. Pokud musí překladatelé pracovat za těchto podmínek, kvalita překladu trpí, nebo potřebný čas — a tedy náklady na překlad — rostou.
Dále pokud překladatelé, kteří pracují na knize, netuší jak nastavovat soubor publican.cfg
Publicanu a nemají ponětí o platných podmínkách pro knihu, nemohou zpětně kontrolovat svou práci. Bez těchto znalostí se budou při své kontrole dokumentu tázat, proč nemohou v dokumentu nalézt text, o kterém vědí, že ho přeložili, přitom ho lze snadno nalézt v souboru PO. Musíte-li v knize používat podmínky, buďte připraveni poskytovat překladatelům podporu v mnohem větším rozsahu, než běžně poskytujete.
Jako náhradu za podmínky zvažte, zda nebude vhodnější udržovat různé verze knihy v různých větvích v repozitáři se správou verzí. Stále budete moci sdílet soubory XML a dokonce i soubory PO mezi různými větvemi, jak bude nezbytné, a některé systémy se správou verzi vám umožní sdílet změny přímo mezi větvemi.
Udržujete-li dvě verze knihy ve stejném repozitáři, doporučujeme používat pro každou verzi samostatný konfigurační soubor. Na příklad soubor dodavatel.cfg
může obsahovat podmínku condition: dodavatelska
a prodejni.cfg
podmínku condition: prodejni
. Uvést verzi dokumentu, která se má sestavit nebo sbalit, lze volbou --config
; na příklad $
publican package --lang en-US --config prodejni.cfg. Použití dvou samostatných konfiguračních souborů vás chrání před nutností upravovat jeden konfigurační soubor pokaždé, kdy sestavujete nebo balíte dokument.
Dokončená dokumentace pro software, který se nachází ve stavu před svým oficiálním zveřejněním (pre-release), není to samé, jako je dokumentace v návrhu.
Návrhy dokumentace jsou nedokončené verze knihy nebo článku a jejich nedokončený stav nemá nic společného se stavem softwaru, který dokumentují.
V obou případech je však důležité stav softwaru, dokumentace nebo obojího jasně vysvětlit uživatelům, vývojářům, čtenářům či recenzentům.
Dokumentace pro software před jeho oficiálním zveřejněním, zejména takový, který je šířen těm, kdo ho testují, zákazníkům nebo partnerům, by měla nosit jasný znak, který upozorní na stav beta softwaru.
Pro vytvoření tohoto znaku proveďte následující:
Přidejte číslo neoficiální verze softwaru, popř. jinou odpovídající informaci o jeho stavu, do tagu <subtitle>
v souboru Book_Info.xml
. Tento doplňující text umístěte mezi tagy <remark>
. Na příklad:
<subtitle>Používání Red Hat Enterprise Warp Drive<remark> Verze 1.1, Beta 2</remark></subtitle>
přidejte show_remarks
do souboru publican.cfg
a nastavte ho na '1':
show_remarks: 1
Je-li kniha sestavena s tímto tagem <remark>
a nastavením show_remarks
, je neoficiální povaha softwaru zřetelně a nezaměnitelně zobrazena. Sestavení PDF zobrazí poznámku na obálce a titulních stranách. Sestavení HTML (jak jedno- tak vícestránkové HTML) zobrazí poznámku blízko začátku index.html
.
Jelikož tento přístup nikterak nemění informace v Book_Info.xml
využívaném pro tvorbu balíčků RPM, zajišťuje rovněž, že se ve fungování subsystému RPM nevyskytují nejednoznačnosti.
Příklad 4.7. Příklad inline poznámky
Zde máme příklad inline poznámky.
Odstranění tagu <remark>
a jeho obsahu a odstranění či vypnutí show_remarks
je na odpovědnosti autora při aktualizaci dokumentace, jež má být používána s veřejnou (oficiální) verzí softwaru.
Nedokončená dokumentace, která je dána k dispozici druhým k recenzi, by tak měla být označena.
Vodoznak návrhu přidáte do dokumentace přidáním atributu status="draft"
do tagu <article>
, <book>
či <set>
v kořenovém uzlu dokumentu. Na příklad:
<book status="draft">
Ve výchozím nastavení je kořenovým uzlem tag <book>
v souboru Nazev_Dok.xml
.
Pracujete-li na článku nebo sadě, kořenovým uzlem je tag <article>
či <set>
v Nazev_Dok.xml
.
Přidání atributu status="draft"
způsobí, že každá stránka dokumentu zobrazí vodoznak návrhu. Takto je Publican navržen.
I pokud změníte před odesláním k recenzi pouze část díla, označení každé stránky jako návrh povzbudí recenzenty k hlášení chyb nebo překlepů, které zaznamenají při čtení. Zajistí také to, že ti, kdo se nepodílí na recenzi, a tudíž kontrole, a přesto dílo zaznamenají, si návrh nezamění za dokončenou verzi.
Příklad 4.8. Příklad bloku označeného za návrh
Toto je příklad bloku textu, který je označen za návrh
Není to krása?!
Chcete-li označit nedokončenou dokumentaci softwaru, který se nachází ve stavu před oficiálním zveřejněním, postupujte podle výše uvedených postupů.
DocBook umožňuje u mnoha prvků nastavit přiznak v podobě atributu revisionflag
, který slouží k snadnější revizi změněných dokumentů. Publican od verze 4.1 tyto prvky zvýrazňuje, nachází-li se kniha v režimu návrhu. Např. revisionflag="added"
.
Takto by měl být označkován prvek, který byl v nové revizi přidán.
Takto by měl být označkován prvek, který byl v nové revizi upraven/změněn.
Takto by měl být označkován prvek, který je označen pro výmaz z nové revize. Publican tento obsah automaticky neodstraní ani neskryje, musíte zajistit vy, aby se tak stalo před zveřejněním.
Grafické úpravy (pozn. překl.: anglicky "brand") jsou sbírky souborů, které používá Publican k uplatnění jednotného vzhledu a stylu na výstupy HTML a PDF. Poskytují předpřipravený text, který se zobrazí na začátku dokumentů, obrázky, jako jsou loga, a stylistické prvky, jako jsou barevná schémata. Publican je šířen s jednou grafickou úpravou, common/
. Dokumentační projekty mohou vytvářet a šířit grafické úpravy pro své přispěvatele, ať již jako balíček (např. balíček RPM) nebo jako archiv (např. tarball nebo soubor ZIP).
Grafické úpravy Publicanu pro dokumenty Fedory, Genome a oVirt jsou ve Fedoře k dispozici v podobě balíčků RPM. Podobně Red Hat interně šíří balíčky RPM, které obsahují grafické úpravy Publicanu pro dokumenty GIMP, JBoss a Red Hat. Máte-li přístup k příslušným repozitářům, lze tyto grafické úpravy nainstalovat na počítač, kde běží Red Hat Enterprise Linux nebo Fedora — nebo operační systémy na nich založené — příkazem yum install publican-grafickauprava nebo grafickým správcem balíčků, jako např. PackageKit.
Používáte-li Publican na operačním systému, který nepoužívá balíčky RPM, váš dokumentační projekt může poskytovat svou grafickou úpravu v jiném formátu. Ať již je formát, ve kterém se grafická úprava poskytuje, jakýkoliv, musíte soubory grafické úpravy umístit do podadresáře adresáře Common_Content
Publicanu. Standardně se tento adresář na operačních systémech Linux nachází v /usr/share/publican/Common_Content
, u operačních systémů Windows v %SystemDrive%/%ProgramFiles%/Publican/Common_Content
— obvykle tedy C:/Program Files/Publican/Common_Content
Jak je uvedeno níže, každá v současnosti dostupná grafická úprava je šířena pod svojí vlastní licencí:
Chcete-li nainstalovat grafickou úpravu:
Byla-li vám grafická úprava poskytnuta jako archiv některého druhu, na příklad tarball nebo soubor ZIP, rozbalte grafickou úpravu na svém systému do nového adresáře.
Přejděte do adresáře, ve kterém jste vytvořili, nebo do něhož jste rozbalili grafickou úpravu:
$
cd publican-grafickauprava
kde grafickauprava je název grafické úpravy.
Sestavte grafickou úpravu:
$
publican build --formats xml --langs all --publish
Nainstalujte grafickou úpravu:
$
sudo publican install_brand --path cesta
kde cesta je cesta k souborům Common Content Publicanu. Na příklad na Linuxovém systému spusťte:
$
sudo publican install_brand --path /usr/share/publican/Common_Content
nebo na systému Windows spusťte:
$
publican install_brand --path "C:/Program Files/Publican/Common_Content"
Tabulka 5.1. Současné grafické úpravy a jejich balíčky
Grafická úprava | Licence souborů Common Content | Výchozí licence pro dokumenty | Balíček | Poznámka |
---|---|---|---|---|
common | CC0 1.0 | GFDL Version 1.2 | publican | Licence kompatibilní s GPL. Žádné možnosti. |
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 | Žádné možnosti. |
oVirt | OPL 1.0 | OPL 1.0 | publican-ovirt | Žádné možnosti. |
GIMP | GFDL Version 1.2 | GFDL Version 1.2 | publican-gimp | Odpovídá licenci pro existující dokumentaci GIMPu. |
Genome | OPL 1.0 | OPL 1.0 | publican-genome | Žádné možnosti. |
Všimněte si rozdílů v licencování mezi soubory common content poskytovaných v grafické úpravě common (CC0) a výchozí licencí nastavenou pro knihy vytvořené s touto grafickou úpravou (GFDL). CC0 licence povoluje další šíření a přelicencování souborů tvořících tuto grafickou úpravu (včetně obrazových a CSS souborů) dle potřeb vašeho projektu. Publican navrhuje používat pro dokumentaci jako výchozí licenci GFDL, neboť Publican je především vyvíjen pro sestavování dokumentace k softwaru. Licence GFDL je kompatibilní s licencí GPL, která je nejčastěji běžně používanou licencí pro open-source software.
Novou grafickou úpravu vytvoříte pomocí akce $
create_brand. Při vytváření nové grafické úpravy ji musíte pojmenovat a pro její soubory XML určit původní jazyk. Volba --name
poskytuje název a volba --lang
určuje jazyk. Celý příkaz tedy vypadá takto:
$
publican create_brand --name=grafickauprava --lang=kod_jazyka
Publican vytvoří nový podadresář nazvaný publican-grafickauprava
, kde grafickauprava je graficka uprava, kterou jste uvedli ve volbě --name
.
Chcete-li na příklad vytvořit grafickou úpravu nazvanou Acme
, jejíž soubory XML Common Content jsou napsány původně v americké angličtině, spusťte:
$
publican create_brand --name=Acme --lang=en-US
Publican vytvoří grafickou úpravu v podadresáři nazvaném publican-Acme
.
Chcete-li měnit nastavení své grafické úpravy, hledejte ve výchozích souborech vytvořených Publicanem slovo SETUP
a upravte tyto soubory doplněním chybějících údajů. Na linuxových operačních systémech lze vyhledávat příkazem:
$
grep -r 'SETUP' *
Spuštění příkazu $
publican create_brand --name=grafuprava --lang=kód_jazyka vytvoří adresářovou strukturu s potřebnými soubory. Adresář grafické úpravy prvně obsahuje:
COPYING
defaults.cfg
overrides.cfg
publican.cfg
publican-grafuprava.spec
, kde grafuprava je název grafické úpravy.
README
podadresář pro soubory XML, styly CSS a výchozí obrázky grafické úpravy. Podadresář je nazvaný dle kódu původního jazyka grafické úpravy (na příklad en-US
). Těmito soubory jsou:
Feedback.xml
Legal_Notice.xml
podadresář css
, který obsahuje:
overrides.css
podadresář images
, který obsahuje 43 obrazových souborů jak v rastrovém (PNG), tak vektorovém (SVG) formátu.
Soubor publican.cfg
v grafické úpravě slouží podobnému účelu jako publican.cfg
dokumentu — nastavuje několik základních voleb, které určují grafickou úpravu.
version
určuje číslo verze grafické úpravy. Když vytvoříte grafickou úpravy příkazem $
publican create_brand, číslo verze je nastaveno na 0.1
. Až připravíte novou verzi grafické úpravy, zaktualizujte číslo verze zde, v souboru publican.cfg
grafické úpravy, a v souboru publican-grafuprava.spec
.
Všimněte si, že parametr nemá žádný vztah k číslu verze dokumentů sestavených s danou grafickou úpravou. Na příklad Instalační příručka Fedory 12 má svou verzi nastavenu v souboru publican.cfg
na 12
, ale lze ji sestavit s verzí 1.0 grafické úpravy publican-fedora.
xml_lang
určuje jazyk zdrojových souborů XML Common Content grafické úpravy, na příklad en-US
, nastavován volbou --lang
u příkazu $
publican create_brand.
release
určuje číslo vydání grafické úpravy. Když vytvoříte grafickou úpravu příkazem $
publican create_brand, číslo vydání je nastaveno na 0
. Až připravíte nové vydání existující verze grafické úpravy, zaktualizujte číslo verze zde, v souboru publican.cfg
grafické úpravy, a v souboru publican-grafuprava.spec
.
type
je-li nastaven na type: brand
, parametr označí položky tohoto adresáře za grafickou úpravu, nikoliv za knihu, článek či sadu.
brand
určuje název grafické úpravy, nastavován volbou --name
u příkazu $
publican create_brand.
web_cfg
úplná cesta ke konfiguračnímu souboru webových stránek vytvořených Publicanem pro nestandardní webové stránky RPM.
web_dir
úplná cesta, kam se soubory nainstalují. Musíte rovněž nastavit wwwdir v publican-brand.spec
.
web_req
název balíčku RPM, který poskytne konfigurační soubor webových stránek vytvořených v Publicanu.
Každý dokument sestavený v Publicanu má ve svém kořenovém adresáři soubor publican.cfg
, který nastavuje pro dokument sestavovací volby. Úplný popis těchto voleb viz 4.1.1 – „Soubor publican.cfg“. Soubor defaults.cfg
a overrides.cfg
v grafické úpravě poskytují výchozí hodnoty pro kterékoliv parametry, které lze jinak nastavit v souboru publican.cfg
dokumentu.
Sestavíte-li dokument s danou grafickou úpravou, Publican uplatní před hodnotami v souboru publican.cfg
dokumentu nejdříve hodnoty ze souboru defaults.cfg
grafické úpravy. Proto hodnoty v souboru publican.cfg
dokumentu nahradí ty, které se nacházejí v souboru defaults.cfg
grafické úpravy.
Poté Publican uplatní hodnoty ze souboru overrides.cfg
grafické úpravy, které proto nahradí kterékoliv hodnoty ze souboru defaults.cfg
grafické úpravy a publican.cfg
dokumentu.
Soubor defaults.cfg
využívejte pro nastavení hodnot, které rutinně uplatňujete u své grafické úpravy, ale chcete umožnit autorům je změnit v určitých knihách; soubor overrides.cfg
využívejte pro hodnoty, u kterých nechcete, aby je autoři měnili.
Lze přidat seznam nepovolených tagů nebo atributů použitím banned_tags či banned_attrs jak do defaults.cfg
, tak overrides.cfg
. Tyto budou vypsány do seznamu akcí print_banned Publicanu.
Některé operační systémy Linux používají Správce balíčků RPM pro šíření softwaru, v podobě balíčků RPM. Obecně balíček RPM obsahuje soubory softwaru komprimovaných do archivu, doplněný o soubor spec, který sděluje Správci balíčků RPM, jak a kam má tyto soubory nainstalovat.
Když vytvoříte grafickou úpravu, Publican vytvoří pro grafickou úpravu jakýsi návrh souboru spec RPM. Tento automaticky vygenerovaný soubor spec vám poskytne startovací čáru, ze které lze vytvořit balíček RPM pro šíření své grafické úpravy. Jak nastavit soubor spec a použít ho k vytvoření balíčku RPM viz 5.4 – „Balení grafické úpravy“.
Soubor README
obsahuje stručný popis balíčku grafické úpravy.
Soubor COPYING
obsahuje podrobnosti o licenci k autorskému dílu balíčku a snad i text samotné licence.
Uvnitř adresáře grafické úpravy je podadresář nazvaný dle výchozího jazyka XML grafické úpravy, který se nastavuje volbou --lang
, když ji vytváříte. Tento podadresář obsahuje soubory XML a obrazové soubory, které nahradí výchozí Common Content (společný obsah) dodávaný s Publicanem. Vaše vlastní (zákaznická) úprava těchto souborů poskytne grafické úpravě odlišný vzhled, včetně barevného schématu a loga.
Feedback.xml
Soubor Feedback.xml
je standardně obsažen v předmluvě každé knihy vytvořené v Publicanu. Nabádá čtenáře k zanechání zpětné vazby k dokumentu. Tento soubor si (zákaznicky) upravte s kontaktními informacemi svého projektu. Používá-li váš projekt systém pro sledováni chyb, jako např. Bugzilla, JIRA nebo Trac, můžete zde zahrnout příslušné informace.
Legal_Notice.xml
Soubor Legal_Notice.xml
obsahuje právní doložku, která se nachází na začátku každého dokumentu vytvořeného v Publicanu. Do tohoto souboru vložte podrobnosti o vámi zvolené licenci k autorskému dílu. Obvykle zahrnují název, krátké shrnutí a odkaz na úplné podrobnosti licence.
css
Podadresář css
obsahuje jediný soubor: override.css
Soubor css
nastavuje vizuálni styl grafické úpravy. Hodnoty v tomto souboru nahradí ty v souboru Common_Content/common/jazyk_xml/css/common.css
Publicanu.
images
Podadresář images
obsahuje 43 obrazových souborů jak ve formátu přenosné síťové grafiky (PNG), tak škálovatelné vektorové grafiky (SVG). Tyto soubory jsou předpřipravené nahraditelné obrazy pro různé navigační ikony, upozorňovací grafiku a loga grafické úpravy. Mezi nimi:
image_left
je logo produktu, na který se dokument vztahuje. Umístěn je v levém horním rohu stránek HTML, kde obsahuje hypertextový odkaz na webovou stránku produktu, určený parametrem prod_url
v souboru publican.cfg
dokumentu. Zvažte nastavení prod_url
v souboru defaults.cfg
či overrides.cfg
grafické úpravy.
image_right
je logo týmu, který vytváří tento dokument. Je umístěn v pravém horním rohu stránek HTML, kde obsahuje hypertextový odkaz na webovou stránku dokumentačního týmu, určený parametrem doc_url
v souboru publican.cfg
dokumentu. Je-li všechna dokumentace s touto grafickou úpravou vytvářena stejným týmem, zvažte nastavení doc_url
v souboru defaults.cfg
či overrides.cfg
grafické úpravy.
title_logo
je větší verze loga produktu, které se zobrazuje na titulní straně dokumentů PDF a na začátku dokumentů HTML.
note
, important
, warning
jsou ikony, které doprovázejí upozornění v XML <note>
, <important>
a <warning>
.
dot
, dot2
jsou odrážky pro položky <listitem>
seznamů <itemizedlist>
.
stock-go-back
, stock-go-forward
, stock-go-up
, stock-home
jsou navigační ikony pro stránky HTML.
h1-bg
je pozadí nadpisu, který obsahuje název produktu, jenž je umístěn na úplném začátku dokumentu HTML.
watermark_draft
je vodoznak, který je zobrazen na stránkách dokumentace v návrhu. Viz 4.10.2 – „Označování návrhu dokumentace“.
Sestavovací volba brand_dir Publicanu umožňuje uvést umístění souborů grafické úpravy. Tyto soubory nemusí být součástí nainstalované grafické úpravy.
Můžete distribuovat vlastní (zákaznicky) upravené XSL ve složce xsl
své grafické úpravy: nachází se na stejné úrovni jako různé jazykové soubory vaší grafické úpravy. Publican používá kterékoliv XSL, které v tomto adresáři najde, k nahrazení šablon XSL, které jsou poskytovány v grafické úpravě common (která naopak nahrazuje šablony XSL dodávané projektem DocBook).
Grafické úpravy s vlastními (zákaznicky) upravenými XSLT potřebují změnit relativní cestu pro odkazování šablon XSL na URI.
Tento oddíl rozebírá tvorbu balíčků dokumentů, které se distribuují pomocí Správce balíčků RPM. Ačkoliv příkazem $
publican package vygeneruje Publican balíček s archivem, tarball, který lze použít k sestavení balíčku pro distribuci pomocí různého softwaru pro správu balíčků. Spustíte-li příkaz publican package na počítači, na kterém není nainstalován rpmbuild, Publican přesto vygeneruje tento tarball, i když pak z něj nemůže vygenerovat balíček RPM.
Poté, co vytvoříte grafickou úpravu (popsáno v 5.2 – „Vytvoření grafické úpravy“), Publican vám může pomoci s jejím rozšířením mezi členy vašeho dokumentačního projektu, jako balíček RPM. Balíčky RPM jsou používány k šíření softwaru na počítače s operačními systémy Linux, které používají Správce balíčků RPM. Mezi těmito operačními systémy jsou Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, Yellow Dog Linux, a další.
Publican může vytvářet jak zdrojové balíčky RPM (balíčky SRPM), tak binární balíčky RPM. Jako součást tohoto procesu vytváří také soubor spec — soubor, který obsahuje podrobnosti o tom, jak je balíček konfigurován a instalován.
Balíčky SRPM obsahují místo samotného softwaru zdrojový kód, ze kterého se software generuje. Aby se dal balíček SRPM použít, počítač musí zdrojový kód přeložit do softwaru. Balíčky SRPM grafických úprav Publicanu obsahují konfigurační soubory, soubory XML a obrazové soubory, které definují grafickou úpravu ve svém původním jazyce, plus soubory PO, které generují soubory Common Content u přeložených jazyků. Nelze instalovat dokumentaci přímo z balíčků SRPM se současnými verzemi Správce balíčků RPM.
Naopak binární balíčky RPM obsahují software — v tomto případě grafickou úpravu Publicanu — ten je připraven ke zkopírování do místa v souborovém systému počítače a okamžitému použití. Obsah binárního balíčku RPM se nemusí překládat počítačem, na kterém jsou instalovány, a proto tento počítač nemusí mít nainstalován ani Publican.
Chcete-li zabalit grafickou úpravu, použijte příkaz $
publican package v adresáři grafické úpravy. Je-li příkaz použit bez dalších voleb, Publican vytvoří balíček SRPM. Volby pro zabalení grafické úpravy jsou tyto:
--binary
uvádí, aby Publican sestavil balíček jako binární balíček RPM.
--brew
uvádí, aby Publican odeslal dokončený balíček do Brew. Brew je sestavovací systém, který je interně používán ve společnosti Red Hat; tato volba nemá význam mimo Red Hat.
--scratch
spolu s volbou --brew
stanoví, aby byl balíček SRPM po odeslání do Brew sestaven jako náčrt sestavení. Náčrty (scratch) sestavení se využívají k ověření, zda je balíček SRPM správně strukturován, bez oznámení databázi balíčků, aby výsledný balíček používala.
Volby --lang
, --desktop
a --short_sighted
, které se uplatňují při balení knih (popsáno v 4.8 – „Balení dokumentu“ nemají smysl pro balení grafických úprav. Zejména si všimněte, že ačkoliv volba --lang
je povinná pro balení knihy, pro balení grafické úpravy ji nepotřebujete.
Ve výchozím nastavení má název grafické úpravy vytvořené v Publicanu podobu:
publican-grafuprava-verze-vydani.cil_sestaveni.noarch.pripona_souboru
.
Publican využívá pro získání parametrů do názvu souboru informace ze souboru publican.cfg
. Podrobnosti o konfiguraci tohoto souboru viz 5.3.1 – „Soubor publican.cfg“. Dále:
Balíčky SRPM mají příponu souboru .src.rpm
, ale binární balíčky RPM mají příponu .rpm
binární balíčky RPM mají před příponou souboru cil_sestaveni.noarch
, kde [cil_sestaveni] zastupuje operační systém a verzi, pro který je balíček sestaven, dle nastavení parametru os_ver
v souboru publican.cfg
. Prvek noarch
uvádí, že balíček lze nainstalovat na kterýkoliv systém bez ohledu na jeho architekturu.
Sada je soubor knih zveřejněný jako celek. Na příklad Services Plan je sada skládající se z mnoha knih, jako např. Developer Guide, Engineering Content Services Guide a Engineering Operations Guide. Šablonu sady vytvoříte příkazem $
create_book nastavením parametru type
na Set
.
Jsou dva druhy sad:
samostatné sady
distribuované sady
Samostatná sada obsahuje soubory XML každé knihy, všechny jsou umístěny uvnitř adresáře sady. Samostatné sady se vždy sestavují jako celek; bez úprav nelze sestavit samostatně jednotlivé knihy.
Postup, který následuje, vás provede procesem vytvoření samostatné sady s názvem Moje Sada umístěné v adresáři knihy/Moje_Sada/
. Sada se bude skládat z Knihy A a Knihy B, jež obě budou vytvořeny ručně uvnitř adresáře knihy/Moje_Sada/en-US
.
Postup 6.1. Tvorba samostatné sady
Vytvořte sadu nazvanou Moje_Sada
s grafickou úpravou ve stylu Red Hat, a ve které bude XML napsáno v americké angličtině, spuštěním následujícího příkazu v shellu v adresáři knihy/
:
publican create --type=Set --name=Moje_Sada --brand=RedHat --lang=en-US
Přejděte příkazem $
cd do adresáře Moje_Sada/en-US
a vytvořte dva adresáře (nikoliv knihy) nazvané Kniha_A
a Kniha_B
.
$
cdMoje_Sada/en-US
$
mkdirKniha_A
Kniha_B
Přejděte příkazem $
cd do adresáře knihy/Moje_Sadaa/en-US/Kniha_A
. Vytvořte a upravte soubor Kniha_A.xml
, Book_Info.xml
, a kterékoliv další soubory xml, které kniha vyžaduje, jako např. soubory jednotlivých kapitol. Zajistěte, aby Kniha_A.xml
obsahoval správné odkazy xi:include
na všechny vaše soubory xml v adresáři. Na příklad obsahuje-li Kniha A Book_Info.xml
a Kapitola_1.xml
, soubor Kniha_A.xml
by měl mít podobu:
<?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>
Stejný postup použijte pro Knihu_B, jenž se nachází v adresáři knihy/Moje_Sada/en-US/Kniha_B
.
Otevřete soubor knihy/Moje_Sada/en-US/Moje_Sada.xml
v editoru. Přidejte pro každou knihu sady odkaz xi:include
na primární soubor xml knihy. Primární soubor xml Knihy A bude Kniha_A.xml
a Knihy B Kniha_B.xml
. Soubor Moje_Sada.xml
by nyní měl mít podobu:
<?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>
Abyste učinili XML sady validní, musíte změnit toto:
V souboru Moje_Sada.xml
zakomentujte tyto řádky:
<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>
V souboru Preface.xml
a Book_Info.xml
každé použité knihy přidejte na začátek každého řetězce Common_Content ../../. Na příklad:
<xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Je nutné změnit na:
<xi:include href="../../Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Je to nutné, neboť adresář Common Content je u samostatné sady vzdálen o dva adresáře od místa, kde ho Publican obvykle hledá. Proto je nutné toto oznámit ručně. Chcete-li svou knihu sestavit samostatně, bez sestavení celé sady, tento krok neprovádějte.
Sadu otestujte spuštěním příkazu publican build --formats=test --langs=en-US.
Používáte-li knihy, které již existují, je nutné je přeskupit tak, aby soubory XML byly na úrovni sady a všechny obrazové soubory uvnitř adresáře images na stejné úrovni. Na příklad:
-- 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
Soubory XML lze rovněž umístit do podadresářů tak, aby byly od sebe oddělené. To platí stejně i pro soubory v adresáři images. Na příklad:
-- 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
Distribuovaná sada obsahuje knihy, které se nacházejí v repozitáři se správou verzí. Ačkoliv existuje několik systémů se správou verzí, tato verze Publicanu podporuje pouze jeden: Subversion (SVN). Nastavením adresy repozitáře a názvů zahrnutých knih v souboru publican.cfg
lze každou knihu exportovat k sestavení celé sady. Postup, který následuje, vás provede skrze proces tvorby sady nazvané Moje Sada obsahující Knihu A a Knihu B.
Následující postup předpokládá, že Kniha A a Kniha B již existují a jsou dostupné v repozitáři SVN. V současnosti podporuje Publican pouze SVN.
Postup 6.2. Vytvoření sady
V shellu spusťte následující příkaz, kterým vytvoříte sadu s názvem Moje_Sada
v grafické úpravě Red Hat a v níž bude XML napsáno v americké angličtině.
$ publican create --type=Set --name=Moje_Sada --brand=RedHat --lang=en-US
Do souboru publican.cfg
doplňte tyto řádky:
books: Kniha_A Kniha_B repo: http://CESTA-K-REPOZITARI-SVN scm: SVN
Cesta k repozitáři by měla končit v místě před adresářem knihy, kterou potřebujete.
Otevřete soubor My_Set.xml
v editoru. Pro každou knihu ze sady přidejte odkaz xi:include
na primární soubor XML knihy. Primárním souborem XML Knihy A bude Kniha_A.xml
a Knihy B Kniha_B.xml
. Soubor Moje_Sada.xml
by měl nyní vypadat takto:
<?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>
Abyste učinili XML sady validní, je nutné v Moje_Sada.xml
zakomentovat následující řádky
<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>
Sadu otestujte spuštěním příkazu publican build --formats=test --langs=en-US.
Při sestavování sady bude vykonán příkaz publican clean_ids u každé knihy kvůli omezení, kdy ID musí být jedinečné napříč všemi knihami. Vyvarujte se vytvoření ID, která závisí na obsahu, který nemusí být k dispozici, když jsou knihy sestavovány nezávisle mimo sadu.
Publican nesestavuje ke zveřejnění pouze dokumenty, ale dokáže rovněž sestavit a spravovat webové stránky dokumentace. Publican lze použít k sestavení webových stránek na místním systému pro řadu dokumentů, které si udržujete; poté lze webové stránky nahrát na webový server způsobem dle své volby. Tento přístup však neškáluje nejlépe pro tzv. týmově založené dokumentační projekty, Publican dokáže generovat balíčky RPM dokumentace, které lze instalovat na webový server. Aby bylo možné instalovat balíčky RPM generované Publicanem na webový server, musí být na serveru nainstalován Publican (verze 2.1 nebo vyšší) a rpm. Sestavíte-li a udržujete-li webové stránky na pracovní stanici a nahrajete je ke zveřejnění na webový server, Publican a rpm nejsou na webovém serveru potřeba.
Webové stránky, které vytváří Publican, se skládají ze čtyř částí: struktura webových stránek, domovská stránka, stránky popisující produkt a verzi a (na webových stránkách) zveřejněné dokumenty. Struktura webových stránek se skládá z:
konfiguračního souboru,
souboru databáze SQLite,
podadresáře zveřejněných dokumentů, který obsahuje:
index.html
— stránku indexu, která přesměrovává na lokalizované verze domovské stránky webových stránek,
interactive.css
— styl CSS, který obsahuje styly navigační nabídky,
opds.xml
— katalog Open Publication Distribution System (OPDS), který umožňuje odpovídajícím čtečkám e-knih nalézt jednoduše dokumenty EPUB na webových stránkách,
Sitemap
— mapa webových stránek je seznam adres URL stránek na webových stránkách a jejich metadat, jako např. historie aktualizací, frekvence změn a relativní důležitost vůči jiným URL na webových stránkách. Mapu stránek lze poskytovat mnoha významným vyhledávačům, kde se používá pro jejich snazší a inteligentnější indexaci indexovacími automaty (crawlers). Mapa stránek nezaručuje, že vaše webové stránky budou ve vyhledávacích výsledcích umisťovány výše. Nicméně pomáhá vyhledávacím strojům vracet nejpodstatnější výsledky z webových stránek jako odpověď na dotazy uživatelů. Více informací o mapách stránek je k dispozici na sitemaps.org,
site_overrides.css
— styl CSS, který potlačuje styly obsažené v interactive.css
a poskytuje specifické styly webových stránek. Tento soubor není vytvořen při procesu vytvoření webových stránek, musí být přidán ručně později, nebo poskytnut domovskou stránkou webových stránek,
default.js
— skript JavaScript, který směruje návštěvníky na lokalizovaný obsah na základě nastavení národního prostředí v jejich prohlížeči a který řídí prezentaci navigační nabídky,
podadresáře každé zveřejněné jazykové verze. Zpočátku obsahují opds.xml
a toc.html
. Později obsahují rovněž opds-produkt.xml
:
opds.xml
— katalog dokumentů EPUB OPDS v daném jazyce,
opds-produkt.xml
— katalog dokumentu EPUB OPDS pro každý produkt, pro který v daném jazyce publikujete dokumentaci. V rámci každého produktového katalogu je dokumentace rozdělena do kategorií <category>
pro různé verze téhož produktu,
toc.html
— obsah v daném jazyce, nejprve bez odkazů na dokumenty,
podadresář pro každý produkt, pro který publikujete v daném jazyce dokumentaci.
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 7.1 – „Ruční sestavování webových stránek“ and 7.2 – „Sestavování webových stránek za použití balíčků RPM“ for details of creating a dump file, and to D – „Obsah souboru s výpisem webových stránek“ for a description of the dump file contents.
Chcete-li vystavět strukturu webových stránek:
Na své pracovní stanici vytvořte nový adresář a přejděte do něj. Na příklad na linuxovém systému spusťte:
$
mkdir ~/docsite$
cd ~/docsite
Spusťte publican create_site s uvedením těchto parametrů:
--site_config
— název konfiguračního souboru webových stránek, s příponou .cfg
--db_file
— název souboru databáze SQLite pro stránky, s příponou .db
--toc_path
— cesta k adresáři, do kterého budete ukládat své dokumenty
Na počítači s jiným operačním systémem než je Linux také nastavte:
--tmpl_path
— cesta k adresáři templates/
vaší instalace Publicanu. Na počítačích s operačními systémy Windows má obvykle cesta podobu %SystemDrive%\%ProgramFiles%\Publican\templates
.
Na příklad:
$
publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
Názvy konfiguračnímu souboru a souboru databáze webových stránek lze přidělit tak, aby bylo možné snadno rozlišit, ke kterým webovým stránkám patří. Na příklad pro webové stránky dokumentace FooMaster lze tyto soubory nazvat foomaster.cfg
a foomaster.db
. --toc_path
lze nastavit dle vlastního uvážení.
Konfigurační soubor webových stránek upravte tak, aby obsahoval název webových stránek, hostitelský počítač webu a volitelně parametry vyhledávání, výchozí jazyk, nastavení souboru dump a nastavení aktualizací pro webové stránky.
Název uveďte v parametru title
, na příklad:
title: "Foomaster Dokumentace"
Obvykle návštěvníci webových stránek tento název nevidí, neboť JavaScript stránek je přesměruje na domovskou stránku. Nicméně tento název bude k nalezení a oindexován vyhledávači.
Hostitelský počítač webových stránek uveďte v podobě úplné URL v parametru host
, včetně protokolu (na příklad http://
). Na příklad:
host: http://docs.example.com
Publican využívá hodnotu nastavenou v host
k sestavení adres URL v souboru XML Sitemap
, který vytváří pro indexovací automaty (crawlers) vyhledávačů a omezení vyhledávacích dotazů učiněných přes vyhledávací okno v navigační nabídce na výsledky pouze z vašich webových stránek.
Volitelně sestavte dotaz pro vyhledávač, který použijete ve vyhledávacím okně navigační nabídky a uveďte parametrem search
celý obsah <form>
HTML. Neuvedete-li své přizpůsobené vyhledávání na webu, Publican vytvoří vyhledávání Google omezené na hosta, který jste uvedli v parametru host
.
Na příklad chcete-li sestavit vyhledávání Yahoo! omezené na docs.example.com
, nastavte:
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>'
Podrobnosti o sestavování zákaznicky přizpůsobených vyhledávání naleznete v dokumentaci vybraného vyhledávače.
Nastavíte-li v kódu tlačítka pro odeslání value="###Search###"
, Publican použije slovo Search
pro tlačítko, lokalizované do kteréhokoliv jazyka, který Publican podporuje.
Publican neprovádí validaci u parametru search
, ale zabuduje hodnotu parametru do navigační nabídky zcela tak, jak jste ho uvedli. Buďte obzvláště opatrní, když tuto vlastnost využíváte.
Volitelně nastavte výchozí jazyk webových stránek. Publican vytváří samostatnou, přeložitelnou navigační nabídku pro každý jazyk, ve kterém zveřejňujete dokumentaci. Pokud dokument není v daném jazyce k dispozici, Publican přesměruje návštěvníky na nepřeloženou verzi dokumentu. Chcete-li nastavit výchozí, nepřekládaný jazyk webových stránek, nastavte v def_lang
kód jazyka. Na příklad:
def_lang: fr-FR
S nastaveným def_lang
na fr-FR
jsou návštěvníci při prohlížení navigační nabídky (na příklad) ve španělštině odkázáni na originální francouzskou verzi dokumentu, pokud dokument ještě nebyl do španělštiny přeložen.
Volitelně nastavte pro webové stránky soubor dump. Publican může vypsat soubor XML, který poskytuje podrobnosti o celém obsahu webových stránek a který lze využít pro doručování dalších služeb, jako např. webové zdroje/kanály nebo přizpůsobené prohledávání stránek. Tento soubor je aktualizován kdykoliv je nainstalována nebo odstraněna z webových stránek kniha, nebo je spuštěn příkaz $
publican update_site. Nastavte parametry dump
, dump_file
a zip_dump
takto:
dump
Nastavte dump: 1
, pokud chcete, aby soubor dump fungoval. Výchozí hodnotou parametru je 0
(vypnuto).
dump_file
Nastavte dump_file: nazev
uvedením názvu souboru dump a adresáře, do něhož ho Publican ukládá. Výchozí hodnotou parametru je /var/www/html/DUMP.xml
.
zip_dump
Nastavení zip_dump: 1
způsobí, že Publican bude tohoto souboru XML vytvářet také jeho zazipovanou verzi. Výchozí hodnotou parametru je 0
(vypnuto).
Popis obsahu souboru dump viz D – „Obsah souboru s výpisem webových stránek“.
Volitelně uveďte webový styl s 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)
Webové stránky obsahují drobečkovou navigační lištu na vrchu dokumentace.
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.
Volitelně uveďte parametrem manual_toc_update
, že obsahy na stránkách jsou aktualizovány ručně, na příklad:
manual_toc_update: 1
Publican obvykle aktualizuje obsahy na webových stránkách pokaždé, kdy je přidán nebo odstraněn balíček s dokumentací. Na stránkách s velkým množství dokumentů (více než několik stovek), nebo tam, kde jsou dokumenty aktualizovány častěji (desítky aktualizací týdně), může tento proces velmi zatěžovat server. Na velkých nebo často navštěvovaných stránkách doporučujeme, abyste nastavili tento parametr a poté pravidelně aktualizovali obsahy příkazem $
publican update_site.
Volitelně potlačte výchozí JavaScript pro webové stránky parametrem toc_js
, na příklad:
toc_js: "mojegrafuprava/scripty/megafoo.js"
Na tento soubor bude příkazem $
publican update_site vytvořen symbolický odkaz toc_path
/toc.js. Tato cesta by měla být vůči parametru toc_path
relativní.
Vytvořte prázdný soubor s názvem site_overrides.css
v adresáři, který jste uvedli v doc_path
(adresář, jenž obsahuje interactive.css
a různé jazykové adresáře). Chcete-li používat na webové stránky aplikovat zvláštní styly, které potlačí styly poskytované v interactive.css
, lze přidat site_overrides.css
do dokumentu, který poskytuje domovskou stránku webových stránek — viz 7.1.2 – „Vytvoření, instalace a aktualizace domovské stránky“. Nechcete-li používat zvláštní styly, prázdný soubor, který jste sem přidali, bude předcházet chybám 404 na vašem serveru. Na linuxovém systému se přesuňte do adresáře uvedeném v doc_path
a spusťte:
$
touch site_overrides.css
Sestavte a nainstalujte každou grafickou úpravu, včetně grafické úpravy common
Publicanu.
Přejděte do adresáře, v němž se nachází zdrojové soubory grafické úpravy.
$
cd brandsrc_dir
Sestavte grafickou úpravu.
$
publican build --formats=xml --langs=all --publish
Nainstalujte grafickou úpravu na webové stránky.
$
publican install_brand --web --path=cesta_ke_korenovemu_adresari_webstranek
Tyto kroky proveďte u všech grafických úprav.
Aktualizujte webové stránky.
$
publican update_site
Aby Publican aktualizoval strukturu stránek kdykoliv, spusťte:
$
publican update_site --site_config cesta_ke_konfiguracnimu_souboru_webstranek.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:
Přejděte do příhodného adresáře a spusťte následující příkaz publican create:
$
publican create --type Article --name nazev_stranky
Na příklad:
$
publican create --type Article --name Home_Page
Většina grafických úprav (včetně úpravy common
) zobrazí název dokumentu velkým, barevným písmem poblíž vrchu stránky, pod bannerem, v němž je uveden název produktu (volba --name
nastavuje tag <title>
). Proto se ve výchozím nastavení zobrazuje návštěvníkům webových stránek hodnota nastavená volbou --name
; ve výše uvedeném příkladu jsou návštěvníci přivítáni slovy Home Page
pod produktovým bannerem.
Přejděte do adresáře článku:
$
cd page_name
Na příklad:
$
cd Home_Page
V kořenovém souboru XML zrušte odkaz na Article_Info.xml
.
Pravděpodobně pouze málo z obsahu Article_Info.xml
bude užitečné pro vaše webové stránky. Proto upravte kořenový soubor XML domovské stránky odstraněním tagu <xi:include>
odkazujícího na Article_Info.xml
. Publican stále využívá informace z Article_Info.xml
pro vytváření balíčků, ale nezahrne ho do samotné stránky.
Upravte soubor publican.cfg
.
Alespoň jako nejnutnější musíte přidat parametr web_type
a nastavit ho na hodnotu 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
Chcete-li nastylizovat domovskou stránku shodně s vaší dokumentací, přidejte:
brand: nazev_grafupravy
docname
, product
Měl-li by <title>
nebo <product>
, který jste nastavili v souboru Article_Info
, obsahovat cokoliv jiného než základní latinské znaky bez diakritiky, nastavte docname
a product
, jak je nezbytné.
Upravte obsah souboru nazev_stranky.xml
(na příklad Home_Page.xml
), tak jako u kterýkoliv jiného dokumentu napsaného v DocBook.
Odstraníte-li <xi:include>
, který odkazuje na Article_Info.xml
, uveďte název stránky v tomto formátu:
<title role="producttitle">Dokumentace FooMaster</title>
Uveřejňujete-li dokumentaci ve více než jednom jazyce, vytvořte řadu souborů POT a PO pro každý jazyk příkazy $
publican update_pot a publican update_po.
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/
.
Zvláštní styly, které potlačí styly nastavené v souboru interactive.css
webových stránek, přidejte do souboru site_overrides.css
a umístěte ho do kořene zdroje dokumentu (stejný adresář, který obsahuje publican.cfg
a jazykové adresáře).
Sestavte domovskou stránku ve formátu jednostránkového HTML s volbou --embedtoc
a nainstalujte ji do struktury webových stránek. Na příklad:
$
publican build --publish --formats html-single --embedtoc --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Kod_Jazyka
Všimněte si, že lze sestavit všechny jazyky najednou, ale nainstalovat domovskou stránku v každém jazyce musíte jednotlivě příkazem $
publican install_book.
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:
Přejděte do vhodného adresáře a spusťte následující příkaz $
publican create:
$
publican create --type Article --name nazev_stranky
Na příklad stránka produktu by mohla být vytvořena takto:
$
publican create --type Article --name FooMaster
nebo stránka verze takto:
$
publican create --type Article --name FooMaster_3
Přejděte do adresáře článku:
$
cd nazev_stranky
Na příklad:
$
cd FooMaster
V kořenovém souboru XML odstraňte odkaz na soubor Article_Info.xml
.
Pravděpodobně pouze málo z obsahu souboru Article_Info.xml
bude k užitku pro stránky produktu nebo verze. Proto upravte kořenový soubor XML stránky odstraněním tagu <xi:include>
odkazujícího na Article_Info.xml
. Publican stále využívá informace z Article_Info.xml
pro vytváření balíčků, ale nezahrne ho do samotné stránky.
Upravte soubor publican.cfg
.
Alespoň jako nejnutnější musíte přidat parametr web_type
a nastavit ho na hodnotu product
nebo version
:
web_type: product
nebo
web_type: version
Parametr web_type
přinutí Publican zpracovat tento dokument jinak než dokumentaci produktu. Jedná se o jedinou povinnou úpravu souboru publican.cfg
. Dalšími, volitelnými změnami tohoto souboru, které jsou často užitečné pro stránky produktu nebo stránky verze, jsou tyto:
brand
Chcete-li nastylizovat stránku shodně s vašimi dokumenty, přidejte:
brand: nazev_grafupravy
docname
, product
Měl-li by <title>
nebo <product>
, který jste nastavili v souboru Article_Info
, obsahovat cokoliv jiného než základní latinské znaky bez diakritiky, nastavte docname
či product
, jak je nezbytné.
Upravte obsah souboru nazev_stranky.xml
(na příklad FooMaster.xml
) tak, jako u kteréhokoliv jiného dokumentu napsaného v DocBook.
Odstraníte-li <xi:include>
, který odkazuje na Article_Info.xml
, uveďte název stránky v tomto formátu:
<title role="producttitle">Dokumentace FooMaster</title>
Uveřejňujete-li dokumentaci ve více než jednom jazyce, vytvořte řadu souborů POT a PO pro každý jazyk příkazy $
publican update_pot a publican update_po.
Sestavte stránku produktu nebo stránku verze ve formátu jednostránkového HTML s volbou --embedtoc
a nainstalujte ji do struktury webových stránek. Na příklad:
$
publican build --publish --formats html-single --embedtoc --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Kod_Jazyka
Všimněte si, že lze sestavit všechny jazyky najednou, ale nainstalovat stránku produktu či verze v každém jazyce musíte jednotlivě příkazem $
publican install_book.
Chcete-li nainstalovat dokument na webové stránky, které sestavujete ručně, přejděte do adresáře, který obsahuje zdroj dokumentu a spusťte příkaz:
$
publican build --embedtoc --formats=seznam_formatu --langs=kody_jazyku --publish$
publican install_book --site_config cesta_ke_konfiguracnimu_souboru_webstranek.cfg --lang kod_jazyka
Všimněte si, že lze spustit jen jeden příkaz $
publican build pro všechny jazyky, ve kterých chcete dokument zveřejnit, ale příkaz publican install_book musíte spustit jednotlivě pro každý jazyk. Do formátů musíte v příkazu publican build zahrnout html
; volitelně zahrňte jeden či všechny následující formáty v čárkou odděleném seznamu: html-single
, pdf
a epub
.
Chcete-li dokument zaktualizovat, přejděte do adresáře, kde se nachází aktuální zdroj dokumentu, a spusťte ty samé příkazy, které jste použili při první instalaci dokumentu. Publican nahradí starou verzi verzí novou.
Přejete-li si dokument odstranit, přejděte do adresáře se zdrojem dokumentu a spusťte:
$
publican remove_book --site_config cesta_ke_konfiguracnimu_souboru_webstranek.cfg --lang kod_jazyka
Až dokumenty nainstalujete, webové stránky jsou připraveny k nahrání na webový server kterýmkoliv procesem, který obvykle využíváte, na příklad scp, rsync nebo klientem FTP.
Když vytvoříte strukturu webových stránek, Publican umístí soubory do adresáře /var/www/html/docs
. Existující soubory v tomto adresáři mohou být tímto postupem přepsány.
Na svém webovém serveru proveďte tyto kroky:
Přihlaste se do webového serveru.
Nainstalujte Publican a balíček jeho webových komponent. Na příklad na webovém serveru s operačním systémem Fedora spusťte:
$
sudo yum install publican publican-common-web
S právy uživatele root upravte soubor /etc/publican-website.cfg
, kde uvedete název webových stránek, hostitelský počítač webu a volitelně parametry vyhledávání, výchozí jazyk, nastavení souboru dump a webový styl stránek:
Název uveďte v parametru title
, na příklad:
title: "Dokumentace Foomaster"
Za normálních okolností návštěvníci vašich webových stránek s tímto názvem do styku nepřijdou, neboť JavaScript stránek je přesměruje na domovskou stránku. Nicméně tento název bude mít šanci být nalezen a oindexován vyhledávači.
Hostitelský počítač uveďte v parametru host
jako úplnou URL, včetně protokolu (např. http://
. Na příklad:
host: http://docs.example.com
Publican využívá hodnotu nastavenou v host
k sestavení adres URL v souboru XML Sitemap
, který vytváří pro indexovací automaty (crawlers) vyhledávačů a omezení vyhledávacích dotazů učiněných přes vyhledávací okno v navigační nabídce na výsledky pouze z vašich webových stránek.
Volitelně sestavte dotaz pro vyhledávač, který použijete ve vyhledávacím okně navigační nabídky, a uveďte parametrem search
celý obsah <form>
HTML. Neuvedete-li své přizpůsobené vyhledávání na webu, Publican vytvoří vyhledávání Google omezené na hostitelský počítač, který jste uvedli v parametru host
.
Na příklad, abyste sestavili vyhledávání Yahoo! omezené na docs.example.com
, spusťte:
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>'
Podrobnosti o sestavování zákaznicky přizpůsobených vyhledávání naleznete v dokumentaci vybraného vyhledávače.
Nastavíte-li v kódu tlačítka pro odeslání value="###Search###"
, Publican použije slovo Search
pro tlačítko, lokalizované do kteréhokoliv jazyka, který Publican podporuje.
Publican neprovádí validaci u parametru search
, avšak zabuduje hodnotu parametru do navigační nabídky zcela tak, jak jste ho uvedli. Při využívání této vlastnosti buďte obzvláště opatrní.
Volitelně nastavte výchozí jazyk webových stránek. Publican vytváří samostatnou, přeložitelnou navigační nabídku pro každý jazyk, ve kterém uveřejňujete dokumentaci. Pokud dokument není v daném jazyce k dispozici, Publican přesměruje návštěvníky na nepřeloženou verzi dokumentu. Chcete-li nastavit výchozí, nepřekládaný jazyk webových stránek, nastavte v def_lang
kód jazyka. Na příklad:
def_lang: fr-FR
S nastaveným def_lang
na fr-FR
jsou návštěvníci při prohlížení navigační nabídky (na příklad) ve španělštině odkázáni na originální francouzskou verzi dokumentu, pokud dokument ještě nebyl do španělštiny přeložen.
Volitelně nastavte pro webové stránky soubor dump. Publican může vypsat soubor XML, který poskytuje podrobnosti o celém obsahu webových stránek a který lze využít pro doručování dalších služeb, jako např. webové zdroje/kanály nebo přizpůsobené prohledávání stránek. Tento soubor je aktualizován kdykoliv je nainstalována nebo odstraněna z webových stránek kniha, nebo je spuštěn příkaz $
publican update_site. Nastavte parametry dump
, dump_file
a zip_dump
takto:
dump
Nastavte dump: 1
, pokud chcete, aby soubor dump fungoval. Výchozí hodnotou parametru je 0
(vypnuto).
dump_file
Nastavte dump_file: nazev
uvedením názvu souboru dump a adresáře, do něhož ho Publican ukládá. Výchozí hodnotou parametru je /var/www/html/DUMP.xml
.
zip_dump
Nastavení zip_dump: 1
způsobí, že Publican bude tohoto souboru XML vytvářet také jeho zazipovanou verzi. Výchozí hodnotou parametru je 0
(vypnuto).
Popis obsahu souboru dump viz D – „Obsah souboru s výpisem webových stránek“.
Volitelně uveďte webový styl ve 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)
Webové stránky obsahují drobečkovou navigační lištu na vrchu dokumentace.
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.
Volitelně uveďte parametrem manual_toc_update
, že obsahy na stránkách jsou aktualizovány ručně, na příklad:
manual_toc_update: 1
Publican obvykle aktualizuje obsahy na webových stránkách pokaždé, kdy je přidán nebo odstraněn balíček s dokumentací. Na stránkách s velkým množství dokumentů (více než několik stovek), nebo tam, kde jsou dokumenty aktualizovány častěji (desítky aktualizací týdně), může tento proces velmi zatěžovat server. Na velkých nebo často navštěvovaných stránkách doporučujeme, abyste nastavili tento parametr a poté pravidelně aktualizovali obsahy příkazem $
publican update_site.
Volitelně potlačte výchozí JavaScript pro webové stránky parametrem toc_js
, na příklad:
toc_js: "mojegrafuprava/scripty/megafoo.js"
Na tento soubor bude příkazem $
publican update_site vytvořen symbolický odkaz toc_path
/toc.js. Tato cesta by měla být vůči parametru toc_path
relativní.
Vytvořte prázdný soubor s názvem site_overrides.css
. Chcete-li na webové stránky aplikovat zvláštní styly, které potlačí styly poskytované v interactive.css
, lze přidat site_overrides.css
do dokumentu, který poskytuje domovskou stránku webových stránek — viz 7.1.2 – „Vytvoření, instalace a aktualizace domovské stránky“. Nechcete-li používat zvláštní styly, prázdný soubor, který jste sem přidali, bude předcházet na serveru chybám 404. Na linuxovém systému spusťte:
#
touch /var/www/html/docs/site_overrides.css
Aby Publican aktualizoval strukturu stránek kdykoliv, spusťte:
$
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.
Na pracovní stanici vytvořte domovskou stránku použitím postupu popsaného v 7.1.2 – „Vytvoření, instalace a aktualizace domovské stránky“.
V adresáři, ve kterém jste vytvořili domovskou stránku, spusťte:
$
publican package --binary
Publican sestaví balíček RPM a umístí ho do adresáře /tmp/rpms/noarch/
domovské stránky. Standardně Publican sestaví balíček RPM pro operační systém, na němž Publican běží. Chcete-li sestavit balíček RPM, který se instaluje na server, kde běží jiný operační systém, nastavte parametr os_ver
v souboru publican.cfg
domovské stránky.
Nahrajte balíček domovské stránky na webový server a nainstalujte ho příkazem rpm -i či yum localinstall, nebo balíček umístěte do repozitáře a nakonfigurujte webserver tak, aby instaloval z repozitaře, když spustíte yum install.
Chcete-li domovskou stránku zaktualizovat, sestavte nový balíček s vyšším číslem <edition>
nebo <pubsnumber>
v Article_Info.xml
. Publican využívá tyto hodnoty k nastavení verze a čísla vydání balíčku RPM. Když tento balíček instalujete na webový server, yum dokáže nahradit starou verzi verzí novou, spustíte-li yum localinstall pro místní balíček, nebo yum update pro balíček získaný z repozitáře.
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.
Na pracovní stanici vytvořte stránku produktu nebo stránku verze využitím postupu popsaného ve 7.1.3 – „Vytvoření, instalace a aktualizace stránek produktu a verze“.
V adresáři, ve kterém jste vytvořili stránku, spusťte:
$
publican package --binary
Publican sestaví balíček RPM a umístí ho do adresáře /tmp/rpms/noarch/
stránky produktu nebo stránky verze. Standardně Publican sestaví balíček RPM pro operační systém, na němž Publican běží. Chcete-li sestavit balíček RPM, který se instaluje na server, kde běží jiný operační systém, nastavte parametr os_ver
v souboru publican.cfg
stránky produktu nebo stránky verze.
Nahrajte balíček na webový server a nainstalujte ho příkazem rpm -i či yum localinstall, nebo balíček umístěte do repozitáře a nakonfigurujte webserver tak, aby při spuštění yum install instaloval z repozitáře.
Chcete-li stránku produktu či stránku verze zaktualizovat, sestavte nový balíček s vyšším číslem <edition>
nebo <pubsnumber>
v Article_Info.xml
. Publican využívá tyto hodnoty k nastavení verze a čísla vydání balíčku RPM. Když tento balíček instalujete na webový server, yum dokáže nahradit starou verzi verzí novou, spustíte-li yum localinstall pro místní balíček, nebo yum update pro balíček získaný z repozitáře.
Na pracovní stanici přejděte do adresáře se zdrojem dokumentu a spusťte:
$
publican package --binary --lang kod_jazyka
Publican sestaví balíček RPM a umístí ho do adresáře /tmp/rpms/noarch/
dokumentu. Standardně Publican sestaví balíček RPM pro operační systém, na němž Publican běží. Chcete-li sestavit balíček RPM, který se instaluje na server, kde běží jiný operační systém, nastavte parametr os_ver
v souboru publican.cfg
dokumentu.
Nahrajte balíčky dokumentů na webový server a nainstalujte je příkazem rpm -i či yum localinstall, nebo balíčky umístěte do repozitáře a nakonfigurujte webserver tak, aby při spuštění yum install instaloval z repozitáře.
Chcete-li dokument zaktualizovat, sestavte nový balíček s vyšším číslem <edition>
nebo <pubsnumber>
v Book_Info.xml
či Article_Info.xml
. Publican využívá tyto hodnoty k nastavení verze a čísla vydání balíčku RPM. Když tento balíček instalujete na webový server, yum dokáže nahradit starou verzi verzí novou, spustíte-li yum localinstall pro místní balíček, nebo yum update pro balíček získaný z repozitáře.
Dokument z webového serveru odstraníte příkazem rpm -e nebo yum erase.
Na velkých nebo často navštěvovaných webových stránkách vám doporučujeme, abyste v konfiguračním souboru webových stránek nastavili parametr manual_toc_update
. Při tomto nastaveném parametru je nutné spustit příkaz $
publican update_site po nainstalování, aktualizaci či odstranění dokumentů. Více informací viz 7.1.1 – „Vytvoření struktury webových stránek“.
Webové stránky vytvořené Publicanem obsahují soubor XML mapy stránek. Mapu stránek lze předložit mnoha významným vyhledávacím strojům, s cílem pomoci jim oindexovat vaše stránky inteligentněji a podrobněji. Každý vyhledávací stroj má svůj vlastní předkládací postup. Tento oddíl obsahuje dokumentaci jak předložit mapu stránek vyhledávačům Google a Bing.
Postup 7.1. Chcete-li předložit mapu stránek Googlu:
Zaregistrujte si účet Google na stránce Nástroje Google pro webmastery. Máte-li již účet Google vytvořen, lze ho použít.
Přihlaste se do svého účtu pro Nástroje Google pro webmastery na této URL: http://www.google.com/webmasters/tools/home.
Nejprve musíte ověřit, že jste vlastníkem vlastních webových stránek vytvořených v Publicanu. Klepněte na tlačítka
.Stránku přidáte ve zobrazeném dialogovém okně. Do textového pole zadejte URL svých stránek a klepněte na
.Postupujte podle pokynů, které se zobrazí, a uložte soubor HTML poskytnutý Googlem do dokumentačního kořenu (document root) svých stránek.
Až potvrdíte, že poskytnutý soubor HTML byl nahrán do požadovaného umístění tím, že k němu přistoupíte přes webový prohlížeč, klepněte na tlačítko
.Pokud jste úspěšně ověřili Googlu vlastnictví svých webových stránek, vraťte se zpět na domovskou stránku Nástrojů Google pro webmastery. Vaše stránky jsou zobrazeny na seznamu. Klepněte na ně.
Jste přeneseni na konfigurační stránku Nástrojů pro webmastery svých webových stránek. Po levé straně stránky se nachází nabídka. Klepněte na nabídku Konfigurace stránek, aby se rozbalila. Rozbalená nabídka obsahuje položku Mapa stránek. Klepněte na ni.
Jste přeneseni na Stránku předložení mapy stránek. Klepněte na tlačítko
.Zobrazí se textové pole, včetně základní URL vašich stránek, s místem pro zadání URL vašeho souboru XML mapy stránek. Vložte jeho umístění a klepněte na tlačítko
. Podrobnosti o mapě stránek se zobrazí v tabulce.Výsledek. Mapa vašich webových stránek vytvořených v Publicanu byla úspěšně předložena Googlu.
Postup 7.2. Chcete-li předložit mapu stránek Bingu:
Zaregistrujte si účet Bing pro správce webu na Bing správce webu. Máte-li již účet Windows LiveID zřízen, lze použít tento.
Přihlaste se do svého účtu Bing správce webu na URL: http://www.bing.com/toolbox/webmaster/.
Klepněte na tlačítko
.Zobrazí se dialogové okno Přidat web. Do textového pole zadejte URL svých webových stránek vytvořených v Publicanu a klepněte na .
Zobrazí se dialog Ověřit vlastnictví s třemi možnostmi. Postupujte dle pokynů, když se rozbalí Možnost 1: Umístěte soubor XML na svůj webový server. Nahrajte soubor BingSiteAuth.xml
poskytnutý Bingem do dokumentačního kořenu svých webových stránek.
Až potvrdíte, že poskytnutý soubor BingSiteAuth.xml
byl nahrán do požadovaného umístění tím, že k němu přistoupíte ve webovém prohlížeči, klepněte na tlačítko .
Po úspěšném ověření vlastnictví svých webových stránek se vraťte na domovskou stránku Bing správce webu. Zde by měly být webové stránky uvedeny v seznamu. Klepněte na ně.
Zvolte kartu
.Zvolte Mapy stránek a poté Přidat feed.
Zobrazí se dialog Přidat feed. Vložte URL souboru mapy svých stránek a klepněte na . Zobrazí se podrobnosti o mapě stránek.
Výsledek: Mapa vašich webových stránek vytvořených v Publicanu byla úspěšně předložena Bingu.
Publican 3.1 obsahuje nové funkce, které umožní uživatelů vytvořit a naimportovat knihu do Drupalu. Všechny soubory xml v knize jsou převedeny do jediného souboru CSV, který se později použije pro import do Drupalu.
Soubor CSV sestává z infomací, které poskytnou Drupalu instrukce, jak knihu importovat. Každý řádek v souboru CSV představuje stránku HTML.
Chcete-li vytvořit soubor CSV pro import do Drupalu, použijte příkaz $
publican build. Před spuštěním příkazu přejděte pomocí příkazu cd do adresáře, kde se nachází kniha. Například máte-li ve svém domovském adresáři knihu s názvem "Prirucka_Uzivatele", pak spusťte následující příkaz.
$
cd Prirucka_Uzivatele/$
publican build --langs en-US --formats=drupal-book
Po spuštění příkazu budete moci nalézt vytvořený soubor CSV v adresáři tmp/en-US/drupal-book/
.
Publican ukládá všechny výstupní soubory do adresáře /tmp/en-US/drupal-book/
. Tento adresář obsahuje následující soubory:
soubor CSV - konvence názvu souboru je $product-$version-$docname-$lang-$edition.csv
adresář en-US - obsahuje všechny obrázky html
soubor tar.gz - archiv jak souboru CSV, tak adresáře en-US.
Po spuštění příkazu $
publican build --langs en-US --formats=drupal-book si můžete všimnout, že soubory XML v adresáři en-US
byly změněny. Stalo se tak proto, že Publican přidal do každého tagu xml, který má id, atribut 'Conformance'
. Tento atribut obsahuje číslo, které je unikátní napříč soubory xml knihy. Používáte-li pro své soubory xml systém pro správu verzí jako git, pak potřebujete přiznat (commit) změny, aby se číslo nenastavilo znovu při spuštění jinými uživateli. Tato unikátní čísla jsou velmi důležitá, neboť se v Drupalu používají jako cesta url. Kromě toho Publican rovněž vytvořil v adresáři en-US
soubor databáze nazvaný max_unique_id.db
. Tento soubor se používá ke sledování současného maximálního unikátního čísla v knize, proto může Publican poznat pokud aktualizujete a přidat nové unikátní číslo pro vaši novou kapitolu či oddíl. A proto je velmi důležité přidat soubor databáze pod správu verzí a přiznat ho kdykoliv u něj proběhne změna. Přidáte-li do xml nový oddíl, nenastavujte atribut 'Comformance'
sami, jelikož by to učinilo databázi zastaralou. Jednoduše ponechte jeho nastavení na starosti Publicanu.
Níže se nachází několik parametrů, které lze nastavit v souboru publican.cfg pro import do Drupalu:
drupal_author
uvádí autora, který by měl být zobrazen na stánce knihy v drupalu. Jméno musí být platné uživatelské jméno Drupalu. Výchozím autorem je 'Redhat'. Chcete-li potlačit hodnotu tohoto parametru, nastavte ji v souboru publican.cfg
.
Autor musí mít oprávnění v Drupalu pro řízení (tvorbu, aktualizaci a výmaz) uzlů. Je-li použit výchozí autor, ujistěte se, že jste v Drupalu vytvořili účet s uživatelským jménem 'Redhat'.
drupal_menu_title
potlačte název knihy (bookname), který bude zobrazen v nabídce Drupalu. Není-li nastaveno nic, publican použije výchozí hodnotu, kterou je "$product $version $docname". Tedy například Publican 3.1 User_Guide.
drupal_menu_block
uvádí, který blok nabídky by kniha měla v Drupalu zobrazit. Výchozí hodnotou je "user-guide"
.
Blok nabídky musí v Drupalu existovat. Více informací o přidávání bloků nabídky v Drupalu viz 8.3.1 – „Jak přidat blok nabídky“.
drupal_image_path
uvádí adresář s uloženými obrazovými soubory na serveru drupal. Výchozí hodnotou je "sites/default/files/"
.
Předtím než lze naimportovat knihu, potřebujete do Drupalu nainstalovat modul s názvem 'Node Import'. Tento modul povoluje Drupalu importovat a aktualizovat obsah ze souboru CSV nebo TSV. Chcete-li modul nainstalovat, přejděte jednoduše na stránky Drupalu a postupujte k jeho stažení dle pokynů. Poté zkopírujte stažený modul do adresáře 'modules' na serveru Drupal. Například máte-li svůj Drupal umístěn v adresáři /var/www/html/drupal/
, pak byste měli modul zkopírovat do adresáře /var/www/html/drupal/sites/all/modules/
. Nainstalovaný modul povolíte přihlášením se na stránky serveru a přejděte do Administer -> Site building -> Modules . V oddílu Vývoj zatrhněte a stiskněte tlačítko , abyste aktivovali modul Node Import.
Potřebujete rovněž povolit následující core moduly Drupalu:
Book
Menu
Path
Nemáte-li oprávnění pro instalaci modulu v Drupalu, obraťte se prosím na svého správce webu.
Import directory - adresář, kam budou ukládány importované soubory CSV. Výchozí cesta je sites/default/files/imports/
.
FTP settings
Allow FTP uploads - Ujistěte se, že zaškrtávací pole je zatržené, aby nový soubor CSV mohl být autodetekován, když je nahrán do import directory
.
File owner - Tomuto uživateli bude přiděleno vlastnictví souboru CSV nahraného do import directory
.
Uživatelům bude polovelno používat soubory, které sami nahráli, a soubory vlastněné anonymně. Ponecháte-li toto pole prázdné, všechny soubory nahrané přes FTP budou vlastněné anonymně, a tedy budou viditelné a použitelné všemi uživateli. Zadáte-li do pole uživatelské jméno, soubory nahrané pomocí FTP budou vlastněny tímto uživatelem a pouze tento uživatel bude moci zobrazit tyto nahrané soubory. Doporučuje se ponechat toto pole prázdné.
Allowed extensions - povolená přípona importovaného souboru. Ostatní přípony budou modulem ignorovány.
Default settings
Content type - Výchozí typ obsahu, který se bude používat pro rychlý import. Ujistěte se, že je vybrán Book Page content type
.
First row contains column names - dává modulu Node import instrukci, že v prvním řádku souboru CSV se nachází názvy sloupců.
Postup 8.1. Chcete-li importovat knihu do Drupalu:
Postupujte dle kroků v 8.1 – „Jak sestavit soubor CSV pro import do Drupalu“.
Nahrajte soubor CSV do import directory
na serveru Drupal.
Nahrajte adresář en-US
do adresáře "sites/default/files/"
na serveru Drupal. Tuto hodnotu lze polačit v publican.cfg
. Více informací si prosím přečtěte v 8.2 – „Soubor publican.cfg“.
Přihlaste se na své stránky Drupal a přejděte do Administer -> Content management -> Import content. Soubor CSV, který jste právě nahráli, se zobrazí v tabulce 'Pending Tasks' a je připraven pro import.
Stiskněte
pro zahájení importu knihy. Budete přesměrováni na další stránku, která zobrazuje průběh importu.Odkaz na knihu by se měl nyní zobrazovat v uvedeném bloku nabídky.
Chcete-li knihu aktualizovat, jednoduše zopakujte kroky v 8.3.3 – „Jak importovat knihu“.
Aktualizujete-li knihu s nižší úrovní stránkování oddílů (ve smyslu umístění na samostatnou stránku), pak chybějící stánky samostatných oddílů budou Drupalem odstraněny a cesty URL odstraněných stránek budou odstraněny rovněž.
Jak do své knihy přidám jazyk?
Spusťte $
publican update_po --langs=jazyk, kde jazyk je kód nového jazyka, který chcete přidat. Lze přidat více než jeden jazyk najednou, s jazykovými kódy oddělenými čárkami. Například publican update_po --langs=ja-JP vytvoří adresář a soubory PO pro japonský jazyk a publican update_po --langs=ja-JP,ko-KR vytvoří adresáře a soubory PO pro japonštinu i korejštinu.
A pokud nechci používat kódy zemí? Mohu například spustit $
publican update_po --langs=es,de,fr?
Ano — tento příkaz funguje také. Ale vynecháte-li kód země, výstup může být nepředvídatelný, pokud Publican či grafická úprava obsahuje více než jednu definici regionální varianty jazyka — například zh-CN
(zjednodušená čínština používaná v Čínské lidové republice) a zh-TW
(tradiční čínština používaná v Čínské republice, na Tchaj-wanu). Dokonce i pokud je definována pouze jedna varianta, je vždy bezpečnější použít kód země, proto aby například budoucí aktualizace Publicanu nezpůsobila, že by se na vaše německé (de-DE
) dokumenty aplikoval švýcarský (švýcarská němčina, de-CH
Common Content a nadpisy.
Jak aktualizuji všechny soubory po?
Spusťte příkaz $
publican update_po --langs=all.
Kde mohu získat úplný seznam možností pro příkaz build Publicanu?
Spusťte příkaz $
publican build --help.
Kde mohu získat úplný seznam parametrů, které lze nastavit v publican.cfg
?
Spusťte příkaz $
publican help_config v adresáři, kde se nachází kterýkoliv dokument vytvořený v Publicanu.
Kde se nachází společné soubory Publicanu?
Na operačních systémech Linux se standardě nachází v /usr/share/publican/
a na Windows v %SystemDrive%/%ProgramFiles%/publican/Common_Content
— obvykle C:/Program Files/publican/Common_Content
.
Lze zahrnout do balíčků archivu nebo RPM libovolné soubory?
Ano. Vytvoříte-li v adresáři zdrojového jazyka adresář nazvaný files
, bude zahrnut do kteréhokoliv balíčku archivu či balíčku SRPM, který Publican vytvoří.
Adresář files
nebude dostupný během validačního procesu, proto nelze zahrnout pomocí xi:include
či jiným způsobem žádné soubory v tomto adresáři do svého XML.
Proč mi Publican poskytuje varovaná hlášení o neznámých tazích?
Toto varovné hlášení vás informuje o tom, že používáte tag, jehož výstup nebyl testován z hlediska atraktivity, souladu se specifikací XHTML 1.0 Strict nebo Sekce 508 (Přístupnost).
Mohu bez problému sestavit dokumenty HTML, ale pokud zkusím sestavit dokumenty PDF, dostanu chybová hlášení jako java.lang.NullPointerException
a žádný soubor PDF nevznikne. Co je špatně?
Zkuste sestavit verzi PDF jiného dokumentu — nejlépe nejnovějšího, který jste vytvořili příkazem $
publican create. Netýká-li se problém pouze jednoho dokumentu, pravděpodobně si neodpovídají Java Runtime Environment (JRE) a Java Development Kit (JDK), jež používáte na svém systému. Máte-li JDK nainstalován, FOP vyžaduje, aby se verze JDK a JRE shodovaly. Navíc FOP neumí používat GNU Compiler for Java (GCJ).
Spusťte alternatives --config java a alternatives --config javac, abyste zjistili, které JRE a JDK se používá, poté vyberte verze, které se shodují a nemají ve svých názvech gcj
. Například následující nastavení Java zobrazuje shodné JRE a JDK, které umožní sestavení PDF:
$
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:
Můžete potřebovat nainstalovat další JDK, nemáte-li na svém systému JDK, který odpovídá JRE.
Některé instalace Java nenastavují prostředí alternatives správně. Pro tuto situaci však náprava/oprava ještě určena není.
Dostávám chybovou zprávu, že Batik se nenachází v classpath, přitom však Batik nainstalován je. Co je špatně?
Věříme, že se tak děje kvůli problému s classpath způsobeném užitím různých verzí JRE a JDK. Přečtěte si, prosíme, předchozí dotaz o chybách java.lang.NullPointerException
a použití příkazů alternatives, kterými zajistíte, že JRE a JDK se shodují.
Dostávám chybovou zprávu Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
, když zkouším sestavit PDF. Co je špatně?
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.
Předchozí verze Publicanu odstraňovaly prázdné tagy <para>
. Odstraňuje je Publican stále?
Ne. Publican dříve odstraňoval prázdné tagy <para>
při převodu XML, neboť tyto prázdné tagy rozbíjely dřívější řetězce nástrojů pro překlad používané společností Red Hat a Projektem Fedora. Prázdné tagy <para>
jsou validním DocBook XML a Publican je již neodstraňuje.
Co stalo s kontrolou pravopisu?
Rané verze Publicanu (do verze 0.45 včetně) spouštěly kontrolu pravopisu při převodu XML dokumentu. Tato vlastnost však byla odstraněna kvůli zápornému ohlasu uživatelů.
V kořenovém adresáři svého dokumentu spusťte následující bash skript, chcete-li provést kontrolu pravopisu svých souborů XML nástrojem příkazové řádky aspell.
#!/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
Proč nefungují <segmentedlist>
, když sestavuji PDF?
Zkontrolujte počet sloupců ve svých <segmentedlist>
. Jsou-li <segmentedlist>
formátovány jako tabulky, DocBook XSL omezuje počet sloupců na dva a Publican formátuje <segmentedlist>
jako tabulky.
Co se stalo s barvami u mých obrázků v tomto PDF?
Toto je výsledek chyby ve FOP, která narušuje barvy v obrazových souborech 24bitového PNG. Abyste obešli tento problém, převeďte své obrazy na obrazy 32bitového PNG.
Při sestavování svého dokumentu dostávám chybová hlášení o 'undefined language' (nedefinovaném jazyku) - co je špatně?
Zvýrazňování kódu v Publicanu je generováno modulem Syntax::Highlight::Engine::Kate jazyka Perl. Uvedete-li jazyk v tagu <programlisting>
, který Syntax::Highlight::Engine::Kate nerozpozná, obdržíte při sestavování knihy chybové hlášení. První řádky chybové zprávy vypadají:
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'
Všimněte si, že Syntax::Highlight::Engine::Kate je velmi striktní s ohledem na názvy jazyků a rozlišuje velikost písmen. Proto <programlisting language="Java">
funguje, avšak <programlisting language="java">
či <programlisting language="JAVA">
nikoliv. Chybová zpráva, kterou jste obdrželi, identifikuje problémový jazykový atribut.
Úplný seznam jazyků, které Syntax::Highlight::Engine::Kate podporuje, včetně jejich očekávané kapitalizace a interpunkce, viz http://search.cpan.org/dist/Syntax-Highlight-Engine-Kate/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS.
Jak povolím dokončování příkazů příkazové řádky pro Publican?
Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:
Nainstalujte balíček nebo balíčky, které poskytují dokončování příkazů v bash pro vás operační systém. Například na Fedoře spusťte sudo yum install bash-completion.
Přidejte toto do svého souboru ~/.bashrc
:
# Use bash-completion, if available if [ -f /etc/bash_completion ]; then . /etc/bash_completion fi
Restartujte svůj terminál nebo spusťte source ~/.bashrc.
Proč mám problém se sestavením své obsáhlé knihy?
Pravděpodobně protože kernel dokáže pracovat pouze s určitým počtem handlů na soubory najednou a vy jste toto číslo překročili. Na některých linuxech lze spustit ulimit -n 8192, čímž změníte limit pro současný shell.
Chcete-li tuto změnu provést trvale, otevřete /etc/security/limits.conf
a přidejte tyto dva řádky:
* soft nofile 8192 * hard nofile 8192
Poté soubor uložte a znovu se přihlaste, aby se promítly změny.
Proč Jeff oslovuje Isaaca 'Ivane'?
Protože Jeffova paměť se zadrhává!
Ne každý prvek (tag) a atribut, který v Publicanu funguje je podporován. Zvláště ne každý tag byl otestován s ohledem na svůj vliv na vzhled dokumentu, když byl sestaven do HTML nebo PDF.
Publican funguje s téměř všemi prvky DocBook a jejich atributy a většina těchto prvků je podporována. Podporované prvky a atributy jsou ty, jejichž prezentace ve výstupu HTML nebo PDF Publicanu byla otestována a je přijatelné kvality.
Ostatní prvky a atributy, u nichž je známo, že nejsou škodlivé nebo nadbytečné, ale nebyly testovány na kvalitu, jsou nepodporované. Pokud materiál uvnitř konkrétního tagu DocBook se nezobrazuje správně, když sestavíte dokument do HTML či PDF, problémem může být skutečnost, že logika převodu pro tento tag nebyla ještě otestována. Sestavte dokument znovu a pozorujte výstup Publicanu při sestavování dokumentu. Publican zobrazuje varování o nepodporovaných tazích, které zaznamená ve vašich souborech XML.
Konečně malá skupina prvků a atributů je nedoporučených. Tyto prvky a atributy jsou uvedeny níže, každý doplněn o zdůvodnění vysvětlující, proč je nedoporučován.
Použijte příkaz $
publican print_known pro výtisk seznamu tagů, které Publican podporuje, a příkaz publican print_banned pro výtisk seznamu tagů, které jsou v Publicanu nepovolené.
<glossdiv>
Tato sada tagů zobrazuje pojmy ve slovníku v abecedním pořadí; ačkoliv pojmy jsou seřazeny dle originálního jazyka XML, bez ohledu na to, jak jsou tyto pojmy přeloženy do kteréhokoliv dalšího jazyka. Například slovník vytvořený pomocí <glossdiv>
, který vypadá v anglickém jazyce přibližně takto:
Apple
— an apple is…
Grapes
— grapes are…
Orange
— an orange is…
Peach
— a peach is…
vypadá ve španělštině takto:
Manzana
— la manzana es…
Uva
— la uva es…
Naranja
— la naranja es…
Melocotonero
— el melocotonero es…
V jazyce překladu, který nesdílí stejný psací systém s originálním jazykem, ve kterém je XML napsáno, dokáže být výsledek ještě nesmyslnější.
<inlinegraphic>
Tento prvek zobrazuje informaci spíše jako grafiku než text a neposkytuje možnost pro zobrazení textové alternativy grafiky. Tento tag proto skrývá informace lidem se zrakovým postižením. V jurisdikcích, jenž mají zákonné požadavky na elektronický obsah přístupný lidem se zrakovým postižením, nebudou dokumenty obsahující tento tag v souladu s těmito požadavky. Sekce 508 zákona o rehabilitaci z roku 1973[4] je příkladem takového požadavku na federální agentury Spojených států.
Uvědomte si, že <inlinegraphic>
není v DocBook verze 5 validní.
<olink>
Tag <olink>
poskytuje křížový odkaz mezi dokumenty XML. Aby <olink>
fungoval mimo dokumenty, které jsou hostovány v jedné knihovně souborů XML, musíte poskytnout URL dokumentu, na který odkazujete. V prostředích, které využívají <olink>
, lze tato URL poskytnout jak pomocí entity XML, tak skriptem na straně serveru. Publican neposkytuje žádný způsob, jak sestavit nebo používat databázi těchto odkazů.
<[prvek] xreflabel="[nejaky_retezec]">
Výskyt atributu <xreflabel>
snižuje použitelnost tištěných verzí knihy. A rovněž hodnoty atributu nelze zobrazit překladatelům, a jako důsledek nemohou být přeloženy.
Například máte-li toto:
<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.
při sestavování vašeho XML do HTML, tag <xref>
se stává v HTML následujícím tagem odkazu (anchor):
…see <a href="#ch03">Chapter Three</a> for details.
Text obsažený v tagu odkazu je stejný jako údaj v atributu <xreflabel>
. V tomto případě to znamená, že čtenáři tištěné kopie mají méně dostupných informací.
Toto lze obejít, pokud hodnotu atributu <xreflabel>
nastavíte na stejný text, který se nachází mezi tagy prvku <title>
</title>
. Avšak tato duplikace zvyšuje nebezpečí překlepů a nijak nenabízí podstatné zdokonalení. A stále snižuje množství informací předkládané čtenářům tištěných verzí.
Následující 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.
vyústí v tento tag odkazu HTML:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
Není to zdaleka tolik informativní, jako text předložený čtenáři, když nepoužijete atribut <xreflabel>
. Následující text:
<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.
převede prvek <xref>
při sestavení do HTML takto:
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
Mnohem důležitější jsou však problémy u překladu, které tagy <xreflabel>
působí. Hodnoty atributů jsou pro překladatele neviditelné. A jako důsledek nejsou přeloženy. Zvažte znovu výše uvedený druhý příklad:
<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.
V anglickém jazyce je <xref>
stále převáděn na tag odkazu:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
Avšak někdo, kdo bude číst německou verzi, bude mít jako své HTML toto:
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
Není-li používán atribut <xreflabel>
, název a ukazatel kapitoly, jsou-li řádně přeloženy, se čtenáři zobrazí. To znamená, že tento text:
<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.
se po překladu nabídne německy mluvícímu čtenáři takto:
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
To je, jak jsme předpokládali, přesně to, co jsme zamýšleli.
Proto je atribut xreflabel
nedoporučován.
<[prvek] endterm="[nejaky_retezec]">
Atribut endterm
umožňuje zobrazit raději odkazovaný text, než název oddílu či kapitoly, na který odkaz ukazuje. Jako takový tedy snižuje použitelnost tištěných verzí dokumentů a způsobuje obtíže překladatelům.
Text uvedený v prvku (jako např. <xref>
), který obsahuje atribut endterm
je převzat z tagu <titleabbrev>
v cílové kapitole nebo oddílu. Ačkoliv je obsaho tagu <titleabbrev>
k dispozici překladatelům souborů PO dokumentu, je odstraněn z kontextu <xref>
. Absence tohoto kontextu činí věrný překlad neuskutečnitelným v jazycích, které označují předložky či členy pro gramatické číslo či gramatický rod.
Například máte-li toto:
<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"/>.
Text obklopující <xref>
se zobrazí v anglické verzi dokumentu takto:
The solution is in
the final chapter
.
Překladatel uvidí text v <titleabbrev>
v souboru PO takto:
#. Tag: titleabbrev #, no-c-format msgid "the final chapter" msgstr ""
a text, který obsahuje <xref>
, uvidí v souboru PO zcela jinde (anebo mnohem pravděpodobněji ve zcela jiném souboru PO) takto:
#. Tag: para #, no-c-format msgid "The solution is in <xref linkend=\"The_Secret\" endterm=\"final\"/>." msgstr ""
Překladatel nemá jak zjistit, co se dosadí za <xref linkend="The_Secret" endterm="final"/>
při sestavení dokumentu, proto překlad do italštiny může vypadat takto:
#. 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\"/>."
Všimněte si předložky in
.
Pokud překladatel použije the final chapter
v italštině jako l'ultimo capitolo
, výsledkem sestavení dokumentu bude:
La soluzione è in
l'ultimo capitolo
.
Tomuto výsledku sice lze rozumět, ale není elegantní, neboť italština kombinuje některé své předložky s určitými členy. Mnohem elegantní italštinou by bylo:
La soluzione è nell'
ultimo capitolo
.
Bez znalosti jaký text se zobrazí na místě <xref linkend="The_Secret" endterm="final"/>, si nemůže být italský překladatel jist, zda ponechat předložku in
samostatně, či kterou ze sedmi dalších možných kombinací s určitým členem použít: nel
, nei
, nello
, nell'
, negli
, nella
nebo nelle
.
Navíc si ještě uvědomte, že kombinace předložek se členy znamenají rovněž problém s ohledem na to, zda toto slovo by mělo být umístěno v textu obklopujícím <xref>
nebo v <titleabbrev>
. Ať již si překladatel zvolí jednu či druhou možnost, způsobí to problémy, když se endterm
objeví v jiném gramatickém kontextu, neboť ne všechny italské předložky lze kombinovat s určitými členy tímto způsobem.
Kvůli problémům, které představuje endterm
pro překladatele, není tento atribut Publicanem doporučován.
Povolí přístup k síti při zpracování XML a XSLT. Výchozí stav je vypnuto.
Adresář, ze kterého se načtou soubory grafické úpravy.
Potlačí (uvádí novou) cestu k adresáři Common_Config
Potlačí (uvádí novou) cestu k adresáři Common_Content
Použít nestandardní konfigurační soubor
Zobrazit zprávu nápovědy
Zakázat barevné zvýrazňování protokolu/-ů dle ANSI.
Zakázat tvorbu protokolů.
$
publican add_revisionPřidá záznam do historie revizí
Datum revize.
e-mail, který se má u revize použít.
křestní jméno, které se má u revize použít.
Jazyk, ve kterém bude napsáno XML
Záznam, který se přidá do historie revizí. Lze ho uvést vícekrát.
Číslo revize, které se u revize použije.
příjmení, které se u revize použije.
$
publican buildPřevede XML do jiných formátů (pdf, html, html-single, drupal-book atd.)
Tento příznak říká publicanu, že zpracovávané údaje jsou distribuovanou sadou. Poznámka: nepoužívejte distributed_set na příkazové řádce. Publican používá tento příznak při svém vlastním volání, aby zpracoval distribuovanou sadu. Toto je ten jediný bezpečný způsob použití, kterým lze tento příznak použít.
Vestavit objekt obsahu webové stránky do generovaného HTML
Čárkou oddělený seznam formátů, např. html,pdf,html-single,html-desktop,txt,epub
Čárkou oddělený seznam jazyků, např. en-US,de-DE,all
Neprovádět validaci DTD
Potlačí (uvádí jiný) nástroj, který se použije pro tvorbu PDF. Platné volby jsou wkhtmltopdf nebo fop.
Adresář, do kterého se uloží soubory určené ke zveřejnění. Ve výchozím nastavení se jedná o adresář publish.
Připravit sestavený obsah ke zveřejnění
Ve výstupu se zobrazí položky, jejichž překlad je neúplný. Výchozí hodnotou je off.
Adresář, ze kterého se načtou soubory publicanu.
$
publican cleanOdstraní všechny dočasné soubory a adresáře
Adresář, do kterého se uloží soubory určené ke zveřejnění. Ve výchozím nastavení se jedná o adresář publish.
$
publican clean_idsSpustí pro zdrojový XML vyčištění identifikátorů
$
publican clean_setOdstraní místní kopie vzdálených sad knih
$
publican copy_web_brandZkopíruje nainstalovaný webový obsah grafické úpravy do jiné internetové stránky
Grafická úprava, která se má použít
Konfigurační soubor webových stránek, který se má použít při kopírování obsahu mezi webovými stránkami.
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
$
publican createVytvoří novou knihu, sadu nebo článek
Grafická úprava, která se má použít
Verze DocBook DTD, která se má použít.
Číslo vydání knihy, článku nebo sady
Jazyk, ve kterém bude napsáno XML
Název knihy, článku, sady nebo grafické úpravy
Název produktu
Typ (book, article nebo set)
Verze produktu
$
publican create_brandVytvoří novou grafickou úpravu
Jazyk, ve kterém bude napsáno XML
Název knihy, článku, sady nebo grafické úpravy
$
publican create_siteVytvoří nové webové stránky v zadaném umístění.
Potlačí (uvede jiný) výchozí databázový soubor.
Jazyk, ve kterém bude napsáno XML
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
Potlačí (uvede jinou) výchozí cestu k šabloně.
Potlačí (uvede jinou) výchozí cestu k obsahu.
$
publican help_configZobrazí text nápovědy pro konfigurační soubor
$
publican install_bookNainstalovat knihu do webových stránek.
Jazyk, ve kterém bude napsáno XML
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
$
publican install_brandNainstalovat grafickou úpravu do uvedeného místa
/cesta/kam/se/nainstaluje
Adresář, do kterého se uloží soubory určené ke zveřejnění. Ve výchozím nastavení se jedná o adresář publish.
Nainstalovat webový obsah pro grafickou úpravu.
$
publican lang_statspřipraví zprávu o statistice souborů PO
Jazyk, ve kterém bude napsáno XML
$
publican migrate_sitePřevede databázi webových stránek z verze Publican < 3 na verzi Publican 3.
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
$
publican packageZabalí jazyk k expedici
Při běhu balíčku sestaví binární rpm.
Nahraje balíček SRPM do sestavovacího systému brew
Namísto webového vytvoří balíček pro stolní počítač
Jazyk, ve kterém bude napsáno XML
Adresář, do kterého se uloží soubory určené ke zveřejnění. Ve výchozím nastavení se jedná o adresář publish.
Použít scratch sestavení namísto tagovaného
Vytvořit balíček bez uvedení verze v jeho názvu
Vyčkat, než brew dokončí sestavení
$
publican print_bannedVytiskne seznam nepovolených tagů DocBook
$
publican print_knownVytiskne seznam tagů DocBook s kontrolou kvality.
$
publican print_treeVytisknout strom xi:includes
$
publican print_unusedVytiskne seznam nepoužitých souborů XML
$
publican print_unused_imagesVytiskne seznam nepoužitých grafických souborů
$
publican remove_bookOdstraní knihu z webových stránek.
Jazyk, ve kterém bude napsáno XML
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
$
publican renamePřejmenuje knihu v publicanu
Název knihy, článku, sady nebo grafické úpravy
Název produktu
Verze produktu
$
publican reportVytiskne zprávu o čitelnosti zdrojového textu.
$
publican site_statsPřipraví zprávu o obsahu na webových stránkách
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
$
publican trans_dropVytvoří okamžitý snímek zdrojového jazyka pro použití v překladu.
$
publican update_dbPřidá nebo odstraní záznamy z databáze. Užívá se pro zpracování předsestavených (pre-build) knih, jako např. při sestavování balíčků.
Abstrakt knihy
Přidá záznam do databáze
Jazyk, na němž je tento překlad založen.
Číslo verze knihy, která je instalována.
Smazat databázový záznam
Čárkou oddělený seznam formátů, např. html,pdf,html-single,html-desktop,txt,epub
Jazyk, ve kterém bude napsáno XML
Název knihy, článku, sady nebo grafické úpravy
popisek názvu knihy
Název produktu
popisek produktu knihy
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
Směr seřazení knihy
Podtitul knihy
Verze produktu
popisek verze knihy
$
publican update_poAktualizovat soubory PO
e-mail, který se má u revize použít.
křestní jméno, které se má u revize použít.
Čárkou oddělený seznam jazyků, např. en-US,de-DE,all
Použít msgmerge gettextu pro sloučení POT/PO.
Zachovat předchozí identifikátory zpráv (msgid), nalézají-li se nepřesné překlady v aktualizovaných PO souborech.
příjmení, které se u revize použije.
$
publican update_potAktualizovat soubory POT
$
publican update_siteAktualizovat šablony existujících stránek.
Konfigurační soubor webových stránek, který má být použit nebo vytvořen.
$
publican zt_pullNačíst překlady ze systému Zanata.
$
publican zt_pushNahrát překlady do systému Zanata.
Ty jsou nastaveny v konfiguračních souborech knih nebo grafických úprav.
Architektura, na níž se filtruje výstup.
Cílová skupina, na níž se filtruje výstup.
Čárkou oddělený seznam knih, které se použijí v této vzdálené sadě.
Grafická úprava, která se má použít při sestavování tohoto balíčku.
Výchozí hodnotou tohoto parametru je: common
Distribuce sestavovacího systému brew, která se má použít k sestavení samostatného rpm pro desktop.
Výchozí hodnotou tohoto parametru je: docs-5E
Toto pole je označeno za zastaralé a v budoucnu bude z Publicanu odstraněno.
Zobrazit elementy bridgehead v obsazích?
Výchozí hodnotou tohoto parametru je: 0.
Má být, u formátu HTML, první oddíl umístěn na stránce svého rodiče?
Výchozí hodnotou tohoto parametru je: 0.
Jaká je, pro formát HTML, nejhlubší úroveň vhnízdění, na které má být oddíl umístěn na svou vlastní stránku?
Výchozí hodnotou tohoto parametru je: 4
Cesta k souborům jar pro FOP.
Výchozí hodnotou tohoto parametru 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
Cesta k obsahu publicanu.
Výchozí hodnotou tohoto parametru je: /usr/share/publican
Cesta ke společnému obsahu publicanu.
Výchozí hodnotou tohoto parametru je: /usr/share/publican/Common_Content
Podmínky, za kterých zredukovat (prune) XML před transformací.
Jedná se o důvěrný obsah?
Výchozí hodnotou tohoto parametru je: 0.
Text, který je použit k označení důvěrného obsahu.
Výchozí hodnotou tohoto parametru je: CONFIDENTIAL
Conformance, na níž se filtruje výstup.
Vytisknout zvláštní zprávy?
Výchozí hodnotou tohoto parametru je: 0.
URL dokumentačního týmu pro tento balíček. Použito u HTML v horním pravém URL.
Výchozí hodnotou tohoto parametru je: https://fedorahosted.org/publican
Název tohoto dokumentu. Získán z tagu title v xml_lang/TYPE_Info.xml, není-li nastaven v konfiguračním souboru.
Tento parametr se omezuje na tento regulární výraz: ^[0-9a-zA-Z_\-\.\+]+$
Toto pole není podporováno pro: brand
Jméno autora zobrazené v drupalu na stránce knihy. Musí být platné uživatelské jméno drupalu.
Výchozí hodnotou tohoto parametru je: Publican
Adresář na serveru drupal, ve kterém by měl být uložen obraz.
Výchozí hodnotou tohoto parametru je: /sites/default/files/documentation
Nabídka, ve které se kniha nachází.
Výchozí hodnotou tohoto parametru je: user-guide (uživatelská příručka)
Potlačuje název knihy (bookname), který bude zobrazen v nabídce drupalu.
Formát, který se použije pro výstup pro desktop.
Výchozí hodnotou tohoto parametru je: html-desktop
Seznam balíčků oddělený mezerami, které budou desktopovým balíčkem označeny za zastaralé.
Seznam balíčků oddělený mezerami, které vyžaduje desktopový balíček.
Verze DocBook DTD, na které je založen tento projekt.
Výchozí hodnotou tohoto parametru je: 4.5
ID zásuvného modulu Eclipse. Standardně "$product.$docname"
Název zásuvného modulu Eclipse. Standardně "$product $docname"
Poskytovatel zásuvného modulu Eclipse. Standardně "Publican-v4.2.2"
Adresář s obrazy.
Výchozí hodnotou tohoto parametru je: extras
Vytvářet obsah do uvedené hloubky oddílů.
Výchozí hodnotou tohoto parametru je: 0.
Jazyky, které se nahradí parametrem xml_lang bez ohledu na stav překladu.
Adresář s obrazy.
Výchozí hodnotou tohoto parametru je: images
Potlačuje výchozí soubor Info.
Jazyk, na nějž se filtruje výstup.
Licence, kterou tento balíček používá.
Výchozí hodnotou tohoto parametru je: GFDL
Název hlavního souboru xml a ent pro tuto knihu, rozšíření souboru sans a jazyk. Získáno z docname, není-li nastaveno.
Seznam kategorií nabídek oddělený středníkem pro balíček desktopu.
operační systém, na nějž se filtruje výstup.
OS, pro který se mají balíčky sestavit.
Písmo, které se má v PDF použít pro tělo textu.
Výchozí hodnotou tohoto parametru je: Liberation Sans
Písmo, které se má v PDF použít pro neproporciální text.
Výchozí hodnotou tohoto parametru je: Liberation Mono
URL pro produkt. Použito u HTML v horním levém URL.
Výchozí hodnotou tohoto parametru je: https://fedorahosted.org/publican
Produkt, který je pokryt tímto balíčkem. Získán z tagu productname v souboru xml_lang/TYPE_Info.xml
Tento parametr se omezuje na tento regulární výraz: ^[0-9a-zA-Z_\-\.\+]+$
Toto pole není podporováno pro: brand
Úložiště (repository), ze kterého získat vzdálenou sadu knih.
Standardně je přehled revizí řazen sestupně. Nastavením na 'asc' nebo 'ascending' obrátí směr řazení na vzestupné.
Potlačuje výchozí soubor Revision History (Přehled revizí).
Revize, na níž se filtruje výstup.
příznak revize, na nějž se filtruje výstup.
role, na níž se filtruje výstup.
Typ repozitáře, ve kterém jsou uloženy knihy, jenž jsou součástí vzdálené sady. Podporované typy: SVN, GIT.
bezpečnost, na níž se filtruje výstup.
Zobrazit poznámky v převedeném výstupu.
Výchozí hodnotou tohoto parametru je: 0.
Potlačuje výchozí váhy řazení. Standardně má hodnotu 50.
URL, kde se nalézá soubor tar se zdrojovými soubory. Použito u souborů RPM Spec.
status, na nějž se filtruje výstup.
Adresář, který se použije pro sestavení.
Výchozí hodnotou tohto parametru je: tmp
Hloubka oddílů (podkapitol), které budou uvedeny v obsahu.
Výchozí hodnotou tohto parametru je: 2
Vybere generátor formátu (formatter), který se má použít při tvorbě výstupu txt.
Výchozí hodnotou tohoto parametru je: default
Tento parametr se omezuje na tento regulární výraz: ^(links{1}|tables{1}|default)$
Druh obsahu, který obsahuje tento balíček. Podporováno: set, book, article, brand
Výchozí hodnotou tohoto parametru je: Book
userlevel (úroveň uživatele), na níž se filtruje výstup.
vendor (prodejce, výrobce), na nějž se filtruje výstup.
Verze tohoto balíčku. Získána z tagu productnumber v xml_lang/TYPE_Info.xml
Tento parametr se omezuje na tento regulární výraz: ^[0-9][^\p{IsSpace}]*$
Distribuce sestavovacího systému brew, která se má použít k sestavení webového rpm.
Výchozí hodnotou tohoto parametru je: docs-5E
Čárkou oddělený seznam formátů, které se použijí pro webové balíčky.
Výchozí hodnotou tohoto parametru je: html,html-single,pdf,epub
Toto je domovská stránka webové stránky vygenerované Publicanem, nikoliv standardní kniha.
web_home je označen za zastaralý a v budoucích verzích Publicanu bude odstraněn. Misto něj používejte "web_type: home".
Toto je název hosta pro webovou stránku vygenerovanou Publicanem, používá se pro vyhledávání a mapu stránek. Ujistěte se, že jste zadali celou cestu ke stromu dokumentu. Např. pokud jsou vaše dokumenty v adresáři docs: http://www.example.com/docs
web_host je označen az zastaralý a v budoucích verzích Publicanu bude odstraněn. Místo něj pužívejte "host" v konfiguračním souboru webové stránky.
Potlačuje název knihy, spodní úroveň, popisek nabídky na webové stránce Publicanu.
Balíčky k označení za zastaralé ve webovém RPM.
Potlačuje produkt, horní úroveň, popisek nabídky na webové stránce Publicanu.
Potlačuje výchozí vyhledávací formulář pro webovou stránku Publicanu. Ve výchozím nastavení je použit vyhledávač Google a vyhledá se stránka, je-li nastaven web_host.
web_search je označen az zastaralý a v budoucích verzích Publicanu bude odstraněn. Místo něj pužívejte "search" v konfiguračním souboru webové stránky.
Toto je zvláštní stránka pro webovou stránku vygenerovanou Publicanem, nikoliv standardní kniha. Platné typy jsou home, product a version.
Tento parametr se omezuje na tento regulární výraz: ^(home|product|version)$
Potlačuje verzi, střední úroveň, popisek nabídky na webové stránce Publican. Chcete-li tuto položku nabídky skrýt, nastavte na: UNUSED
Zvláštní volby předávané do wkhtmltopdf. Např. wkhtmltopdf_opts: "-O landscape -s A3"
wordsize (velikost slova), na níž se filtruje výstup.
Jazyk v němž je XML napsán.
Výchozí hodnotou tohoto parametru je: en-US
Tyto parametry jsou nastavovány v konfiguračních souborech grafických úprav.
Čárkou oddělený seznam atributů XML, které nejsou ve zdroji povoleny.
Čárkou oddělený seznam tagů XML, které nejsou ve zdroji povoleny.
Základní grafická úprava, která se má použít pro tuto grafickou úpravu.
Výchozí hodnotou tohoto parametru je: common
Potlačuje Type pro DocType. Musí mít formu celého řetězce.
Potlačuje URI pro DocType. Musí mít podobu celého řetězce.
Volba grafické úpravy, která ve webových balíčcích zakazuje vytvoření obsahu s navigací.
Úplná cesta ke konfiguračnímu souboru stránky publicanu pro nestandardní webové stránky RPM.
Cesta pro instalaci nestandardních webových stránek RPM.
Název balíčku webové stránky pro nestandardní stránky RPM. Vyžaduje se k zajištění, že stránka je nainstalována.
Nastavují se v konfiguračním souboru webové stránky.
Název souboru databáze SQLite pro vaši webovou stránku, s příponou souboru .db
Při běhu publicanu vypisovat zvláštní zprávy.
Výchozí hodnotou tohoto parametru je: 0.
Výchozí jazyk pro tuto webovou stránku. Obsahy u jazyků jiných, než je výchozí jazyk, budou odkazovat na dokumenty ve výchozím jazyce, pokud nejsou k dispozici jejich překlady.
Výchozí hodnotou tohoto parametru je: en-US
Vypsat databázi publicanu do souboru XML.
Název souboru, do kterého vypsat databázi publicanu.
Výchozí hodnotou tohoto parametru je: /var/www/html/DUMP.xml
HTML, které se má vložit do patičky každé stránky webové stránky.
Výchozí hodnotou tohoto parametru je:
Host webové stránky, může být úplná URI nebo relativní cesta.
Výchozí hodnotou tohoto parametru je: /docs
Zamezuje publicanu automaticky znovu sestavovat webovou stránku pokaždé, kdy je instalována, aktualizována nebo odstněna kniha.
Výchozí hodnotou tohoto parametru je: 0.
HTML, které se vloží jako vyhledávání na webové stránce.
Výchozí hodnotou tohoto parametru je: Google site search
Název, který se použije u všech navigačních stránek webové stránky.
Výchozí hodnotu tohto parametru je: Documentation
Úplný cesta k adresáři šablon.
Výchozí hodnotou thoto parametru je: /usr/share/publican/templates
Zdrojový soubor, který se má použít pro funkcionalitu JavaScript.
Výchozí hodnotou tohoto parametru je: default.js
Cesta k adresáři, ve kterém se vytvoří sobor index.html nejvyšší úrovně.
Šablona, která se má použít pro vygenerování souboru s obsahem webového stylu 1.
Výchozí hodnotou tohoto parametru je: toc
Toto pole je označeno za zastaralé a v budoucnu bude z Publicanu odstraněno.
Publican podporuje vícenásobné základní styly pro webové stránky, toto některý z nich vybere.
Výchozí hodnotou tohoto parametru je: 1
Tento parametr je omezen tínmto regulárním výrazem: [1-2]
Toto pole je označeno za zastaralé a v budoucnu bude z Publicanu odstraněno.
Zabalit soubor výpisu (dump) po dokončení zápisu do formátu zip.
Výchozí hodnotou tohoto parametru je: 0.
Soubor výpisu (dump) webových stránek vytvořených v Publicanu obsahuje některé základní podrobnosti o nastavení webových stránek, společně s podrobnostmi o každém dokumentu na nich zveřejněném. Těmito podrobnostmi nastavení jsou:
<host>
URL kořenu webových stránek dokumentace, jak je nastaven parametrem host
v konfiguračním souboru webových stránek.
<def_lang>
Výchozí jazyk dokumentace na webových stránkách, jak je nastaven parametrem def_lang
v konfiguračním souboru webových stránek.
Každý dokument, v každém jazyku, v každém formátu má svůj vlastní záznam. Tyto záznamy obsahují tyto údaje:
<name>
Název dokumentu, získaný z tagu <title>
v souboru Book_Info.xml
, Article_Info.xml
či Set_Info.xml
, pokud není potlačen (přenastaven) parametrem docname
v souboru publican.cfg
. Mezery v názvu jsou nahrazeny podtržítkem.
<ID>
Jedinečné číslo ID pro daný dokument, v daném formátu, v daném jazyku.
<abstract>
Krátké shrnutí obsahu dokumentu, získané z tagu <abstract>
v souboru Book_Info.xml
, Article_Info.xml
či Set_Info.xml
. Stejný obsah používá Publican k vytvoření oddílu %description
souboru spec při balení dokumentu. Je-li <abstract>
přeložen, toto pole obsahuje přeložený text.
<format>
Formát, v němž je dokument vytvořen — html
pro vícestránkové html, html-single
pro jednostránkové html, pdf
pro PDF a epub
pro EPUB.
<language>
Kód jazyka dokumentu. Více informací o jazykových kódech v XML viz F – „Jazykové kódy“.
<name_label>
Název dokumentu, který je zobrazen v obsahu webových stránek. Tento popisek lze nastavit parametrem web_name_label
v souboru publican.cfg
dokumentu. V opačném případě zůstává pole prázdné pro dokument ve svém originálním jazyce, nebo se použije přeložený název dokumentu v přeloženém jazyce. Všechny mezery v popisku názvu jsou nahrazeny podtržítkem.
<product>
Produkt, o němž pojednává dokument, získaný z tagu <productname>
v souboru Book_Info.xml
, Article_Info.xml
či Set_Info.xml
, pokud není potlačen parametrem product
v souboru publican.cfg
. Všechny mezery v názvu produktu jsou nahrazeny podtržítkem.
<product_label>
Název produktu, který je zobrazen v obsahu webových stránek. Tento popisek lze nastavit parametrem web_product_label
v souboru publican.cfg
dokumentu. V opačném případě zůstává pole prázdné pro dokument ve svém originálním jazyce, nebo se použije přeložený název dokumentu v přeloženém jazyce. Všechny mezery v popisku názvu jsou nahrazeny podtržítkem.
Je-li popisek názvu produktu nastaven na UNUSED
, pro tento produkt se v obsahu webových stránek nezobrazí žádný nadpis (položka obsahu).
<subtitle>
Jednořádkový popis obsahu dokumentu, získaný z tagu <subtitle>
v souboru Book_Info.xml
, Article_Info.xml
či Set_Info.xml
. Stejný obsah používá Publican k vytvoření oddílu Summary
souboru spec při balení dokumentu. Je-li <subtitle>
přeložen, toto pole obsahuje přeložený text.
<update_date>
Datum, kdy byl dokument nejnověji nainstalován na webové stránky, ve formátu RRRR-MM-DD.
<version>
Verze produktu, o němž pojednává dokument (nikoliv verze samotného dokumentu), získaná z tagu <productnumber>
v souboru Book_Info.xml
, Article_Info.xml
či Set_Info.xml
, pokud není potlačen parametrem version
v souboru publican.cfg
.
<version_label>
Verze produktu, jak je zobrazena v obsahu webových stránek. Tento popisek lze nastavit parametrem web_version_label
v souboru publican.cfg
dokumentu.
Je-li popisek verze produktu nastaven na UNUSED
, pro tuto verzi se v obsahu webových stránek nezobrazí žádný nadpis (položka obsahu).
Příklad D.1. Ukázkové záznamy ze souboru DUMP.xml
Tyto dva záznamy ze souboru DUMP.xml
ukazují stejnou knihu, Red Hat Enterprise Linux 5 Installation Guide, ve dvou různých formátech a dvou různých jazycích — anglickém v PDF a francouzském ve vícestránkovém HTML.
<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>
Použitím těchto polí lze zpracovat URL kteréhokoliv dokumentu na webových stránkách:
<host>
<name>
<format>
<language>
<product>
<version>
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
Například http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html
.
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
Například 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
Například 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
Například http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.epub
Všimněte si, že pole <product_label>
, <version_label>
a <name_label>
nemají pro URL žádný význam, ani když jsou potlačeny v obsahu nastavením UNUSED
.
Jediná povinná část tagu language v XML v Publicanu je subtag jazyka. Avšak Publican je navržen s předpokladem, že budete rutinně zahrnovat při uvádění jazyka i subtag regionální. V mnoha jazycích se hláskování a slovník významně liší dle regionu. Neuvedete-li regionální variantu jazyka, ve kterém je váš dokument napsán nebo přeložen, můžete po sestavení dokumentu v Publicanu obdržet neočekávané výsledky.
Kódový systém používaný pro identifikaci jazyků v normě XML není jediným systémem jazykových kódů, který se dnes na světě používá. Protože však Publican usiluje o soulad se standardem XML, jedná se o jediné kódy, které Publican podporuje. Zejména si uvědomte, že kódy používané v nástrojích GNU (identifikovatelné užíváním podtržítek a symbolu @
k oddělení svých prvků — například en_GB
nebo sr_RS@latin
) nejsou v souladu se standardem XML, a proto v Publicanu nefungují.
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]
Jazykové tagy (značky) se skládají z jednoho z mnoha subtagů (podznaček), oddělených od sebe navzájem pomlčkami. Jejich pořadí v jazykové značce je následující:
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).
Podznačka varianty identifikuje dobře definovanou, uznávanou variantu jazyka nebo písma a může obsahovat velká písmena, malá písmena a číslice. Podznačky varianty, které začínají písmenem, musí mít délku alespoň pět znaků a které začínají číslicí, musí být dlouhé alespoň čtyři znaky. Většinu podznaček varianty lze používat pouze v kombinaci se specifickými podznačkami nebo kombinacemi podznaček. Podznačky varianty nesledují soulad s žádnou normou; jsou výsledkem oddělené registrace u IETF zájmovými osobami nebo skupinami.
Dle současné normy jsou dialekty několika jazyků určeny podznačkou varianty, např. nedis
označuje nadižu (též Natisone), slovinský dialekt. Tato podznačka musí být užita ve spojení s podznačkou jazyka slovinštiny, proto: sl-nedis
. V září 2009 vydalo IETF výzvu k připomínkám (RFC), která (mimo jiné) navrhuje, aby byly dialekty reprezentované rozšiřujícími podznačkami jazyka připojeny k podznačkám jazyka.[14]
Většina podznaček varianty značí konkrétní pravopis (ortografii), nejčastěji jako výsledek zvláštní reformy hláskování nebo významného díla dokumentujícího jazyk. Mezi tyto příklady patří (s jejich povinnými jazykovými podznačkami): fr-1606nicot
(francouzština zdokumentovaná Jeanem Nicotem roku 1606), de-1901
(německý pravopis kodifikovaný 2. Ortografickou konferencí v roce 1901) a be-1959acad
(běloruština kodifikovaná Ortografickou komisí v roce 1959).
Konečně některé podznačky variant značí zvláštní variantu písma nebo transliterace. Například zh-Latn-wadegile
je čínština zapsaná v latinské abecedě, dle systému transliterace vyvinutého Thomasem Wadem a Herbertem Gilesem; ja-Latn-hepburn
je japonština zapsaná v latinské abecedě užitím systému transliterace Jamese Curtise Hepburna.
Publican obsahuje podporu pro následující jazyky:
ar-SA — arabština
as-IN — ásámština
ast-ES — asturština
bg-BG — bulharština
bn-IN — bengálština (Indie)
bs-BA — bosenština
ca-ES — katalánština
cs-CZ — čeština
da-DK — dánština
de-CH — němčina (Švýcarsko)
de-DE — němčina (Německo)
el-GR — řečtina
es-ES — španělština
fa-IR — perština
fi-FI — finština
fr-FR — francouzština
gu-IN — gudžarátština
he-IL — hebrejština
hi-IN — hindština
hr-HR — chorvatština
hu-HU — maďarština
id-ID — indonéština
is-IS — islandština
it-IT — italština
ja-JP — japonština
kn-IN — kannadština
ko-KR — korejština
lv-LV — lotyština
ml-IN — malajálamština
mr-IN — maráthština
nb-NO — norština (Bokmål ortografie)
nl-NL — nizozemština
or-IN — urijština
pa-IN — paňdžábština
pl-PL — polština
pt-BR — portugalština (Brazílie)
pt-PT — portugalština (Portugalsko)
ru-RU — ruština
si-LK — sinhálština
sk-SK — slovenština
sr-Cyrl-RS — srbština (azbuka)
sr-Latn-RS — srbština (latinka)
sv-SE — švédština
ta-IN — tamilština
te-IN — telugština
th-TH — thaijština
uk-UA — ukrajinština
zh-CN — čínština (Čínská lidová republika, implicitně zjednodušené písmo Han)
zh-TW — čínština (Čínská republika, implicitně tradiční písmo Han)
Přehled revizí | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Revize 4.2-0.4 | Thu Apr 30 2015 | ||||||||||
| |||||||||||
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 | ||||||||||
|