| Linux - Friheden til at skrive dokumentation: Version 2.7.20040524 - 2020-12-31 | ||
|---|---|---|
| forrige | Kapitel 2. DocBook | næste |
Her er en kort beskrivelse af de dele, som indgår i docbook systemet.
Et dokument system består af tre dele:
En specifikation af formatet, altså en syntax og/eller dokumentation af de elementer, man bruger, og hvad meningen er med dem.
Filer med formateringskommandoer, som omformer det abstrakte dokument til et output, som kan printes eller på anden måde publiceres.
Et program (eller flere programmer), som læser og udfører formateringskommandoerne.
En print-mekanisme, som kan omforme fra et almindeligt printerformat til det, som printeren nu måtte forlange.
Det var jo 4 ting!? Jo, men den sidste del er jo oftest en generel mekanisme, som for eksempel Linux/GNU print systemet, der kan tage en postscript fil og konvertere den til de fleste af de printerformater, som man kan købe i dag.
DocBook systemet er sammensat af mange elementer. De kommer forskellige steder fra, og programmørerne (eller forfatterne) har ikke ønsket at sætte dem sammen i én pakke.
Her er en liste over alle de ting, som skal fungere sammen for at DocBook kildetekster kan "oversættes" til html, pdf eller postscript filer.
Openjade, programmet, som foretager konverteringer af sgml dokumenter til andre formater. jade læser en document type definition (DTD) og agerer efter denne instruktion på dokument "source".
DocBook SGML - DTD. Det er de filer, som beskriver reglerne for de elementer, som OpenJade skal acceptere, altså regler eller syntax for, hvornår man skal bruge for eksempel <para>.
ISO entity filer. De definerer de tegn, som bruges i output fra openjade. Der er mange typer tegn, græske bogstaver, matematiske tegn, specielle valutasymboler etc. Det er faktisk filer fra International Standards Organization (ISO).
DocBook DSSSL, Document Style Semantics and Specification Language (DSSSL) filer med endelsen .dsl specificerer hvordan OpenJade skal konvertere til html, rtf, tex med videre. DSSSL er en ISO standard.
Docbook-utils. Nogle konverteringer foregår i flere trin. Disse tools er blot scripts, som samler flere kommandoer til én kommando.
collateindex.pl, et perl-script, som kan generere index.sgml til pdfjadetex - systemet.
TeX, for eksempel tetex implementationen, som følger med Red Hat og de fleste andre Linux/GNU distributioner. Man skal også have hyperref og latex, for at det hele spiller sammen, men dem har distributøren pakket sammen med tetex.
jadetex og pdfjadetex, formaterings-specifikationer til TeX, som gør det muligt at konvertere det output, som jade laver, til postscript filer og pdf filer.
HTMLdoc, er en af måderne til generering af bookmarks eller index til PDF filer.
SGMLSpm and docbook2X, for konvertering til man-page format.
Her er korte forklaringer af pakkerne, som vi skal arbejde med:
Openjade: OpenJade er et program, som behandler "Standard Generalized Markup Language" (SGML) og "Document Style Semantics and Specification Language" (DSSSL). Den transformerer DocBook sgml kildefiler til html, tex, rtf, txt og andet. OpenJade er den essentielle maskine til konvertering af en DocBook fil til andre formater. TeX output formatet bruges mest som et mellemformat for at opnå dvi, pdf og postscript filer via TeX macro'er og dvi konverterings programmer.
DocBook SGML DTD, dokument-type-definitionen for den eller de docbook - versioner, som du ønsker at benytte. Der er ikke den store forskel mellem for eksempel version 4.0 og version 4.1. Ved at rette i dokument-type-versions-specifikationen øverst i kildeteksten kan man skifte fra den ene til den anden version, og ofte vil oversættelse, d.v.s. generering af html og/eller pdf-filer, stadig kunne foretages uden at der opstår fejl.
DTD filerne for en DocBook version ligger i et directory, som på Red Hat er /usr/share/sgml/docbook/<dir-navn> Disse filer definerer sammen med entity filerne et sæt regler som anvendes af OpenJade, når den læser kildeteksten af en sgml-pakke.
OpenJade skal have tilgang til et katalog for hver type dokument, som man forventer, at den skal kunne oversætte. Strengt taget kan man specificere dcl-filer, d.v.s. docbook-erklæringer, på kommandolinjen, men det er altså ikke praktisk, så derfor har man catalog-mekanismen.
ISO8879 ENTITY SGML. Entiteter definerer repræsentation af specielle tegn, som enten ikke har nogen keyboard-knap eller som har speciel funktion i SGML-kildeteksten. Eksempel: "&" = '&' og "≈" = '≈' (approximation, tilnærmelsesvis-lig-med).
DocBook DSSSL, Document Style Semantics and Specification Language (DSSSL) filerne med .dsl endelse, for hver af de forskellige typer output format, som man ønsker, html, rtf og så videre. DSSSL er en ISO-standard, og man kan finde dokumentationen på OASIS-hjemmesiden, http://www.oasis-open.org/.
Det er små scripts, som benytter et lidt større script, jw, jade-wrapper, til opsætning, så oversættelsen sker uden for mange overflødige krav til kommandolinjen.
Konvertering af en docbook fil til postscript eller pdf er en to-trins proces. Openjade skriver en tex-fil, som så er input for jadetex, som producerer en dvi, og pdfjadetex, som producerer en pdf-fil. Postscript opnås så ved at sende dvi filen igennem dvips. Docbook-utils sparer os for alle de kommandoer, så vi med en enkelt kommando kan udføre disse operationer.
Mini-Howto'en for installering af DocBook pakker nævner dette som et specielt system, men jeg har p.t. ikke nogen idé om, hvilke Red Hat 7.1++ pakker dette svarer til. HTMLdoc er et frit program, som konverterer html filer til pdf eller ps filer.
SGMLspm er et perl modul, som sammen med andre programmer (docbook2X) kan generere man-pages. SGMLSpm er et perl-library modul, som behandler parsed output fra onsgmls (open new sgml - parser). SGMLSpm inkluderer en applikation, som hedder sgmlspl, for at kunne bruge SGMLSpm modul-library'et. Sgmlspl har brug for spec filer, som kan fås fra forskellige andre sites på internettet, for hver type konvertering, som den skal foretage. DocBook2X er en pakke, som leverer spec-filer, der kan transformere docbook-filer til man-pages.