# Uživatelská příručka

## Zveřejnění knih, článků, dokumentů a vícesvazkových sad s DocBook XML

### Don Domingo

Red Hat
Engineering Content Services
`ddomingo@redhat.com`

### Zac Dover

Red Hat
Engineering Content Services
`zdover@redhat.com`

### Sven Dowdeit

Instalační pokyny pro Debian a Docker

### Norman Dunbar

Instalační pokyny pro OpenSUSE

### Brian Forté

Red Hat
Engineering Content Services
`bforte@redhat.com`

### Rüdiger Landmann

Red Hat
Engineering Content Services
`r.landmann@redhat.com`

### Rebecca Newton

Red Hat
Engineering Content Services

### Joshua Oakes

Red Hat
Engineering Content Services

### Joshua Wulf

Red Hat
Engineering Content Services
`jwulf@redhat.com`

### Jeff Fearn

Významné přepracování, hrubé návrhy, přetrvávající obtíže.
`jfearn@redhat.com`

### Josef Hruška

Kontrola příkladů českého jazyka v Entities a překlad
Fedora
Localization Project

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.

# Předmluva

## 1. Konvence používané v dokumentu

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

### 1.1. Typografické konvence

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 a `dir` 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 System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).

> Chcete-li do souboru gedit vložit speciální znak, vyberte Aplikace → Příslušenství → Mapa znaků z lišty hlavní nabídky. Dále vyberte Vyhledat → Hledat… z nabídkové lišty Mapa znaků, napiště jméno znaku v poli Hledat a klepněte na Další. 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 Zkopírovat. Nyní přejděte zpět do vašeho dokumentu a vyberteÚpravy → Vložit 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.

### 1.2. Konvence pro Citace

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"));
       }
    }

### 1.3. Admonitions

Pro zvýraznění informací, které by jinak mohly být přehlédnuty, používáme tři vizuální styly.

Poznámka

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.

Tip

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é

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.

Výstraha

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í

Varování by neměla být přehlížena. Přehlížení varování povede většinou ke ztrátě dat.

## 2. Potřebujeme zpětnou vazbu!

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.

# Úvod

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.

## 1. Tento oddíl slouží k testování výstupu a nebude součástí zvěřejňovaných dokumentů

### 1.1. Testing BZ #1092351 Code Switcher

Perl C++

    #!/usr/bin/perl
    use strict;
    use warnings;

    print "Hello, World!\n";

    #include <iostream>

    int main()
    {
      std::cout << "Hello World!"; &lies;
    }

### 1.2. Testing BZ #1088051 Code Popper

    [Show All][Hide]$ apt-get search libxslt
    gambas3-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

### 1.3. Testing BZ #1112899 Callouts and BZ #1101050 Entities in CDATA

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;
        }
      }

1

  Navazuje spojení s messaging broker.

2

  Vytváří objekt relace, který udržuje stav všech interakcí s messaging broker a řídí vysílače a příjímače.

3

  Vytváří příjímač, který čte z dané adresy.

4

  Vytváří vysílač, kterí odesílá na danou adresu.

5

  Čte další zprávu. Doba trvání je nepovinná, není-li zadána, bude čekat na příští zprávu nekonečně.

6

  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.

7

  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

1

  `column_name` (povinný): název sloupce se sadou hodnot indexu.

2

  `base` (nepovinný - výchozí `0`): hodnota sloupce s indexy, která odpovídá prvnímu prvku seznamu nebo pole.

### 1.4. Testing BZ #752021 Cross-Browser embed external video

### 1.5. Testing BZ #1110611 A line break is automatically inserted after cdata in code.

Je vložen nový řádek po tomto `CDATA`?

### 1.6. Testing BZ #1117561 CDATA tags

=, >, >=, <, <=, <>

!=

<>

### 1.7. Testing BZ #1135827 Single line comment being highlighted in a callout.

    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
      }

    }

1

  Třída `ServiceRegistry` je názorná třída implementující obchodní logiku úlohy.

2

  Volání `completeWorkItem()` dokončuje vykonání pracovní položky.

### 1.8. Testing BZ #1168765 programlisting no longer support language attribute.

    <?xml version="1.0" encoding="UTF-8"?><test></test>

# Kapitola 1. Instalace Publicanu

## 1.1. Operační systémy Linux

Důležité — Dostupnost v repositářích

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.

### 1.1.1. Fedora & Red Hat Enterprise Linux 6

1. Otevřete terminál.

2. Přihlaste se jako uživatel root: su -

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

### 1.1.2. Ubuntu

1. Otevřete terminál.

2. Spusťte následující příkaz, abyste nainstalovali balíček publican:

       $ sudo apt-get install publican

### 1.1.3. Debian

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.

1. Otevřete terminál.

2. Přihlaste se jako uživatel root: su -

3. Spusťte následující příkaz, abyste nainstalovali balíček publican:

       $ apt-get install publican

4. Spusťte následující příkaz, abyste určili, která verze publicanu je nainstalována:

       $ publican -v
       version=2.8

Důležité — Instalace nejnovějších balíčků použitím Apt-Pinning

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:

1. Otevřete terminál.

2. Přihlaste se jako uživatel root: su -

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

4. Přidejte tuto řádku na konec souboru:

       #### testing  #########
       deb http://ftp.us.debian.org/debian testing main contrib non-free

5. Uložte soubor a zavřete textový editor.

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

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

8. Uložte soubor a zavřete textový editor.

9. Spusťte následující příkaz, aby se zaktualizoval seznam balíčků dostupných pro váš počítač:

       $ apt-get update

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

    $ publican
    Warning: 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.

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:

1.     [Show All][Hide]$ apt-get search libxslt
       gambas3-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 to samé znovu pro libxml2)

2. A poté povýšit verzi těchto balíčků na testovací.

       $ apt-get -t testing upgrade libxml2 libxslt1.1

### 1.1.4. OpenSuse 12

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:

1. Otevřete sezení terminálu.

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

   Poznámka

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

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

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

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

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

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

   Poznámka

   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

   Poznámka

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

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

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

   Poznámka

   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.

### 1.1.5. Docker kontejner

Poznámka

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.

1. Otevřete terminál.

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

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

4. nyní můžete používat publican dle své dokumentace

       $ publican --version
       version=3.2.1

### 1.1.6. Spuštění publicanu z GIT checkout

Je možné spustit publican z GIT checkout, bez nutnosti jeho instalace, jsou-li nainstalovány závislosti.

1. Chcete-li stáhnout, nebo přesněji zkontrolovat (checkout), zdroj z GIT, otevřete terminál.

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

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

## 1.2. Operační systémy Windows

1. Stáhněte instalační soubor Publicanu ze stránky https://fedorahosted.org/releases/p/u/publican/.

2. Přejděte do adresáře, do kterého jste stáhli soubor `Publican-Installer-verze.exe`.

3. Poklepejte na soubor `Publican-Installer-version.exe`.

4. 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 Souhlasím, jinak stiskněte Zrušit.

5. 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 Další.

6. 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ář.

7. Jste-li spokojení s cílovým adresářem, klepněte na Instalovat.

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

8. Když tento proces skončí, instalační program vás upozorní zprávou `Dokončeno`.

   Klepněte na Zavřít, čímž ukončíte instalační program.

## 1.3. OSX Lion

1. Nainstalujte Xcode z obchodu Mac App Store.

   Poznámka

   Xcode má velikost asi 4GB, proto se obrňte trpělivostí. Nicméně obsahuje potřebné věci.

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

3. Otevřete terminál.

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

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

6. Nainstalujte FOP, chcete-li, aby fungovaly PDF:

       $ sudo port install fop

       $ echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc

7. 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 clone git://git.fedorahosted.org/publican.git

8. Změňte adresáře:

       $ cd publican/publican

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

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

1.     $ publican create --name=testbook

2.     $ cd testbook

3.     $ publican build --formats=html --langs=en-US

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

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

