Kapitola 7. Pokročilé techniky

Obsah

7.1. Rozdělení jednoho dokumentu do více souborů
7.2. Automatický výběr obrázků
7.3. Generování rejstříku
7.3.1. XSL styly
7.3.2. DSSSL styly
7.4. Vkládání obsahu externích souborů
7.5. Generování sady HTML stránek
7.6. Profilace dokumentů (podmíněné dokumenty)
7.7. Odkazy mezi dokumenty
7.8. Automatické vyznačování změn v XML dokumentech

V této kapitole se podíváme, jak řešit některé problémy, se kterými se setkáme při tvorbě dokumentace. Půjde jak o jednoduché tipy tak i o postupy vedoucí k výsledkům, které jsou mnohdy dostupné pouze v poměrně drahých komerčních nástrojích.

7.1. Rozdělení jednoho dokumentu do více souborů

U větších dokumentů je celkem logické jejich rozdělení do několika souborů. Jednak se s menšími soubory lépe pracuje, a druhak může na jednom dokumentu pracovat více lidí najednou – každý edituje jen jednu jeho část. V DocBooku lze jeden dokument rozdělit na více části velice snadno pomocí mechanismu externích textových entit.

Příklad 7.1. Rozložení dokumentu do několika souborů – velkakniha.xml

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
               'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY kap1 SYSTEM "xinline.xml">
<!ENTITY kap2 SYSTEM "xcallouts.xml">
<!ENTITY kap3 SYSTEM "xobrazky.xml">
<!ENTITY kap4 SYSTEM "xseznamy.xml">
<!ENTITY kap5 SYSTEM "xtabulky.xml">
<!ENTITY kap6 SYSTEM "xtrida.xml">
<!ENTITY ref  SYSTEM "xreference.xml">
]>
<book lang="cs">
  <bookinfo>
    <title>Velká kniha</title>
    <subtitle>Složená z několika entit</subtitle>
  </bookinfo>
  <preface>
    <title>Úvod</title>
    <para>Následuje několik sice nesouvisejících kapitol, ale na
ukázku to stačí ne?</para>
  </preface>
  &kap1;
  &kap2;
  &kap3;
  &kap4;
  &kap5;
  &kap6;
  &ref;
</book>

Jediné, na co si musíme dát pozor, je to, že v XML musí jednotlivé entity začínat jen deklarací kódování a nesmějí obsahovat deklaraci typu dokumentu (<!DOCTYPE...>).

Příklad 7.2. Ukázka načítané entity

<?xml version="1.0" encoding='utf-8'?>
<chapter lang="cs">
  <title>Kapitola se seznamy</title>
    ...
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
sgml-doctype: velkakniha.xml
sgml-parent-document: ("velkakniha.xml" "book" "chapter")
End:
-->

Komentář na konci je používán PSGML módem v Emacsu. Pokud tyto parametry nastavíme, dokáže Emacs bez problémů pracovat s dokumenty rozdělenými do souborů. V parametrech se udává jméno souboru, do kterého je entita vložená, element, do kterého je entita vnořena, a nakonec element, který je kořenovým elementem entity.

Podobně lze nastavit parametry pro editor jEdit:

Příklad 7.3. Ukázka načítané entity v jEditu

<?xml version="1.0" encoding="utf-8"?>
<chapter lang="cs">
  <title>Kapitola se seznamy</title>
    ...
</chapter>
<!-- jEdit buffer-local properties: -->
<!-- :xml.root=velkakniha.xml: -->

Práce s externími entitami není úplně pohodlná – musíme je předem deklarovat a jednotlivé entity nemohou obsahovat vlastní deklaraci typu dokumentu. Tento problém lze obejít používáním standardu XInclude pro vkládání XML dokumentů. Tento standard zatím není podporován všemi aplikacemi, nicméně jej podporuje například XSLT procesor xsltproc nebo parser Xerces, který může být použit společně se Saxonem, takže je možné XInclude použít již dnes.

