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
- 2. Potřebujeme zpětnou vazbu!
Úvod
- 1. Tento oddíl slouží k testování výstupu a nebude součástí zvěřejňovaných dokumentů
1. Instalace Publicanu
2. Výchozí hodnoty Publicanu
- 2.1. Příklady výchozích hodnot Publicanu
3. Příkazy Publicanu
4. Tvorba dokumentu
5. Grafická úprava
6. Užití sad
- 6.1. Samostatné sady
- 6.2. Distribuované sady
7. Sestavování webových stránek Publicanem
8. Import knihy do Drupalu
9. Často kladené dotazy
A. Nedoporučené prvky a atributy
- A.1. Nedoporučené prvky
- A.2. Nedoporučené atributy
B. Shrnutí příkazů
- B.1. Volby příkazu
- B.2. Akce příkazu
C. Přehled nastavení
D. Obsah souboru s výpisem webových stránek
- D.1. Zpracování URL ze souboru výpisu
E. Ukázkový soubor spec balíčku nabídky pro stolní počítač
F. Jazykové kódy
G. Revision History

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

PerlC++

#!/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|..."/>

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

Otevřete terminál.
Přihlaste se jako uživatel root: su -
Spusťe následující příkaz, abyste nainstalovali balíček publican a dokumentační balíček publican-doc:
```
$ yum install publican\*
```

Je k dispozici několik balíčků grafické úpravy, které lze využít s Publicanem. Spusťte následující příkaz jako uživatel root, abyste nainstalovali balíčky pro sestavení knih s grafickými úpravami.

$  yum install publican-grafuprava

Nahraďte grafupravu na příklad slovem redhat, fedora, jboss, ovirt nebo gimp. Více informací o grafických úpravách viz 5 – „Grafická úprava“.

1.1.2. Ubuntu

Otevřete terminál.
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.

Otevřete terminál.
Přihlaste se jako uživatel root: su -
Spusťte následující příkaz, abyste nainstalovali balíček publican:
```
$ apt-get install publican
```
Spusťte následující příkaz, abyste určili, která verze publicanu je nainstalována:
```
$ publican -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:

Otevřete terminál.
Přihlaste se jako uživatel root: su -
Otevřete soubor /etc/apt/sources.list v textovém editoru. Na příklad chcete-li upravit soubor v gedit, spusťte:
```
$ gedit /etc/apt/sources.list
```

Přidejte tuto řádku na konec souboru:

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

Uložte soubor a zavřete textový editor.
Otevřete (nebo vytvořte) soubor /etc/apt/preferences v textovém editoru. Na příklad chcete-li upravit soubor v gedit, spusťte:
```
$ gedit /etc/apt/preferences
```

Přidejte tuto řádku na konec souboru:

Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release a=testing
Pin-Priority: 400

Package: *
Pin: release o=Debian
Pin-Priority: -10

Uložte soubor a zavřete textový editor.
Spusťte následující příkaz, aby se zaktualizoval seznam balíčků dostupných pro váš počítač:
```
$ apt-get update
```
Spusťte následující příkaz, abyste zkusili nainstalovat testovací verzi balíčku publican i všechny aktualizované závislosti:
```
$ apt-get -t testing install publican
```

Jelikož Apt Pinning kombinuje 2 různé proudy debianu neprověřeném způsobem, mohou nastat nekompatibility. Na příklad můžete obdržet varování jako:

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

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

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:

Otevřete sezení terminálu.
Nainstalujte závislosti, které jsou k dispozici z různých online repozitářů - mnoho z nich se nenachází v repozitáři instalačního DVD.
```
$ sudo zypper install perl-Config-Simple perl-DateTime \
perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \
perl-File-Find-Rule perl-File-Which perl-HTML-Format \
perl-Locale-MakeText-Gettext perl-Template-Toolkit \
perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \
perl-YAML liberation-fonts
```
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í.

Využijte cpan pro instalaci zbývajících závislostí, které nelze instalovat pomocí zypper:

$ sudo sh
cpan File::pushd File::Copy::Recursive Locale::PO pp \
Syntax::Highlight::Engine::Kate XML::TreeBuilder
exit

Stáhněte zdrojový kód:

$ cd ~
mkdir -p SourceCode/publican
cd SourceCode/publican
svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./

Sestavte sestavovací skript Publicanu:
```
$ perl Build.PL
```
Jsou-li nainstalovány všechny závislosti, mělo by se zobrazit toto:
```
WARNING: the following files are missing in your kit:
        META.yml
 Please inform the author.

Created MYMETA.yml and MYMETA.json
Creating new 'Build' script for 'Publican' version '2.9'
```
Pokud ne, pak použitím cpan (jako uživatel root) nainstalujte chybějící moduly a spusťte opět sestavovací příkaz. Odstraňte všechna lomítka '/'pomocí dvojité dvojtečky '::' a ujistěte se, že jste použili přesně stejnou velikost písmen, na příklad: Je-li prohlášen soubor File/pushd.pm za chybějící, měli byste použít k jeho instalaci toto:
```
$ sudo sh
cpan File::pushd
exit
```
Za předpokladu, že vše proběhlo jak má, skript Build.PL vytvoří nový skript s názvem Build, který použijeme pro vytvoření, otestování a instalaci Publicanu 2.9.
```
$ ./Build
```
Na obrazovku bude vypisováno po několik minut mnoho textu, nakonec byste měli spatřit toto:
```
DEBUG: Publican::Builder: end of build
```
Otestujte sestavení:
```
$ ./Build test
```
Opět bude probíhat dlouhý výpis textových informací, na jejichž konci byste měli narazit na toto:
```
Test Summary Report
-------------------
t/910.publican.Users_Guide.t (Wstat: 256 Tests: 5 Failed: 1)
  Failed test:  5
  Non-zero exit status: 1
t/pod-coverage.t            (Wstat: 256 Tests: 9 Failed: 1)
  Failed test:  7
  Non-zero exit status: 1