2. Zkontrolujte SVN vámi vybrané grafické úpravy, nebo získejte předsestavenou grafickou úpravu od přítele.

   1. Umístění SVN pro grafické úpravy poskytované společností Red Hat je na adrese http://svn.fedorahosted.org/svn/publican

   2. Použijete-li předsestavenou grafickou úpravu, rozbalte ji jak je třeba.

3. Získáte-li grafickou úpravu z SVN, sestavte ji.

       $ cd publican/publican-jboss

       $ publican build --formats=xml --langs=all --publish

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

# Kapitola 2. Výchozí hodnoty Publicanu

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)

Poznámka

Tento soubor je zcela jiný než `publican.cfg`, který se užívá k sestavení knihy. Ten stejné parametry nepřijímá.

## 2.1. Příklady výchozích hodnot Publicanu

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 build
    Setting 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"

# Kapitola 3. Příkazy Publicanu

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 Nabídky Start.

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_akce

  Akce 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_akce

  Ně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“

# Kapitola 4. Tvorba dokumentu

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

## 4.1. Soubory v adresáři knihy

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`

### 4.1.1. Soubor publican.cfg

Poznámka - vlastní úprava výstupu

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

  Používat opatrně

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

  Arch nastavená pro kořenové uzly

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

  xref a atribut arch

  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

  chunk_section_depth: 0

    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, …

  chunk_section_depth: 1

    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 …

  chunk_section_depth: 2

    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 …

  chunk_section_depth: 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 …

  chunk_section_depth: 4 (výchozí)

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

  Root nodes and conditional tagging

  If the root node of an XML file is excluded with a conditional, your document will not build, because empty files are not valid XML. For example, if `Installation_and_configuration_on_Fedora.xml` contains a single chapter:

      <?xml version='1.0' encoding='utf-8' ?>
      <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
      ]>
      <chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora">
      <title>Installation and configuration on Fedora</title>

      [text of chapter]

      </chapter>

  and this chapter is included in `User_Guide.xml` with an `<xi:include>` tag, the document will not build with `$` condition: Ubuntu set in the `publican.cfg` file.

  To exclude this chapter, add a condition to the `<xi:include>` tag in `User_Guide.xml`, not to the `<chapter>` tag in `Installation_and_configuration_on_Fedora.xml`.

  xrefs and conditional tagging

  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.

  Různé DTD mohou zpomalit sestavování

  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.

  Poznámka

  Tento parametr je povolen pouze v grafické úpravě.

`dtd_uri`

  Potlačuje URI pro DocType. Musí mít podobu celého řetězce.

  Poznámka

  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.

  Poznámka

  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

  generate_section_toc_level: 0 (default)

    Publican vytvoří obsahy na začátku dokumentu a v částech, kapitolách a přílohách, nikoliv však v oddílech.

  generate_section_toc_level: 1

    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 …

  generate_section_toc_level: 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

  toc_section_depth: 0

    Publican vygeneruje hlavní obsah pouze z kapitol.

  toc_section_depth: 1

    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 …

  toc_section_depth: 2 (výchozí)

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

  Důležité — `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"`

Nápověda z příkazové řádky

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.

### 4.1.2. Book_Info.xml

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

Jiné balíčky než balíčky RPM

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

  Permitted characters

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

  Permitted characters

  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.

  Permitted characters

  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.

  Permitted characters

  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.

  Permitted characters

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

#### 4.1.2.1. Balíčky RPM, vydání, přetisky a verze

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.

### 4.1.3. Author_Group.xml

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

### 4.1.4. Chapter.xml

Články a kapitoly

Č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

Poznámka

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

### 4.1.5. Nazev_Dok.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`.

Důležité

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.

### 4.1.6. Nazev_Dok.ent

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

#### 4.1.6.1. Entity a překlad

Entity používejte s maximální opatrností

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.

### 4.1.7. Revision_History.xml

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.

## 4.2. Přidání obrázků

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.

Umístění obrazových souborů

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

[1] Viz http://www.section508.gov/