Jednotlivé části dokumentu uložíme do samostatných souborů, které jsou samostatné XML dokumenty včetně vlastní deklarace typu dokumentu. To nám umožňuje jejich bezproblémové samostatné zpracování pomocí klasických nástrojů, XML editory nevyjímaje. Pokud pak chceme části dokumentu (např. kapitoly) použít v nějakém větším dokumentu, vložíme je pomocí speciálního elementu XInclude:

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
            href="kapitola.xml"/>

Příklad 7.4. Složení dokumentu z několika částí pomocí XInclude – velkakniha2.xml

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
               'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
<book lang="cs" xmlns:xi="http://www.w3.org/2001/XInclude">
  <bookinfo>
    <title>Velká kniha</title>
    <subtitle>Složená z několika entit</subtitle>
  </bookinfo>
  <preface>
    <title>Úvod</title>
    <para>Následuje několik sice nesouvisejících kapitol, ale na
ukázku to stačí ne?</para>
  </preface>
  <xi:include href="inline.xml"/>
  <xi:include href="callouts.xml"/>
  <xi:include href="obrazky.xml"/>
  <xi:include href="seznamy.xml"/>
  <xi:include href="tabulky.xml"/>
  <xi:include href="trida.xml"/>
  <xi:include href="reference.xml"/>
</book>

Pokud chceme takto složený dokument validovat, musíme parseru říci, aby validaci provedl až po složení celého dokumentu (volbou --postvalid místo --valid):

xmllint --xinclude --postvalid --noout dokument.xml

Při zpracování dokumentu XSL styly musíme zapnout podporu XInclude. Procesor xsltproc k tomu používá parametr --xinclude. Např. pro převod do jedné HTML stránky použijeme:

xsltproc --xinclude -o dokument.html c:/docbook/xsl/html/docbook.xsl dokument.xml

V Saxonu se podpora XInclude aktivuje rekonfigurací použitého parseru XML (viz „Saxon s podporou XML katalogů a XInclude“).

7.2. Automatický výběr obrázků

Pokud připravujeme dokumentaci pro tištěný i on-line výstup, potřebujeme mít obrázky většinou ve dvou formátech – ve vektorovém a bitmapovém. Styl by pak měl vybrat formát, který je nejvhodnější pro dané médium. Existují v zásadě dva způsoby, jak toho jednoduše dosáhnout.

První metoda využívá toho, že do dokumentu vkládáme obrázky v několika (alespoň ve dvou formátech) do elementu mediaobject. Styl pak podle formátu (atribut format) nebo přípony souboru vybere nejvhodnějšího kandidáta. Vybere se přitom první obrázek, který je v podporovaném formátu. Obrázky by proto měly být uvedeny v pořadí od nejkvalitnějšího (např. vektorová verze v EPS, PDF nebo WMF) k méně kvalitním (např. bitmapové verze v GIF nebo PNG).

<mediaobject>
<imageobject>
<imagedata fileref="pic/uvod-ep.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="pic/uvod-ep.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>

V DSSSL stylech můžeme seznam podporovaných formátů změnit nastavením následující proměnných:

(define preferred-mediaobject-extensions
  (list "eps" "ps" "jpg" "jpeg" "png"))

(define preferred-mediaobject-notations
  (list "EPS" "PS" "JPG" "JPEG" "PNG" "linespecific"))

V XSL stylech lze podobného efektu dosáhnout změnou následujících šablon:

<xsl:template name="is.graphic.format">
  <xsl:param name="format"></xsl:param>
  <xsl:if test="$format = 'PNG'
                or $format = 'JPG'
                or $format = 'JPEG'
                or $format = 'linespecific'
                or $format = 'GIF'
                or $format = 'GIF87a'
                or $format = 'GIF89a'
                or $format = 'BMP'">1</xsl:if>
</xsl:template>

