3.2. "Alle" de grimme detaljer

3.2.1. Stikordsregister

At få lavet et stikordsregister er ikke så integreret i Docbook som man kunne ønske sig, men modsat så kan det nemt indføres, når bare man har en vejledning. Det første er at man skal hente et Perl-program, collateindex.pl, som f.eks. kan findes fra http://www.sslug.dk/linuxbog/misc/collateindex.pl. Filen skal gøres eksekverbar og f.eks. placeres i /usr/local/bin.

3.2.1.1. Markere til stikordsregisteret - indexterm

Før man får en stikordsliste skal man igennem hele ens dokument og markere de steder, man ønsker et link til. Det er manuelt arbejde. Hvert sted man ønsker et link til skal man tilføje

<indexterm><primary>Søgeord</primary></indexterm>

I stikordsregisteret vil man så kunne se at "Søgeord" kan man læse om det pågælende afsnit. Man kan godt lave henvisning til flere forskellige steder med samme søgeord. Indføj blot flere linier som den ovenstående og man får et tilsvarende antal referencer i stikordsregisteret.

Samme markeringsteknik kan laves med underinddelinger, så man under "Søgeord" kan have f.eks. "At lave søgeord" og et andet sted "At finde søgeord". For at lave det første eksempel skrives følgende, og det kan bemærkes, at liniedelingen og indrykningen nedenfor alene tjener til at gøre SGML-koden nemmere at læse.

<indexterm>
 <primary>Søgeord</primary>
 <secondary>At lave søgeord</secondary>
</indexterm>

3.2.1.2. Generere indholdsfortegnelsen - collateindex.pl

Når man har sat alle sine stikordshenvisninger ind i dokumentet kommer turen til at at få genereret dokumentet med collateindex.pl. Tricket er at man skal oversætte sit dokument en gang før man kører db2html (eller hvad man nu har som mål-format).

Jeg plejer typisk at have en Makefile, hvor jeg oversætter min hoved SGML-fil bog.sgml på følgende måde. Jeg har kommenteret Makefilen med kommentarer før kommandoen

# Slet mit midlertidige katalog "tempdir" og "stikord.sgml"
    rm -rf tempdir stikord.sgml
# Skab et  midlertidige katalog "tempdir"
    mkdir tempdir
# Initialiser "stikord.sgml" til at være tom
    perl /usr/local/bin/collateindex.pl \
        -s Symboler  -t Stikordsregister -g \
        -i stikord -N -o stikord.sgml
# Kopier alle SGML filer til "tempdir"
    cp *.sgml tempdir
# Gå ned i "tempdir" og oversæt SGML-filerne hvor HTML.index dannes
    (cd tempdir; jade -t sgml -ihtml \
        -d /usr/lib/sgml/stylesheets/cygnus-both.dsl\#html \
        -V html-index bog.sgml)
# Kør nu "collateindex.pl" som oversætter "HTML.index" til indholdet
# af SGML-filen "stikord.sgml". -s er at symboler optræder under
# navnet "symboler". -t angiver overskrift for "stikord.sgml"
    perl /usr/local/bin/collateindex.pl -s Symboler \
        -t Stikordsregister  -g -i stikord \
        -o stikord.sgml tempdir/HTML.index
# Nu er "stikord.sgml" fuld af referencer som kan oversættes
    db2html bog.sgml