## 4.3. Přidání příkladů kódu

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 (&amp; and &lt; 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:

1. Vytvořte adresář extras

       $ mkdir cs-CZ/extras

2. Zkopírujte soubor s kódem do adresáře extras

       $ cp ~/priklady/foo.c en-US/extras/.

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

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

## 4.4. Přidání souborů

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

## 4.5. Změna názvu dokumentu

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_nazev

  změ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_produkt

  změ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_verze

  změ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

## 4.6. Překlad dokumentu

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í:

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

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

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

   Odstraňte nepoužívané soubory XML

   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.

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

   Odstraňte nepoužívané sobory POT

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

5. Přeložte řetězce nacházející se v souborech PO.

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

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

### 4.6.1. Autorská skupina překladu

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.

### 4.6.2. Překlad rejstříků a slovníků

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

## 4.7. Sestavení dokumentu

Poznámka — Vlastní úprava výstupu

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:

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

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

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

4. 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=jazyky

  Sestavit knihu do formátu vícestránkového HTML, jednostránkového HTML i PDF.

### 4.7.1. Sestavení dokumentu bez validace

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

## 4.8. Balení dokumentu

Jiné balíčky než balíčky RPM

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.

Poznámka - vlastní úprava výstupu

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

### 4.8.1. Druhy balíčků RPM

Publican může vytvářet jak zdrojové balíčky RPM (balíčky SRPM), tak binární balíčky RPM.

#### 4.8.1.1. Zdrojové balíčky RPM a 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“.

#### 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 Systém → Dokumentace. 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.

#### 4.8.1.3. Položky nabídky pracovní plochy pro dokumenty

Ve výchozím nastavení se balíčky RPM dokumentů pro použití na stolním počítači vytvořené v Publicanu zobrazují na ploše pracovního prostředí GNOME pod nabídkou Systém → Dokumentace. Pokud mají uživatelé na svém systému nainstalováno příliš mnoho dokumentů, tato nabídka začne být nepřehledná. Smíchává se dokumentace pro mnoho různých produktů a možná i v různých jazycích, to vše přispívá ke zmatečnosti.

Chcete-li v nabídce Systém → Dokumentace GNOME seskupit dokumentaci pro svůj produkt do samostatné podnabídky, musíte:

- vytvořit a šířit balíček nabídky pro pracovní plochu stolního počítače, který vytvoří novou podnabídku,

- uvést kategorii nabídky v dokumentu a volitelně popřípadě zajistit, aby balíček s dokumentací vyžadoval balíček nabídky.

Všimněte si, že nabídka Dokumentace neseskupuje položky do podnabídky dokud nejsou nainstalovány dva nebo více dokumentů, které patří do podnabídky. První dokument se zobrazí pod Systém → Dokumentace.

##### 4.8.1.3.1. Vytvoření balíčku nabídky pracovní plochy

Balíček nabídky pracovní plochy se skládá z:

- souboru položky pracovní plochy (`.directory`), který poskytuje metadata o nové podnabídce,

- souboru nabídky pracovní plochy (`.menu`), který určuje pozici nové podnabídky v nabídce Dokumentace.

Soubor `.directory` pro dokumentaci vytvořenou v Publicanu má tuto strukturu:

- nadpis skupiny `[Desktop Entry]`,

- parametr `Name`, nastaven na název podnabídky, kterou chcete umístit pod nabídku Dokumentace,

- volitelně lokalizace parametru `Name` ve formátu `Name[kod_jazyka]`, kde kod_jazyka je kód jazyka ve formátu knihovny glibc, nikoliv ve formátu XML, který používá pro jazykové kódy Publican,

- parametr `Comment`, nastaven na krátký popis nové podnabídky,

- volitelně lokalizace parametru `Comment` ve formátu `Comment[kod_jazyka]`, kde kod_jazyka je kód jazyka ve formátu knihovny glibc, nikoliv ve formátu XML, který používá pro jazykové kódy Publican,

- parametr `Type`, nastaven na `Directory`,

- parametr `Encoding`, nastaven na `UTF-8`,

Soubor položky pracovní plochy je umístěn v `/usr/share/desktop-directories/`

Úplný popis fungování položek pracovní plochy viz Desktop Entry Specification, dostupné on-line na adrese http://standards.freedesktop.org/entry-spec/latest/

Soubor nabídky pracovní plochy je soubor XML, který obsahuje:

- deklaraci typu dokumentu pro freedesktop.org Desktop Menu Specification:

      <!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
      "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">

- kořenový prvek `<Menu>`

  - prvek `<Name>` a v něm text `Documentation`

  - další prvek `<Menu>`, který naopak obsahuje:

    - prvek `<Name>` s textem `Documentation` (stejně jako kořenový prvek),

    - prvek `<Directory>`, jehož obsahem je název souboru položky pracovní plochy, kterou jste vytvořili, např.:

          <Directory>menu-example.directory</Directory>,

    - prvek `<Includes>`, jehož obsah je `X-nazev_kategorie`, kde nazev_kategorie je identifikátor pro dokumenty, které budou pod touto položkou nabídky seskupeny. Například:

          <Includes>X-Example-Docs</Includes>

Soubor nabídky pracovní plochy je umístěn v `/etc/xdg/menus/settings-merged/`

Úplný popis fungování nabídek pracovní plochy viz Desktop Menu Specification, dostupné on-line na adrese http://standards.freedesktop.org/desktop-menu-spec/latest/

##### 4.8.1.3.2. Nastavení kategorie nabídky pracovní plochy

Dokument umístíte do podnabídky nabídky Systém → Dokumentace nastavením parametru `menu_category` v jeho souboru `publican.cfg` tak, aby se jeho obsah shodoval s prvkem `<Includes>` v příslušném souboru nabídky pracovní plochy. Například zvažte soubor nabídky pracovní plochy, který obsahuje prvek:

    <Includes>X-Example-Docs</Includes>

Chcete-li umístit dokument do podnabídky definované tímto souborem nabídky pracovní plochy, soubor `publican.cfg` dokumentu by měl obsahovat:

    menu_category: X-Example-Docs

Důležité

Publican zpracuje řetězec v menu_category a nahradí `__LANG__` současným jazykem. To umožňuje nabídkám, aby byly upraveny na jazykovém základě.

    menu_category: X-Example-Docs-__LANG__

Všimněte si, že tento parametr lze zahrnout do souboru `defaults.cfg` nebo `overrides.cfg` grafické úpravy, aby všechny dokumenty sestavené s touto grafickou úpravou byly seskupeny do dané podnabídky automaticky, bez nutnosti nastavovat parametr `menu_category` v každém dokumentu.

Šíříte-li soubory nabídky a položky pracovní plochy jako balíček RPM, můžete zajistit, aby balíčky RPM dokumentace vyžadovaly balíčky nabídky pracovní plochy. S takto nastavenou závislostí se balíčky nabídky pracovní plochy nainstalují na systémy uživatelů automaticky při instalaci balíčku dokumentace, což zajistí, aby se dokumentace zobrazovala pod podnabídkou, kterou jste vytvořili pro svůj projekt. Závislost nastavíte parametrem `dt_requires` v souboru `publican.cfg` dokumentu. Například šíříte-li balíček nabídky pracovní plochy nazvaný foodocs-menu, nastavte:

    dt_requires: foodocs-menu

Všimněte si, že tento parametr lze zahrnout do souboru `defaults.cfg` nebo `overrides.cfg` grafické úpravy, aby všechny dokumenty sestavené s touto grafickou úpravou vyžadovaly stejný balíček nabídky pracovní plochy.

### 4.8.2. Příkaz `$` 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` jazyk

  uvádí jazyk, pro který se připraví balíček dokumentace.

  Neúplné překlady

  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.

  Vynechání čísla verze softwaru

  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.

#### 4.8.2.1. Příkaz `$` 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-CZ

  vytvoří 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-CZ

  vytvoří 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-CZ

  vytvoří 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-CZ

  vytvoří 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-CZ

  vytvoří 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.

[3] Viz http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA

## 4.9. Podmíněné tagování

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

Root nodes and conditional tagging

If the root node of an XML file is excluded with a conditional, your document will not build, because empty files are not valid XML. For example, if `Installation_and_configuration_on_Fedora.xml` contains a single chapter:

    <?xml version='1.0' encoding='utf-8' ?>
    <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    ]>
    <chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora">
    <title>Installation and configuration on Fedora</title>

    [text of chapter]

    </chapter>

and this chapter is included in `User_Guide.xml` with an `<xi:include>` tag, the document will not build with `$` condition: Ubuntu set in the `publican.cfg` file.

To exclude this chapter, add a condition to the `<xi:include>` tag in `User_Guide.xml`, not to the `<chapter>` tag in `Installation_and_configuration_on_Fedora.xml`.

xrefs and conditional tagging

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

### 4.9.1. Podmíněné tagování a překlady

Podmíněné tagování používejte velmi opatrně

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.

## 4.10. Software před oficiálním zveřejněním a návrh dokumentace

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.

### 4.10.1. Označování softwaru před oficiálním zveřejnění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í:

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

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

Důležité

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.

### 4.10.2. Označování návrhu dokumentace

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?!

### 4.10.3. Označování návrhu dokumentace softwaru před oficiálním zveřejněním

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

### 4.10.4. Označování upraveného obsahu New section

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

added

  Takto by měl být označkován prvek, který byl v nové revizi přidán.

changed

  Takto by měl být označkován prvek, který byl v nové revizi upraven/změněn.

deleted

  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.

# Kapitola 5. Grafická úprava

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

## 5.1. Instalace grafické úpravy

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:

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

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

3. Sestavte grafickou úpravu:

       $ publican build --formats xml --langs all --publish

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

## 5.2. Vytvoření grafické úpravy

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' *

## 5.3. Soubory v adresáři grafické úpravy

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.

### 5.3.1. Soubor publican.cfg

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.

### 5.3.2. Soubor defaults.cfg a overrides.cfg

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.

### 5.3.3. Soubor publican-grafuprava.spec

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

### 5.3.4. README

Soubor `README` obsahuje stručný popis balíčku grafické úpravy.

### 5.3.5. COPYING

Soubor `COPYING` obsahuje podrobnosti o licenci k autorskému dílu balíčku a snad i text samotné licence.

### 5.3.6. Common Content grafické úpravy

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.

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

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

### 5.3.7. Podadresář `css`

Podadresář `css` obsahuje jediný soubor: `override.css`

#### 5.3.7.1. overrides.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.

### 5.3.8. Podadresář `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“.

### 5.3.9. Volba brand_dir

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

Důležité

Grafické úpravy s vlastními (zákaznicky) upravenými XSLT potřebují změnit relativní cestu pro odkazování šablon XSL na URI.

## 5.4. Balení grafické úpravy

Jiné balíčky než balíčky RPM

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.

# Kapitola 6. Užití sad

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

## 6.1. Samostatné 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

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

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

       $ cd Moje_Sada/en-US
       $ mkdir Kniha_A Kniha_B

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

4. Stejný postup použijte pro Knihu_B, jenž se nachází v adresáři `knihy/Moje_Sada/en-US/Kniha_B`.

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

6. Abyste učinili XML sady validní, musíte změnit toto:

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

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

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

## 6.2. Distribuované sady

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.

Důležité

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

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

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

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

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

5. Sadu otestujte spuštěním příkazu publican build --formats=test --langs=en-US.

   Důležité

   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.

# Kapitola 7. Sestavování webových stránek Publicanem

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.

## 7.1. Ruční sestavování webových stránek

### 7.1.1. Vytvoření struktury webových stránek

Chcete-li vystavět strukturu webových stránek:

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

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

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

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

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

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

      Důležité — u vyhledávacího parametru není provázena validace

      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.

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

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

   6. Volitelně uveďte webový styl s `web_style`.

      web_style: 1

        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)

      web_style: 2

        Webové stránky obsahují drobečkovou navigační lištu na vrchu dokumentace.

      Důležité

      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.

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

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

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