<xsl:template name="is.graphic.extension">
  <xsl:param name="ext"></xsl:param>
  <xsl:if test="$ext = 'png'
                or $ext = 'jpeg'
                or $ext = 'jpg'
                or $ext = 'avi'
                or $ext = 'mpg'
                or $ext = 'mpeg'
                or $ext = 'qt'
                or $ext = 'gif'
                or $ext = 'bmp'">1</xsl:if>
</xsl:template>

Druhý způsob předpokládá, že stejné obrázky v různých formátech máme uložené v souborech se stejným názvem, ale odlišnou příponou. Do dokumentu pak odkaz vkládáme bez přípony a styl automaticky doplní odpovídající příponu. Obrázek tedy do dokumentu vložíme pomocí následujícího kódu.

<mediaobject>
  <imageobject>
    <imagedata fileref="schema"/>
  </imageobject>
</mediaobject>

Ve skutečnosti přitom máme k dispozici např. obrázky schema.eps a schema.png. Při generování tištěného výstupu, kdy chceme použít obrázky v EPS, přidáme do stylu následující parametr:

(define %graphic-default-extension% "eps")

Pro generování HTML podoby budeme mít jiný styl a v něm jako standardní příponu nastavíme PNG.

Obdobný parametr lze nastavit i v XSL stylech:

<xsl:param name="graphic.default.extension">png</xsl:param>

Novější verze XSL stylů podporují ještě jednu metodu. U elementu imageobject můžeme v atributu role určit výstupní formát, pro který je obrázek určen. Jako hodnota se typicky uvádí html nebo fo. Styly pak vyberou odpovídající obrázek, bez ohledu na pořadí elementů imageobject. Dokonce můžeme mít i několik různých variant obrázků pro různé procesory FO:

<mediaobject>
  <imageobject  role="html">
    <imagedata  format="PNG"  fileref="pic/uvod-ep.png"/>
  </imageobject>
  <imageobject  role="fop">
    <imagedata  format="SVG"  fileref="pic/uvod-ep.svg"/>
  </imageobject>
  <imageobject  role="xep">
    <imagedata  format="PDF"  fileref="pic/uvod-ep.pdf"/>
  </imageobject>
</mediaobject>

Stylům pak v parametru preffered.mediaobject.role předáme údaj o tom (html, fop, xep), jaké obrázky chceme použít.

7.3. Generování rejstříku

Kvalita rejstříku generovaná různými druhy stylů se liší, nicméně poslední verze XSL stylů jsou schopné generovat rejstřík se všemi obvyklými náležitostmi.

Rejstříková hesla se zapisují přímo do dokumentu pomocí elementu indexterm. Jeho obsah se v dokumentu nezobrazuje, ale slouží jako podklad pro generování rejstříku.

<para>Bohatství moderních společností je založeno na 
informacích<indexterm><primary>informace</primary></indexterm>.</para>

Do elementu indexterm se zapisují hesla a to i víceúrovňová:

<indexterm>
<primary>informace</primary>
</indexterm>

<indexterm>
<primary>informace</primary>
<secondary>získání</secondary>
</indexterm>

<indexterm>
<primary>informace</primary>
<secondary>šíření</secondary>
</indexterm>

<indexterm>
<primary>informace</primary>
<secondary>šíření</secondary>
<tertiary>ústní</tertiary>
</indexterm>

V rejstříku se pak takto definovaná hesla objeví například jako:

informace, 13
  šíření, 17
    ústní, 25
  získání, 15

Rejstříková hesla v DocBooku mohou mít až čtyři úrovně.

Pokud nějakému termínu odpovídá větší úsek dokumentu, můžeme ho celý pokrýt jako rozsah. Použijí se dva elementy indexterm, které označují začátek a konec platnosti určitého hesla.

<indexterm class="startofrange" id="ix.xml.historie">
<primary>XML</primary>
<secondary>historie</secondary>
</indexterm>
  ...
<indexterm class="endofrange" startref="ix.xml.historie"/>

Ve vygenerovaném rejstříku pak dostaneme interval:

XML
  historie, 27–42

