DocBook - stručný popis instalace

1. Instalace Jade

   Jade je programový balík, který slouží k převodu dokumentů ve formátu SGML do jiných formátů, např. HTML, RTF, PostScript, apod.

   Základní instalace spočívá v kompilaci zdrojových textů z distribučního balíku a umístění dvou klíčových nástrojů nsgmls a jade do vhodného adresáře, aby se daly snadno spouštět. Já jsem nechal vše nainstalovat do defaultního instalačního adresáře /opt/local/bin/ a v adresáři /usr/bin/ jsem vytvořil 2 symbolické linky nsgmls -> /opt/local/bin/nsgmls a jade -> /opt/local/bin/jade.

   Dále jsem vytvořil nový adresář /usr/local/sgml/jade/, do kterého jsem nakopíroval všechny soubory z podadresáře dsssl/ z distribučního balíku Jade.

   Je možno též instalovat jade z rpm, které je např. v distribuci Redhat.

2. Instalace DocBook DTD

   DocBook DTD definuje SGML tagy pro vytváření dokumentů ve formátu DocBook.

   Já jsem použil poslední verzi 4.1, vytvořil jsem nový adresář /usr/local/sgml/dtd/, a do něj jsem nakopíroval všechny soubory z distribučního balíku.

   Dále byly potřeba jakési entities. Opět jsem vše z tohoto distribučního balíku nakopíroval do adresáře /usr/local/sgml/dtd/ s tím, že jsem všechny soubory přejmenoval podle vzoru ISO* -> iso-*.gml.

   Na přejmenování je možno použít např. skript for i in ISO*; do mv $i $(echo $i | sed s/ISO/iso-/ ).gml; done

3. Instalace DSSSL

   DSSSL je datový balík, který definuje, jakým způsobem se bude převádět dokument ve formátu SGML do daného výstupního formátu.

   Vlastní datový balík má 2 části: db156.zip, což jsou vlastní převodní pravidla a db156d.zip, kde je dokumentace. Já jsem si vytvořil nový adresář /usr/local/sgml/dsssl/ a do něj jsem nakopíroval všechny soubory z obou částí.

4. Nastavení SGML_CATALOG_FILES

   Proměnnou prostředí SGML_CATALOG_FILES používají nástroje z balíku Jade pro nalezení potřebných datových souborů.

   Já jsem ji nastavil příkazem export SGML_CATALOG_FILES=/usr/local/sgml/dtd/docbook.cat:/usr/local/sgml/dsssl/catalog:/usr/local/sgml/jade/catalog.

   V případě že instalujete jade z rpm, nastavte proměnnou takto: export SGML_CATALOG_FILES=/usr/local/sgml/dtd/docbook.cat:/usr/local/sgml/dsssl/catalog:/usr/doc/jade-1.2.1/dsssl/catalog

5. Počeštění instalace

   • Budeme předpokládat použití standardního kódování ISO-8859-2.

   • V úvodním tagu SGML dokumentu je potřeba uvést atribut lang="cs".

     Příklad:	<book lang="cs">
     	...
     	</book>

   • Aby se do výsledného HTML dokumentu generoval do hlavičky správný META tag o použitém kódování, je potřeba modifikovat soubor /usr/local/sgml/dsssl/html/dbparam.dsl. Konkrétně se jedná o funkci html-header-tags, jejíž poslední řádek je potřeba modifikovat na:

     '(("META" ("HTTP-EQUIV" "CONTENT-TYPE") ("CONTENT" "text/html; charset=ISO-8859-2"))))

6. Další možné modifikace konfigurace

   • Pokud chceme ve výsledném dokumentu číslovat i podkapitoly je potřeba v souboru /usr/local/sgml/dsssl/html/dbparam.dsl modifikovat funkci section-autolabel, konkrétně její poslední řádek na:

     #t)

7. Závěrečný test instalace

   Kontrola syntaxe SGML dokumentu

   nsgmls -s cgml.sgml

   Mělo by proběhnout bez chyb. U mě to vypisuje 1 warning ohledně DTDDECL. Podle dokumentace není tato položka ve verzi 1.2.1 (nejnovější dosažitelná verze) balíku Jade podporována.

   Warning týkající se DTDDECL je možné potlačit modifikací souboru /usr/local/sgml/dtd/docbook.cat. V tomto souboru je potřeba zakomentovat řádek s definicí DTDDECL následovně:

   -- DTDDECL "-//OASIS//DTD DocBook V4.1//EN" "docbook.dcl" --

   Převod SGML dokumentu do formátu HTML

   jade -b iso-8859-2 -t sgml -i html -d /usr/local/sgml/dsssl/html/docbook.dsl cgml.sgml

   Mělo by proběhnout bez chyb. Výsledkem je několik HTML souborů s příponou htm. Vlastní dokument pak začíná souborem cgml.htm, ze kterého vedou odkazy do ostatních vytvořených htm souborů.

   Převod SGML dokumentu do formátu TeX

   jade -t tex -d /usr/local/sgml/dsssl/print/docbook.dsl cgml.sgml

   Mělo by proběhnout bez chyb. Výsledkem je soubor cgml.tex ve formátu TeX.

   Do tisknutelné podoby je nutný JadeTeX (nadstavba nad LaTeX). Instalace je poněkud složitější, neboť je nutno zvětšit implicitní limity TeXu. Je to dobře popsáno v instal.pdf v zdrojové distribuci. Pokusím se o zkrácený popis při instalci z rpm.

   1. Nainstalivat jadetex*.rpm
   2. Stáhnout z CTANu passivetex a nakopírovat ho do /usr/share/texfm/tex/latex/passivetex Spustit texhash aby ho TeX našel.
   3. Zvětšit limity v /usr/share/texfm/web2c/texmf.cnf

      extra_mem_top.latex = 400000 
      extra_mem_bot.latex = 400000 
      hash_extra.latex = 15000 
      pool_size.latex = 5000000
      string_vacancies.latex = 45000 
      max_strings.latex = 55000
      pool_free.latex = 47500 
      nest_size.latex = 500 
      param_size.latex = 1500 
      save_size.latex = 5000 
      stack_size.latex = 15000 
      % jadetex &  pdfjadetex 
      hash_extra.jadetex = 20000
      hash_extra.pdfjadetex = 20000
      pool_size.jadetex = 300000
      pool_size.pdfjadetex = 300000
            

   4. Nakonec již by mělo fungovat jadetex file.tex nebo pdftex file.tex pro převod do tisknutelné podoby.