5. Sestavte a nainstalujte každou grafickou úpravu, včetně grafické úpravy `common` Publicanu.

   1. Přejděte do adresáře, v němž se nachází zdrojové soubory grafické úpravy.

          $ cd brandsrc_dir

   2. Sestavte grafickou úpravu.

          $ publican build --formats=xml --langs=all --publish

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

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

### 7.1.2. Vytvoření, instalace a aktualizace domovské stránky

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:

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

2. Přejděte do adresáře článku:

       $ cd page_name

   Na příklad:

       $ cd Home_Page

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

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

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

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

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

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

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

### 7.1.3. Vytvoření, instalace a aktualizace stránek produktu a verze

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:

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

2. Přejděte do adresáře článku:

       $ cd nazev_stranky

   Na příklad:

       $ cd FooMaster

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

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

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

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

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

### 7.1.4. Instalace, aktualizace a odstranění dokumentů

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.

## 7.2. Sestavování webových stránek za použití balíčků RPM

### 7.2.1. Vytvoření struktury webových stránek

Varování — Tento postup přepisuje soubory

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:

1. Přihlaste se do webového serveru.

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

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

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

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

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

      Důležité — u vyhledávacího parametru není provázena validace

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

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

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

   6. Volitelně uveďte webový styl ve `web_style`.

      web_style: 1

        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)

      web_style: 2

        Webové stránky obsahují drobečkovou navigační lištu na vrchu dokumentace.

      Důležité

      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.

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

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

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

### 7.2.2. Vytvoření, instalace a aktualizace domovské stránky

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.

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

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

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

### 7.2.3. Vytvoření, instalace a aktualizace stránek produktu a verze

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.

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

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

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

### 7.2.4. Instalace, aktualizace a odstranění dokumentů

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

## 7.3. Předložení mapy stránek vyhledávacím strojům

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.

### 7.3.1. Předložení mapy stránek vyhledávači Google

Postup 7.1. Chcete-li předložit mapu stránek Googlu:

1. Zaregistrujte si účet Google na stránce Nástroje Google pro webmastery. Máte-li již účet Google vytvořen, lze ho použít.

2. Přihlaste se do svého účtu pro Nástroje Google pro webmastery na této URL: http://www.google.com/webmasters/tools/home.

3. 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 Přidat stránky.

4. 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 Pokračovat.

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

6. 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 Ověřit.

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

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

9. Jste přeneseni na Stránku předložení mapy stránek. Klepněte na tlačítko Předložit mapu stránek.

10. 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 Odeslat mapu stránek. 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.

### 7.3.2. Předložení mapy stránek vyhledávači Bing

Postup 7.2. Chcete-li předložit mapu stránek Bingu:

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

2. Přihlaste se do svého účtu Bing správce webu na URL: http://www.bing.com/toolbox/webmaster/.

3. Klepněte na tlačítko Přidat web.

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

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

6. 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 Ověřit.

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

8. Zvolte kartu Crawl.

9. Zvolte Mapy stránek a poté Přidat feed.

10. Zobrazí se dialog Přidat feed. Vložte URL souboru mapy svých stránek a klepněte na Odeslat. 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.

# Kapitola 8. Import knihy do Drupalu

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.

## 8.1. Jak sestavit soubor CSV 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.

Důležité — Používejte systém pro správu verzí

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.

## 8.2. Soubor publican.cfg

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

  Důležité — Nastavení autora

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

  Důležité — Nastavení bloku nabídky

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

## 8.3. Příručka pro import do Drupalu

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 zaškrtávací pole a stiskněte tlačítko Uložit nastavení, abyste aktivovali modul Node Import.

Důležité — Povolte core moduly Drupalu

Potřebujete rovněž povolit následující core moduly Drupalu:

- Book

- Menu

- Path

Oprávnění pro instalaci modulu

Nemáte-li oprávnění pro instalaci modulu v Drupalu, obraťte se prosím na svého správce webu.

### 8.3.1. Jak přidat blok nabídky

Lze určit, kterou nabídku má kniha v Drupalu zobrazit. Pokud uvedený blok nabídky neexistuje, Drupal zahrne všechny importované obsahy do primárního odkazu. Proto, přejete-li si zobrazit svou knihu v bloku nabídky, se ujistěte, že jste blok vytvořili před importem knihy. Chcete-li přidat nový blok nabídky, jednoduše se přihlaste na svých stránkách Drupal a přejděte do Administer -> Menus -> Add menu .

- Menu name - jedinečný název nabídky. Jedná se o hodnotu, kterou byste měli nastavit v parametru `drupal_menu_block` v `publican.cfg`.

- Title - název nabídky. Bude zobrazen navrchu bloku nabídky.

### 8.3.2. Nastavení Node import

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

    Důležité — Vlastnictví souboru

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

### 8.3.3. Jak importovat knihu

Chcete-li importovat knihu do Drupalu:

1. Postupujte dle kroků v 8.1 – „Jak sestavit soubor CSV pro import do Drupalu“.

2. Nahrajte soubor CSV do `import directory` na serveru Drupal.

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

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

5. Stiskněte Import now pro zahájení importu knihy. Budete přesměrováni na další stránku, která zobrazuje průběh importu.

6. Odkaz na knihu by se měl nyní zobrazovat v uvedeném bloku nabídky.

### 8.3.4. Jak zaktualizovat knihu

Chcete-li knihu aktualizovat, jednoduše zopakujte kroky v 8.3.3 – „Jak importovat knihu“.

Varování — stránkování oddílů

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

# Kapitola 9. Často kladené dotazy

- Otázka: Jak do své knihy přidám jazyk?
- Otázka: A pokud nechci používat kódy zemí? Mohu například spustit $ publican update_po --langs=es,de,fr?
- Otázka: Jak aktualizuji všechny soubory po?
- Otázka: Kde mohu získat úplný seznam možností pro příkaz build Publicanu?
- Otázka: Kde mohu získat úplný seznam parametrů, které lze nastavit v publican.cfg?
- Otázka: Kde se nachází společné soubory Publicanu?
- Otázka: Lze zahrnout do balíčků archivu nebo RPM libovolné soubory?
- Otázka: Proč mi Publican poskytuje varovaná hlášení o neznámých tazích?
- Otázka: 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ě?
- Otázka: Dostávám chybovou zprávu, že Batik se nenachází v classpath, přitom však Batik nainstalován je. Co je špatně?
- Otázka: Dostávám chybovou zprávu Exception in thread "main" java.lang.OutOfMemoryError: Java heap space, když zkouším sestavit PDF. Co je špatně?
- Otázka: Předchozí verze Publicanu odstraňovaly prázdné tagy <para>. Odstraňuje je Publican stále?
- Otázka: Co stalo s kontrolou pravopisu?
- Otázka: Proč nefungují <segmentedlist>, když sestavuji PDF?
- Otázka: Co se stalo s barvami u mých obrázků v tomto PDF?
- Otázka: Při sestavování svého dokumentu dostávám chybová hlášení o 'undefined language' (nedefinovaném jazyku) - co je špatně?
- Otázka: Jak povolím dokončování příkazů příkazové řádky pro Publican?
- Otázka: Proč mám problém se sestavením své obsáhlé knihy?
- Otázka: Proč Jeff oslovuje Isaaca 'Ivane'?

Otázka:

Jak do své knihy přidám jazyk?

Odpověď:

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.

Otázka:

A pokud nechci používat kódy zemí? Mohu například spustit `$` publican update_po --langs=es,de,fr?

Odpověď:

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.

Otázka:

Jak aktualizuji všechny soubory po?

Odpověď:

Spusťte příkaz `$` publican update_po --langs=all.

Otázka:

Kde mohu získat úplný seznam možností pro příkaz build Publicanu?