Pokud chceme, aby se položka řadila nestandardním způsobem, použijeme atribut sortas. Třídění se pak provede podle jeho obsahu, ne podle skutečného textu hesla. To je výhodné v případech, kdy heslo obsahuje nějaké speciální znaky apod. Následující příklad v rejstříku zobrazí písmeno Ω, ale bude se řadit jako text „Omega“.

<indexterm>
<primary sortas="Omega">&Omega;</primary>
</indexterm>

Chceme-li některé výskyty hesla v rejstříku zvýraznit (například mít stránku s primární definicí hesla tučně), můžeme u hesla nastavit jeho důležitost.

<indexterm significance="preferred">
<primary>informace</primary>
</indexterm>

Nechceme-li, aby rejstříkové heslo obsahovalo odkaz na konkrétní číslo strany, ale odkaz na jiné heslo, můžeme k tomu využít elementy see a seealso.

<indexterm>
<primary>DTD</primary>
</indexterm>

<indexterm>
<primary>definice typu dokumentu</primary>
<see>DTD</see>
</indexterm>

<indexterm>
<primary>XML schéma</primary>
<seealso>DTD</seealso>
</indexterm>

Ve výsledném rejstříku bychom dostali:

- D -
definice typu dokumentu, viz DTD
DTD, 42

- X -
XML schéma, 81, viz též DTD

Tímto jsme se seznámili skoro se všemi možnostmi zápisu rejstříkových hesel v DocBooku. Nezmínili jsme pouze možnost uložit definici rejstříkových hesel zcela mimo místo jejich výskytu s využitím atributu zone. Tato metoda není dle mého názoru příliš praktická, více se o ní můžete dočíst v [TDG].

7.3.1. XSL styly

V XSL stylech je situace velice jednoduchá. Pokud máme v dokumentu označené nějaké termíny jako rejstříková hesla, rejstřík se automaticky vygeneruje. Vyzkoušet si to můžete na souboru uvod.xml, který obsahuje několik rejstříkových hesel.

saxon -o uvod.html uvod.xml c:\docbook\xsl\html\docbook.xsl

Rejstřík by měl v tištěné verzi fungovat úplně stejně, ale prakticky můžete zkusit, že např. v PassiveTeXu se zatím správně nedopočítají čísla stran. Oproti tomu komerční XEP si s čísly stran poradí. Podpora tvorby rejstříků v XSL stylech a procesorech FO se neustále zlepšuje. Při použití komerčních procesorů FO jako XEP a XSL Formatter fungují i takové věci jako slučování duplicitních čísel stran apod.

Standardní mechanismus pro generování rejstříku bohužel neumí správně obsloužit takové případy jako slovo začínající písmenem „ch“ nebo znakem s diakritikou. V takových případech je nutné použít rejstříkový mechanismus nové generace, který funguje pouze s procesorem Saxon a s některými verzemi xsltproc. Pro jeho potřebí si musíme připravit vlastní styl s úpravami, který načítá soubor autoidx-ng.xsl odpovídající použité verzi stylů.

Příklad 7.5. Generování českého rejstříku – html-rejstrik.xsl

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0"
                xmlns:saxon="http://icl.com/saxon"
                extension-element-prefixes="saxon">

<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
<xsl:include href="http://docbook.sourceforge.net/release/xsl/current/html/autoidx-ng.xsl"/>

<!-- Úpravy parametrů -->

<!-- Změna výstupního kódování -->
<xsl:output method="html" encoding="iso-8859-2" 
                          saxon:character-representation="native"/>

<!-- Mají se používat rozšíření -->
<xsl:param name="use.extensions" select="1"/>

<!-- Mají se sekce automaticky číslovat -->
<xsl:param name="section.autolabel" select="1"/>

<!-- Mají čísla sekcí obsahovat i čísla kapitol -->
<xsl:param name="section.label.includes.component.label" select="1"/>

<!-- Mají se číslovat kapitoly -->
<xsl:param name="chapter.autolabel" select="1"/>

</xsl:stylesheet>

