Kapitola 3. Přehled struktur a elementů DocBooku

Kapitola 3. Přehled struktur a elementů DocBooku
Předcházející		Další

DocBook umožňuje vytvářet několik druhů dokumentů. Mezi ty nejpoužívanější patří knihy (book), články (article), FAQ (qandaset) a referenční stránky (refentry). Nyní se podíváme na základní struktury, které se v těchto typech dokumentů používají. Detailní popis naleznete v [TDG].

3.1. Knihy

Kniha je asi nejpoužívanější typ dokumentu, který se v DocBooku vytváří. Struktura knihy je poměrně volná a vyhoví většině požadavků. Jednak kniha může obsahovat metainformace (bookinfo) a různé pomocné části jako věnování (dedication) a tiráž (colophon). Dále se kniha skládá ze tří druhů elementů:

Navigační komponenty

Sem patří zejména obsah (ToC), seznamy obrázků, tabulek, příkladů apod. (LoT) a rejstřík (index). Tyto elementy se většinou nepoužívají, protože obsahy i rejstřík lze vygenerovat automaticky.

Části

Každá kniha se může skládat z několika částí (part) a referencí (reference).

Části knihy se pak skládají z jednotlivých komponent. U jednodušších knih nemusíme části používat, komponenty můžeme do knihy vložit přímo.

Komponenty

Sem patří elementy, které dělí knihu na úrovni kapitol – předmluva (preface), kapitoly (chapter), přílohy (appendix), slovníček (glossary) a seznam literatury (bibliography). Pokud chceme sdružit více článků do jednoho celku, můžeme jako komponentu použít i článek (article). Jednotlivé komponenty se skládají z elementů, které jsou popsány dále.

Více souvisejících knih můžeme zahrnout do jedné sady (set).

3.2. Sekce

Komponenty knih (kapitoly, přílohy apod.) a články můžeme dále strukturovat pomocí následujících elementů:

sect1–sect5: Pět úrovní sekcí, při vkládání sekcí do sebe nemůžeme přeskočit nějakou sekci v hierarchii.
section: Rekurzivní element, který umožňuje vytváření víceúrovňových sekcí rekurzivním zanořováním.
simplesect: Sekce, kterou již nelze dále rozdělit na podsekce.
bridgehead: Samostatný nadpis sekce, který neslouží jako kontejner pro další elementy nebo sekce.
refsect1–refsect3: Sekce, které umožňují členit položky reference.
glossdiv, bibliodiv, indexdiv: Elementy pro členění slovníčku, seznamu literatury a rejstříku.

3.3. Metainformace

K většině komponent a vyšších elementů můžeme přidat bibliografické informace jako autor, název, copyright apod. Tyto informace se zapisují do elementu *info, kde * je název příslušného elementu. Například informace o knize se zapisují do elementu bookinfo.

3.4. Blokové elementy

Blokové elementy jsou ty elementy, které text dělí na odstavce a podobné úseky. Bývá u nich obvyklé, že tvoří samostatný odstavec – před i za nimi je zalomená řádka. Oproti tomu existují ještě in-line elementy, které jen vyznačují část textu odstavce a po zformátování se obvykle projeví jen změnou písma.

3.4.1. Odstavce

DocBook obsahuje tři druhy odstavců – para, simpara a formalpara.

3.4.2. Seznamy

K dispozici máme několik druhů seznamů:

itemizedlist: Běžný druh seznamu s odrážkami.
orderedlist: Číslovaný seznam.
variablelist: Seznam s pojmů a jejich definic.

Kromě těchto nejpoužívanějších seznamů jsou k dispozici i některé další – seznam popisů k nějakému výpisu (calloutlist), seznam pojmů ze slovníku (glosslist) a jednoduché seznamy simplelist a segmentedlist.

3.4.3. Upozornění

Pro vkládání různých výstrah a upozornění můžeme použít následující elementy – caution, important, note, tip a warning.

Všechny tyto elementy mohou obsahovat nepovinný nadpis (title) a za ním libovolné elementy pro odstavce textu.