Odpověď:

Spusťte příkaz `$` publican build --help.

Otázka:

Kde mohu získat úplný seznam parametrů, které lze nastavit v `publican.cfg`?

Odpověď:

Spusťte příkaz `$` publican help_config v adresáři, kde se nachází kterýkoliv dokument vytvořený v Publicanu.

Otázka:

Kde se nachází společné soubory Publicanu?

Odpověď:

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

Otázka:

Lze zahrnout do balíčků archivu nebo RPM libovolné soubory?

Odpověď:

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

Důležité

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.

Otázka:

Proč mi Publican poskytuje varovaná hlášení o neznámých tazích?

Odpověď:

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

Otázka:

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ě?

Odpověď:

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

Otázka:

Dostávám chybovou zprávu, že Batik se nenachází v classpath, přitom však Batik nainstalován je. Co je špatně?

Odpověď:

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

Otázka:

Dostávám chybovou zprávu `Exception in thread "main" java.lang.OutOfMemoryError: Java heap space`, když zkouším sestavit PDF. Co je špatně?

Odpověď:

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.

Otázka:

Předchozí verze Publicanu odstraňovaly prázdné tagy `<para>`. Odstraňuje je Publican stále?

Odpověď:

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.

Otázka:

Co stalo s kontrolou pravopisu?

Odpověď:

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

Otázka:

Proč nefungují `<segmentedlist>`, když sestavuji PDF?

Odpověď:

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.

Otázka:

Co se stalo s barvami u mých obrázků v tomto PDF?

Odpověď:

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.

Otázka:

Při sestavování svého dokumentu dostávám chybová hlášení o 'undefined language' (nedefinovaném jazyku) - co je špatně?

Odpověď:

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.

Otázka:

Jak povolím dokončování příkazů příkazové řádky pro Publican?

Odpověď:

Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:

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

2. Přidejte toto do svého souboru `~/.bashrc`:

       # Use bash-completion, if available
       if [ -f /etc/bash_completion ]; then
               . /etc/bash_completion
       fi

3. Restartujte svůj terminál nebo spusťte source ~/.bashrc.

Otázka:

Proč mám problém se sestavením své obsáhlé knihy?

Odpověď:

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.

Otázka:

Proč Jeff oslovuje Isaaca 'Ivane'?

Odpověď:

Protože Jeffova paměť se zadrhává!

# Nedoporučené prvky a atributy

Podporované, nepodporované a nedoporučené

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

## A.1. Nedoporučené prvky

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

  A

    `Apple` — an apple is…

  G

    `Grapes` — grapes are…

  O

    `Orange` — an orange is…

  P

    `Peach` — a peach is…

  vypadá ve španělštině takto:

  A

    `Manzana` — la manzana es…

  G

    `Uva` — la uva es…

  O

    `Naranja` — la naranja es…

  P

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

## A.2. Nedoporučené atributy

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

[4] viz http://www.section508.gov/

# Shrnutí příkazů

## B.1. Volby příkazu

--allow_network

  Povolí přístup k síti při zpracování XML a XSLT. Výchozí stav je vypnuto.

--brand_dir=s

  Adresář, ze kterého se načtou soubory grafické úpravy.

--common_config=s

  Potlačí (uvádí novou) cestu k adresáři Common_Config

--common_content=s

  Potlačí (uvádí novou) cestu k adresáři Common_Content

--config=s

  Použít nestandardní konfigurační soubor

--help

  Zobrazit zprávu nápovědy

--nocolours

  Zakázat barevné zvýrazňování protokolu/-ů dle ANSI.

--quiet

  Zakázat tvorbu protokolů.

## B.2. Akce příkazu

`$` publican add_revision

  Přidá záznam do historie revizí

  --date=DATE

    Datum revize.

  --email=EMAIL

    e-mail, který se má u revize použít.

  --firstname=JMENO

    křestní jméno, které se má u revize použít.

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --member=CLEN

    Záznam, který se přidá do historie revizí. Lze ho uvést vícekrát.

  --revnumber=CISLOREVIZE

    Číslo revize, které se u revize použije.

  --surname=PRIJMENI

    příjmení, které se u revize použije.

`$` publican build

  Převede XML do jiných formátů (pdf, html, html-single, drupal-book atd.)

  --distributed_set

    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.

  --embedtoc

    Vestavit objekt obsahu webové stránky do generovaného HTML

  --formats=FORMATY

    Čárkou oddělený seznam formátů, např. html,pdf,html-single,html-desktop,txt,epub

  --langs=JAZYKY

    Čárkou oddělený seznam jazyků, např. en-US,de-DE,all

  --novalid

    Neprovádět validaci DTD

  --pdftool=PDFTOOL

    Potlačí (uvádí jiný) nástroj, který se použije pro tvorbu PDF. Platné volby jsou wkhtmltopdf nebo fop.

  --pub_dir=PUB_DIR

    Adresář, do kterého se uloží soubory určené ke zveřejnění. Ve výchozím nastavení se jedná o adresář publish.

  --publish

    Připravit sestavený obsah ke zveřejnění

  --showfuzzy

    Ve výstupu se zobrazí položky, jejichž překlad je neúplný. Výchozí hodnotou je off.

  --src_dir=ZDROJOVYADRESAR

    Adresář, ze kterého se načtou soubory publicanu.

`$` publican clean

  Odstraní všechny dočasné soubory a adresáře

  --pub_dir=PUB_DIR

    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_ids

  Spustí pro zdrojový XML vyčištění identifikátorů

`$` publican clean_set

  Odstraní místní kopie vzdálených sad knih

`$` publican copy_web_brand

  Zkopíruje nainstalovaný webový obsah grafické úpravy do jiné internetové stránky

  --brand=GRAFICKAUPRAVA

    Grafická úprava, která se má použít

  --old_site_config=OLD_SITE_CONFIG

    Konfigurační soubor webových stránek, který se má použít při kopírování obsahu mezi webovými stránkami.

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

`$` publican create

  Vytvoří novou knihu, sadu nebo článek

  --brand=GRAFICKAUPRAVA

    Grafická úprava, která se má použít

  --dtdver=VERZEDTD

    Verze DocBook DTD, která se má použít.

  --edition=VYDANI

    Číslo vydání knihy, článku nebo sady

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --name=NAZEV

    Název knihy, článku, sady nebo grafické úpravy

  --product=PRODUKT

    Název produktu

  --type=TYP

    Typ (book, article nebo set)

  --version=VERZE

    Verze produktu

`$` publican create_brand

  Vytvoří novou grafickou úpravu

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --name=NAZEV

    Název knihy, článku, sady nebo grafické úpravy

`$` publican create_site

  Vytvoří nové webové stránky v zadaném umístění.

  --db_file=SOUBOR_DB

    Potlačí (uvede jiný) výchozí databázový soubor.

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

  --tmpl_path=CESTA_K_SABLONE

    Potlačí (uvede jinou) výchozí cestu k šabloně.

  --toc_path=CESTA_K_OBSAHU

    Potlačí (uvede jinou) výchozí cestu k obsahu.

`$` publican help_config

  Zobrazí text nápovědy pro konfigurační soubor

`$` publican install_book

  Nainstalovat knihu do webových stránek.

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

`$` publican install_brand

  Nainstalovat grafickou úpravu do uvedeného místa

  --path=CESTA

    /cesta/kam/se/nainstaluje

  --pub_dir=PUB_DIR

    Adresář, do kterého se uloží soubory určené ke zveřejnění. Ve výchozím nastavení se jedná o adresář publish.

  --web

    Nainstalovat webový obsah pro grafickou úpravu.

`$` publican lang_stats

  připraví zprávu o statistice souborů PO

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

`$` publican migrate_site

  Převede databázi webových stránek z verze Publican < 3 na verzi Publican 3.

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

