2.2. Igang med Docbook

2.2.1.1. Kommandoer - command

I en <para> block skal man måske indikere at nu kommer der en kommando, som kan køres.

I Linux kan man skrive <command>find / -name
"*.htm?"</command> for at finde HTML-filer.

2.2.1.2. Filer - filename

For at indikere et filnavn i en <para> kan man bruge <filename>

Linux har altid filen <filename>/etc/password</filename>.

2.2.1.3. Skråskrift - emphasis

For at markere en del af sætningen med kursiv skrift i en <para> kan man bruge <emphasis>

Linux giver <emphasis>mange</emphasis> muligheder.

2.2.1.4. URL - ulink

For at markere en URL i en <para> kan man bruge <ulink>

Læs om SSLUG på
<ulink url="http://www.sslug.dk">SSLUG's hjemmeside http://www.sslug.dk</ulink>. Der er
mange aktiviteter.

2.2.2.1. Elementer i "screen"-elementet

For at kunne skelne mellem hvad et program udskriver og hvad brugeren taster, så anvender jeg et par Docbook elementer inden i "screen"-elementet. "prompt" bruges til spørgsmål til brugeren og "userinput" bruges til det brugeren indtaster.

<programlisting>
<prompt>[root@tyge /root]# </prompt> <userinput>ls -al /etc/passwd</userinput>
-rw-r--r-- 1 root root 649 jun 16 21:54 /etc/passwd 
</programlisting>

[root@tyge /root]#  ls -al /etc/passwd
-rw-r--r-- 1 root root 649 jun 16 21:54 /etc/passwd 

2.2.3.1. Tabeller - tabel

Tabeller laves med <table>. Bemærk at denne ikke må være inden i en <para>. I eksemplet skal med cols= angives antallet af søjler. Indrykningen har ingen betydning for resultatet, og anvendes alene til at man selv har overblik over koderne. Igen bemærkes, at det er ligegyldigt om man anvender store eller små bogstaver.

<TABLE id="db-firmaet">
<TITLE>Firma-tabel</TITLE>
<TGROUP cols=3 align="char">
<THEAD>
  <ROW>
   <ENTRY>FirmaNavn</ENTRY>
   <ENTRY>Vej</ENTRY>
   <ENTRY>PostNr</ENTRY>
  </ROW>
</THEAD>
<TBODY>
<ROW>
 <ENTRY>Vagabondos</ENTRY>
 <ENTRY>Tagensvej 100</ENTRY>
 <ENTRY>2200</ENTRY>
</ROW>
<ROW>
 <ENTRY>DKUUG</ENTRY>
 <ENTRY>Fruebjergvej 3</ENTRY>
 <ENTRY>2100</ENTRY>
</ROW>
<ROW>
 <ENTRY>Niels Bohr Institutet</ENTRY>
 <ENTRY>Blegdamsvej 17-21</ENTRY>
 <ENTRY>2100</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>

Bemærk at vi har anført id="label" sammen med <table>. Det er for at kunne krydsreferere til tabellen fra et sted i teksten.

Det skal bemærkes, at man med <colspec> kan lave en del bedre formattering af tabeller, såsom farvelægning af celler og andre fikse ting som bredde af tabeller, kolonner etc.

2.2.3.2. Figurer - figure

Figurer kan inkluderes i Docbook-dokumenter. Selvom det anføres at en lang række grafik formater er understøttet, så gælder det i praksis ikke, hvis man skal kunne oversætte både til HTML, PDF og Postscript. Vi anbefaler PNG-format til billeder, da dette er generelt understøttet.

<FIGURE id="linustorvalds-fig" float="1">
<TITLE>Linus Torvalds</TITLE>
<GRAPHIC fileref="linus.&magic;"  scale="60"></GRAPHIC>
</FIGURE>