3.4.4. Elementy zachovávající řádkování

Následující elementy zachovávají konce řádků tak, jak jsou uvedeny ve zdrojovém XML dokumentu. To je výhodné například u výpisu programů apod. DocBook neobsahuje ekvivalent HTML tagu br pro ukončení řádky, proto mají tato prostředí svůj velký význam.

address: Element pro zápis poštovních adres. Kromě toho že zachovává konce řádek v něm můžeme použít další elementy, pro vyznačení jména, města, státu apod.
literallayout: Element zachovává konce řádků a většinou se zobrazuje normálním písmem.
programlisting: Element určený pro zařazování výpisu programů, obvykle se zobrazuje neproporcionálním písmem.
screen: Element obvykle zachycuje nějaký výstup z obrazovky apod.
screenshot: Speciální element pro zařazování sejmutých obrazovek. Obvykle obaluje obrázek.
synopsis: Element obsahující popis syntaxe příkazu nebo funkce.

3.4.5. Příklady, obrázky a tabulky

Pro vkládání příkladů, obrázků a tabulek slouží elementy example, informalexample, figure, informalfigure, table a informaltable. Neformální verze neobsahují nadpis. K praktickému vkládání obrázků a tabulek se ještě vrátíme.

3.4.6. Rovnice

Rovnice lze vkládat pomocí elementů equation, informalequation a inlineequation. Rovnice se vkládají jako obrázek a alternativní text. Pokud chceme do textu vkládat hodně rovnic, je možné DocBook rozšířit o podporu jazyka MathML pro zápis matematických výrazů.

3.4.7. Obrázky

Obrázky se vkládají pomocí elementů graphics, inlinegraphics, mediaobject a inlinemediaobject. Pokud chceme mít u obrázků popis, musíme je vložit do elementu figure.

3.4.8. Další blokové elementy

blockquote: Delší citace.
classsynopsis: Element pro zápis definice třídy.
constructorsynopsis: Element pro zápis konstruktoru a jeho parametrů.
cmdsynopsis: Popis příkazu včetně všech voleb a parametrů.
destructorsynopsis: Element pro zápis destruktoru a jeho parametrů.
epigraph: Krátká citace na začátku kapitoly.
funcsynopsis: Element pro zápis funkce a jejích parametrů.
highlights: Souhrn hlavních bodů knihy nebo komponenty.
methodsynopsis: Element pro zápis metody a jejích parametrů.
msgset: Množina souvisejících chybových hlášení.
procedure: Element obsahuje kroky, které tvoří nějaký postup.
sidebar: Poznámka na okraji (marginálie).

3.5. Inline elementy

Inline elementy přiřazují význam jednotlivým částem textu. DocBook jich obsahuje opravdu mnoho a záleží na každém autorovi, jak přesně bude dokument značkovat. Jelikož přidávání elementů zdržuje psaní je dobré vždy vytvořit nějaký kompromis. Značkovat jen to, co skutečně potřebujeme – pokud například píšeme dokumentaci k nějakému API, je dobré v textu označovat názvy funkcí – tuto informaci pak můžeme využít při generování rejstříku. Pro snazší orientaci jsou elementy rozděleny do několika kategorií.

3.5.1. Obecné elementy

abbrev: Zkrácené slovo.
acronym: Zkratka.
emphasis: Zvýraznění textu.
footnote: Poznámka pod čarou.
phrase: Označená část textu.
quote: Text v uvozovkách.
trademark: Obchodní značka.

3.5.2. Odkazy

anchor: Označuje místo v dokumentu.
citation: Citace položky ze seznamu literatury.
citetitle: Název citovaného díla.
firstterm: První výskyt pojmu.
glossterm: Pojem ze slovníčku.
link: Odkaz na jiné místo dokumentu.
olink: Odkaz na jiný dokument zapsaný nepřímo.
ulink: Odkaz na URL adresu.
xref: Odkaz na jinou část dokumentu.

3.5.3. Značkování