`$` publican package

  Zabalí jazyk k expedici

  --binary

    Při běhu balíčku sestaví binární rpm.

  --brew

    Nahraje balíček SRPM do sestavovacího systému brew

  --desktop

    Namísto webového vytvoří balíček pro stolní počítač

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --pub_dir=PUB_DIR

    Adresář, do kterého se uloží soubory určené ke zveřejnění. Ve výchozím nastavení se jedná o adresář publish.

  --scratch

    Použít scratch sestavení namísto tagovaného

  --short_sighted

    Vytvořit balíček bez uvedení verze v jeho názvu

  --wait

    Vyčkat, než brew dokončí sestavení

`$` publican print_banned

  Vytiskne seznam nepovolených tagů DocBook

`$` publican print_known

  Vytiskne seznam tagů DocBook s kontrolou kvality.

`$` publican print_tree

  Vytisknout strom xi:includes

`$` publican print_unused

  Vytiskne seznam nepoužitých souborů XML

`$` publican print_unused_images

  Vytiskne seznam nepoužitých grafických souborů

`$` publican remove_book

  Odstraní knihu z webových stránek.

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

`$` publican rename

  Přejmenuje knihu v publicanu

  --name=NAZEV

    Název knihy, článku, sady nebo grafické úpravy

  --product=PRODUKT

    Název produktu

  --version=VERZE

    Verze produktu

`$` publican report

  Vytiskne zprávu o čitelnosti zdrojového textu.

`$` publican site_stats

  Připraví zprávu o obsahu na webových stránkách

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

`$` publican trans_drop

  Vytvoří okamžitý snímek zdrojového jazyka pro použití v překladu.

`$` publican update_db

  Př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ů.

  --abstract=ABSTRAKT

    Abstrakt knihy

  --add

    Přidá záznam do databáze

  --book_src_lang=ZDROJOVY_JAZYK_KNIHY

    Jazyk, na němž je tento překlad založen.

  --book_version=VERZE_KNIHY

    Číslo verze knihy, která je instalována.

  --del

    Smazat databázový záznam

  --formats=FORMATY

    Čárkou oddělený seznam formátů, např. html,pdf,html-single,html-desktop,txt,epub

  --lang=JAZYK

    Jazyk, ve kterém bude napsáno XML

  --name=NAZEV

    Název knihy, článku, sady nebo grafické úpravy

  --name_label=POPISEK_NAZVU

    popisek názvu knihy

  --product=PRODUKT

    Název produktu

  --product_label=POPIS_PRODUKTU

    popisek produktu knihy

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

  --sort_order=SMER_RAZENI

    Směr seřazení knihy

  --subtitle=PODTITUL

    Podtitul knihy

  --version=VERZE

    Verze produktu

  --version_label=POPISEK_VERZE

    popisek verze knihy

`$` publican update_po

  Aktualizovat soubory PO

  --email=EMAIL

    e-mail, který se má u revize použít.

  --firstname=JMENO

    křestní jméno, které se má u revize použít.

  --langs=JAZYKY

    Čárkou oddělený seznam jazyků, např. en-US,de-DE,all

  --msgmerge

    Použít msgmerge gettextu pro sloučení POT/PO.

  --previous

    Zachovat předchozí identifikátory zpráv (msgid), nalézají-li se nepřesné překlady v aktualizovaných PO souborech.

  --surname=PRIJMENI

    příjmení, které se u revize použije.

`$` publican update_pot

  Aktualizovat soubory POT

`$` publican update_site

  Aktualizovat šablony existujících stránek.

  --site_config=SITE_CONFIG

    Konfigurační soubor webových stránek, který má být použit nebo vytvořen.

`$` publican zt_pull

  Načíst překlady ze systému Zanata.

`$` publican zt_push

  Nahrát překlady do systému Zanata.

# Přehled nastavení

## C.1. Obecné možnosti

Ty jsou nastaveny v konfiguračních souborech knih nebo grafických úprav.

arch

  Architektura, na níž se filtruje výstup.

audience

  Cílová skupina, na níž se filtruje výstup.

books

  Čárkou oddělený seznam knih, které se použijí v této vzdálené sadě.

brand

  Grafická úprava, která se má použít při sestavování tohoto balíčku.

  Výchozí hodnotou tohoto parametru je: common

brew_dist

  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

  Varování

  Toto pole je označeno za zastaralé a v budoucnu bude z Publicanu odstraněno.

bridgehead_in_toc

  Zobrazit elementy bridgehead v obsazích?

  Výchozí hodnotou tohoto parametru je: 0.

chunk_first

  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.

chunk_section_depth

  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

classpath

  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

common_config

  Cesta k obsahu publicanu.

  Výchozí hodnotou tohoto parametru je: /usr/share/publican

common_content

  Cesta ke společnému obsahu publicanu.

  Výchozí hodnotou tohoto parametru je: /usr/share/publican/Common_Content

condition

  Podmínky, za kterých zredukovat (prune) XML před transformací.

confidential

  Jedná se o důvěrný obsah?

  Výchozí hodnotou tohoto parametru je: 0.

confidential_text

  Text, který je použit k označení důvěrného obsahu.

  Výchozí hodnotou tohoto parametru je: CONFIDENTIAL

conformance

  Conformance, na níž se filtruje výstup.

debug

  Vytisknout zvláštní zprávy?

  Výchozí hodnotou tohoto parametru je: 0.

doc_url

  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

docname

  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_\-\.\+]+$

  Tip

  Toto pole není podporováno pro: brand

drupal_author

  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

drupal_image_path

  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

drupal_menu_block

  Nabídka, ve které se kniha nachází.

  Výchozí hodnotou tohoto parametru je: user-guide (uživatelská příručka)

drupal_menu_title

  Potlačuje název knihy (bookname), který bude zobrazen v nabídce drupalu.

dt_format

  Formát, který se použije pro výstup pro desktop.

  Výchozí hodnotou tohoto parametru je: html-desktop

dt_obsoletes

  Seznam balíčků oddělený mezerami, které budou desktopovým balíčkem označeny za zastaralé.

dt_requires

  Seznam balíčků oddělený mezerami, které vyžaduje desktopový balíček.

dtdver

  Verze DocBook DTD, na které je založen tento projekt.

  Výchozí hodnotou tohoto parametru je: 4.5

ec_id

  ID zásuvného modulu Eclipse. Standardně "$product.$docname"

ec_name

  Název zásuvného modulu Eclipse. Standardně "$product $docname"

ec_provider

  Poskytovatel zásuvného modulu Eclipse. Standardně "Publican-v4.2.2"

extras_dir

  Adresář s obrazy.

  Výchozí hodnotou tohoto parametru je: extras

generate_section_toc_level

  Vytvářet obsah do uvedené hloubky oddílů.

  Výchozí hodnotou tohoto parametru je: 0.

ignored_translations

  Jazyky, které se nahradí parametrem xml_lang bez ohledu na stav překladu.

img_dir

  Adresář s obrazy.

  Výchozí hodnotou tohoto parametru je: images

info_file

  Potlačuje výchozí soubor Info.

lang

  Jazyk, na nějž se filtruje výstup.

license

  Licence, kterou tento balíček používá.

  Výchozí hodnotou tohoto parametru je: GFDL

mainfile

  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.

menu_category

  Seznam kategorií nabídek oddělený středníkem pro balíček desktopu.

os

  operační systém, na nějž se filtruje výstup.

os_ver

  OS, pro který se mají balíčky sestavit.

pdf_body_font

  Písmo, které se má v PDF použít pro tělo textu.

  Výchozí hodnotou tohoto parametru je: Liberation Sans

pdf_mono_font

  Písmo, které se má v PDF použít pro neproporciální text.

  Výchozí hodnotou tohoto parametru je: Liberation Mono

prod_url

  URL pro produkt. Použito u HTML v horním levém URL.

  Výchozí hodnotou tohoto parametru je: https://fedorahosted.org/publican

product

  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_\-\.\+]+$

  Tip

  Toto pole není podporováno pro: brand