7.3.2. DSSSL styly

Nejprve si musíme vytvořit nový XML soubor pro rejstřík. Toho dosáhneme spuštěním perlového skriptu, který je součástí distribuce stylů.

perl c:\docbook\dsssl\bin\collateindex.pl -N -o index.xml

Vznikne nám soubor index.xml, do kterého se bude ukládat rejstřík. Tento soubor bychom měli do našeho dokumentu načíst pomocí mechanismu externích entit (viz uvod2.xml).

Nyní musíme vygenerovat podklady pro skript collateindex.pl. Vždy musíme použít HTML verzi stylu (i tehdy, když chceme rejstřík získat v tištěné verzi dokumentu):

jade -d c:\docbook\dsssl\html\docbook.dsl -t sgml -V html-index c:\docbook\jade\xml.dcl uvod2.xml

Jade nám vygeneruje soubor HTML.index, ze kterého lze vytvořit rejstřík. Rejstřík v souboru index.xml vytvoříme pomocí příkazu.

perl c:\docbook\dsssl\bin\collateindex.pl -o index.xml HTML.index

Jediný problém je v tom, že vygenerovaný soubor na svém začátku nemá správnou deklaraci kódování. To můžeme změnit ručně, případně opravit skript. Nemusíme také dělat nic, protože tento dokument budeme zpracovávat jen pomocí Jade, který deklaraci kódování nevyžaduje.

Nyní můžeme zcela běžným způsobem zpracovat dokument a budeme v něm mít rejstřík jak pro tištěnou tak pro HTML verzi.

7.4. Vkládání obsahu externích souborů

Pokud potřebujeme do dokumentu vložit obsah externího souboru, můžeme k tomu použít element inlinegraphic nebo inlinemediaobject. DSSSL styly tuto vlastnost podporují automaticky, v XSL stylech musíme zapnout podporu rozšíření nastavením parametru use.extensions=1.

<programlisting><inlinegraphic fileref="seznamy.xml" format="linespecific"/></programlisting>

S výhledem do budoucna je lepší použít konstrukci využívající inlinemediaobject.

<programlisting><inlinemediaobject>
<imageobject>
<imagedata fileref="seznamy.xml" format="linespecific"/>
</imageobject>
</inlinemediaobject></programlisting>

DocBook 4.2 nabízí poněkud přehlednější možnost pro dosažení stejného efektu.

<programlisting><textobject>
<textdata fileref="seznamy.xml"/>
</textobject></programlisting>

Kromě atributu fileref můžeme použít i atribut encoding pro určení kódování načítaného dokumentu. DSSSL styly tuto novou sémantiku zatím nepodporují, XSL už ano, ale informaci o kódování souboru podporují až od verze stylů 1.65.2 (resp. 1.66.0).

7.5. Generování sady HTML stránek

Pokud nám nevyhovují jména generovaných stránek, můžeme pomocí parametru stylu říci, že se jména mají brát z identifikátorů odpovídajících elementů (parametr use.id.as.filename).

<chapter id="jazyk">
<title>Drobná vylepšení jazyka</title>
  ...

Další možností je použití speciální instrukce pro zpracování <?dbhtml filename="jméno souboru"?>.

<chapter>
<title>Drobná vylepšení jazyka</title>
<?dbhtml filename="jazyk.html"?>
  ...

7.6. Profilace dokumentů (podmíněné dokumenty)

V mnoha případech potřebujeme z jedné předlohy generovat několik obsahově drobně odlišných verzí dokumentů. Uživatelská příručka k programu, který je k dispozici ve verzích pro Windows a pro Linux, se bude patrně lišit jen v pár bodech týkajících se instalace a konfigurace. Je kvůli tomu zbytečné vytvářet a udržovat sladěné dva dokumenty. Stejně tak můžeme mít kromě standardní dokumentace, také příručku doplňovanou o aktuální postřehy z pracoviště technické podpory. Opět asi vhodnější tyto dokumenty uchovávat v jednom, aby byly naprosto synchronizované.