Files=10, Tests=68, 420 wallclock secs ( 0.31 usr  0.17 sys + 246.87 cusr 18.73 csys = 266.08 CPU)
Result: FAIL
Failed 2/10 test programs. 2/68 subtests failed.
```
Nelekejte se. Toto se děje kvůli chybějícímu pomocnému programu wkhtmltopdf, který prochází testy z důvodu přidaní do Publicanu v budoucnu, aby jako vybraný nástroj pro vytváření pdf nahradil Apache FOP. Nalezne-li Publican wkhtmltopdf, použije ho, jinak použije FOP.
Naneštěstí v době psaní nazývá OpenSuse jednu ze závislostí wkhtmltopdf odlišně (ghostscript-fonts-std namísto ghostscript-fonts), proto wkhtmltopdf se nespustí, ani když bude instalován silou bez kontroly závislostí.
Nainstalujte wkhtmltopdf.
Tento krok je volitelný. V době psaní wkhtmltopdf na OpenSuse 12.1 nefungoval. Nicméně jelikož problémy, které brání jeho správné funkčnosti z Publicanu, mohou být vyřešeny, následující pokyny poskytují podrobnosti k instalaci wkhtmltopdf.
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.
Nainstalujte Publican.
Závěrečnou fází je instalace Publicanu, i když testovací fáze měla pár podtestů, které selhaly.
```
$ sudo sh
./Build test
exit
```
Následující kroky jsou volitelné, ale vždy je dobrý nápad otestovat, zda vše funguje předtím, než strávíte čas na svých dokumentech.

Otestujte nainstalované sestavení Publicanu:

$ publican create --type=book --product=testing --version=1.2.3 --name=TestPublican
  Processing file en-US/Author_Group.xml -> en-US/Author_Group.xml
  Processing file en-US/Book_Info.xml -> en-US/Book_Info.xml
  Processing file en-US/Chapter.xml -> en-US/Chapter.xml
  Processing file en-US/Preface.xml -> en-US/Preface.xml
  Processing file en-US/Revision_History.xml -> en-US/Revision_History.xml
  Processing file en-US/TestPublican.xml -> en-US/TestPublican.xml

$ cd TestPublican/
publican build --lang=all --formats=html,html-single,html-desktop,txt,pdf,epub

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.

Otevřete terminál.
Stáhněte a nainstalujte kontejner svendowideit/publican z adresy https://index.docker.io/u/svendowideit/publican/:
```
$ docker pull svendowideit/publican
```
To bude trvat nějakou chvíli, neboť stáhne kontejner založený na Fedoře, a poté závislosti nutné pro publican
Přidejte bash alias pro publican, abyste si ulehčili používání:
```
$ echo 'alias publican="docker run -t -i -v $(pwd):/mnt svendowideit/publican"' >> ~/.bashrc
```
Tento alias předpokládá, že máte publican spuštěn v kořenovém adresáři dokumentace (adresář se souborem publican.cfg)
nyní můžete používat publican dle své dokumentace
```
$ publican --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.

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

Pro zkontrolování zdrojových souborů publicanu z GITu spusťte následující příkazy:

$ cd CESTA KAM ULOŽIT ZDROJOVÉ SOUBORY
$ git clone git://git.fedorahosted.org/publican.git publican

Chcete-li spustit publican z této kontroly, spusťte tyto příkazy:

$ PUBLICAN_PATH="CESTA, KDE JSOU ULOŽENY ZDROJOVÉ SOUBORY/publican"
$ perl -CDAS -I $PUBLICAN_PATH/lib $PUBLICAN_PATH/bin/publican build  --brand_dir $PUBLICAN_PATH/datadir/Common_Content/common --formats html

1.2. Operační systémy Windows

Stáhněte instalační soubor Publicanu ze stránky https://fedorahosted.org/releases/p/u/publican/.
Přejděte do adresáře, do kterého jste stáhli soubor Publican-Installer-verze.exe.
Poklepejte na soubor Publican-Installer-version.exe.
Instalační program vám zobrazí sadu licenčních smluv. Všechny soubory, které představují instalaci Publicanu, jsou k dispozici pod svobodnou licencí. Nicméně protože jsou různé licence vhodnější pro určité části Publicanu než jiné, soubory Publicanu nejsou k dispozici pod jednou svobodnou licencí. Každá licence vám dává různou sadu práv a odpovědností, pokud rozmnožujete nebo měníte soubory ve své instalaci Publicanu. Zvolili jsme tuto kombinaci licencí, abychom vám umožnili používat Publican jak nejsvobodněji lze a zvolit si jakoukoliv licenci, kterou upřednostňuje pro dokumenty, které Publicanem zveřejníte.
Přečtěte si ustanovení těchto různých licenčních smluv. Pokud s jejich zněním souhlasíte, stiskněte na každé tlačítko Souhlasím, jinak stiskněte Zrušit.
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ší.
Software instalačního programu standardně vytvoří ve vašem počítači adresář nazvaný Publican v adresáři%ProgramFiles% — nejčastěji C:\Program Files\Publican. Ručně lze tuto cestu upravit v okně Cílový adresář, abyste zvolili jiný adresář.
Jste-li spokojení s cílovým adresářem, klepněte na 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.
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

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.
Ze stránky http://guide.macports.org/chunked/installing.macports.html nainstalujte Macports. Vše, co nainstalujete bude umístěno v /opt/local, tedy dostatečně daleko od vašich normálních souborů.
Otevřete terminál.

Nainstalujte závislosti pro publican, které jsou k dispozici jako porty:

$sudo port installdocbook-xml docbook-xsl docbook-sgml-4.2 perl5 bash-completion p5-file-pushd p5-config-simple p5-file-find-rule p5-file-slurp p5-class-trigger p5-time-hires p5-list-moreutils p5-ipc-run3 p5-class-accessor p5-test-perl-critic p5-xml-libxslt p5-locale-gettext p5-image-size p5-file-copy-recursive p5-datetime p5-archive-zip p5-timedate p5-html-format p5-dbd-sqlite p5-xml-simple p5-devel-cover p5-test-pod p5-test-pod-coverage p5-template-toolkit

