| Linux - Friheden til at skrive dokumentation: Version 2.7.20040524 - 2020-12-31 | ||
|---|---|---|
| forrige | Kapitel 2. DocBook | næste |
Du kan oversætte SGML filerne til HTML, PDF, Postscript og RTF. Der er også mulighed for at vælge at oversætte SGML til én HTML-fil og ikke til mange, opdelt for hver <sect1>. Skal din HTML-fil hentes lokalt på læserens harddisk, kan dette være en fordel, men skal den sendes via nettet, bliver det for langsommeligt.
Du oversætter din hoved SGML fil (f.eks. bog.sgml) til HTML ved at skrive docbook2html bog.sgml. Dine HTML filer gemmes i bog under dit nuværende katalog, fordi SGML-filen hedder bog.sgml.
Du skal selv sørge for at kopiere dine billed-filer (f.eks. PNG) til kataloget bog. Typisk kan dette gøres med en Makefile.
Tilsvarende kan man oversætte bog.sgml til PDF ved at skrive docbook2pdf bog.sgml. Igen skal alle billed-filer (typisk PNG) være placeret der hvor SGML-filerne oversættes. Jeg kopierer normalt alle de filer til et midlertidigt katalog og oversætter der.
Skal man oversætte til Postscript hedder kommandoen docbook2ps og RTF laves med docbook2rtf.
Har du lavet fejl i din SGML-tekst, så er den oversætter man har i docbook2html faktisk til stor hjælp. Vi skal se på et par eksempler.
Eksempel 2-16. Manglende /para
Lad os prøve at oversætte følgende tekst
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
]>
<book id="index" lang="da">
<bookinfo>
<title>Min første Docbook-bog</title>
</bookinfo>
<chapter id="forord">
<title>Mit første kapitel</title>
<para>
Vil du skrive i Docbook ?
</para>
<para>
Ja - men jeg kan ikke huske at slutte mine para-blokke.
</chapter>
</book>
Filen eks1.sgml oversættes nu
[root@MinMaskine /root]# docbook2html eks1.sgml TMPDIR is DBTOHTML_OUTPUT_DIR3088 input file was called eks1.sgml -- output will be in eks1 working on ../eks1.sgml jade:../eks1.sgml:24:9:E: end tag for "PARA" omitted, but OMITTAG NO was specified jade:../eks1.sgml:19:0: start tag was here about to copy cascading stylesheet and admon graphics to temp dir about to rename temporary directory to eks1
For det første laves et temporært katalog DBTOHTML_OUTPUT_DIR3088, og resultatet vil ende i eks1/ idet filen hedder eks1.sgml. Man får to ret klare fejlbeskeder. I linje 24 (næstsidste linje) må der ikke komme en </chapter>, når der bør komme en slut PARA, dvs. </para>. Den følgende linje fortæller dernæst at i linje 19 var den <para>, som ikke kunne matches.
Tilføj en </para> før næstsidste linje og teksten oversætter fejlfrit.
Eksempel 2-17. To ens ID
Lad os prøve at oversætte følgende tekst
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
]>
<book id="index" lang="da">
<bookinfo>
<title>Eksempel</title>
</bookinfo>
<toc id="toc"></toc>
<chapter id="id1">
<title>Mit første kapitel</title>
<para>
Vil du skrive i Docbook ?
</para>
<sect1 id="id1">
<title>Mit første underkapitel</title>
<para>
tekst1
</para>
</sect1>
</chapter>
</book>
Filen eks2.sgml oversættes nu
[root@MinMaskine /root]# docbook2html eks2.sgml TMPDIR is DBTOHTML_OUTPUT_DIR3110 input file was called eks2.sgml -- output will be in eks2 working on ../eks2.sgml jade:../eks2.sgml:19:11:E: ID "ID1" already defined jade:../eks2.sgml:12:13: ID "ID1" first defined here about to copy cascading stylesheet and admon graphics to temp dir about to rename temporary directory to eks2
Her ses at ID1 er erklæret to gange - og der oplyses hvilke steder det sker. Omdefiner den ene og oversæt igen.
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 man skal gøre er at hente et Perl-program, collateindex.pl, som f.eks. kan hentes fra www.linuxbog.dk/misc/collateindex.pl. Filen skal gøres kørbar og f.eks. placeres i /usr/local/bin.
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 linjer 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 linjedelingen 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>
Når man har sat alle sine stikordshenvisninger ind i dokumentet kommer turen til at få genereret dokumentet med collateindex.pl. Tricket er at man skal oversætte sit dokument en gang før man kører docbook2html (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
docbook2html 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 "docbook2pdf" i "bogpdf/"
(cd bogpdf; docbook2pdf bog.sgml)
# Flytter PDF-filen til nuværende katalog
mv bogpdf/bog.pdf .
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.
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 linjen
<!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.
I forhold til standardopsætningen kan det være interessant at kigge på:
(define %section-autolabel%
Sættes den til #t bliver afsnit ("sections") automatisk nummereret. Første afsnit ("sect1") i kapitel 7 vil så få nummer 7.1.
Hvis man vil undgå at få en indholdsfortegnelse over tabeller og figurer nedenunder den almindelige indholdsfortegnelse, skal $generate-book-lot-list$ sættes til
(define ($generate-book-lot-list$) ;; REFENTRY generate-book-lot-list ;; PURP Which Lists of Titles should be produced for Books? ;; DESC ;; This parameter should be a list (possibly empty) of the elements ;; for which Lists of Titles should be produced for each 'Book'. ;; ;; It is meaningless to put elements that do not have titles in this ;; list. If elements with optional titles are placed in this list, only ;; the instances of those elements that do have titles will appear in ;; the LOT. ;; ;; /DESC ;; AUTHOR N/A ;; /REFENTRY (list ))
Hvis du ønsker at styre udseendet af bogen (i HTML-udgaven), kan det gøres ved at vælge at bruge et eksternt Cascading Style Sheet. Filnavnet på dette angives i
(define %stylesheet% ;; REFENTRY stylesheet ;; PURP Name of the stylesheet to use ;; DESC ;; The name of the stylesheet to place in the HTML LINK TAG, or '#f' to ;; suppress the stylesheet LINK. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY "../style/style.css")
Du skal selvfølgelig sørge for, at der er et stylesheet på den angivne placering...
For PDF og Postscript-generering (kaldes "print" i Docbook) vil du nok ændre i /usr/share/sgml/docbook/dsssl-stylesheets/print/dbparam.dsl (Red Hat 6.2 /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")
Vil du have to kolonner tekst i PS og PDF-udskrift rettes tilsvarende
(define %page-n-columns% ;; REFENTRY page-n-columns ;; PURP Sets the number of columns on each page ;; DESC ;; Sets the number of columns on each page ;; /DESC ;; AUTHOR N/A ;; /REFENTRY 1)
til
(define %page-n-columns% ;; REFENTRY page-n-columns ;; PURP Sets the number of columns on each page ;; DESC ;; Sets the number of columns on each page ;; /DESC ;; AUTHOR N/A ;; /REFENTRY 2)
Tilsvarende kan man lede efter margin og finde de marginer, som anvendes i PDF-dokumentet, ligesom "%section-autolabel%" og "$generate-book-lot-list$" kan ændres på samme vis som i /usr/share/sgml/docbook/dsssl-stylesheets/html/dbparam.dsl.