Mnohem vhodnější je vytvářet dokument jeden a v něm označit části určené pro konkrétní platformu nebo skupinu uživatelů. Při generování výsledné podoby dokumentu pak provedeme profilaci, či chcete-li přizpůsobení cílově skupině. Z dokumentu se vyberou pouze jeho odpovídající části. DocBook k těmto účelům nabízí např. atributy os a userlevel. Do nich se ukládá identifikátor operačního systému, resp. skupiny uživatelů, pro které je daná část dokumentu určena. Část příručky tak může vypadat takto.

Příklad 7.6. Dokument s dvěma verzemi postupu pro různé operační systémy

<para>Pro správný chod programu je potřeba nastavit proměnnou
<envar>APPHOME</envar>.</para>

<para os="Unix">Proměnnou nastavíme příkazem <command
moreinfo="none">APPHOME=/usr/local/app; export APPHOME</command>.</para>

<para os="Win">Proměnnou nastavíme v <application
moreinfo="none">Ovládacím Panelu</application> tak, že v položce
<guimenuitem moreinfo="none">Systém</guimenuitem> vybereme volbu
<guibutton moreinfo="none">Prostředí</guibutton>...</para>

Když budeme generovat příručku pro Windows, budeme chtít vynechat všechny elementy, které mají atribut os a nemají v něm uloženou hodnotu Win. Totéž bude analogicky platit pro unixovou verzi dokumentace.

Tento problém můžeme velice jednoduše vyřešit tím, že při formátování pomocí stylu z dokumenty momentálně nepotřebné části vyřadíme. V XSLT toho lze dosáhnout velice jednoduše použitím importu stávajícího stylu a přidáním jednoduché šablony. Tento přístup sice vygeneruje správný výstup, ale některé části dokumentu jako obsah budou obsahovat i položky pro elementy, které jsme nechtěli zpracovat. Úpravy XSL stylů by proto musely být poměrně komplexní.

Schůdnější cestou je vytvoření jednoduchého stylu, který z původního dokumentu pouze vynechá nepotřebné části. Dostaneme tak nový zcela legální docbookový dokument, který můžeme zpracovat libovolným nástrojem včetně XSL a DSSSL stylů. Postup se sice o jeden krok prodlouží, ale v případě opakovaného použití tohoto postupu si můžeme vytvořit dávkový soubor, který vše provede za nás. Styl pro profilaci dokumentů naleznete v souboru profiling/profile.xsl ve standardní distribuci XSL stylů.

K vytvoření profilovaného dokumentu stačí na náš dokument aplikovat tento styl a XSLT procesoru v parametrech předat informace o operačním systému a/nebo skupině uživatelů, pro které chceme dokument připravit. Informace se předávají v parametrech profile.os a profile.userlevel.

saxon -o výstup dokument c:\docbook\xsl\profiling\profile.xsl "profile.os=kód OS" "profile.userlevel=kód úrovně uživatele"

Parametry mohou obsahovat i více hodnot oddělených středníkem. V současné době styl umožňuje profilaci na základě následujících parametrů a jim odpovídajích atributů:

profile.os, profile.userlevel, profile.arch, profile.condition, profile.conformance, profile.revision, profile.revisionflag, profile.security, profile.vendor, profile.role, profile.lang

Profilace je provedena na základě obsahu odpovídajícího atributu.

profile.attribute

Jméno atributu, ve kterém jsou informace pro profilaci. Tento parametr použijeme v případě, kdy námi použitý parametr nemá přímo svůj parametr.

profile.value

Hodnota pro uživatelsky definovaný atribut.

profile.separator

Oddělovač identifikátorů profilů. Standardně se používá středník (;).

Od verze 1.50 umožňují XSL styly provádět profilaci a transformaci během jednoho běhu stylu. Ke všem stylům jako docbook.xsl, chunk.xsl a htmlhelp.xsl. Např. pro profilaci pro Windows a následný převod do HTML můžeme použít:

saxon dokument.xml c:\docbook\xsl\html\profile-chunk.xsl "profile.os=Win"

7.7. Odkazy mezi dokumenty

DocBook nabízí bohaté možnosti pro tvorbu odkazů v rámci jednoho dokumentu pomocí elementů xref a link. Při zpracování rozsíhlejších dokumentačních projektů však potřebujeme vytvářet odkazy i mezi jednotlivými dokumenty. Jedním z řešení je všechny dokumenty spojit do jedné obrovské sady knih s využitím elementu set. Má to však své nevýhody – dokument je hodně velký, pro jeho skládání je proto potřeba využít XInclude, chceme-li pracovat s jednotlivými knihami současně. Navíc je mnohem náročnější dodržet jedinečnost identifikátorů v takto rozsáhlém dokumentu.

Přijatelnějším řešením je využití elementu olink, který umožňuje vytváření odkazů mezi nezávislými dokumenty. Odkaz je určen dvěma parametry – identifikátorem dokumentu a identifikátorem místa v dokumentu. Identifikátor dokumentu si můžeme volit libovolně, identifikátor místa v dokumentu musí být nějaké id existující v dokumentu.

<olink targetdoc="InstalačníPříručka" targetptr="uvod"/>

<olink targetdoc="InstalačníPříručka" targetptr="uvod">úvod
instalační příručky</olink>

První varianta odkazu se přitom chová podobně jako xref a automaticky vygeneruje text odkazu. Druhá varianta je obdobou elementu link, kdy text odkazu určujeme ručně.

Práce s takto vytvořenými odkazy samozřejmě vyžaduje, aby existovalo nějaké mapování, které z identifikátoru dokumentu dokáže určit jeho umístění a skutečný název souboru. Pro tyto účely je potřeba vytvořit si databázi cílů v dokumentech. Tuto databázi umí z velké části automaticky generovat XSL styly. Přesný postup si popíšeme dále.

První co musíme vymyslet, jsou identifikátory pro naše dokumenty. Je dobré vymyslet jména, která zůstanou unikátní i po případném rozšiřování kolekce dokumentů a budou dostatečně výstižná. V našem příkladu takovým identifikátorem byl řetězec InstalačníPříručka. Zvolené identifikátory pak používáme pro tvorbu odkazů mezi dokumenty v elementu olink.

Další rozhodnutí spočívá ve vymyšlení adresářové struktury, pro dokumentaci v podobě HTML stránek. Tuto hierarchii adresářů musíme znát dopředu, aby se mohly správně dopočítat relativní odkazy, které vzniknou z olinku. Výstupní hierarchii musíme uložit v podobě dokumentu XML, jak ukazuje následující příklad.

Příklad 7.7. Databáze cílů v dokumentech – olinkdb.xml

<?xml version="1.0" encoding="utf-8"?> 
<!DOCTYPE targetset SYSTEM "http://docbook.sourceforge.net/release/xsl/current/common/targetdatabase.dtd" [
<!ENTITY ol1targets SYSTEM "ol1target.db"> 
<!ENTITY ol2targets SYSTEM "ol2target.db"> 
]>
<targetset> 
  <targetsetinfo> 
    Popis databáze cílů odkazů. Tato databáze je pouze jednoduchá 
    testovací pro účely školení.
   </targetsetinfo>

  <!-- Site map for generating relative paths between documents -->
  <sitemap> 
    <dir> 
      <dir name="book1">
        <document targetdoc="OLink1"> 
          &ol1targets;
        </document>
      </dir>
      <dir name="book2">
        <document targetdoc="OLink2"> 
          &ol2targets;
        </document>
      </dir>
    </dir>
  </sitemap>
</targetset>

Elementy dir (kromě toho na nejvyšší úrovni) odpovídají výstupní adresářové struktuře. V našem případě tedy výstupní HTML stránky očekáváme v adresářích book1 a book2. Elementy dir do sebe můžeme podle potřeby vnořovat a vytvářet tak libovolně hluboké adresářové struktury.