repo

  Úložiště (repository), ze kterého získat vzdálenou sadu knih.

rev_dir

  Standardně je přehled revizí řazen sestupně. Nastavením na 'asc' nebo 'ascending' obrátí směr řazení na vzestupné.

rev_file

  Potlačuje výchozí soubor Revision History (Přehled revizí).

revision

  Revize, na níž se filtruje výstup.

revisionflag

  příznak revize, na nějž se filtruje výstup.

role

  role, na níž se filtruje výstup.

scm

  Typ repozitáře, ve kterém jsou uloženy knihy, jenž jsou součástí vzdálené sady. Podporované typy: SVN, GIT.

security

  bezpečnost, na níž se filtruje výstup.

show_remarks

  Zobrazit poznámky v převedeném výstupu.

  Výchozí hodnotou tohoto parametru je: 0.

sort_order

  Potlačuje výchozí váhy řazení. Standardně má hodnotu 50.

src_url

  URL, kde se nalézá soubor tar se zdrojovými soubory. Použito u souborů RPM Spec.

status

  status, na nějž se filtruje výstup.

tmp_dir

  Adresář, který se použije pro sestavení.

  Výchozí hodnotou tohto parametru je: tmp

toc_section_depth

  Hloubka oddílů (podkapitol), které budou uvedeny v obsahu.

  Výchozí hodnotou tohto parametru je: 2

txt_formater

  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)$

type

  Druh obsahu, který obsahuje tento balíček. Podporováno: set, book, article, brand

  Výchozí hodnotou tohoto parametru je: Book

userlevel

  userlevel (úroveň uživatele), na níž se filtruje výstup.

vendor

  vendor (prodejce, výrobce), na nějž se filtruje výstup.

version

  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}]*$

web_brew_dist

  Distribuce sestavovacího systému brew, která se má použít k sestavení webového rpm.

  Výchozí hodnotou tohoto parametru je: docs-5E

web_formats

  Čá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

web_home

  Toto je domovská stránka webové stránky vygenerované Publicanem, nikoliv standardní kniha.

  Varování

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

web_host

  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

  Varování

  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.

web_name_label

  Potlačuje název knihy, spodní úroveň, popisek nabídky na webové stránce Publicanu.

web_obsoletes

  Balíčky k označení za zastaralé ve webovém RPM.

web_product_label

  Potlačuje produkt, horní úroveň, popisek nabídky na webové stránce Publicanu.

web_search

  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.

  Varování

  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.

web_type

  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)$

web_version_label

  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

wkhtmltopdf_opts

  Zvláštní volby předávané do wkhtmltopdf. Např. wkhtmltopdf_opts: "-O landscape -s A3"

wordsize

  wordsize (velikost slova), na níž se filtruje výstup.

xml_lang

  Jazyk v němž je XML napsán.

  Výchozí hodnotou tohoto parametru je: en-US

## C.2. Možnosti grafické úpravy

Tyto parametry jsou nastavovány v konfiguračních souborech grafických úprav.

banned_attrs

  Čárkou oddělený seznam atributů XML, které nejsou ve zdroji povoleny.

banned_tags

  Čárkou oddělený seznam tagů XML, které nejsou ve zdroji povoleny.

base_brand

  Základní grafická úprava, která se má použít pro tuto grafickou úpravu.

  Výchozí hodnotou tohoto parametru je: common

dtd_type

  Potlačuje Type pro DocType. Musí mít formu celého řetězce.

dtd_uri

  Potlačuje URI pro DocType. Musí mít podobu celého řetězce.

no_embedtoc

  Volba grafické úpravy, která ve webových balíčcích zakazuje vytvoření obsahu s navigací.

web_cfg

  Úplná cesta ke konfiguračnímu souboru stránky publicanu pro nestandardní webové stránky RPM.

web_dir

  Cesta pro instalaci nestandardních webových stránek RPM.

web_req

  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.

## C.3. Možnosti webových stránek (site):

Nastavují se v konfiguračním souboru webové stránky.

db_file

  Název souboru databáze SQLite pro vaši webovou stránku, s příponou souboru .db

debug

  Při běhu publicanu vypisovat zvláštní zprávy.

  Výchozí hodnotou tohoto parametru je: 0.

def_lang

  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

dump

  Vypsat databázi publicanu do souboru XML.

dump_file

  Název souboru, do kterého vypsat databázi publicanu.

  Výchozí hodnotou tohoto parametru je: /var/www/html/DUMP.xml

footer

  HTML, které se má vložit do patičky každé stránky webové stránky.

  Výchozí hodnotou tohoto parametru je:

host

  Host webové stránky, může být úplná URI nebo relativní cesta.

  Výchozí hodnotou tohoto parametru je: /docs

manual_toc_update

  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.

search

  HTML, které se vloží jako vyhledávání na webové stránce.

  Výchozí hodnotou tohoto parametru je: Google site search

title

  Název, který se použije u všech navigačních stránek webové stránky.

  Výchozí hodnotu tohto parametru je: Documentation

tmpl_path

  Úplný cesta k adresáři šablon.

  Výchozí hodnotou thoto parametru je: /usr/share/publican/templates

toc_js

  Zdrojový soubor, který se má použít pro funkcionalitu JavaScript.

  Výchozí hodnotou tohoto parametru je: default.js

toc_path

  Cesta k adresáři, ve kterém se vytvoří sobor index.html nejvyšší úrovně.

toc_type

  Šablona, která se má použít pro vygenerování souboru s obsahem webového stylu 1.

  Výchozí hodnotou tohoto parametru je: toc

  Varování

  Toto pole je označeno za zastaralé a v budoucnu bude z Publicanu odstraněno.

web_style

  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]

  Varování

  Toto pole je označeno za zastaralé a v budoucnu bude z Publicanu odstraněno.

zip_dump

  Zabalit soubor výpisu (dump) po dokončení zápisu do formátu zip.

  Výchozí hodnotou tohoto parametru je: 0.

# Obsah souboru s výpisem webových stránek

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>

## D.1. Zpracování URL ze souboru výpisu

Použitím těchto polí lze zpracovat URL kteréhokoliv dokumentu na webových stránkách:

- `<host>`

- `<name>`

- `<format>`

- `<language>`

- `<product>`

- `<version>`

vícestránkové HTML

  `<host>`/`<language>`/`<product>`/`<version>`/`<format>`/`<name>`/`index.html`

  Například `http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html`.

