Linux - Friheden til at skrive dokumentation: Version 2.7.20040524 - 2020-12-31 | ||
---|---|---|
forrige | Kapitel 2. DocBook | næste |
Når man skal igang med docBook er det nemmest at have en model, en tom ramme, som man så kan starte med at skrive i med det samme. Du kan for eksempel fjerne alle paragraffer i eksemplet, som følger med denne bog, og skrive i de rensede filer.
DocBook-dokumentationen ligger på http://www.oasis-open.org/docbook/. Her kan du finde information om alle de elementer, som kan anvendes. Desværre må man sige, at det er en ringe hjælp for dem som skal igang med at skrive for første gang. Det skal denne bog råde bod på. Først ser vi på et par af de vigtigste SGML-elementer og senere hvordan man bruger dem til at lave et helt dokument.
Det første vi skal vide er at alle elementer åbnes og lukkes med et mærke. Åbningsmærket starter med < fulgt af elementets navn, eventuelle atributter og til sidst >. Afslutningsmærket er blot </ fulgt af elementets navn og >. Et eksempel er <command>ls -l</command> som markerer at strengen "ls -l" er en kommando.
Ud over at < har speciel betydning, så har & også speciel betydning. Det betyder, at du ikke kan skrive < og & direkte i din tekst, men i stedet må man skrive < og & (Du kan så vælge også at skrive > som > - men det er ikke tvungent). Tegn, som ikke opfører sig almindeligt, kaldes metategn.
Alle tekstblokke skal indkapsles med <para> og </para>. Linjedeling overlades til docbook-formateringsprogrammerne. Hvis man skriver et linjeskift midt i en <para> blok, ignorerer docbook-programmerne det.
Hvis man vil have linjeskift, må man slutte paragraffen og enten starte en ny paragraf, en liste, en SCREEN, eller, hvis man foretrækker det, skrive al sin tekst som programlisting, så får man docbook til at acceptere ren asciitekst, "typewriter-style".
Der findes ikke en <br>-konstruktion som man kender det fra HTML.
Eksempel 2-3. para
<para> Dette er en tekstblok. </para> <para> Dette er en anden tekstblok, som starter på ny linje. </para>
Dette kommer til at se ud som:
Dette er en tekstblok.
Dette er en anden tekstblok, som starter på ny linje.
I en <para> block skal man måske indikere at nu kommer der en kommando, som kan køres.
For at indikere et filnavn i en <para> kan man bruge <filename>
For at markere en del af sætningen med kursiv skrift i en <para> kan man bruge <emphasis>
For at markere en URL i en <para> kan man bruge <ulink>
Eksempel 2-7. ulink
Læs om SSLUG på <ulink url="http://www.sslug.dk">SSLUG's hjemmeside http://www.sslug.dk</ulink>. Der er mange aktiviteter.
Dette kommer til at se ud som:
Læs om SSLUG på SSLUG's hjemmeside http://www.sslug.dk. Der er mange aktiviteter.
Har man brug for at vise noget kildetekst bør man sætte det ind i et "programlisting"-element. Hvis man derimod vil vise noget der står på skærmen bør man sætte det ind i et "screen"-element. Både i "programlisting"- og "screen"-elementer følger linjeskiftene i uddata (selvfølgelig) linjeskiftene i SGML/XML-koden.
Eksempel 2-8. programlisting
Koden:
<para> Nu vil jeg vise lidt Perl-kode </para> <programlisting> #!/usr/bin/perl -i.bak -p s/Microsoft/Linux/g; </programlisting>vil resultere i disse uddata:
Nu vil jeg vise lidt Perl-kode
#!/usr/bin/perl -i.bak -p s/Microsoft/Linux/g;
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.
Eksempel 2-9. "prompt" og "userinput" i et "screen"-element
<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>
Dette kommer til at se ud som:
[root@tyge /root]# ls -al /etc/passwd -rw-r--r-- 1 root root 649 jun 16 21:54 /etc/passwd
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.
Eksempel 2-10. table
<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>
Dette kommer til at se ud som:
Tabel 2-1. Firma-tabel
FirmaNavn | Vej | PostNr |
---|---|---|
Vagabondos | Tagensvej 100 | 2200 |
DKUUG | Fruebjergvej 3 | 2100 |
Niels Bohr Institutet | Blegdamsvej 17-21 | 2100 |
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.
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.
Eksempel 2-11. figure
<FIGURE id="linustorvalds-fig" float="1"> <TITLE>Linus Torvalds</TITLE> <GRAPHIC fileref="linus.&magic;" scale="60"></GRAPHIC> </FIGURE>
Dette kommer til at se ud som:
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 -->
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]
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>
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.
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.
Eksempel 2-12. id og xref
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.
Dette kommer til at se ud som:
Vi kan referere til den forrige figur, altså Figur 2-1 eller tabellen Tabel 2-1 uden at tænke på hvilket nummer de har. Vi anvender blot deres label.
Ofte har man brug for at lave en liste. I Docbook er der flere muligheder, jeg bruger dog kun en type med enkle punkter
Eksempel 2-13. itemizedlist
<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>
Dette kommer til at se ud som:
Første punkt i listen skriver jeg her.
Andet punkt i listen skriver jeg derefter her.
Tilsvarende til <itemizedlist> kan man lave lister, som er nummererede.
Eksempel 2-14. orderedlist
<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>
Dette kommer til at se således ud
Første punkt i listen skriver jeg her.
Andet punkt i listen skriver jeg derefter her.
En bog inddeles i kapitelniveauer med <chapter>, og tilsvarende lavere niveauer <sect1>, <sect2>, og <sect3>. Opdelingen afspejler ikke nødvendigvis de filer man skriver. For hver ny inddeling skal man have et <title></title> til at anføre titel.
En artikel har samme inddelinger, pånær <chapter>, og første inddelingsniveau er <sect1>.
Hver af de elementer kan tage en id="label", som man kan bruge til at referere til.
Eksempel 2-15. Opdeling
<sect2 id="introduktion"> <title>Dette er en introduktion</title> <para> Tekst kommer her i en para-blok og bemærkede du at afsnittet har label "introduktion"? </para> <para> Havde det været en bog, skulle vi starte med chapter og sect1, men men det er jo et eksempel :-) </para> <para> Læs mit næste afsnit i <xref linkend="naeste-inddeling"/>. </para> <sect3 id="naeste-inddeling"> <title>Dette er næste inddeling</title> <para> Her er et underafsnit. Du skal bemærke, at jeg ikke bruger æ, ø og å i labels. Det giver ellers problemer med HTML-filnavne. </para> <para> Bemærk at <command><!-- Dette er en kommentar --></command> kan bruges til at angive en kommentar som ikke vises </para> </sect3> </sect2> <!-- Denne afslutning skal man huske -->
Dette kommer til at se ud som:
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.
Her er et underafsnit. Du skal bemærke, at jeg ikke bruger æ, ø og å i labels. Det giver ellers problemer med HTML-filnavne.
Bemærk at <!-- Dette er en kommentar --> kan bruges til at angive en kommentar som ikke vises
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.
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;.
På dansk skrives tankestreger sådan – altså en mellemlang streg med mellemrum omkring. Dette skal ikke forveksles med minus, som er en kort streg, som her -. Eller den amerikanske udgave, som er en ret lang streg, uden mellemrum—som ikke anvendes på dansk. (NB: Hvis du ser dette i en HTML udgave, er det ikke sikkert at tegnene ser forskellige ud!)
Docbook koderne for disse tegn er "-", "&ndash" og "—".
[1] |
Denne tekst ender som fodnote. |