Installeer de packages

Voor de installatie

In de volgende secties worden suggesties gedaan voor hoe je de gedownloade packages wellicht zou kunnen installeren om je DocBook SGML omgeving op te zetten. Het kan zijn dat de voorbeelden verwijzen naar oude versies van de packages, maar je zou ze in plaats daarvan zo aan moeten passen dat je de meest recente versies gebruikt.

Voor de meest bijgewerkte, authoratieve informatie moet je altijd de documentatie lezen die met een package dat je gaat installeren wordt meegeleverd. Vaak zul je een README en een INSTALL bestand aantreffen als je het archief hebt uitgepakt.

De gedetailleerde instructies hieronder werken wellicht niet exact zoals weergegeven, aangezien packages voortdurend aan wijzigingen onderhevig zijn. De instructies zouden je echter een algemeen idee kunnen geven van de procedure om DocBook SGML werkend te krijgen.

Installeer OpenJade

openjade

Hieronder staat wat je moet doen, maar denk eraan de bestanden te lezen die met Openjade werden meegeleverd om erachter te komen of er iets speciaals moet worden gedaan voor je platform:

cd /usr/local
tar -xvzf ~/openjade-1.3.tar.gz
cd openjade-1.3
./configure --prefix=/usr/local/openjade-1.3
make
make install

# Eenmaal geïnstalleerd, kunnen de objecten, enz worden
# verwijderd.
make clean

De installatie plaatst library's in /usr/local/openjade-1.3/lib, dus wellicht dat je ze graag toe wilt voegen aan /etc/ld.so.conf en ldconfig uit wilt voeren. Voeg /usr/local/openjade-1.3/bin toe aan je $PATH.

Wellicht dat je je afvraagt waarom ik de openjade source directory in /usr/local dump. De auteur ervaarde het een en ander bij de installatie van openjade. Bij nieuwere releases van OpenJade echter, zou je een standaard (/usr/local/src) lokatie voor het openjade source package kunnen proberen met een ander voorvoegsel als installatielokatie, en zien hoe dat gaat.

jadetex & pdfjadetex

Zoals vermeld zijn jadetex en pdfjadetex TeX macro's die met OpenJade worden verpakt. Ze zijn te vinden in /usr/local/openjade-3.1/dsssl. Een handige handleiding om deze macro's te installeren werd voorbereid door Frank Atanassow Christoph en het is te vinden op:

ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf

http://reaster.com/installjadetex.pdf

Het volgende is gebaseerd op de instructies in install.pdf:

Maak (zonodig) hugelatex aan

De texmacros jadetex en pdfjadetex vereisen meer geheugen dan een reguliere uitvoering van tex. De standaard geheugenlimietconfiguratie van tex is vaak te beperkt. Het tex configuratiebestand texmf.cnf kan worden gewijzigd en de variabelen die het geheugengebruik van tex beperken kan worden verhoogd. Maar in plaats van gewoon het bestand texmf.cnf te wijzigen waardoor tex onder alle omstandigheden meer geheugen heeft, kan een aangepaste tex context worden gecreërd, genaamd hugelatex. Als hugelatex reeds op je systeem is geconfigureerd, dan kun je deze subsectie overslaan (which hugelatex).

Verifieer dat een werkende TeX is geïnstalleerd en het zijn directory kan vinden:
bash$ which tex
/usr/share/texmf/bin/tex
bash$ kpsewhich -expand-var='$TEXMFMAIN'
/usr/share/texmf
bash$

Het gebruik van which zou de lokatie van het programma tex moeten lokaliseren. Als het niet wordt gevonden, dan moet je teTeX wellicht nog installeren en daarna hiernaar toe terugkeren. kpsewhich is een utility dat met teTeX wordt meegeleverd en dat de main tex directory weet te lokaliseren als alles goed gaat.

Nu de directory texmf bekend is, kan de installatie beginnen:

cd /usr/share/texmf
cd tex/latex
cp -r config config-temp
cd config-temp
tex -ini -progname=hugelatex latex.ini
mv latex.fmt hugelatex.fmt
mv hugelatex.fmt /usr/share/texmf/web2c
cd ..
rm -r config-temp
cd /usr/share/texmf/bin
ln -s tex hugelatex
cd /usr/share/texmf/web2c

De web2c directory bevat het configuratiebestand texmf.cnf. Maak een backup van dit bestand: cp texmf.cnf texmf.cnf.orig. Wijzig het bestand met een editor naar keuze en voeg de volgende regels aan het einde van het bestand toe:

% hugelatex settings
extra_mem_top.hugelatex = 8000000
extra_mem_bot.hugelatex = 8000000
hash_extra.hugelatex = 15000
pool_size.hugelatex = 5000000
string_vacancies.hugelatex = 45000
max_strings.hugelatex = 55000
pool_free.hugelatex = 47500
nest_size.hugelatex = 500
param_size.hugelatex = 1500
save_size.hugelatex = 5000
stack_size.hugelatex = 15000

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

% pdfjadetex
extra_mem_top.pdfjadetex = 8000000
extra_mem_bot.pdfjadetex = 8000000
hash_extra.pdfjadetex = 20000
pool_size.pdfjadetex = 5000000
string_vacancies.pdfjadetex = 45000
max_strings.pdfjadetex = 55000
pool_free.pdfjadetex = 47500
nest_size.pdfjadetex = 500
param_size.pdfjadetex = 1500
save_size.pdfjadetex = 5000
stack_size.pdfjadetex = 15000
Hier zijn we verder gegaan en hebben regels toegevoegd voor jadetex en pdfjadetex, die we hieronder zullen instellen. Je kunt wat spelen met deze geheugeninstellingen zoals je dat wilt als je problemen ondervindt.

Na het instellen van hugelatex, zoals hierboven, werkt het wellicht niet totdat het programma texhash is aangeroepen:
root# texhash
texhash: Updating /usr/share/texmf/ls-R...
texhash: Updating /var/cache/fonts/ls-R...
texhash: Done.
root#

jadetex & pdfjadetex

Het instellen van jadetex en pdfjadetex is vergelijkbaar met het instellen van hugelatex.
cd /usr/local/openjade-1.3/dsssl
make -f Makefile.jadetex install
# make creates and installs the .fmt
# files to /usr/share/texmf/web2c

# Maak nu symlinks aan ...
cd /usr/share/texmf/bin
ln -s tex jadetex
ln -s pdftex pdfjadetex

# Start als laatste texhash op.
root# texhash
Deze Makefile gebruikt hugelatex, dus hugelatex moest reeds zijn ingesteld. Wanneer tex als hugelatex, jadetex, of pdfjadetex wordt uitgevoerd, krijgt het zijn programmanaam (context) van argv[0] in de omgeving. Dan scant het texmf.cnf, en gebruikt het alle context specifieke instellingen die het aantreft. De formaat (.fmt) bestanden in /usr/share/texmf/web2c worden ook gebaseerd op de context geladen.

De opdracht jadetex accepteert een tex bestand gegenereerd door openjade, en geeft als uitvoer een dvi. pdfjadetex accepteert een tex bestand gegenereerd door openjade en geeft als uitvoer een pdf bestand. Het programma dvips accepteert het dvi bestand en geeft als uitvoer een PostScript ps bestand welke je naar je printer kunt sturen of met ghostscript gs kunt bekijken.

DocBook SGML DTD

Pak de DocBook SGML DTD uit

De DocBook DTD bestaat gewoon uit een aantal sgml tekstbestanden, dus valt er niets te compileren. Pak ze gewoon ergens uit.
# DocBook DTD V4.1 in
# /usr/local/share/sgml/docbook/4.1

cd /usr/local/share
mkdir sgml; cd sgml
mkdir docbook; cd docbook
mkdir 4.1; cd 4.1
unzip -a ~/docbk41.zip
Als je doctools-1.2 uit de XFree86 distributie installeert, zullen er een aantal oudere versies van de DocBook DTD, zoals 2.4.1/ en 3.0/ in subdirectory's van docbook worden geïnstalleerd.