jednostránkové 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`

PDF

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

EPUB

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

# Ukázkový soubor spec balíčku nabídky pro stolní počítač

Následující soubor spec poskytuje příklad, jak lze zabalit soubor položky pracovní plochy (`.directory`) a soubor nabídky pracovní plochy (`.menu`) do balíčku RPM, který lze dále šířit. Struktura těchto souborů viz 4.8.1.3 – „Položky nabídky pracovní plochy pro dokumenty“.

V tomto příkladu se předpokládá, že soubor položky pracovní plochy nazvaný `menu-example.directory`, soubor nabídky pracovní plochy nazvaný `menu-example.menu` a soubor readme nazvaný `README` jsou uloženy v adresáři s názvem `menu-example-0`, který je zaarchivován jako `menu-example-0.tgz`.

Výsledkem sestavení je balíček s názvem menu-example.

    Name:		menu-example
    Version:	0
    Release:	8%{?dist}.t1
    Summary:	Example of how to do a documentation menu package
    Group:		Development/Tools
    License:	GPLv2+
    URL:		http://engineering.redhat.com
    Source0:	%{name}-%{version}.tgz
    BuildRoot:	%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
    BuildArch:      noarch

    %description
    Example of how to do a documentation menu package

    %prep
    %setup -q

    %build

    %install
    rm -rf %{buildroot}
    mkdir -p $RPM_BUILD_ROOT%{_datadir}/desktop-directories
    mkdir -p $RPM_BUILD_ROOT/etc/xdg/menus/settings-merged

    install -m644 menu-example.directory $RPM_BUILD_ROOT%{_datadir}/desktop-directories/menu-example.directory
    install -m644 menu-example.menu $RPM_BUILD_ROOT%{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu

    %{_fixperms} $RPM_BUILD_ROOT/*

    %clean
    rm -rf %{buildroot}

    %files
    %defattr(-,root,root,-)
    %doc README
    %{_datadir}/desktop-directories/menu-example.directory
    %config(noreplace) %{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu

    %changelog
    * Tue Nov 23 2010 Jeff Fearn <jfearn@redhat.com> 0-8
    - Creation

# Jazykové kódy

Regionální subtag

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.

Další jazykové kódy

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:

subtag language

  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.

  Rozšiřující podznačky jazyka

  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.

subtag script

  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.

Subtag region

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

Subtag variant

  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)

[5] http://www.w3.org/TR/REC-xml/#sec-lang-tag

[6] http://tools.ietf.org/html/bcp47

[7] http://www.iana.org/assignments/language-subtag-registry

[8] http://www.infoterm.info/standardization/iso_639_1_2002.php

[9] http://www.loc.gov/standards/iso639-2/

[10] http://tools.ietf.org/html/rfc5646

[11] http://www.unicode.org/iso15924/

[12] http://www.iso.org/iso/country_codes.htm

[13] http://unstats.un.org/unsd/methods/m49/m49.htm

[14] http://tools.ietf.org/html/rfc5646

# Příloha G. Revision History

Přehled revizí
Revize 4.2-0.4 | Thu Apr 30 2015 | Jeff Fearn

Soubory překladů synchronizovány s XML zdroji 4.2-0

Revize 4.2-0.3 | Fri Oct 3 2014 | Jeff Fearn

Soubory překladů synchronizovány s XML zdroji 4.2-0

Revize 4.2-0.2 | Fri Oct 3 2014 | Jeff Fearn

Soubory překladů synchronizovány s XML zdroji 4.2-0

Revize 4.2-0.1 | Fri Oct 3 2014 | Jeff Fearn

Soubory překladů synchronizovány s XML zdroji 4.2-0

Revize 4.2-0 | Mon May 12 2014 | Jeff Fearn

Convert to DocBook 5
Update a lot of content

Revize 4.0-5 | Thu Mar 27 2014 | Rüdiger Landmann

Corrections to website building instructions

Revize 4.0-4 | Mon Nov 25 2013 | Rüdiger Landmann

Improve instructions for translation BZ#1021287
Document use of "sortas" for indexes and glossaries

Revize 4.0-3 | Thu Nov 14 2013 | Roman Joost

Clarify where relative paths are used in brand instructions - BZ#1028815

Revize 4.0-2 | Thu Nov 14 2013 | Norman Dunbar

Corrected OpenSUSE installation instructions - BZ#1000534

Revize 4.0-1 | Thu Nov 14 2013 | Svein Dowdeit

Updated Debian installation instructions - BZ#1013934
Add Docker installation instructions - BZ#1015943

Revize 3.2-1 | Thu Jul 11 2013 | Zac Dover

Added command prompts to all commands - BZ#880456
Added quotes around the web_formats list - BZ#839141
Replaced a broken link to kate plugins page on CPAN with a working link - BZ#973461
Updated web site instructions - BZ#979224

Revize 3.2-0 | Thu Jul 11 2013 | Jeff Fearn

Publican 3.2.0
Document site config option 'toc_js'
Document build option --pdftool
Document build option --pub_dir

Revize 3.1-0 | Tue Jan 8 2013 | Norman Dunbar

Add Section on Installing Publican on OpenSuse 12

Revize 3.0-0 | Mon Feb 20 2012 | Jeff Fearn

Publican 3.0

Revize 2.7-1 | Tue Sep 6 2011 | Rebecca Newton

Improve documentation of standalone <set> usage

Revize 2.6-1 | Mon Jul 18 2011 | Rüdiger Landmann

Document new manual_toc_update parameter -- BZ#719573
Document new update_db action -- BZ#661948
Document new rename action -- BZ#694698
Document new mainfile parameter -- BZ#688585
Include advice about multiple config files for conditionalised books -- BZ#657132
Fix broken command example -- BZ#663211
Incorporate proofreading fixes from Luigi Votta `lewis41@fedoraproject.org` BZ#657576, BZ#663399

Revize 2.4-1 | Wed Dec 1 2010 | Rüdiger Landmann

Incorporate proofreading fixes from Luigi Votta `lewis41@fedoraproject.org` BZ#657576
Document not shipping PDFs in known broken languages
Document the web_formats parameter
Document customising desktop menus
Document site_overrides.css

Revize 2.3-0 | Mon Oct 25 2010 | Rüdiger Landmann

Document website dump files
Document bump command
Update image width behaviour

Revize 2.3-0 | Tue Oct 5 2010 | Rüdiger Landmann

Update lang_stats to include multiple languages
Correct details for web_logo.png BZ#638153
Correct list of characters usable in product names and document titles
Document new web_type parameter and relocate web_host and web_search parameters to site config file
Describe OPDS catalogs
Document product and version pages
Document man page as an output format
Document bridgehead_in_toc parameter
Correction -- def_langs is a site config parameter, not a homepage config file parameter

Revize 2.2-0 | Thu Aug 19 2010 | Rüdiger Landmann

Expand on including code samples BZ#604255
Clarify clean_ids BZ#612819
Document --novalid BZ#616142

Revize 2.1-1 | Fri Jul 16 2010 | Rüdiger Landmann

Correct and clarify website instructions BZ#614259
Clarify use of Product-Version-Id for packaging

Revize 1.6-1 | Mon May 24 2010 | Rüdiger Landmann

Update Ubuntu installation instructions

Revize 1.6-0 | Fri May 7 2010 | Rüdiger Landmann

Revise action and option nomenclature
Document print_known, print_banned, and print_unused actions
Correct and expand documentation on installing a brand
Document max_image_width and confidential_text parameters
Document Eclipse help plugin format and supporting parameters

Revize 1.5-0 | Fri Feb 26 2010 | Rüdiger Landmann

Document --config option

Revize 1.4-0 | Wed Feb 17 2010 | Jeff Fearn

remove obsolete reference to path to the DocBook catalog files. BZ#565498.
document CVS options.

Revize 1.3-0 | Mon Dec 7 2009 | Rüdiger Landmann

Add an FAQ entry about code highlighting errors.
Add a section about valid formats.
Update author list.
More specific installation instructions for Ubuntu; add installation instructions for Debian. BZ#542711
Metadata in the Book_Info.xml file

Revize 1.2-0 | Fri Nov 27 2009 | Jeff Fearn

Document lang_stats action. BZ#540696.

Revize 1.1-1 | Thu Nov 26 2009 | Jeff Fearn

Fix wrong docs for condition usage. BZ#540691

Revize 1.1-0 | Thu Oct 22 2009 | Rüdiger Landmann

Fix various small inconsistencies and general clean up

Revize 1.0-0 | Tue Oct 13 2009 | Rüdiger Landmann

Updated for Publican 1.0

Revize 0.5-0 | Thu Dec 18 2008 | Jeff Fearn

Added appendix on Makefile parameters
Added entry to FAQ about java heap space.

Revize 0.4-0 | Tue Nov 25 2008 | Brian Forté

Added "Pre-release and draft documentation" section.

Revize 0.3-0 | Fri Oct 10 2008 | Don Domingo

Adding "Conditional Tagging" section.

Revize 0.2-0 | Fri Sep 05 2008 | Brian Forté

General edits and updates related to Publican 0.36 release. Also, new section added to Chapter 3.3.

Revize 0.1-1 | Fri Jun 06 2008 | Murray McAllister

Updated Branding to note addition of oVirt and GIMP brands

Revize 0.1-0 | Fri May 16 2008 | Jeff Fearn

Updated FAQ

Revize 0.0-0 | Thu Dec 13 2007 | Murray McAllister

Initial content release