Bemærk at vi igen her har sat id="label" ind under <figure id="linustorvalds-fig" float="1"> for at kunne krydsreferere til figuren. Du skal selv skalere billedet (i PDF og Postscript udskrift via scale-parameteren.

Det kan være lidt vanskeligt at gennemskue, hvor stort ens billede bliver, når man har taget et screenshot og det skal med i ens bog. Det kan også være lidt svært at regne ud hvor store billeder man skal lave.Her følger en gennemgang af hvordan man kan forudsige lidt om skaleringen, så man kan forstå hvad der sker og hvordan scale-paremeteren skal bruges.

Det er formentlig velkendt at alle billeder har en opløsning i pixels, det vi som regel forstår som størrelsen af et billede. Et skærmskud kan f.eks. være 900x600 pixels. Hvis man ser det billede på to forskellige computere, hvor den ene har en 20" skærm med en opløsning på 1024x768 og den anden har en 15" skærm med en opløsning på 1024x768, vil det samme billede have to meget forskellige størrelser, når de ses på skærmen. Det er vi vant til og tager ikke så højtideligt – typisk kan vi forstørre eller formindske billedet for at se det bedre alligevel.

Det er meget værre hvis vi taler om udskrivning. Hvis vi fulgte samme metode som for skærme – hvor hver af billedets pixels optager een pixel på skærmen – ville et billede på 900 pixels bredde være 3 tommer bredt på en 300 dpi printer (en printers dpi bestemmer hvor mange (evt. farvede) prikker den kan lave pr. tomme/cm) og 1.5 tomme bredt på en 600 dpi printer. Det er ikke særligt ønskeligt. For at imødekomme det, taler man også om et billedes opløsning pr. enhed, typisk pixels pr. centimeter, eller pixels pr. tomme (det sidste er det der kaldes dpi).

Afhængigt af hvordan du har lavet dit billede (og hvilket format det er) har det allerede en dpi størrelse. Nogen programmer tillader dig at se og ændre denne størrelse (f.eks. gimp med jpg billeder). Men, de fleste billeder har ikke et tal indbygget, og derfor antager Docbook en standard værdi, når den skal lave dit billede om til noget der kan skrives ud på en printer (f.eks. postscript eller pdf). Denne standardværdi er, så vidt jeg ved, 72 dpi.

Lad os tage et eksempel. Antag at du har et 900 pixel bredt billede og du vil skrive det ud på en 300 dpi printer (eller en fil med indbygget antagelse om opløsningen, som f.eks. postscript eller pdf). Docbook antager at billedet er 72 dpi, derfor skaleres billedet først op med printerdpi/billededpi = 300/72 ~= 4.2, dvs. at billedet bliver ca. 3750 pixels bredt eller 12.5 tommer, eller ca. 31 cm. Det er jo alt for stort til en A4 side, så her kommer scale parameteren ind. Vi bruger scale parameteren til at sætte det til 40%, så bliver det 1500 pix, 5 tommer eller ca. 13 cm, som passer fint på docbook siden. Det endelige billedes opløsning bliver 1500/5 = 300 dpi – lige som det skal være. Når Docbook laver f.eks. HTML, sker der dog ingen skalering. Her vil billedet stadig være 900 pixels bredt.

Så, hvor stort skal ens billede være? Det vigtigeste er at undgå nedskalering – det er bedre at skulle skalere op på papir, end ned, fordi der uundgåeligt går detaljer tabt ved nedskalering. Så, hvornår bliver der skaleret ned? Hvis man har 15 cm plads, har man typisk plads til mindst 15/2.54*300 pixels = 1771 pixels. Billeder mindre end det, bliver skaleret op, mens billeder større bliver skaleret ned. Hvis man udskriver på 600 dpi, har man selvklart plads til det dobbelte. Men, det er nok ikke smart at lave billeder meget større end 1000 pixels, da de kan blive meget store på skærme med en lav opløsning.

Hvis man vil lave små billeder, så lav dem små til at starte med, lad være med at brug gimp eller lignende til at resample dem med: de bliver alligevel resamplet når de skal skrives ud/vises og på webben betyder det ingenting.

Hvis du gerne vil regne ud hvad din scale-parameter skal være, for at optage en bestemt bredde, kan du bruge den her formel: "scale = ønsket bredde i tommer * billeddpi / billedbredde i pixels". Her kan du antage at billeddpi er 72 hvis du ikke ved andet. Det er måske lidt nemmere i centimeter for os danskere, og så bliver det 72 dpi (ca) = 28.3 punkter pr. centimeter. Så bliver formlen: "scale = ønsket bredde i cm * 28.3 / billedebredde i pixels". Et eksempel; vi ønsker at et 900 pixels billede skal være 15 cm bredt ved udskrift, så vi får "scale = 15 * 28.3 / 900 = 0.47". scale-parameteren skal altså sættes til 47%. På webben bliver scale parameteren ignoreret, og brugeren får et 900 pix bredt billede. Det kan han så se det hele af, og skalere ned eller bruge scrollbars.

Hvad nu med &magic;? Der er et problem med grafik - hvis man alene laver PDF og HTML-filer, så kan man anføre at det er en .png fil eller lignende. Skal man også lave PostScript, så skal man anvende .eps-filer. Der skal en konvertering af billederne til. En nem måde at styre magic-variablen er at tilføje denne i den hoved-sgml-fil man laver

<!ENTITY % magic-entities SYSTEM "magic.sgml">
  %magic-entities;  <!-- This is where we include it -->

2.2.3.3. Fodnoter

Skal du lige lave en fodnote i din SGML-fil skal du prøve dette

<para>
Denne tekst er til almindelig brug
<footnote id="fodid">
<para>
Denne tekst ender som fodnote.
</para>
</footnote>
</para>

Som eksempler bliver dette til

Denne tekst er til almindelig brug [1]

2.2.3.4. Info-boks

Skal du lave en info-boks findes tagget "sidebar".

<sidebar>
<para>
Det er da ikke særlig svært at se hvordan man laver en 
"sidebar". 
</para>
</sidebar>

2.2.3.5. Kommentarer

Skal du lige lave en kommentar i din SGML-fil som ikke kommer med ud i HTML, PDF og Postscript-filerne, så kan du anvende.

<!-- Dette er en kommentar -->

Bemærk at der er to minus-tegn efter hinanden. I udprintning vil de se ud som ét langt minustegn.

2.2.3.6. Referencer - id og xref

Vi har allerede set at vi kan give en tabel og en figur en label. Dette gjorde vi med id="label". Tilsvarende kan vi referere til den label i en tekstblok et andet sted ved at bruge <xref>. Bemærk at denne kommando ikke har en tilsvarende </xref>. Lad i øvrigt være med at bruge danske bogstaver, mellemrum og understregning (eng. underscore). Grunden er at værdien af "ID" bruges til filnavne - og her kan man ikke tillade de nævnte tegn.

Vi kan referere til den forrige figur, altså 
<xref linkend="linustorvalds-fig"/> eller tabellen 
<xref linkend="db-firmaet"/> uden at tænke på hvilket
nummer de har. Vi anvender blot deres label.

2.2.3.7. Lister - itemizedlist og orderedlist

Ofte har man brug for at lave en liste. I Docbook er der flere muligheder, jeg bruger dog kun en type med enkle punkter

<itemizedlist mark="bullet">
<listitem>
 <para>
  Første punkt i listen skriver jeg her.
 </para>
</listitem>
<listitem> 
 <para>
  Andet punkt i listen skriver jeg derefter her.
 </para>
</listitem>
</itemizedlist>

Tilsvarende til <itemizedlist> kan man lave lister, som er nummererede.

<orderedlist>
<listitem>
 <para>
  Første punkt i listen skriver jeg her.
 </para>
</listitem>
<listitem> 
 <para>
  Andet punkt i listen skriver jeg derefter her.
 </para>
</listitem>
</orderedlist>

2.2.4.1. Dette er en introduktion

Tekst kommer her i en para-blok og bemærkede du at afsnittet har label "introduktion"?

Havde det været en bog, skulle vi starte med chapter og sect1, men det er jo et eksempel :-)