Er bestaan een aantal verschillen tussen de verschillende versies van de DocBook DTD. In de xxissues.txt bestanden worden die zaken gedocumenteerd. Tags die zijn toegevoegd, verwijderd en hernoemd tussen de versies.

Als je de DocBook DTD V3.1 nodig hebt, dan kun je het vanaf dezelfde plaats downloaden als waar V4.1 kan worden gedownload. V3.1 wordt veel gebruikt, dus het is een goed idee het op te halen en het te installeren in een 3.1/ subdirectory.

Pak de ISO8879 Entiteiten uit

Ga voor elk uitgepakte DocBook DTD naar die betreffende directory en pak het bestand iso8879-entities.tar.gz uit:
cd /usr/local/share/sgml/docbook/4.1
tar -xvzf ~/iso8879-entities.tar.gz
In elke DocBook directory zou een docbook.cat of catalog bestand of beiden voor moeten komen. Als beiden aanwezig zijn, dan zijn ze naar alle waarschijnlijkheid identiek. Als alleen docbook.cat aanwezig is, ga dan je gang en maak een symlink:
# Zonodig ...
cd /usr/local/share/sgml/docbook/4.1
ln -s docbook.cat catalog

DocBook DSSSL

De installatie van de DocBook DSSSL, welke voor alle versies van DocBook is, is slechts een kwestie van het ergens uitpakken.
cd /usr/local/share/sgml
mkdir dsssl; cd dsssl
unzip -a ~/db160.zip

# Als je de ldp.dsl stylesheet aanpassing downloadde, kopieer het dan naar
cd docbook
cp ~/ldp.dsl html
cp ~/ldp.dsl print
# Kopieer het naar beide directory's.
Dat is alles betreft het installeren van de DSSSL, behalve dan de setup van de variabele $SGML_CATALOG_PATH welke later wordt besproken. Vergeet niet de bestandsmodi en eigenaar/groep van deze uitgepakte bestanden recht te zetten, vaak zijn ze onjuist.

SGMLtools-Lite

Als je dat wilt, kun je de SGMLtools-Lite installeren, maar het is optioneel. De installatie ervan is de standaard:
cd /usr/src
tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
cd sgmltools-lite-3.0.2
./configure
make install
Hiermee wordt het sgmltools python script naar /usr/local/bin geïnstalleerd. Het maakt gebruik van python, dus als je het niet hebt, is dit package onbruikbaar.

Een aanpassing die moet worden uitgevoerd om het sgmltools script werkend te krijgen is het wijzigen ervan en het instellen van het pad naar openjade: vi `which sgmltools`. Raadpleeg de docs om er meer over te leren.

htmldoc

binary

Bijvoorkeur downloadde je een binaire distributie voor je platform van htmldoc. De installatie is eenvoudig: pak het gewoon uit en voer de setup uit. Lees de docs in het package voor meer info.

source

Als je de broncode downloadde, zul je ook de Fast Light Tool Kit nodig hebben, anders zal het niet linken:

http://www.fltk.org/

Installatie volgens de autoconf stijl. Start gewoon het script configure en make, make install. Als alles goed gaat, zal het worden geïnstalleerd in /usr/bin.

ldp_print

Het programma htmldoc heeft (of had) een paar tekortkomingen bij het genereren van uitvoer van html bestanden vanuit openjade. Opsommingsitems werden bijvoorbeeld niet juist weergegeven en geschaduwde gebieden waren niet altijd voorzien van schaduw.

Ter correctie van dit probleem is een perl script (ldp_print) beschikbaar vanaf LinuxDoc.org. Het script lpd_print verwerkt een nochunks html bestand van openjade en past er dan htmldoc op toe om een correct weergegeven pdf en ps te genereren.

Tip

Haal het op!

tar -xvzf ldp_print.tar.gz
cd ldp_print