foreignphrase: Fráze v cizím jazyce.
wordasword: Slovo.
computeroutput: Výstup generovaný počítačem.
literal: Text, který lze chápat jako literál.
markup: Značkování, které má být zobrazeno tak, jak je zapsáno.
prompt: Řetězec označující vstupní pole na obrazovce.
replaceable: Text, který má být podle potřeby nahrazen uživatelem.
sgmltag: Element pro zápis SGML/XML elementů, tagů, atributů apod.
userinput: Text zadaný uživatelem.
code: Kousek programového kódu.
uri: URI adresa.

3.5.4. Matematické výrazy

inlineequation: Matematický výraz.
subscript: Dolní index.
superscript: Horní index.

3.5.5. Uživatelské rozhraní

accel: Označuje klávesovou zkratku uvnitř menu.
guibutton: Text na tlačítku.
guiicon: Text nebo obrázek vystupující jako ikona.
guilabel: Text na popisce.
guimenu: Název menu.
guimenuitem: Koncová položka menu.
guisubmenu: Název podmenu.
keycap: Text napsaný na klávese.
keycode: Kód určité klávesy.
keycombo: Kombinace kláves.
keysym: Symbolické jméno klávesy.
menuchoice: Výběr z menu.
mousebutton: Tlačítko myši.
shortcut: Klávesová zkratka odpovídající příkazu v menu.

3.5.6. Programování

action: Odezva na nějakou událost.
code: Kousek programového kódu.
classname: Název třídy.
constant: Konstanta.
errorcode: Chybový kód.
errorname: Chybové hlášení.
errortype: Druh chyby.
exceptionname: Název výjimky.
function: Název funkce, rutiny, metody.
interface: Část uživatelského rozhraní.
interfacedefinition: Název formální specifikace uživatelského rozhraní.
interfacename: Název rozhraní (API).
literal: Text, který lze chápat jako literál.
methodname: Název metody.
msgtext: Text hlášení.
parameter: Parametr.
replaceable: Text, který má být podle potřeby nahrazen uživatelem.
returnvalue: Hodnota vrácená funkcí.
structfield: Položka struktury/záznamu.
structname: Název struktury/záznamu.
symbol: Název, který je před zpracováním nahrazen hodnotou.
token: Jednotka určená ke zpracování.
type: Klasifikace hodnoty.
varname: Název proměnné.

3.5.7. Operační systémy

application: Název aplikace.
command: Příkaz.
envar: Proměnná prostředí.
filename: Název souboru.
medialabel: Název média (diskety, pásky apod.).
option: Volba příkazu.
parameter: Parametr.
prompt: Řetězec označující vstupní pole na obrazovce.
systemitem: Položka nebo pojem svázaný se systémem.

3.5.8. Obecné inline elementy

application: Název aplikace.
database: Databáze.
email: E-mailová adresa.
filename: Název souboru.
hardware: Fyzická součást počítače.
inlinegraphics, inlinemediaobject: Obrázek vložený přímo do textu.
optional: Nepovinná informace.
remark: Komentář, který se má zobrazovat v pracovních verzích dokumentu.

3.6. Předdefinované znakové entity

DocBook obsahuje mnoho předdefinovaných entit, které můžeme používat pro zápis neobvyklých znaků. Kompletní přehled lze najít v DTD pro DocBook nebo v [TDG]. Některé nejpoužívanější entity jsou shrnuty v tabulce 3.1 – „Nejběžnější entity“.

Tabulka 3.1. Nejběžnější entity

Entita	Znak	Popis
`–`	–	krátká pomlčka
`—`	—	dlouhá pomlčka
`…`	…	tři tečky
`α`	α	řecké písmeno „alfa“
`&half;`	½	1/2
`©`	©	znak copyrightu
`®`	®	registrovaná značka
`±`	±
`§`	§	paragraf
`&ldquor;`	„	české uvozovky (jednodušší je zápis uvozovek pomocí elementu `quote`)
`“`	“

Předcházející	Domů	Další
Kapitola 2. První kroky	Nahoru	Kapitola 4. Ukázky nejpoužívanějších docbookových konstrukcí