Læs mit næste afsnit i Afsnit 2.2.4.1.1.

2.2.4.2. Start filen

Nu har vi set på inddelinger af dokumentet og hvordan man laver tabeller, figurer, viser kildetekst og URL'er.

Lad os antage at man har lavet tre kapitler med hver deres <chapter id="label-for-kapitel">, som er gemt i tre filer introduktion.sgml, linux.sgml og konklusion.sgml. Her er så en opskrift på at lave hoved-filen som binder det hele sammen.

Forfattere angives i <AUTHORGROUP> og titler som tidligere vist i <title>.

<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
 <!entity intro SYSTEM "introduktion.sgml"> <!-- Filnavn ej lig id -->
 <!entity Linux SYSTEM "linux.sgml"> <!-- Filnavn ej lig id -->
 <!entity konklusion SYSTEM "konklusion.sgml"> <!-- Filnavn her lig id -->
]>

<book id="index" lang="da"> <!-- med lang="da" vælges
den danske docbook-localization fil, altså man får danske ord
for chapter, section, content, appendix, index m.v. -->
<bookinfo>
 <title>Bog titel kommer her</title>
 <subtitle>Her er en undertitel</subtitle>

 <AUTHORGROUP>

 <AUTHOR>
   <FIRSTNAME>Peter</FIRSTNAME>
   <SURNAME>Toft</SURNAME>
 </AUTHOR>

 <AUTHOR>
   <FIRSTNAME>Hans</FIRSTNAME>
   <SURNAME>Schou</SURNAME>
 </AUTHOR>

 </AUTHORGROUP>
 <COPYRIGHT>
   <YEAR>2002</YEAR>
   <HOLDER>Peter Toft og mange andre under
   "ÅDL" licensen</HOLDER>
 </COPYRIGHT>

 <ABSTRACT>
  <PARA>
   Her skriver vi et kort abstract.
  </PARA>
 </ABSTRACT>
</bookinfo>

<!-- Følgende linje skaber automatisk en indholdsfortegnelse -->
<toc id="toc"></toc> 
&intro;
&Linux;
&konklusion;
</book>

I hovedet af filen erklæres hvilke eksterne filer, vil skal læse ind. Hver af disse får en label (intro, Linux og konklusion) som vi anvender til sidst i filen med et & foran. Der er her til sidst vi angiver den rækkefølge filerne indsættes i.

Bemærk at kommandoerne <toc></toc> bruges til at få genereret en indholdsfortegnelse. Dette kræver intet andet end den linje.

2.2.4.3. Entities

Vi har i Afsnit 2.2.4.2 allerede set ordet entity anvendt. Denne bruges til at definere enten en forkortelse eller at inkludere en anden fil. Vi så tidligere at tre filer blev defineret og her er vist samme definitioner samt at en forkortelse "pto" er sat til "Peter Toft".

 <!entity intro SYSTEM "introduktion.sgml"> <!-- Filnavn ej lig id -->
 <!entity Linux SYSTEM "linux.sgml"> <!-- Filnavn ej lig id -->
 <!entity konklusion SYSTEM "konklusion.sgml"> <!-- Filnavn her lig id -->
 <!entity pto "Peter Toft"> 

Når man ønsker indholdet af introduktion.sgml, så skriver man blot &intro;, tilsvarende &Linux; og &konklusion;. Skal man bruge teksten "Peter Toft", så er det nemmere at bruge &pto;.