E-learning a DocBook

XInclude [6] je standard pro vkládání textu do XML souborů, nabízí mnohem elegantnější a silnější prostředek než je vkládání pomocí entit:

<!ENTITY intro "intro.xml"/>

Při vkládání dokumentů jako entity jsme nemohli uvádět DOCTYPE a XML soubory nebyly tak plnohodnotné a nešly validovat. S XInclude tento problém odpadá. Navíc můžeme pomocí Xpointer odkazu stanovit, kterou část dokumentu vložit, vybrat si zdali dokument vložit jako text nebo jako XML kód a ošetřovat případy, kdy se vložení nepodařilo.

Elementy použité pro XInclude patří do vlastního jmenného prostotu, který musí být všude v dokumentu stejný.

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

Dokument nemusíme vkládat celý, ale třeba jen danou kapitolu, nejednodušší způsob je použít ID dané kapitoly.

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

Mnohem více lze docílit, pokud použijeme Xpointer ukazatel na požadovanou část dokumentu, pomocí Xpath syntaxe.

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
   href="intro.xml#xpointer(/sect1/section[1]/*)"/>

XInclude můžeme použít i ke vkládání prostého textu. Atribut parse="text" sdělí procesoru, aby daný obsah namísto XML zobrazil jako prostý text. Tím jsou speciální XML znaky převedeny na odpovídající entity:

& na &
< na &lt;
> na &gt;
" na &quot;

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

Při vkládání prostého textu můžeme využít rozšířené interpretace URL vkládaného souboru. V URL textového souboru nemají standardně znaky za # žádný speciální význam např. code.c#1 je běžně interpretováno stejně jako code.c. Prostor za # proto využijeme ke specifikaci, které řádky ze vstupního souboru vložit, např.:

Toto rozšíření samozřejmě nefunguje automaticky v každém XInclude procesoru. V Javě je možno použít místo nástroje xincluder.jar [7] jeho vylepšenou verzi xincluder-fi.jar vyvinutou na pracovišti autorů tohoto článku.

Pokud vložení neproběhne správně, ať už z důvodu, že daný soubor neexistuje nebo jej nelze stáhnout, lze namísto prázdného xi:include elementu vložit na dané místo vlastní chybové hlášení.

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml">
  <xi:fallback>
    <para><emphasis>CHYBA: XINCLUDE</emphasis></para>
  </xi:fallback>
</xi:include>

Ve skutečnosti může xi:fallback obsahovat další xi:include element, který se procesor pokusí vyhodnotit v případě neúspěchu. Nesmíme však zapomenout, že pokud uvedeme xi:fallback, tak se transformace dokumentu v případě chyby nezastaví. Pokud je nezbytné, aby vložení souboru proběhlo, je lepší xi:fallback element nepoužívat a nechat proces skončit s chybou.

Jednou z hlavních výhod XInclude je, že můžeme jednotlivé soubory zvlášť validovat. Avšak xi:include element není validní element DocBooku a tím pádem nepůjde hlavní dokument zvalidovat. Jsou dva způsoby jak tento problém vyřešit. 1) Nejprve celý dokument sestavíme a poté provedeme validaci.

Pokud chceme použít XInclude pod Javou je potřeba si opatřit XInclude nástroj [7].

2) Upravíme DTD DocBooku tak, aby obsahovalo patřičné xi:include elementy.