Nainstalujte moduly CPAN pro závislosti, které nemohou být vyřešeny porty. Poznámka: tento krok bude příčinou mnoha zpráv, včetně varování. Nedějte si však s nimi starosti.

$sudo cpanLocale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables

Nainstalujte FOP, chcete-li, aby fungovaly PDF:

$ sudo port install fop

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

Přejděte (checkout) do hlavní větve Publicanu. Tento příkaz by měl být spuštěn z vašeho domácího adresáře, na příklad /Uživatelé/vašeuživatelskéjméno
```
$ git clone git://git.fedorahosted.org/publican.git
```
Změňte adresáře:
```
$ cd publican/publican
```
Tento adresář by měl obsahovat soubor s názvem Build.pl. Ověřte, zda se nacházíte ve správném adresáři, poté spusťte následující příkaz. Všechny vypsané zprávy ignorujte.
```
$ perl ./Build.PL
```
```
$ ./Build
```
Spusťte následující příkaz, abyste nainstalovali Publican, a uložte všechny jeho části do adresáře /opt/local:
```
$ sudo ./Build install
```

Postup 1.1. Vytvořte a sestavte knihu

```
$ publican create --name=testbook
```
```
$ cd testbook
```

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

Otevřete soubor tmp/en-US/html/index.html v prohlížeči, abyste zjistili, zda se kniha sestavila bezchybně.

Postup 1.2. Nainstalujte grafickou úpravu

Opravte oprávnění grafické úpravy Commons Brand. To bude nutné pouze jednou. Jedná se o chybu, která bude příležitostně řešena.
```
$ find /opt/local/share/publican -type f |xargs sudo chmod 644
```
Zkontrolujte SVN vámi vybrané grafické úpravy, nebo získejte předsestavenou grafickou úpravu od přítele.
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.

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

$ cd publican/publican-jboss

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

Nainstalujte grafickou úpravu.
```
$ sudo publican install_brand --path=/opt/local/share/publican/Common_Content
```
Nyní můžete využívat grafickou úpravu ve svých knihách, úpravou souboru publican.cfg své knihy nebo uvedením volby --brand při vytváření knihy.

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

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

<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

<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

<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 (& and < respectively).^[2] If you place these files in the extras/ directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.

Chcete-li vložit příklad kódu z adresáře extras/ do dokumentu, dodržujte tento postup:

Vytvořte adresář extras
```
$ mkdir cs-CZ/extras
```
Zkopírujte soubor s kódem do adresáře extras
```
$ cp ~/priklady/foo.c en-US/extras/.
```

vložte ukázkový soubor do svého souboru XML pomocí xi:include

<programlisting>
<xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>

Nyní můžete upravovat cs-CZ/extras/foo.c ve svém oblíbeném editoru bez ohledu na to, jaký bude mít vliv na XML.

Stejný přístup funguje, chcete-li popsat svůj kód popisky. Na příklad:

<programlistingco>
	<areaspec>
		<area id="orbit-for-parameter" coords='4 75'/>
		<area id="orbit-for-magnitude" coords='12 75'/>
	</areaspec>
	<programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for"
	xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
	<calloutlist>
		<callout id="callout-for-parameter" arearefs="orbit-for-parameter">
			<para>
				The <firstterm>standard gravitational parameter</firstterm>
				(μ) is a derived value, the product of Newton's gravitational 
				constant (G) and the mass of the primary body.
			</para>
		</callout>
		<callout id="callout-for-magnitude" arearefs="orbit-for-magnitude">
			<para>
				Since the mass of the orbiting body is many orders of magnitude 
				smaller than the mass of the primary body, the mass of the 
				orbiting body is ignored in this calculation.
			</para>
		</callout>
	</calloutlist>
</programlistingco>

Všimněte si, že elementy <area> určují pozici popisků, které se zobrazí nad příkladem kódu. Atributy coords uvádějí číslo řádku a sloupce oddělené mezerou. V této ukázce jsou popisky použity na řádky 4 a 12, zarovnané na sloupec 75. Ačkoliv tento přístup značí, že byste museli upravit atributy coords, změnili-li byste někdy kód, na který se vztahují, zabraňuje mísení tagů <area> XML do samotného kódu.

^[2] Refer to section 2.4 "Character Data and Markup" in the XML 1.0 standard, available from http://www.w3.org/TR/2008/REC-xml-20081126/.

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

Dokončete dokument v XML.
XML by se pro tuto verzi dokumentu nemělo považovat za ‘zmražené’. Máte-li svůj dokument uložen v repozitáři se správou verzí, měli byste tuto verzi umístit do odděleného adresáře nebo větve. To umožní autorům zahájit práci na následujících verzích dokumentu ve větvi jedné, zatímco se poskytne stabilní základna pro překlad ve větvi jiné.
Volitelné ale doporučené: pusťte, neboli dropněte, dokument pro překlad. Spusťte:
```
$ publican trans_drop
```
Publican vytvoří nový podadresář, nazvaný trans_drop/. Podadresář trans_drop/ obsahuje momentální snímek zdrojových souborů dokumentu. Když se adresář trans_drop/ nachází v dokumentačním projektu, Publican používá jeho obsah jako základnu pro příkazy zdokumentované dále v tomto postupu.
Vygenerujte soubory šablon portable object (POT) ze souborů XML:
```
$ publican update_pot
```
Jsou-li sobory POT pro tento dokument vytvořeny poprvé, Publican vytvoří nový podadresář nazvaný pot. Ten obsahuje soubor POT pro každý soubor XML v dokumentu. Vytvořil-li Publican soubory POT pro tento dokument již dříve, zaktualizuje existující soubory POT, aby promítl změny v XML od poslední aktualizace souborů POT.
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.
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á.
Přeložte řetězce nacházející se v souborech PO.
Aktualizujete-li dříve uveřejněný překlad této revize v zdrojovém jazyce, použijte příkaz Publicanu publican add_revision a popište své změny či opravy. Publican pro vás zaktualizuje soubor Revision_History.xml.
Změnil-li se dokument ve svém původním jazyce, použijte příkazy publican trans_drop, publican update_pot a publican update_po, jak bylo popsáno v tomto postupu dříve.
Sestavte dokument v cílovém jazyce, na příklad:
```
$ publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
```
nebo ho zabalte do cíloveho jazyka, na příklad:
```
$ publican package --lang=is-IS
```
Dokument lze sestavit pro všechny jazyky, pro něž máte překlady, volbou --langs=all, ale uvědomte si, že zabalit ho musíte pro každý jazyk samostatně. Více informací o sestavování dokumentu viz 4.7 – „Sestavení dokumentu“ a balení dokumentu viz 4.8 – „Balení dokumentu“

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:

Si potvrďte, že v souboru Dok_Nazev.ent jsou nastaveny entity YEAR a HOLDER, jak je popsáno v 4.1.6 – „Nazev_Dok.ent“.
Přejděte do kořenového adresáře dokumentu. Na příklad je-li dokument pojmenován Kniha_Test a umístěn v adresáři ~/knihy/, spusťte tento příkaz:
```
$ cd ~/knihy/Kniha_Test
```
Spusťte test pro kontrolu všech chyb, které by mohly zastavit sestavování knihy ve vybraném jazyce, na příklad:
```
$ publican build --formats=test --langs=en-US
```
Spusťte tento příkaz pro sestavení knihy:
```
$ publican build --formats=formaty --langs=jazyky
```
Nahraďte formaty čárkou odděleným seznamem formátů, které chcete sestavit, na příklad html,html-single,pdf. Nahraďte jazyky čárkou odděleným seznamem jazyků, které chcete sestavit, na příklad en-US,sv-SE,uk-UA,ko-KR.

Formáty pro akci build

html

Publican sestaví dokument do podoby mnohostránkového HTML, s každou kapitolou nebo hlavním oddílem na samostatné stránce. Publican umístí na začátek dokumentu rejstřík a navigační prvky do každé stránky.

V souboru publican.cfg použijte parametry chunk_first a chunk_section depth, abyste řídili, do jaké hloubky má Publican v tomto formátu zanořovat (seskupovat) oddíly.

html-single

Publican sestaví dokument do podoby jednostránkového HTML s obsahem blízko začátku stránky.

html-desktop

Publican sestaví dokument do podoby jednostránkového HTML s obsahem v samostatném okně po levé straně dokumentu.

man

Publican sestaví dokument do podoby manuálové stránky ("man page"), které se používají v Linuxu, UNIXu a podobných operačních systémech.

pdf

Publican sestaví dokument do podoby souboru PDF.

test

Publican ověří validitu struktury XML knihy, ale nepřevede XML do jiného formátu.

txt

Publican sestaví dokument do podoby jediného textového souboru.

epub

Publican sestaví dokument do podoby elektronické knihy ve formátu EPUB.

eclipse

Publican sestaví dokument do podoby zásuvného modulu nápovědy Eclipse. Podrobnosti o zadávání parametrů id, name a provider-name pro Eclipse parametry Publicanu ec_id, ec_name a ec_provider viz 4.1.1 – „Soubor publican.cfg“.

Následující příklady ukazují běžně užívané příkazy $ publican build:

$ publican build --help: Nebo-li zobrazit dostupné volby $ publican build pro sestavení knihy.
$ publican build --formats=test --langs=jazyky: Zkontrolovat, zda se kniha sestaví bezchybně. Sestavte --formats=test před spuštěním kteréhokoliv jiného příkazu $ publican build, a před odesláním knihy zpět do repozitáře se správou verzí, z kterého ji mohou stáhnout ostatní přispěvatelé.
$ publican build --formats=html --langs=jazyky: Sestavit knihu do formátu vícestránkového HTML. Výstup HTML bude umístěn v adresáři Dok_Nazev/tmp/jazyk/html/. Každá kapitola a hlavní oddíl je umístěn do svého souboru HTML. Hloubku, do které Publican umisťuje pododdíly do samostatných souborů HTML, lze řídit pomocí parametru chunk-section-depth v publican.cfg — viz 4.1.1 – „Soubor publican.cfg“.
$ publican build --formats=html-single --langs=jazyky: Sestavit knihu do formátu jednostránkového HTML. Výstupem bude jediný HTML soubor umístěný v adresáři Dok_Nazev/tmp/jazyk/html-single/
$ publican build --formats=pdf --langs=jazyky: Sestavit knihu do souboru PDF. Publican pro renderování PDF spoléhá na externí aplikaci, FOP. Proto nemusí být sestavování do PDF k dispozici na všech systémech, vše závisí na dostupnosti FOP. Výstupem bude jediný soubor PDF umístěný v adresáři Dok_Nazev/tmp/jazyk/pdf/.
$ publican build --formats=html,html-single,pdf --langs=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

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,

Příklad 4.5. Příklad souboru .directory

Následující soubor menu-example.directory je ukázkou struktury souboru položky pracovní plochy.

[Desktop Entry]
Name=Example
Name[fr]=Exemple
Name[it]=Esempio
Comment=Example Documentation menu
Comment[fr]=Exemple d'une menu de documentation
Comment[it]=Esempio di un menù di documentazione
Type=Directory
Encoding=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>

Příklad 4.6. Příklad souboru .menu

Následující soubor menu-example.menu je ukázkou struktury souboru nabídky pracovní plochy.

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
	<Name>Documentation</Name>
	<Menu>
		<Name>Documentation</Name>
		<Menu>
			<Name>Example</Name>
			<Directory>menu-example.directory</Directory>
			<Include>
				<Category>X-Example-Docs</Category>
			</Include>
		</Menu>
	</Menu> 
</Menu>

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

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

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

Přidejte číslo neoficiální verze softwaru, popř. jinou odpovídající informaci o jeho stavu, do tagu <subtitle> v souboru Book_Info.xml. Tento doplňující text umístěte mezi tagy <remark>. Na příklad:
```
<subtitle>Používání Red Hat Enterprise Warp Drive<remark> Verze 1.1, Beta 2</remark></subtitle>
```
přidejte show_remarks do souboru publican.cfg a nastavte ho na '1':
```
show_remarks: 1
```