# Kopier alle PNG-filer fra "images/" til "bog/"
    cp images/*.png bog

Skal du tilsvarende oversætte til PDF kan du have en del af en Makefile med et lidt andet indhold. Ideen er den samme, men jade, som anvendes til at lave stikordsregisteret får "print" overført ikke "html". Dette gør, at man få sidenumre og ikke afsnitsnavne i stikordsregisteret. Bemærk også at -V nochunks gør at filen oversættes til en stor fil (svarende til den endelige PDF-fil).

# Slet "stikord.sgml" min midlertidige kataloger 
#  "tempdir" og "bogpdf"
    rm -rf tempdir stikord.sgml bogpdf
# Skab et  midlertidige katalog "tempdir"
    mkdir tempdir
# Initialiser "stikord.sgml" til at være tom
    perl /usr/local/bin/collateindex.pl \
        -s Symboler  -t Stikordsregister -g \
        -i stikord -N -o stikord.sgml
# Kopier alle SGML filer til "tempdir"
    cp *.sgml tempdir
# Gå ned i "tempdir" og oversæt SGML-filerne hvor HTML.index dannes
    (cd tempdir; jade -t sgml -ihtml \
        -d /usr/lib/sgml/stylesheets/cygnus-both.dsl\#print 
        -V html-index -V nochunks bog.sgml > slet_fil.html)
# Kør nu "collateindex.pl" som oversætter "HTML.index" til indholdet
# af SGML-filen "stikord.sgml". -s er at symboler optræder under
# navnet "symboler". -t angiver overskrift for "stikord.sgml"
    perl /usr/local/bin/collateindex.pl -s Symboler \
        -t Stikordsregister  -g -i stikord \
        -o stikord.sgml tempdir/HTML.index
# Nu er "stikord.sgml" fuld af referencer som kan oversættes
    mkdir bogpdf
# Kopier alle SGML-filer til "bogpdf/"
    cp *.sgml bogpdf
# Kopier alle PNG-filer fra "images/" til "bog/"
    cp images/*.png bogpdf
# Kør "db2pdf" i "bogpdf/" 
    (cd bogpdf; db2pdf bog.sgml)
# Flytter PDF-filen til nuværende katalog
    mv bogpdf/bog.pdf .

3.2.1.3. Postscript er et problem

Som vist i forrige afsnit kopieres PNG-filer blot til det katalog hvor man oversætter. Skal man oversætte Docbook dokumentet til Postscript opstår dog problemet; Man kan ikke oversætte dokumentet med PNG-billeder, men godt med EPS-billeder. Det problem kan også løses, men det er bøvlet og kræver at alle billeder oversættes til EPS, f.eks. ved at bruge convertfra ImageMagick-programmet.

3.2.2. Ændring af opsætning

Er du utilfreds med hvordan marginer i PDF-filen er eller hvordan dine HTML style-filer anvendes, så har Docbook et hav af muligheder for at skrue på format.

I /usr/lib/sgml ligger alle de opsætningsfiler Docbook bruger. Oftest vil man ændre i ganske få filer, såsom /usr/lib/sgml/stylesheets/nwalsh-modular/common/dbl1da.ent. I denne fil står alle de oversættelser man har til dansk for referencer og afsnit. Mener du at en "Section" (på engelsk) hedder "Sektion" og ikke "Afsnit" så kan du ændre linien

<!ENTITY Section        "Afsnit"> 

til

<!ENTITY Section        "Sektion"> 

Tilsvarende finder du mange opsætningsparametre fælles for HTML og PDF/Postscript i /usr/lib/sgml/stylesheets/nwalsh-modular/common/dbcommon.dsl. Filen er skrevet i LISP (ligesom Emacs opsætningsfiler) og har mange kommentarer. Oftest er det ikke denne fil man vil ændre i.

For HTML-generering vil du nok ændre i /usr/lib/sgml/stylesheets/nwalsh-modular/html/dbparam.dsl. Du vil se at filen har mange kommentarer og vil du ændre en parameter fra sand til falsk er det #t som ændres til #f.

For PDF og Postscript-generering (kaldes "print" i Docbook) vil du nok ændre i /usr/lib/sgml/stylesheets/nwalsh-modular/print/dbparam.dsl. En ting du nok skal se på er "%paper-type%" som sættes til

(define %paper-type%
  ;; REFENTRY paper-type
  ;; PURP Name of paper type
  ;; DESC
  ;; The paper type value identifies the sort of paper in use, for example,
  ;; 'A4' or 'USletter'. Setting the paper type is an
  ;; easy shortcut for setting the correct paper height and width.
  ;;
  ;; As distributed, only 'A4' and 'USletter' are supported.  You can add
  ;; additional paper types by updating 'page-width' and 'page-height'.
  ;; If you do, please pass along your updates.
  ;; /DESC
  ;; AUTHOR N/A
  ;; /REFENTRY
  ;; "USletter"
  "A4")                 

Tilsvarende kan man lede efter margin og finde de marginer, som anvendes i PDF-dokumentet.