# Kopieer de lib naar een lokatie waar perl het kan vinden.
cp fix_print_html.lib /usr/lib/perl5/site_perl

cp ldp_print /usr/local/bin
Bekijk het script voor het geval er regels instaan die je conform je systeem moet wijzigen. Misschien dat op een dag de programmeerfouten van htmldoc zijn opgelost en dat je dit script niet meer nodig zult hebben.

DocBook2X en SGMLS.pm (sgmlspl)

sgmlspl

Voor de spec files van DocBook2X van enig nut zijn, moet de SGMLS.pm module voor perl versie 5 zijn geïnstalleerd, in de veronderstelling dat perl 5 reeds is geïnstalleerd. De installatie van deze module is niet zo geautomatiseerd als de meeste installaties van perl modules. Het maakt gebruik van een Makefile dat moet worden gewijzigd voordat make wordt uitgevoerd.
cd /usr/src
tar -xvzf ~/SGMLSpm-1.03ii.tar.gz
cd SGMLSpm

# Wijzig Makfile
vi Makefile
# Stel in de user options van de Makefile
# alles correct in overeenkomstig je systeem.
# Voorbeeld:
#PERL = /usr/bin/perl
#BINDIR = /usr/local/bin
#PERL5DIR = /usr/lib/perl5/site_perl
#MODULEDIR = ${PERL5DIR}/SGMLS
#SPECDIR = ${PERL5DIR}
#HTMLDIR= /usr/local/apache/htdocs

make install
sgmlspl wordt gekopieerd naar /usr/local/bin.

docbook2X (docbook2man-spec.pl)

DocBook2X bevat geen programma voor het compileren of de installatie, alhoewel er een paar scripts zijn die je wellicht wilt bekijken. Je hoeft het dus alleen ergens uit te pakken.
cd /usr/local/share/sgml
tar -xvzf ~/docbook2X-0.6.0.tar.gz
cd docbook2X
In de directory met uitgepakte bestanden bevindt zich een docbook2man-spec.pl bestand en een patch file dat een aantal dingen corrigeert. Het toepassen van de patch is optioneel maar aan te bevelen.
patch docbook2man-spec.pl docbook2man-spec.pl.patch
Later, in Het gebruik van DocBook, zul je zien hoe sgmlspl en docbook2man-spec.pl kunnen worden toegepast om een man page vanuit een <refentry> DocBook document te genereren.

$SGML_CATALOG_FILES

De omgevingsvariabele $SGML_CATALOG_FILES wordt gebruikt door openjade (en andere SGML software) om DTD's en DSL (stylesheets) te lokaliseren. SGML software kan niet functioneren zonder deze bestanden, welke zijn uitgepakt in diverse directory's. Gegeven de setup tot dusverre wordt hier aangegeven hoe $SGML_CATALOG_FILES kan worden ingesteld in /etc/profile:
##########################################################################################
# SGML DocBook - openjade sgmltools-lite
JADE_HOME=/usr/local/openjade-1.3
SGML_SHARE=/usr/local/share/sgml

PATH=$PATH:$JADE_HOME/bin

# DSSSL stylesheets
#       Norman Walsh's Modular DocBook Stylesheets
SGML_CATALOG_FILES=$SGML_SHARE/dsssl/docbook/catalog
#       OpenJade stylesheets
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADE_HOME/dsssl/catalog
#       sgmltools-lite's stylesheets
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/stylesheets/sgmltools/sgmltools.cat

# DocBook DTD
#       Van OASIS-Open.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/4.1/catalog
#       Deze oude DTD's werden geïnstalleerd via doctools-1.2 van 
#       XFree86.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/2.4.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.0/catalog

# sgmltools-lite catalog bestanden voor LinuxDoc
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/dtd/sgmltools/catalog

export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES
##########################################################################################
Sla het bestand profile op, logout en log dan weer in om de wijzigingen te activeren.

Installatie compleet! In de volgende sectie, zullen we de installatie testen en een aantal DocBook testbestanden converteren.