Je-li kniha sestavena s tímto tagem <remark> a nastavením show_remarks, je neoficiální povaha softwaru zřetelně a nezaměnitelně zobrazena. Sestavení PDF zobrazí poznámku na obálce a titulních stranách. Sestavení HTML (jak jedno- tak vícestránkové HTML) zobrazí poznámku blízko začátku index.html.

Jelikož tento přístup nikterak nemění informace v Book_Info.xml využívaném pro tvorbu balíčků RPM, zajišťuje rovněž, že se ve fungování subsystému RPM nevyskytují nejednoznačnosti.

Příklad 4.7. Příklad inline poznámky

Zde máme příklad inline poznámky.

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:

Byla-li vám grafická úprava poskytnuta jako archiv některého druhu, na příklad tarball nebo soubor ZIP, rozbalte grafickou úpravu na svém systému do nového adresáře.
Přejděte do adresáře, ve kterém jste vytvořili, nebo do něhož jste rozbalili grafickou úpravu:
```
$ cd publican-grafickauprava
```
kde grafickauprava je název grafické úpravy.

Sestavte grafickou úpravu:

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

Nainstalujte grafickou úpravu:

$ sudo publican install_brand --path cesta

kde cesta je cesta k souborům Common Content Publicanu. Na příklad na Linuxovém systému spusťte:

$ sudo publican install_brand --path /usr/share/publican/Common_Content

nebo na systému Windows spusťte:

$ publican install_brand --path "C:/Program Files/Publican/Common_Content"

Tabulka 5.1. Současné grafické úpravy a jejich balíčky

Grafická úprava	Licence souborů Common Content	Výchozí licence pro dokumenty	Balíček	Poznámka
common	CC0 1.0	GFDL Version 1.2	publican	Licence kompatibilní s GPL. Žádné možnosti.
RedHat	CC-BY-SA 3.0	CC-BY-SA 3.0	publican-redhat
Fedora	CC-BY-SA 3.0	CC-BY-SA 3.0	publican-fedora
JBoss	CC-BY-SA 3.0	CC-BY-SA 3.0	publican-jboss	Žádné možnosti.
oVirt	OPL 1.0	OPL 1.0	publican-ovirt	Žádné možnosti.
GIMP	GFDL Version 1.2	GFDL Version 1.2	publican-gimp	Odpovídá licenci pro existující dokumentaci GIMPu.
Genome	OPL 1.0	OPL 1.0	publican-genome	Žádné možnosti.

Všimněte si rozdílů v licencování mezi soubory common content poskytovaných v grafické úpravě common (CC0) a výchozí licencí nastavenou pro knihy vytvořené s touto grafickou úpravou (GFDL). CC0 licence povoluje další šíření a přelicencování souborů tvořících tuto grafickou úpravu (včetně obrazových a CSS souborů) dle potřeb vašeho projektu. Publican navrhuje používat pro dokumentaci jako výchozí licenci GFDL, neboť Publican je především vyvíjen pro sestavování dokumentace k softwaru. Licence GFDL je kompatibilní s licencí GPL, která je nejčastěji běžně používanou licencí pro open-source software.

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

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

Vytvořte sadu nazvanou Moje_Sada s grafickou úpravou ve stylu Red Hat, a ve které bude XML napsáno v americké angličtině, spuštěním následujícího příkazu v shellu v adresáři knihy/:
```
publican create --type=Set --name=Moje_Sada --brand=RedHat --lang=en-US
```
Přejděte příkazem $ cd do adresáře Moje_Sada/en-US a vytvořte dva adresáře (nikoliv knihy) nazvané Kniha_A a Kniha_B.
```
$ cd Moje_Sada/en-US
$ mkdir Kniha_A Kniha_B
```
Přejděte příkazem $ cd do adresáře knihy/Moje_Sadaa/en-US/Kniha_A. Vytvořte a upravte soubor Kniha_A.xml, Book_Info.xml, a kterékoliv další soubory xml, které kniha vyžaduje, jako např. soubory jednotlivých kapitol. Zajistěte, aby Kniha_A.xml obsahoval správné odkazy xi:include na všechny vaše soubory xml v adresáři. Na příklad obsahuje-li Kniha A Book_Info.xml a Kapitola_1.xml, soubor Kniha_A.xml by měl mít podobu:
```
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
	  
<book>
	  <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
	  <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</book>
```
Stejný postup použijte pro Knihu_B, jenž se nachází v adresáři knihy/Moje_Sada/en-US/Kniha_B.

Otevřete soubor knihy/Moje_Sada/en-US/Moje_Sada.xml v editoru. Přidejte pro každou knihu sady odkaz xi:include na primární soubor xml knihy. Primární soubor xml Knihy A bude Kniha_A.xml a Knihy B Kniha_B.xml. Soubor Moje_Sada.xml by nyní měl mít podobu:

<?xml version="1.0"?>
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<set>
	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</set>

Abyste učinili XML sady validní, musíte změnit toto:
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.
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

V shellu spusťte následující příkaz, kterým vytvoříte sadu s názvem Moje_Sada v grafické úpravě Red Hat a v níž bude XML napsáno v americké angličtině.
```
$ publican create --type=Set --name=Moje_Sada --brand=RedHat  --lang=en-US
```
Do souboru publican.cfg doplňte tyto řádky:
```
books: Kniha_A Kniha_B
repo: http://CESTA-K-REPOZITARI-SVN
scm: SVN
```
Cesta k repozitáři by měla končit v místě před adresářem knihy, kterou potřebujete.

Otevřete soubor My_Set.xml v editoru. Pro každou knihu ze sady přidejte odkaz xi:include na primární soubor XML knihy. Primárním souborem XML Knihy A bude Kniha_A.xml a Knihy B Kniha_B.xml. Soubor Moje_Sada.xml by měl nyní vypadat takto:

<?xml version="1.0"?>
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<set>
	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</set>

Abyste učinili XML sady validní, je nutné v Moje_Sada.xml zakomentovat následující řádky