V místě, kde se pak nachází nějaký dokument převedený do HTML použijeme element document a v atributu targetdoc určíme identifikátor dokumentu, který se pak používá v elementech olink. V našem případě máme dokumenty dva s názvy OLink1 a OLink2. První z nich je přitom v adresáři book1 a druhý v adresáři book2. Nepoužíváme-li výstup do sady HTML stránek, ale jen do jedné velké HTML stránky, musíme u elementu document použít ještě atribut baseuri a určit jméno HTML stránky, která obsahuje převedený dokument.

Obsah elementu document obsahuje odkaz na externí entitu, která zastupuje celý malý dokument XML. V tomto dokumentu jsou pak obsaženy všechny informace potřebné pro vyhodnocení odkazů na daný dokument. Tento dokument je poměrně obsáhlý, ale nemusí nás to trápit, protože jej lze vygenerovat automaticky. Stačí spustit běžnou XSL transformaci a pomocí parametrů říci, že se má soubor vygenerovat. Pro naše dva dokumenty bychom patřičné části databáze vytvořili pomocí příkazů:

saxon olink1.xml chunk.xsl "collect.xref.targets=only" "targets.filename=ol1target.db"

saxon olink2.xml chunk.xsl "collect.xref.targets=only" "targets.filename=ol2target.db"

Tento příkaz bychom měli spustit vždy, když se daný dokument (v našem případě olink1.xml nebo olink2.xml) změní, aby se odkazy vyhodnocovaly správně.

Při běžném převodu dokumentů do HTML nebo formátovacích objektů musíme nyní stylům předat další parametry, které nesou informaci o aktuálním dokumentu, databázi cílů odkazů apod. Naše dva ukázkové dokumenty bychom mohli převést do HTML například pomocí následujících příkazů:

saxon olink1.xml chunk.xsl "target.database.document=olinkdb.xml" "current.docid=OLink1" "base.dir=book1/"

saxon olink2.xml chunk.xsl "target.database.document=olinkdb.xml" "current.docid=OLink2" "base.dir=book2/"

Pokud zároveň generujeme výstup do jedné HTML stránky a do sady HTML stránek, musíme si vytvořit dvě samostatné databáze cílů odkazů. Pro odkazy při výstupu do formátovacích objektů lze využívat databáze určené pro HTML, protože se využívají pouze texty odkazů, nevytváří se skutečné hypertextové odkazy. Podpora olinku pro HTML Help bude dostupná v blízké budoucnosti.

7.8. Automatické vyznačování změn v XML dokumentech

Při editorských a korektorských úpravách dokumentů je užitečná možnost přehledného zobrazení všech změn mezi dvěma odlišnými verzemi téhož dokumentu. Pro XML dokumenty nelze úspěšně použít běžné nástroje pro porovnávání textů jako diff, některé hi-end XML editory proto nabízejí pohodlné nástroje. Další možností je využití utility diffmk od Normana Walshe, resp. její novější verze napsané v Javě.

Tyto utility umí porovnat obsah dvou souborů a do třetího uložit obě dvě verze s vyznačenými změnami.

perl diffmk -doctype docbook stary.xml novy.xml zmeny.xml

resp.

java com.sun.xtc.diffmk.DiffMk -doctype docbook stary.xml novy.xml zmeny.xml

Nově získaný dokument zmeny.xml obsahuje ve speciálních docbookových atributech popis rozdílů mezi verzemi. XSL styly mají speciální styl pro interpretaci těchto informací:

saxon -o zmeny.html zmeny.xml c:\docbook\xsl\html\changebars.xsl

Obrázek 7.1. Automatické vyznačení změn v dokumentu

Automatické vyznačení změn v dokumentu

© Jiří Kosek 2007
Tento dokument je určen výhradně pro osobní potřebu seznámení se systémem DocBook. Jakékoliv jiné použití, včetně dalšího šíření, pořizování kopií apod. je výslovně zakázáno a bude považováno za porušení autorských práv.