<remark>NOTE: the href does not contain a language! This is CORRECT!</remark>
<remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark>
<setindex></setindex>

Sadu otestujte spuštěním příkazu publican build --formats=test --langs=en-US.
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:

Na své pracovní stanici vytvořte nový adresář a přejděte do něj. Na příklad na linuxovém systému spusťte:
```
$ mkdir ~/docsite
$ cd ~/docsite
```
Spusťte publican create_site s uvedením těchto parametrů:
- --site_config — název konfiguračního souboru webových stránek, s příponou .cfg
- --db_file — název souboru databáze SQLite pro stránky, s příponou .db
- --toc_path — cesta k adresáři, do kterého budete ukládat své dokumenty
Na počítači s jiným operačním systémem než je Linux také nastavte:
- --tmpl_path — cesta k adresáři templates/ vaší instalace Publicanu. Na počítačích s operačními systémy Windows má obvykle cesta podobu %SystemDrive%\%ProgramFiles%\Publican\templates.
Na příklad:
```
$ publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
```
Názvy konfiguračnímu souboru a souboru databáze webových stránek lze přidělit tak, aby bylo možné snadno rozlišit, ke kterým webovým stránkám patří. Na příklad pro webové stránky dokumentace FooMaster lze tyto soubory nazvat foomaster.cfg a foomaster.db. --toc_path lze nastavit dle vlastního uvážení.
Konfigurační soubor webových stránek upravte tak, aby obsahoval název webových stránek, hostitelský počítač webu a volitelně parametry vyhledávání, výchozí jazyk, nastavení souboru dump a nastavení aktualizací pro webové stránky.
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í.
Vytvořte prázdný soubor s názvem site_overrides.css v adresáři, který jste uvedli v doc_path (adresář, jenž obsahuje interactive.css a různé jazykové adresáře). Chcete-li používat na webové stránky aplikovat zvláštní styly, které potlačí styly poskytované v interactive.css, lze přidat site_overrides.css do dokumentu, který poskytuje domovskou stránku webových stránek — viz 7.1.2 – „Vytvoření, instalace a aktualizace domovské stránky“. Nechcete-li používat zvláštní styly, prázdný soubor, který jste sem přidali, bude předcházet chybám 404 na vašem serveru. Na linuxovém systému se přesuňte do adresáře uvedeném v doc_path a spusťte:
```
$ touch site_overrides.css
```
Sestavte a nainstalujte každou grafickou úpravu, včetně grafické úpravy common Publicanu.
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.
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:

Přejděte do příhodného adresáře a spusťte následující příkaz publican create:
```
$ publican create --type Article --name nazev_stranky
```
Na příklad:
```
$ publican create --type Article --name Home_Page
```
Většina grafických úprav (včetně úpravy common) zobrazí název dokumentu velkým, barevným písmem poblíž vrchu stránky, pod bannerem, v němž je uveden název produktu (volba --name nastavuje tag <title>). Proto se ve výchozím nastavení zobrazuje návštěvníkům webových stránek hodnota nastavená volbou --name; ve výše uvedeném příkladu jsou návštěvníci přivítáni slovy Home Page pod produktovým bannerem.
Přejděte do adresáře článku:
```
$ cd page_name
```
Na příklad:
```
$ cd Home_Page
```
V kořenovém souboru XML zrušte odkaz na Article_Info.xml.
Pravděpodobně pouze málo z obsahu Article_Info.xml bude užitečné pro vaše webové stránky. Proto upravte kořenový soubor XML domovské stránky odstraněním tagu <xi:include> odkazujícího na Article_Info.xml. Publican stále využívá informace z Article_Info.xml pro vytváření balíčků, ale nezahrne ho do samotné stránky.
Upravte soubor publican.cfg.
Alespoň jako nejnutnější musíte přidat parametr web_type a nastavit ho na hodnotu home:
```
web_type: home
```
The web_type: home parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg file. Other optional changes to the publican.cfg file that are frequently useful for Publican-generated websites include:
brand
Chcete-li nastylizovat domovskou stránku shodně s vaší dokumentací, přidejte:
```
brand: nazev_grafupravy
```
docname, product
Měl-li by <title> nebo <product>, který jste nastavili v souboru Article_Info, obsahovat cokoliv jiného než základní latinské znaky bez diakritiky, nastavte docname a product, jak je nezbytné.
Upravte obsah souboru nazev_stranky.xml (na příklad Home_Page.xml), tak jako u kterýkoliv jiného dokumentu napsaného v DocBook.
Odstraníte-li <xi:include>, který odkazuje na Article_Info.xml, uveďte název stránky v tomto formátu:
```
<title role="producttitle">Dokumentace FooMaster</title>
```
Uveřejňujete-li dokumentaci ve více než jednom jazyce, vytvořte řadu souborů POT a PO pro každý jazyk příkazy $ publican update_pot a publican update_po.
To customize the logo at the top of the navigation menu that provides a link back to the home page, create a PNG image 290 px × 100 px and name it web_logo.png. Place this image in the images/ directory in the document's XML directory, for example en-US/images/.
Zvláštní styly, které potlačí styly nastavené v souboru interactive.css webových stránek, přidejte do souboru site_overrides.css a umístěte ho do kořene zdroje dokumentu (stejný adresář, který obsahuje publican.cfg a jazykové adresáře).
Sestavte domovskou stránku ve formátu jednostránkového HTML s volbou --embedtoc a nainstalujte ji do struktury webových stránek. Na příklad:
```
$ publican build --publish --formats html-single --embedtoc --langs all 
$ publican install_book --site_config ~/docsite/foomaster.cfg --lang Kod_Jazyka
```
Všimněte si, že lze sestavit všechny jazyky najednou, ale nainstalovat domovskou stránku v každém jazyce musíte jednotlivě příkazem $ publican install_book.

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:

Přejděte do vhodného adresáře a spusťte následující příkaz $ publican create:
```
$ publican create --type Article --name nazev_stranky
```
Na příklad stránka produktu by mohla být vytvořena takto:
```
$ publican create --type Article --name FooMaster
```
nebo stránka verze takto:
```
$ publican create --type Article --name FooMaster_3
```
Přejděte do adresáře článku:
```
$ cd nazev_stranky
```
Na příklad:
```
$ cd FooMaster
```
V kořenovém souboru XML odstraňte odkaz na soubor Article_Info.xml.
Pravděpodobně pouze málo z obsahu souboru Article_Info.xml bude k užitku pro stránky produktu nebo verze. Proto upravte kořenový soubor XML stránky odstraněním tagu <xi:include> odkazujícího na Article_Info.xml. Publican stále využívá informace z Article_Info.xml pro vytváření balíčků, ale nezahrne ho do samotné stránky.
Upravte soubor publican.cfg.
Alespoň jako nejnutnější musíte přidat parametr web_type a nastavit ho na hodnotu product nebo version:
```
web_type: product
```
nebo
```
web_type: version
```
Parametr web_type přinutí Publican zpracovat tento dokument jinak než dokumentaci produktu. Jedná se o jedinou povinnou úpravu souboru publican.cfg. Dalšími, volitelnými změnami tohoto souboru, které jsou často užitečné pro stránky produktu nebo stránky verze, jsou tyto:
brand
Chcete-li nastylizovat stránku shodně s vašimi dokumenty, přidejte:
```
brand: nazev_grafupravy
```
docname, product
Měl-li by <title> nebo <product>, který jste nastavili v souboru Article_Info, obsahovat cokoliv jiného než základní latinské znaky bez diakritiky, nastavte docname či product, jak je nezbytné.
Upravte obsah souboru nazev_stranky.xml (na příklad FooMaster.xml) tak, jako u kteréhokoliv jiného dokumentu napsaného v DocBook.
Odstraníte-li <xi:include>, který odkazuje na Article_Info.xml, uveďte název stránky v tomto formátu:
```
<title role="producttitle">Dokumentace FooMaster</title>
```
Uveřejňujete-li dokumentaci ve více než jednom jazyce, vytvořte řadu souborů POT a PO pro každý jazyk příkazy $ publican update_pot a publican update_po.
Sestavte stránku produktu nebo stránku verze ve formátu jednostránkového HTML s volbou --embedtoc a nainstalujte ji do struktury webových stránek. Na příklad:
```
$ publican build --publish --formats html-single --embedtoc --langs all 
$ publican install_book --site_config ~/docsite/foomaster.cfg --lang Kod_Jazyka
```
Všimněte si, že lze sestavit všechny jazyky najednou, ale nainstalovat stránku produktu či verze v každém jazyce musíte jednotlivě příkazem $ publican install_book.

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:

Přihlaste se do webového serveru.
Nainstalujte Publican a balíček jeho webových komponent. Na příklad na webovém serveru s operačním systémem Fedora spusťte:
```
$ sudo yum install publican publican-common-web
```
S právy uživatele root upravte soubor /etc/publican-website.cfg, kde uvedete název webových stránek, hostitelský počítač webu a volitelně parametry vyhledávání, výchozí jazyk, nastavení souboru dump a webový styl stránek:
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í.
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

Na pracovní stanici vytvořte domovskou stránku použitím postupu popsaného v 7.1.2 – „Vytvoření, instalace a aktualizace domovské stránky“.
V adresáři, ve kterém jste vytvořili domovskou stránku, spusťte:
```
$ publican package --binary
```
Publican sestaví balíček RPM a umístí ho do adresáře /tmp/rpms/noarch/ domovské stránky. Standardně Publican sestaví balíček RPM pro operační systém, na němž Publican běží. Chcete-li sestavit balíček RPM, který se instaluje na server, kde běží jiný operační systém, nastavte parametr os_ver v souboru publican.cfg domovské stránky.
Nahrajte balíček domovské stránky na webový server a nainstalujte ho příkazem rpm -i či yum localinstall, nebo balíček umístěte do repozitáře a nakonfigurujte webserver tak, aby instaloval z repozitaře, když spustíte yum install.

Chcete-li domovskou stránku zaktualizovat, sestavte nový balíček s vyšším číslem <edition> nebo <pubsnumber> v Article_Info.xml. Publican využívá tyto hodnoty k nastavení verze a čísla vydání balíčku RPM. Když tento balíček instalujete na webový server, yum dokáže nahradit starou verzi verzí novou, spustíte-li yum localinstall pro místní balíček, nebo yum update pro balíček získaný z repozitáře.

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

Na pracovní stanici vytvořte stránku produktu nebo stránku verze využitím postupu popsaného ve 7.1.3 – „Vytvoření, instalace a aktualizace stránek produktu a verze“.
V adresáři, ve kterém jste vytvořili stránku, spusťte:
```
$ publican package --binary
```
Publican sestaví balíček RPM a umístí ho do adresáře /tmp/rpms/noarch/ stránky produktu nebo stránky verze. Standardně Publican sestaví balíček RPM pro operační systém, na němž Publican běží. Chcete-li sestavit balíček RPM, který se instaluje na server, kde běží jiný operační systém, nastavte parametr os_ver v souboru publican.cfg stránky produktu nebo stránky verze.
Nahrajte balíček na webový server a nainstalujte ho příkazem rpm -i či yum localinstall, nebo balíček umístěte do repozitáře a nakonfigurujte webserver tak, aby při spuštění yum install instaloval z repozitáře.

Chcete-li stránku produktu či stránku verze zaktualizovat, sestavte nový balíček s vyšším číslem <edition> nebo <pubsnumber> v Article_Info.xml. Publican využívá tyto hodnoty k nastavení verze a čísla vydání balíčku RPM. Když tento balíček instalujete na webový server, yum dokáže nahradit starou verzi verzí novou, spustíte-li yum localinstall pro místní balíček, nebo yum update pro balíček získaný z repozitáře.

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:

Zaregistrujte si účet Google na stránce Nástroje Google pro webmastery. Máte-li již účet Google vytvořen, lze ho použít.
Přihlaste se do svého účtu pro Nástroje Google pro webmastery na této URL: http://www.google.com/webmasters/tools/home.
Nejprve musíte ověřit, že jste vlastníkem vlastních webových stránek vytvořených v Publicanu. Klepněte na tlačítka Přidat stránky.
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.
Postupujte podle pokynů, které se zobrazí, a uložte soubor HTML poskytnutý Googlem do dokumentačního kořenu (document root) svých stránek.
Až potvrdíte, že poskytnutý soubor HTML byl nahrán do požadovaného umístění tím, že k němu přistoupíte přes webový prohlížeč, klepněte na tlačítko Ověřit.
Pokud jste úspěšně ověřili Googlu vlastnictví svých webových stránek, vraťte se zpět na domovskou stránku Nástrojů Google pro webmastery. Vaše stránky jsou zobrazeny na seznamu. Klepněte na ně.
Jste přeneseni na konfigurační stránku Nástrojů pro webmastery svých webových stránek. Po levé straně stránky se nachází nabídka. Klepněte na nabídku Konfigurace stránek, aby se rozbalila. Rozbalená nabídka obsahuje položku Mapa stránek. Klepněte na ni.
Jste přeneseni na Stránku předložení mapy stránek. Klepněte na tlačítko Předložit mapu stránek.
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:

Zaregistrujte si účet Bing pro správce webu na Bing správce webu. Máte-li již účet Windows LiveID zřízen, lze použít tento.
Přihlaste se do svého účtu Bing správce webu na URL: http://www.bing.com/toolbox/webmaster/.
Klepněte na tlačítko Přidat web.
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.
Zobrazí se dialog Ověřit vlastnictví s třemi možnostmi. Postupujte dle pokynů, když se rozbalí Možnost 1: Umístěte soubor XML na svůj webový server. Nahrajte soubor BingSiteAuth.xml poskytnutý Bingem do dokumentačního kořenu svých webových stránek.
Až potvrdíte, že poskytnutý soubor BingSiteAuth.xml byl nahrán do požadovaného umístění tím, že k němu přistoupíte ve webovém prohlížeči, klepněte na tlačítko Ověřit.
Po úspěšném ověření vlastnictví svých webových stránek se vraťte na domovskou stránku Bing správce webu. Zde by měly být webové stránky uvedeny v seznamu. Klepněte na ně.
Zvolte kartu Crawl.
Zvolte Mapy stránek a poté Přidat feed.
Zobrazí se dialog Přidat feed. Vložte URL souboru mapy svých stránek a klepněte na 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

Postup 8.1. Chcete-li importovat knihu do Drupalu:

Postupujte dle kroků v 8.1 – „Jak sestavit soubor CSV pro import do Drupalu“.
Nahrajte soubor CSV do import directory na serveru Drupal.
Nahrajte adresář en-US do adresáře "sites/default/files/" na serveru Drupal. Tuto hodnotu lze polačit v publican.cfg. Více informací si prosím přečtěte v 8.2 – „Soubor publican.cfg“.
Přihlaste se na své stránky Drupal a přejděte do Administer -> Content management -> Import content. Soubor CSV, který jste právě nahráli, se zobrazí v tabulce 'Pending Tasks' a je připraven pro import.
Stiskněte Import now pro zahájení importu knihy. Budete přesměrováni na další stránku, která zobrazuje průběh importu.
Odkaz na knihu by se měl nyní zobrazovat v uvedeném bloku nabídky.

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:

Nainstalujte balíček nebo balíčky, které poskytují dokončování příkazů v bash pro vás operační systém. Například na Fedoře spusťte sudo yum install bash-completion.

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

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

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

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)

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

Uživatelská příručka

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

Don Domingo

Zac Dover

Sven Dowdeit

Norman Dunbar

Brian Forté

Rüdiger Landmann

Rebecca Newton

Joshua Oakes

Joshua Wulf

Jeff Fearn

Josef Hruška

Předmluva

1. Konvence používané v dokumentu

1.1. Typografické konvence

1.2. Konvence pro Citace

1.3. Admonitions

2. Potřebujeme zpětnou vazbu!

Úvod

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

1.2. Testing BZ #1088051 Code Popper

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

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.

1.6. Testing BZ #1117561 CDATA tags

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

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

Kapitola 1. Instalace Publicanu

1.1. Operační systémy Linux

1.1.1. Fedora & Red Hat Enterprise Linux 6

1.1.2. Ubuntu

1.1.3. Debian

1.1.4. OpenSuse 12

1.1.5. Docker kontejner

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

1.2. Operační systémy Windows

1.3. OSX Lion

Kapitola 2. Výchozí hodnoty Publicanu

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

Kapitola 3. Příkazy Publicanu

Kapitola 4. Tvorba dokumentu

4.1. Soubory v adresáři knihy

4.1.1. Soubor publican.cfg

4.1.2. Book_Info.xml

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

4.1.3. Author_Group.xml

4.1.4. Chapter.xml

4.1.5. Nazev_Dok.xml

4.1.6. Nazev_Dok.ent

4.1.6.1. Entity a překlad

4.1.7. Revision_History.xml

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

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

4.4. Přidání souborů

4.5. Změna názvu dokumentu

4.6. Překlad dokumentu

4.6.1. Autorská skupina překladu

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

4.7. Sestavení dokumentu

4.7.1. Sestavení dokumentu bez validace

4.8. Balení dokumentu

4.8.1. Druhy balíčků RPM

4.8.1.1. Zdrojové balíčky RPM a binární balíčky RPM

4.8.1.2. Desktopové balíčky a webové balíčky

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

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

4.8.1.3.2. Nastavení kategorie nabídky pracovní plochy

4.8.2. Příkaz $ publican package

4.8.2.1. Příkaz $ publican package — Ukázka použití

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

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

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

4.10.1. Označování softwaru před oficiálním zveřejněním

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

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

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

Kapitola 5. Grafická úprava

5.1. Instalace grafické úpravy

4.8.2. Příkaz `$` publican package

4.8.2.1. Příkaz `$` publican package — Ukázka použití

5.3.6.1. `Feedback.xml`

5.3.6.2. `Legal_Notice.xml`

5.3.7. Podadresář `css`

5.3.8. Podadresář `images`