Utökning av LaTeX med stöd för semantisk information

Examensarbete

Utökning av LaTeX

med stöd för semantisk information

av

Ronny Löfqvist

LITH-IDA-EX--07/001--SE

2007-01-29

Linköpings universitet Institutionen för datavetenskap

Examensarbete

Utökning av LaTeX

med stöd för semantisk information

av

Ronny Löfqvist

LITH-IDA-EX--07/001—SE

2007-01-29

Handledare: Henrik Eriksson

På svenska

Detta dokument hålls tillgängligt på Internet – eller dess framtida ersättare –

under en längre tid från publiceringsdatum under förutsättning att inga

extra-ordinära omständigheter uppstår.

Tillgång till dokumentet innebär tillstånd för var och en att läsa, ladda ner,

skriva ut enstaka kopior för enskilt bruk och att använda det oförändrat för

ickekommersiell forskning och för undervisning. Överföring av upphovsrätten

vid en senare tidpunkt kan inte upphäva detta tillstånd. All annan användning av

dokumentet kräver upphovsmannens medgivande. För att garantera äktheten,

säkerheten och tillgängligheten finns det lösningar av teknisk och administrativ

art.

Upphovsmannens ideella rätt innefattar rätt att bli nämnd som upphovsman i

den omfattning som god sed kräver vid användning av dokumentet på ovan

beskrivna sätt samt skydd mot att dokumentet ändras eller presenteras i sådan

form eller i sådant sammanhang som är kränkande för upphovsmannens litterära

eller konstnärliga anseende eller egenart.

För ytterligare information om Linköping University Electronic Press se

förlagets hemsida

http://www.ep.liu.se/

In English

The publishers will keep this document online on the Internet - or its possible

replacement - for a considerable time from the date of publication barring

exceptional circumstances.

The online availability of the document implies a permanent permission for

anyone to read, to download, to print out single copies for your own use and to

use it unchanged for any non-commercial research and educational purpose.

Subsequent transfers of copyright cannot revoke this permission. All other uses

of the document are conditional on the consent of the copyright owner. The

publisher has taken technical and administrative measures to assure authenticity,

security and accessibility.

According to intellectual property law the author has the right to be

mentioned when his/her work is accessed as described above and to be protected

against infringement.

For additional information about the Linköping University Electronic Press

and its procedures for publication and for assurance of document integrity,

please refer to its WWW home page:

http://www.ep.liu.se/

6

Abstract

The semantic web is a vision of the Internets future, there machines and humans can understand the same information. To make this possible, documents have to be provided with metadata in a general language. W3C has created Web Ontology Language (owl) for this purpose.

This report present the creation of a LA_{TEX package, which makes it possible} to include metadata in pdf files. It also presents how you can create annota-tions, which are bound to the metadata that’s been generated. With the help of this package it’s easy to create pdf documents with automatically generated metadata and annotations.

Sammanfattning

Den semantiska webben ¨ar en framtidsvision av Internet, d¨ar maskiner och m¨anniskor kan f¨orst˚a samma information. F¨or att detta ska vara m¨ojligt m˚aste dokumenten p˚a n¨atet f¨orses med metadata i ett generellt spr˚ak. W3C har tagit fram ett spr˚ak f¨or detta ¨andam˚al som heter Web Ontology Language (owl).

I den h¨ar rapporten presenteras skapandet av ett LA_{TEX-paket, som g¨or det} m¨ojligt att inf¨ora metadata i pdf-filer. Den g˚ar ocks˚a igenom hur man skapar annoteringar, vilka i sin tur ¨ar knutna till metadatan som genererats. Med hj¨alp av paketet ¨ar det enkelt att skapa pdf-dokument med autogenererad metadata och annoteringar.

Inneh˚

all

1 Inledning 11

1.1 Syfte . . . 11

1.2 Problemformulering . . . 11

1.3 Avgr¨ansningar . . . 12

1.4 Metod och k¨allor . . . 12

1.5 Struktur . . . 13

2 Teoretisk grund 15 2.1 TeX . . . 15

2.2 LaTeX . . . 15

2.3 Semantic web . . . 17

2.4 Web ontology language. . . 17

2.5 Pdf och dess uppbyggnad . . . 18

2.6 Bibtex och Natbib . . . 19

3 F¨orarbete 21 3.1 Grundinformation om uppgiften. . . 21

3.2 Vad finns redan inom omr˚adet? . . . 22

3.3 Tidigt st¨allningstagande . . . 23 4 Skapande av paketet 27 4.1 Skapande av UniqueID . . . 27 4.2 Skapa pdf annotering. . . 29 4.3 Annoteringens f¨arg . . . 30 4.4 Skriva ut metadata . . . 31 4.5 Autogenererad metadata . . . 32 4.6 Annotering av referenslista . . . 34 5 Dokumentation 37 5.1 Ontologi . . . 37

5.2 Ut¨okning och underh˚all . . . 38

5.3 Manual . . . 38 7

8

6 Testning 41

6.1 Resultat av test. . . 41

6.2 Emacs . . . 41

6.3 Koppla loss paket. . . 42

6.4 Annotering av index . . . 42

6.5 Nyckelord i metadatan . . . 43

7 Resultat 45 7.1 Slutsats . . . 45

7.2 Diskussion och egna reflektioner. . . 46

7.3 Vidareutveckling . . . 49

A Pdf-dokumentets ontologi 53 B Owl-paketet: owl.sty 59 C Owl-paketets manual 73 D Onepage.tex 93

Figurer och tabeller

3.1 Bild ur Sage Diabetes guide, genererad fr˚an xml . . . 22

5.1 Klassdiagram ¨over pdfontologin . . . 37

K¨

allkod

1 Hello world! . . . 16

2 En post ur min bibfil . . . 19

3 Emphasize funktion till en bstfil. . . 20

4 Minimalistiskt exempel fr˚an Tame The BeaST . . . 20

5 Fr˚an fil test2.pdf . . . 21

6 Skapande av ett hexv¨arde . . . 28

7 Makro f¨or pdf annoteringsobjekt . . . 29

8 Annotthis makro . . . 29

9 Annotering f¨or mer ¨an en rad . . . 31

10 F¨argen r¨od skapas och v¨aljs h¨ar till aktiv f¨arg . . . 31

11 Skapandet av ett grafiskt objekt i createowlcolor makrot . . . 32

12 Makrot owlHash som l¨oser problemet med duplicerade # . . . . 32

13 Makrot owlPartOut . . . 33

14 Annotsection . . . 34

15 Makrot addannotmetadata . . . 35

16 Insertmetadata makrot. . . 35

17 Stilfunktioner . . . 36

18 Kod f¨or att skydda metadata . . . 42

19 Modifikation av @startsection . . . 47

Kapitel 1

Inledning

Sedan Internet slog igenom stort har m¨angden information ¨okat i en snabb takt. Idag ¨ar det inte l¨angre ett problem att hitta information p˚a n¨atet, utan att hitta r¨att bland den till synes o¨andliga m¨angd som finns tillg¨anglig. En vision om framtidens anv¨andning av Internet har tagits fram under namnet den semantiska webben. Den semantiska webben presenterar metoder som ska g¨ora det m¨ojligt att s˚alla bland framtidens kopi¨osa m¨angder data. Bland dessa metoder ¨ar skapandet av ett spr˚ak f¨or semantisk information, som i form av metadata1_{ska inf¨oras i olika dokument p˚a n¨atet. Det h¨ar arbetet g¨or det m¨ojligt}

att via LA_{TEX f˚a denna metadata genererad ˚at sig, vid producering av pdf-filer.}

1.1

Syfte

Syftet med examensarbetet ¨ar att ut¨oka LA_{TEX med st¨od f¨or generering och} inf¨orande av semantisk information i pdf-filer. Denna information beskrivs i ett ontologibaserat spr˚ak kallat owl. Det finns redan system vilka arbetar med xml som kan genomf¨ora detta. Anledningen till att g¨ora det m¨ojligt via LA_{TEX ¨ar} dess f¨orm˚aga att typs¨atta text av mycket h¨og kvalitet. Systemet ska inte bara inkludera semantisk information, utan ocks˚a koppla denna till pdf-annoteringar i dokumentet.

1.2

Problemformulering

Uppgiften best˚ar av f¨oljande fyra punkter: • Skapa en ontologi f¨or pdf-dokumentet. • Generera och inkludera metadata i pdf-filen. • Skapa annoteringar med koppling till metadatan.

1_{Data om data. I det h¨ar fallet information om dokumentstrukturen.}

12 KAPITEL 1. INLEDNING • Granska LA_{TEX m¨ojligheter med avseende p˚a annoteringar.}

Den f¨orsta punkten ¨ar en frist˚aende punkt utan direkt koppling till LA_TEX. Resterande punkter resulterar i ett LA_{TEX-paket som jag h¨adanefter kommer att} kalla owl-paketet.

1.3

Avgr¨

ansningar

Uppgiften ¨ar att f¨ora in metadata i pdf-filer och att ha knutna annoteringar till den metadatan. Det ¨ar d¨arf¨or inte relevant att LA_{TEX-paketet fungerar med} n˚agot annat ¨an pdfTEX2_.

Vid projektets start kom vi ¨overens om att paketet inte beh¨over vara bak˚ at-kompatibelt f¨or ¨aldre pdf-l¨asare. Eftersom pdf-l¨asare ¨ar gratis, s˚a finns det inga stora hinder f¨or anv¨andare att ha en ny version installerad. Det skulle ocks˚a inneb¨ara mer arbete, om gamla versioner skulle beh¨ova testas inf¨or olika ¨

andringar. D¨arf¨or l¨amnas inga garantier f¨or att paketet fungerar v¨al med l¨asare ¨

aldre ¨an Adobe reader 7.0.

Fokus p˚a arbetet ¨ar att f˚a mycket funktionalitet till LA_{TEX, samt stor m¨angd} autogenererad metadata. Jag har d¨arf¨or avst˚att fr˚an att skapa en avancerad eller komplett ontologi till pdf-dokumentet. Den ontologi jag skapat inneh˚aller endast det mest grundl¨aggande som beh¨ovs f¨or att kunna inf¨ora den t¨ankta metadatan. Ontologin som skapats finns ibilaga A.

1.4

Metod och k¨

allor

F¨or att kunna genomf¨ora arbetet s˚a b¨orjade jag med en studie av omr˚adet. H¨ar ¨

ar en lista p˚a de saker jag studerat:

• PdfTEX, fr¨amst med avseende p˚a annoteringar. • Uppbyggnaden av pdf-dokument.

• Andra LA_{TEX-paket, med syfte att l¨ara och bilda mig en uppfattning om} vad som redan finns.

• Studera spr˚aket owl.

Vid studierna s˚a har det funnits ett f˚atal k¨allor som har beh¨ovts under hela arbetet. Dessa k¨allor har alla h¨og kvalitet och ¨ar sj¨alvklara val f¨or ¨amnet. H¨ar f¨oljer en lista p˚a de viktigaste k¨allorna:

• Pdf referensmanualen. (Adobe System Incorporated) • PdfTEX manual. (Thanh et al., 2005)

• W3C’s hemsidor, om den semantiska webben och owl spr˚aket.

1.5. STRUKTUR 13 Vid utvecklandet av owl-paketet s˚a uppstod ibland behovet av att det skulle fungera tillsammans med andra paket. De flesta paket som finns till LA_TEX leve-reras med en manual. Dessa manualer ¨ar av v¨aldigt varierande kvalitet, men de blir av naturliga sk¨al n¨odv¨andiga att studera. M˚anga av de k¨allor som inte finns i listan ovan, ¨ar just manualer till ¨ovriga paket och d¨arf¨or finns inget behov av k¨allkritik.

F¨or information om den semantiska webben har jag anv¨ant mig av Explorer’s guide to the semantic web (Passin, 2004). Huruvida den h¨ar boken ¨ar b¨ast l¨ampad inom omr˚adet eller ej, kan jag inte svara p˚a. Jag har fr¨amst haft behovet att skapa mig sj¨alv en uppfattning om ¨amnet och den har d¨arf¨or inte direkt p˚averkat resultatet av arbetet.

Under mitt arbete s˚a har jag h¨amtat information fr˚an m˚anga hemsidor som inte blir omn¨amnda i denna rapport. Dessa har varit min st¨orsta infor-mationsk¨alla n¨ar det handlat om specifika l¨osningar p˚a problem inom LA_TEX. Eftersom dessa har varit viktiga f¨or mitt l¨arande genom arbetets g˚ang vill jag ta upp dem h¨ar. En bok som p˚atr¨affas vid majoriteten av de bra hemsidorna ¨ar boken som g˚ar under ben¨amningen The TeXbook av Knuth. Den boken ligger s¨akerligen bakom majoriteten av de anv¨andbara exempel som jag l¨art mig fr˚an. Jag vill d¨arf¨or ta upp den h¨ar under k¨allor, ¨aven om jag inte l¨ast sj¨alva boken! Jag kan ocks˚a rekommendera alla andra som har t¨ankt att skapa ett lite mer avancerat paket till LA_{TEX att ha tillg˚ang till en bok om TEX. Det ¨ar n¨amligen} en hel del knep och interna makron som man beh¨over anv¨anda och som ¨ar sv˚ara att hitta information om via n¨atet. Att hitta dessa makron via andras k¨allkod som jag gjort, har med st¨orsta sannolikhet kostat mig en hel del tid.

1.5

Struktur

Rapporten ¨ar uppdelad i kapitel. Kapitel tv˚a g˚ar igenom teoretiska grunder som l¨asaren beh¨over ha k¨annedom om, f¨or att kunna tillgodose sig materialet i resterande av dokumentet. Kapitel tre g˚ar igenom f¨orarbetet som gjordes innan paketet b¨orjade skapas. Kapitel fyra handlar om skapandet av owl-paketet och kapitel fem g˚ar igenom dokumentationen till paketet. Rapporten avslutas med slutsats och diskussioner.

Kapitel 2

Teoretisk grund

F¨or att kunna tillgodog¨ora sig materialet i resten av rapporten ¨ar det viktigt att man f¨orst˚ar vissa grunder. Man m˚aste ha viss k¨annedom om LA_TEX, ef-tersom det mesta av arbetet utf¨orts i det systemet. Det ¨ar ocks˚a viktigt att ha grundl¨aggande f¨orst˚aelse om filformatet pdf, d˚a alla stycken om annoteringar handlar om just detta format. BibTEX m˚aste man k¨anna till om man ska f¨orst˚a referenshantering i LA_{TEX. Det ¨ar dock en ganska liten del av rapporten och den} kan eventuellt l¨asas igenom utan st¨orre f¨ordjupning. Resterande av styckena handlar om metadata och grundl¨aggande f¨orst˚aelse f¨or den semantiska webben.

2.1

TeX

TEX ¨ar ett program avsett f¨or att typs¨atta text och matematiska formler. Pro-grammet skapades av Donald E. Knuth 1977. Syftet med proPro-grammet var fr¨amst att motverka den sjunkande kvalit´e som tryckt text hade p˚_{a den tiden. TEX som} vi ser det idag sl¨apptes ˚ar 1982 med n˚agra mindre modifieringar gjorda ˚ar 1989. TEX ¨ar k¨ant f¨or sin stabilitet, samt att det fungerar p˚a m˚anga olika datorer. (Oetiker et al., 2006)

2.2

LaTeX

LA_{TEX ¨ar ett typs¨attningssystem som bygger p˚a TEX-motorn. Det ¨ar fr¨amst} avsett f¨or matematiska och vetenskapliga dokument, men l¨ampar sig v¨al ¨aven f¨or alla sorters dokument fr˚an sm˚a artiklar till kompletta b¨ocker. LA_TEX han-terar design och struktur av dokumentet, men anv¨ander sig av TEX f¨or sj¨alva typs¨attningen.

Ett LA_{TEX-dokument best˚ar av makron}1 _{och vanlig text. Dokumentet}

pro-cessas (kompileras) sedan f¨or att generera det slutgiltiga utseendet. F¨or att g¨ora

1_{Ett kommando som definierar hur indata ska omvandlas till utdata.}

16 KAPITEL 2. TEORETISK GRUND det m¨ojligt att generera ett dokument, p˚atvingas anv¨andaren att ange dess lo-giska struktur. Med logisk struktur menas d˚a att anv¨andaren anger rubriker och ¨

ovriga strukturella delar som dokumentet ska inneh˚alla. LA_{TEX kommer sedan} att v¨alja en passande layout beroende p˚a den data som ges till den. Saker som LA_{TEX ¨andrar p˚a ¨ar exempelvis avst˚andet mellan tecken och rader. L}A_{TEX ¨andrar} ocks˚a placeringen av tabeller och figurer som kallas floats, se k¨allkod 1 f¨or ett minimalt LA_{TEX-dokument.}

K¨allkod 1 Hello world! \documentclass{article} \begin{document} \section{First section} Hello world!

\end{document}

Det h¨ar s¨attet att producera dokument, skiljer sig markant fr˚an de mer k¨anda WYSIWYG2text editorer som Microsoft Word. Ofta diskuteras huruvida WY-SIWYG editorer eller LA_{TEX ¨ar den b¨asta metoden f¨or textproduktion. Jag ser} ingen anledning att glida f¨or djupt in i den debatten, men eftersom den ¨ar s˚a frekvent f¨orekommande, t¨ankte jag ˚atminstone n¨amna n˚agra av de vanligaste argumenten f¨or de b˚ada alternativen.

H¨ar f¨oljer n˚agra av de f¨orekommande argumenten f¨or LA_TEX:

• Det finns f¨ardiga layouter gjorda s˚a att de dokument man skapar f˚ar ett professionellt utseende.

• Matematiska formler kan beskrivas p˚a ett intuitivt s¨att.

• Som anv¨andare beh¨over man inte engagera sig s˚a mycket i hur utseendet p˚a dokumentet ska bli. Man beh¨over bara k¨anna till n˚agra enkla makron. • Det finns bra st¨od f¨or komplexa saker som bibliografier och inneh˚allsf¨orteckningar

mm.

• LA_{TEX f˚ar anv¨andaren att skriva v¨alstrukturerade dokument.} • TEX ¨ar portabelt och gratis.

H¨ar f¨oljer n˚agra argument mot att anv¨anda LA_TEX: • Det ¨ar en betydligt h¨ogre inl¨arningstr¨oskel.

• Om man ¨ar ute efter ett specifikt utseende, ¨ar det en klar f¨ordel om man f˚ar se resultatet direkt utan att beh¨ova kompilera.

• Det tar l˚ang tid att skapa en helt ny layout.3

2_{WYSIWYG betecknar ”what you see is what you get”, vad du ser ¨ar vad du f˚ar.} 3_{Det ryktas att det kommer ske f¨orb¨attringar h¨ar i L}A_{TEX3. (Oetiker et al.,2006)}

2.3. SEMANTIC WEB 17 • Om din text ska in p˚a granskning s˚a kanske det st¨alls krav p˚a att ditt

dokument ¨ar i Word-format.

• Det kan vara sv˚art att formatera exempelvis k¨allkod som inneh˚aller m˚anga tecken, vilka skiljer sig fr˚an tecknen i vanlig skrift.

Det finns flera olika kompilatorer som bearbetar TEX-dokument och skapar m˚anga former av dokument. Den vanliga kompilatorn genererar en dvi4_{-fil, som}

man sedan kan konvertera till olika filformat. Med hj¨alp av pdfLA_TEX kompila-torn kan man generera pdf-filer direkt (Oetiker et al.,2006).

2.3

Semantic web

Den semantiska webben ses av somliga som efterf¨oljaren till World Wide Web. Den semantiska webben st˚ar f¨or en vision, d¨ar s˚av¨al datorer som m¨anniskor ska kunna s¨oka upp, l¨asa och f¨orst˚a information. Webben idag har anpassats till hur vi m¨anniskor s¨oker och presenterar information, medan situationen f¨or mjukvara inte ¨ar speciellt v¨alutvecklad. Detta medf¨or att den semantiska web-ben mestadels handlar om att utveckla mjukvarust¨od f¨or att s¨oka och f¨orst˚a information. (Passin,2004)

Den ”approach” man tagit f¨or att g¨ora det h¨ar m¨ojligt, ¨ar inf¨orandet av se-mantiska dokument. Ett semantiskt dokument ¨ar ett dokument med extra inf¨ord metadata, som beskriver den semantiska informationen, sefigur 2.1. Metadatan kan sedan anv¨andas f¨or att resonera och s¨oka information i dokumentet. Det h¨ar kan l˚ata som n˚agot som redan finns, d˚a vi har s¨okmotorer som anv¨ander sig av indexering, f¨or att s¨oka i dokument. De h¨ar tj¨ansterna anv¨ander sig av viktade s¨okord och fungerar ganska bra n¨ar man ¨ar relativt s¨aker p˚a vad man letar efter. Den erbjuder dock inge vidare hj¨alp n¨ar man ¨ar os¨aker p˚a vilka s¨okord man ska anv¨anda sig av. Den semantiska webben tar det h¨ar ett steg l¨angre och n¨ojer sig inte med m¨ojligheten att s¨oka endast p˚a s¨okord, utan ¨aven p˚a koncept och kategorier (Passin,2004).

En del av visionen om den semantiska webben handlar om mjukvaruagenter som ska kunna s¨oka och resonera kring data. Att det idag finns indexerings-tj¨anster hj¨alper f¨oga, f¨or att uppn˚a detta m˚al. F¨or att det ska vara m¨ojligt f¨or mjukvara att resonera kr¨avs ett generellt spr˚ak som presenterar informationen (metadatan). Det spr˚ak som utvecklats f¨or detta ¨andam˚al har f˚att ben¨amningen owl, serubrik 2.4

2.4

Web ontology language

Ett av de stora omr˚adena inom den semantiska webben ¨ar/har varit att skapa ett gemensamt s¨att att representera data p˚a. Det spr˚ak som tagits fram f¨or detta ¨

andam˚al har f˚att f¨orkortningen owl (web ontology language). S˚a h¨ar skriver W3Ci deras sammanfattning:

18 KAPITEL 2. TEORETISK GRUND

Figur 2.1: Semantiskt dokument

The OWL Web Ontology Language is designed for use by applications that need to process the content of information instead of just presenting information to humans. OWL facilitates greater machine interpretability of Web content than that supported by XML, RDF, and RDF Schema (RDF-S) by providing addi-tional vocabulary along with a formal semantics. OWL has three increasingly-expressive sublanguages: OWL Lite, OWL DL, and OWL Full. (W3C)

Spr˚aket owl, anv¨ands f¨or att bygga upp ontologier best˚aende av klasser och egenskaper (properties). Spr˚aket inneh˚aller ocks˚a funktioner f¨or att s¨atta upp restriktioner p˚a klasser och objekt. Genom dessa restriktioner kan sedan reso-nemang f¨oras. Owl finns som Lite, DL och Full, som n¨amndes i citatet ovan. Spr˚aken ¨ar uppbyggda som en ut¨okning av sin f¨oreg˚angare. Detta inneb¨ar att allt som ¨ar till˚atet i Lite-versionen ocks˚a ¨ar till˚atet i DL-versionen. Likas˚a till˚ats allt i Full-versionen som till¨ats i DL-versionen.

2.5

Pdf och dess uppbyggnad

Pdf-formatet ¨ags och utvecklas av Adobe System Incorporated, men det ¨ar ocks˚a ett ¨oppet format (Adobe System Incorporated). Pdf ¨ar ett v¨alanv¨ant format idag, vilket g¨or att de flesta format g˚ar att konvertera till pdf.

Pdf-filer ¨ar uppbyggda p˚a objekt som inneh˚aller nummer och nyckelord. S˚a h¨ar ser ett objekt ut:

2 0 obj <</Type /Catalog ... >>endobj.

Punkterna representerar i exemplet att det finns mer information d¨ar. Ett objekt kan ocks˚a efterf¨oljas av en str¨om. Om detta ¨ar fallet efterf¨oljs >> med stream . . . endstream, medan endobj fortfarande avslutar objektet. Det f¨orsta som h¨ander n¨ar en pdf-l¨asare ¨oppnar en pdf-fil ¨ar att den flyttar sig l¨angst bak i filen d¨ar den hittar startxref. D¨ar finns den information som beh¨ovs f¨or att l¨asa in filen.

2.6. BIBTEX OCH NATBIB 19

2.6

Bibtex och Natbib

BibTEX ¨ar ett separat program som ¨ar till f¨or att generera bibliografier till LA_{TEX. BibTEX l˚ater anv¨andaren skapa en databas med referensinneh˚all i en} bstfil, se k¨allkod 2. F¨ore anv¨andandet av bibTEX kr¨avs f¨orst en k¨orning av LA_{TEX f¨or att identifiera olika citationsmakron, exempelvis \cite{owlpackage}.} N¨ar LA_{TEX har processat filen en g˚ang sparas information om citationsmakron i} den aux-fil som LA_{TEX skapar. Sedan k¨or man bibTEX p˚a sin fil, f¨or att generera} en bbl-fil. Denna fil inneh˚aller information f¨or att generera bibliografilistan. Slutligen ˚aterst˚ar att kompilera med LA_{TEX tv˚a g˚anger. Orsaken till att det} beh¨over g¨oras tv˚a g˚anger, ¨ar att f¨orsta g˚angen uppt¨acker LA_{TEX korsreferenser.} D˚a beh¨over man kompilera en g˚ang till f¨or att de ska bli korrekta.

K¨allkod 2 En post ur min bibfil @MANUAL{owlpackage,

TITLE = "User manual for owl package", AUTHOR = "Ronny L¨ofqvist",

MONTH = "11", YEAR = "2006", }

Det finns stora f¨ordelar med att hantera referenser p˚a det h¨ar viset. I och med att man har en databas f¨or sina referenser, s˚a kan man anv¨anda samma fil f¨or flera dokument. Det ¨ar ocks˚a v¨aldigt smidigt att datan finns i en separat databas och ¨ar helt separerad fr˚an information om hur den ska presenteras. Detta medf¨or att man enkelt och snabbt kan byta mellan olika s¨att att hantera referenser p˚a.

F¨or att anv¨anda bibTEX i sitt LA_{TEX dokument anv¨ands \bibliography{bibfile}} och \bibliographystyle{stylefile}. Stilmakrot kan anropas varsomhelst i doku-mentet, men m˚aste finnas innan \bibliography anv¨ands.

Det normala f¨or LA_{TEX ¨ar att referenser best˚ar av en siffra som omsluts av} hakar, exempelvis [1]. Genom att anv¨anda paketet natbib kan man l¨att ¨andra utseendet p˚a sina referenser (Daly,2006). Natbib anv¨ands i det h¨ar dokumentet f¨or att en referens ska best˚a av f¨orfattare och ˚artal, som du kan se vid f¨orsta meningen i det h¨ar stycket.

Referenser som genererats med hj¨alp av bibTEX och natbib ser ganska bra ut redan fr˚an b¨orjan, serubrik 7.3. Beh¨over man ett specifikt utseende s˚a m˚aste man ¨andra sin stilfil. Om man v¨aljer n˚agon av de vanligare layouter som anv¨ands s˚a finns det f¨ardiga stilfiler att anv¨anda. Men om man beh¨over ett lite annorlun-da utseende s˚a kan man bli tvungen att skapa sin fil sj¨alv. Detta ¨ar ganska om-fattande att g¨ora manuellt, d˚a det ¨ar mycket som ska st¨allas in och spr˚aket som anv¨ands ¨ar aningen komplicerat. D¨arf¨or finns verktyget custom-bib (eller ma-kebst) som genererar en fil ˚at anv¨andaren genom att st¨alla fr˚agor. Dessa fr˚agor ¨

ar ofta av typen ja eller nej och ¨ar ganska l¨atta att svara p˚a. Ofta finns det ett f¨orvalt alternativ som funkar bra, om man ¨ar os¨aker p˚a vad man vill ha.

20 KAPITEL 2. TEORETISK GRUND Om man inte kan f˚a den layout man vill ha genom att anv¨anda custom-bib, s˚a ¨

ar det sista alternativet att modifiera eller skapa en ny bstfil sj¨alv. Spr˚aket som anv¨ands i dessa filer bygger p˚a en stack och ett antal f¨ordefinierade kommandon. F¨or att g¨ora en funktion i bstfilen s˚a arbetar man efter f¨oljande tre punkter: • H¨amta argument fr˚an stacken.

• Utf¨or operationer p˚a argumenten. • Stoppa resultatet p˚a stacken.

Eftersom alla funktioner l¨agger sitt resultat p˚a stacken kan alltid n¨asta funk-tion arbeta p˚a deras resultat. Om man exempelvis vill anv¨anda \emph p˚a n˚agot makro s˚a skapar man f¨orslagsvis en funktion som ser ut enligtk¨allkod 3. Denna funktion anropas d˚a efter att man utf¨ort en funktion, som lagt en utskrift p˚a stacken.

K¨allkod 3 Emphasize funktion till en bstfil. FUNCTION {emphasize} { duplicate$ empty$ { pop$ "" } { "\emph{" swap$ * "}" * } if$ }

En minimal bstfil inneh˚aller en ENTRY och en READ. ENTRY anger vilka bibtyper som st¨ods. Sek¨allkod 4f¨or ett exempel av en bstfil ur Tame the beast (Markey,2005).

K¨allkod 4 Minimalistiskt exempel fr˚an Tame The BeaST ENTRY {}{}{}

FUNCTION {test}

{"de la Cierva y Codorn{\´\i}u, Juan" #1 "{ff - }{vv - }{ll}" format.name$ top$} READ

Kapitel 3

F¨

orarbete

F¨orarbete ¨ar viktigt i alla arbeten. F¨or det h¨ar arbetet s˚a inneb¨ar det att stu-dera ett exempel som sedan ska ˚aterskapas. Det inneb¨ar ocks˚a att studera vilka arbeten som redan utf¨orts, samt att planera och fatta beslut inf¨or arbetsstarten.

3.1

Grundinformation om uppgiften

Vid starten av arbetet hade jag tillg˚ang till tv˚a dokument med annoteringar och inf¨ord metadata. Vid granskning av dokumenten har f¨oljande relevanta pdf-objekt hittats:

K¨allkod 5 Fr˚an fil test2.pdf 8 0 obj <</F 4/Type/Annot /Subtype /ADBE:StampeT /Rect [ 70.866 644.585 417.03 632.585 ] /M(D:20050418120033+02’00’) /T(Text Annotation) /AP<</N 9 0 R>>/UniqueID/ce07d1422748af9c:5bb966:10354c06c65:-8000 >>endobj 9 0 obj

<< /Length 53 /Type/XObject/BBox[0 0 100 100]/Resources<</Font << /STAMPR <</Type/Font/Name/STAMPR/BaseFont/Helvetica/Subtype/Type1>> >> /ProcSet[/PDF/Text]/ExtGState <</GS1<</Type/ExtGState/ca 1.0/BM/Darken>> >> >>/Subtype/Form/FormType 1 >> stream q /GS1 gs 1 1 0 RG 1.0 1.0 0.0 rg 0 0 100 100 re f Q endstream endobj 21

22 KAPITEL 3. F ¨ORARBETE

Figur 3.1: Bild ur Sage Diabetes guide, genererad fr˚an xml

B¨agge objekten ¨ar tagna ur samma fil, eftersom den andra filen hade splittrat sin information ¨over flera objekt. Den hade ¨aven krypterat stream datan. B¨agge dessa tv˚a saker g¨or den mera sv˚ar¨oversk˚adlig och har d¨arf¨or utel¨amnats h¨ar. En rad inneh˚allande nyckelordet Selection har ocks˚a tagits bort. Den raden f˚ar mer ing˚aende diskussion irubrik 3.3. En fil som ¨ar autogenererad fr˚an xml och som anv¨ander pdf-annoteringen ovan ser ut enligtfigur 3.1.

Jag b¨orjar h¨ar med att dissekera dessa objekt, f¨or att f˚a fram betydelsen av dem och f¨or att senare kunna anv¨anda mig av denna information. Objekt nummer ˚atta inneh˚aller inte s˚a mycket intressant information. Alla nyckelord som finns h¨ar ¨ar av standardtyp utom UniqueID. Att generera ett uid (Unique identifier) blir en del av uppgiften.

Objekt nummer nio ¨ar ett grafiskt objekt och h¨ar blir informationen in-tressantare. F¨or information om str¨ommen som f¨oljer objektet, se tabell 3.1. ExtGState ¨ar en viktig del av detta objekt. "Darken", nyckelordet ¨ar det som g¨or att f¨argmarkeringen inte t¨acker ¨over texten, utan l˚ater den skina igenom.

¨

Ovriga nyckelord ¨ar standard och beh¨over ej ing˚aende f¨orklaring. (Adobe Sy-stem Incorporated)

3.2

Vad finns redan inom omr˚

adet?

Innan skapandet av paketet tar sin b¨orjan, ¨ar det av intresse att se vad som finns p˚a omr˚adet sedan tidigare. Detta f¨or att undvika att g¨ora arbete som redan ¨ar gjort och f¨or att dra nytta av erfarenheter andra personer har kommit fram till vid skapandet av snarlika paket. Jag hittade fr¨amst tv˚a paket som jag fann av intresse, dessa ¨ar hyperxmp och xmpincl (Pakin, 2006a; Sneep, 2005). Xm-pincl paketet skapar ett nytt makro \includexmp som automatiskt inkluderar

3.3. TIDIGT ST ¨ALLNINGSTAGANDE 23

Tabell 3.1: Grafisk str¨om Del Beskrivning

q & Q Start och slut f¨or en grafisk pdf str¨om gs Koppling till ExtGState

RG F¨argval utan relevans h¨ar rg Representerar f¨argen i rg form re f Indrag fr˚an kanterna

metadata i pdf-filen vid den position som makrot blir anropat. Paketet l¨agger automatiskt till xmp till filnamnet och ser till att det blir inf¨ort som xmp meta-data. Pga detta s˚a ¨ar paketet i sig inte l¨ampligt att anv¨anda f¨or mig, men jag har kunnat dra nytta av tekniken f¨or att hantera filstr¨ommar i LA_{TEX. Hyperxmp} ¨

ar ett paket som bygger p˚a funktionalitet fr˚an hyperref, d¨arav hyper i namnet (Rahtz and Oberdiek, 2006). Hyperref ¨ar ett paket f¨or att skapa hyperl¨ankar i LA_{TEX och ¨ar ett mycket stort och v¨albepr¨ovat paket. Hyperxmp tar till vara p˚a} informationen som ges till hyperref via hypersetup. Informationen till hyperse-tup ¨ar variabler som @pdftitle, @pdfauthor, mfl. Jag tillvaratar kunskapen jag f˚att fr˚an granskningen av det h¨ar paketet och ser till att mitt paket ocks˚a kan interagera p˚a samma fina s¨att med hyperref.

Dessa tv˚a paket var de jag hittade som behandlade metadata. Jag letade ocks˚a efter paket som arbetade med pdfs annoteringar p˚a ett eller annat s¨att. Hyperref som jag n¨amnt tidigare skulle man kunna t¨anka sig arbetar med anno-teringar, men s¨okningar p˚_{a annoteringsmakron ur pdfTEX manual i hyperrefs} k¨allkod ger inga tr¨affar (Thanh et al.,2005). Hur intressant hyperrefs k¨allkod ¨

an m˚a vara, s˚a ¨ar den alldeles f¨or stor f¨or att granskas rad f¨or rad och jag g˚ar d¨arf¨or inte l¨angre p˚a den v¨agen.

Attachfile ¨ar ett paket jag kom i kontakt med som anv¨ander annoteringar kopplade till bifogade filer (Pakin, 2006b). Attachfile ¨ar ett kompetent paket f¨or att bifoga filer, men granskandet av k¨allkoden var inte speciellt givande. Det intressanta var hur paketet hanterade pdfs grafiska str¨ommar, men datam¨angden var alldeles f¨or stor och min f¨orst˚aelse f¨or dessa str¨ommar f¨or liten. Eftersom det jag beh¨over g¨ora med grafiska str¨ommar i paketet jag skapar ¨ar starkt begr¨ansat, s˚a ¨ar det inte v¨art besv¨aret att f¨ors¨oka f¨orst˚a sig p˚a paketets str¨ommar. Jag f˚ar angripa det problemet med hj¨alp av pdf referensmanualen och testning.

3.3

Tidigt st¨

allningstagande

Det fanns en del saker som var oklara fr˚an b¨orjan av projektet. En av dessa saker kr¨avde ett tidigt st¨allningstagande och det var fr˚agan om LA_{TEX makron skulle} omdefinieras eller om nya makron skulle anv¨andas. Det finns klara f¨ordelar med b¨agge l¨osningarna, h¨ar f¨oljer en lista med de jag observerade:

24 KAPITEL 3. F ¨ORARBETE F¨ordelar:

• Enklare att konstruera nya makron. • P˚averkar inte andra paket.

Nackdelar:

• Omst¨andigare att inf¨ora i befintliga dokument. • IDE1

support fungerar s¨amre, d˚a de inte ser vart section makron mfl finns. Orsaken till att man m˚aste ta st¨allning till den h¨ar fr˚agan tidigt, ¨ar att den kommer att p˚averka arbetet redan fr˚an b¨orjan och hela v¨agen till slutet. D¨arf¨or ¨ar det att f¨oredra att fatta ett tidigt beslut. Min vision fr˚an b¨orjan var att anv¨andaren skulle p˚averkas s˚a lite som m¨ojligt av inf¨orandet av mitt paket. D¨arf¨or var jag v¨aldigt intresserad av att omdefiniera befintliga makron. Jag b¨orjade d¨arf¨or med att prova att omdefiniera n˚agra olika makron som \section och \tableofcontents. Det visade sig att metoden f¨or att omdefiniera makron blev v¨aldigt olika beroende p˚a vilken typ av makro det handlade om.

F¨or att l¨ara mig hur andra mer erfarna LA_{TEX-programmerare brukar g¨ora i} liknande situationer s˚a tittade jag p˚a befintliga LA_{TEX-klasser. En v¨alk¨and klass} som jag l¨arde mig mycket av ¨ar memoir (Wilson,2004). Memoir klassen ¨ar till f¨or dynamisk typss¨attning och anv¨ander sig av andra paket, men med diverse ut¨okningar och/eller namn¨andringar. Memoir verkar vara en v¨aldigt komplett klass, med st¨od f¨or det mesta man skulle kunna t¨ankas vilja g¨ora, men d˚a blir den ocks˚a v¨aldigt stor och tar l˚ang tid att l¨ara. En av orsakerna till att memoir klassen ¨ar s˚a k¨and ¨ar dess manual. Manualen ¨ar v¨aldigt utf¨orlig och mycket bra, om man vill l¨ara sig om typs¨attning, ¨aven om man inte t¨ankt anv¨anda deras klass!

Att omdefiniera \section visade sig vara komplicerat och jag ¨ar ¨an idag os¨aker p˚a vad som h¨ander om andra paket ocks˚a omdefinierar makrot. Min teori baserat p˚a experiment ¨ar att det paket som laddas sist kommer att skriva ¨over de andra. Detta medf¨or f¨ormodligen att man saboterar deras ¨andringar. Detta g˚ar att motverka, men d˚a ¨okar komplexiteten f¨or att omdefiniera dem ytterligare. Att omdefiniera \tableofcontents visade sig dock vara mycket enkelt. Det gick att anv¨anda en l¨osning som ¨ar fri fr˚an komplikationer.

Till slut best¨amde jag mig f¨or att ¨overge id´een att skriva ¨over makron. Jag bed¨omde att det fanns en stor risk f¨or att det inte skulle g˚a att slutf¨ora inom ramen av examensarbetet. Problemet med kompatibilitet mot andra paket v¨agdes ocks˚a tungt in i beslutet. Jag bed¨ommer att det mycket v¨al kan vara ett v¨arre problem, ¨an det problem anv¨andaren f˚ar n¨ar han ska ¨andra sina makron i ett befintligt dokument.

Jag st¨alldes inf¨or ett annat problem ganska tidigt i arbetet. Detta problem g¨allde en speciell rad i annoterings objektet som jag utel¨amnade i k¨allkod 5. Raden s˚ag ut enligt f¨oljande: /Selection<</End 11 /Start 5>> d¨ar siffrorna re-presenterar vilka ord p˚a sidan som ¨ar annoterade. Problemet med den h¨ar raden

3.3. TIDIGT ST ¨ALLNINGSTAGANDE 25

¨

ar att LA_{TEX inte r¨aknar ord ¨overhuvudtaget. Mina efterforskningar visade ocks˚a} p˚a att de alternativ som redan finns i regel anv¨ander sig av externa program som dessutom bara approximerar antalet ord. Att anv¨anda externa program ¨

ar uteslutet i det h¨ar sammanhanget och tanken p˚a att f¨ors¨oka r¨akna orden manuellt i LA_{TEX verkade inte genomf¨orbar.}

Eftersom denna rad st¨allde till s˚a stora problem s˚a f¨ors¨okte jag ta reda p˚a dess funktionalitet i sammanhanget. Det visade sig att den inte hade n˚agon p˚averkan p˚a det grafiska utseendet p˚a annoteringen. D˚a ˚aterstod det att avg¨ora om raden hade n˚agon vital funktionalitet f¨or andra ¨andam˚al. Efter diskuterande med Henrik Eriksson, min examinator, s˚a best¨amde vi oss f¨or att se ¨over vilka m¨ojligheter som finns och om de var f¨or komplicerade, skulle raden utel¨amnas. Jag kunde bara se en l¨osning p˚a problemet och det skulle vara att ¨andra i LA_{TEX k¨allkod. Jag unders¨okte k¨allkoden till L}A_{TEX under en kortare period och} bed¨omde att den ¨ar v¨al stor att s¨atta sig in i. Jag gjorde h¨ar bed¨omningen att om det inte fanns v¨aldigt goda sk¨al s˚a skulle jag undvika att ¨andra i den. Att g˚a in och ¨andra i k¨allkoden skulle ¨aven f¨ora med sig fler framtida problem. Varje g˚ang en ny version av LA_{TEX sl¨apps skulle det bli n¨odv¨andigt att p˚a nytt g¨ora} samma ¨andringar. Detta ¨ar ¨annu en god orsak till att f¨ors¨oka undvika att ¨andra i k¨allkoden f¨or ett pakets skull.

Det visade sig under paketets utvecklande att det mesta i ¨ovrigt gick att l¨osa p˚a ett tillfredsst¨allande s¨att med hj¨alp av vanlig LA_{TEX-programmering.} Det stod d˚a klart att det var ett bra val att undvika ¨andringar direkt i LA_TEX k¨allkod.

Kapitel 4

Skapande av paketet

Skapandet av paketet har kretsat kring tv˚a saker fr¨amst. Det ena ¨ar genereran-de av metadata och genereran-den andra ¨ar skapandet av annoteringar. Enda egentliga undantaget ¨ar skapandet av f¨altet UniqueID, som ¨ar en mer frist˚aende uppgift. Detta hade egentligen kunnat skapats som ett eget paket, men d˚a hade det beh¨ovt vara bredare och fungera exempelvis utan pdfTEX

4.1

Skapande av UniqueID

Ik¨allkod 5fanns ett nyckelord UniqueID f¨oljt av en textstr¨ang. Detta id ˚aterfinns b˚ade i metadatan f¨or den annoteringen och i sj¨alva annoteringsobjektet. Detta uppr¨atth˚aller en koppling som g¨or det m¨ojligt att s¨oka tillh¨orande metada-ta/pdfobjekt.

Min f¨orsta tanke f¨or att generera ett uid (Unique identifier) var att skapa en str¨ang med m˚anga slumpartade v¨arden. H˚aller man str¨angen tillr¨ackligt stor och slumpgenereringen ganska bra, s˚a ¨ar sannolikheten f¨or tv˚a stycken likadana uid neglerbar. Jag hade ¨aven funderingar p˚a att anv¨anda mig av en intern r¨aknare f¨or just det dokumentet tillsammans med tiden vid k¨orning. Med den metoden skulle aldrig tv˚a likadana uid kunna uppst˚a i samma dokument. Tiden skulle ocks˚a medf¨ora att det ¨ar v¨aldigt osannolikt att tv˚a likadana uid skulle genereras, d˚a de skulle bli tvungna att k¨oras vid samma systemtid.

Systematiskt letade jag efter befintliga metoder f¨or att generera uid av olika slag. Jag hittade en rfc1 _{som behandlade UUID/GUID}2 _{(Leach et al., 2005).}

I denna rfc behandlar de flera olika s¨att att generera UUID beroende p˚a vilka tillg˚angar man har. En vanlig variant ¨ar att man anv¨ander sig av MAC3

adres-sen fr˚an sitt n¨atverkskort f¨or att garantera unikheten i ett UUID. Detta ¨ar inte alltid ¨onskv¨art, eftersom anonymiteten inte l¨angre garanteras. Alla UUID som genereras fr˚an samma dator kommer att inneh˚alla samma information, vilket

1_{Request for comments}

2_{Universally/Globally Unique Identifier.} 3_{MAC=Media Access Control}

28 KAPITEL 4. SKAPANDE AV PAKETET g¨or det m¨ojligt att sp˚ara datorn som genererat UUID. En av de minst restriktiva l¨osningarna liknar den jag n¨amnde ovan, men med kravet att n˚agra av siffrorna sattes till ett fast v¨arde och att den st¨allde krav p˚a hur str¨angen skulle repre-senteras. Ett av s¨atten som str¨angen kunde representeras p˚a var med hj¨alp av hexadecimala siffror. Orsaken till att anv¨anda hexadecimala siffror ¨ar att det blir effektivare att genomf¨ora dataoperationer p˚a dem.

Jag valde att h˚alla mig till den ide jag hade fr˚an b¨orjan och ett uid kan d˚a se ut s˚a h¨ar: 393bda28-59f1-0625-d865-a7a433e6751c. N¨ar jag f¨orst skapade den h¨ar koden s˚a anv¨ande jag mig av paketet lcg, f¨or att skaffa fram slumptal. Senare bytte jag till att anv¨anda \pdfuniformdeviate makrot ist¨allet, sek¨allkod 6. Det makrot finns med i pdfTEX och eftersom mitt paket bara ska fungera under pdfTEX, s˚a ¨ar den b¨attre l¨ampad.

K¨allkod 6 Skapande av ett hexv¨arde \def\owl@append@hex#1{% \setcounter{hex}{\pdfuniformdeviate16}% \ifnum\thehex<10% \xdef#1{#1\thehex}% \else% \addtocounter{hex}{-10}% \ifcase\thehex% \xdef#1{#1a}% \or\xdef#1{#1b}% \or\xdef#1{#1c}% \or\xdef#1{#1d}% \or\xdef#1{#1e}% \or\xdef#1{#1f}% \fi% \fi% }

Att anv¨anda sig av en MAC-adress ¨ar ingen bra l¨osning via LA_{TEX. Jag tror} att den enda rimliga v¨agen att kunna anv¨anda en s˚adan, ¨ar att l˚ata anv¨andaren ange en MAC-adress och jag tycker det k¨anns b¨attre att l˚ata allt ske automa-tiskt. Jag har inte anv¨ant mig av n˚agra fasta siffror som de f¨oresl˚ar till ett UUID, men s˚a kallar jag inte detta unika id f¨or ett UUID. Jag best¨amde mig f¨or att h˚alla mig till hexadecimala siffror. Motiveringen till att anv¨anda hexadecimala siffor ¨ar att befintlig kod f¨ormodas anv¨anda hexadecimala eller bin¨ara siffror4_.

F¨ordelen med hexadecimala siffror ¨ar att det ¨ar effektivt att utf¨ora bitoperatio-ner p˚a dem.

Orsaken till att jag valde att inte implementera ett UUID fullt ut eller att inf¨ora mina id´eer med r¨aknare och tid, ¨ar att jag bed¨ommer det som h¨ogst osannolikt att det finns ett behov av h¨ogre kvalitet h¨ar. Dessutom ¨ar det mycket enkelt att bara byta ut \owl@create@uid mot en ny metod i efterhand, om krav

4.2. SKAPA PDF ANNOTERING 29 p˚a en vis typ av uid uppkommer. Jag resonerade som s˚a, att tid sparad h¨ar ¨ar tid vunnen till viktigare delar av arbetet.

4.2

Skapa pdf annotering

F¨or att skapa pdf-annoteringar finns det ett antal makron i pdfTEX. Det mest flexibla makrot ¨ar \pdfannot. \pdfannot har flera frivilliga argument man kan ange f¨or att f˚a det beteende man vill. I mitt fall s˚a ¨ar det bara width och height som ¨ar relevanta. F¨orutom de frivilliga argumenten s˚a tar den in annoterings blocket, d¨ar man kan ange vilken data man vill. \pdfannot kommer att skicka ut datan precis som angivet direkt i pdf-filen. Jag skapar d¨arf¨or ett makro som f˚ar agera mall f¨or min rekonstruktion avk¨allkod 5, sek¨allkod 7. Makrot \pdfannotit tar fem stycken argument. Argument fyra och fem ¨ar bredden och h¨ojden p˚a annoteringen. Argument ett ¨ar datum och argument tre ¨ar ett uid. Argument tv˚a f¨orv¨antar sig ett grafiskt objekt. Jag ˚aterkommer snart till skapandet av ett grafiskt objekt.

K¨allkod 7 Makro f¨or pdf annoteringsobjekt \newcommand\annotit[5][\owlNow]{%

\pdfannot width #4 height #5{ /Subtype/ADBE:StampeT /T(Text Annotation) /M(D:#1) /UniqueID/#3 /AP<</N #2 0 R>>}% }

Den enklaste formen av annoteringar har ingen fast bredd och str¨acker sig inte ¨over flera rader. F¨or denna typ av annoteringar, skapade jag makrot \annotthis, sek¨allkod 8. Jag anv¨ander mig av en box h¨ar, f¨or att avg¨ora bred-den och h¨ojden p˚a texten. H¨ar ser man ocks˚a anv¨andandet av uid, som beskrevs irubrik 4.1. Efter att annotit har anropats s˚a sl¨apper jag bara ut texten, s˚a att den kan anv¨andas precis som vanligt av LA_TEX.

K¨allkod 8 Annotthis makro \newcommand\annotthis[1]{% \setbox0 = \hbox{#1}% \owl@create@uid\owl@objid% \annotit{\owl@color}{\owl@objid}{\the\wd0}{\the\ht0}% #1% }

Det som den observanta l¨asaren kan ha uppt¨ackt h¨ar ¨ar att \owl@color inte har beskrivits eller definierats. \owl@color ¨ar det grafiska pdf-objektet, som jag

30 KAPITEL 4. SKAPANDE AV PAKETET n¨amnde i beskrivningen av \annotit. Eftersom det grafiska objektet ¨ar det st¨alle man kan ¨andra f¨argen p˚a annoteringen s˚a har objektet f˚att namnet owl@color. Det ¨ar n¨amligen bara f¨argen som jag planerar att ¨andra i objektet. rubrik 4.3

inneh˚aller en utf¨orligare f¨orklaring om det h¨ar objektet.

Nu ˚aterst˚ar att skapa makron som g¨or det m¨ojligt att ha annoteringar som str¨acker sig ¨over mer ¨an en rad. Tv˚a makron skapar jag f¨or detta, \annotbox och \annotcapbox, sek¨allkod 9. \annotbox kommer att anv¨anda \annotthis endast om det ¨ar m¨ojligt, medan annotcapbox alltid kommer att omsluta texten i en box. Anledningen till att jag skapat dessa snarlika makron ¨ar att ibland ”fl¨ot” annoteringen iv¨ag ut l¨angs med sidan, n¨ar man anv¨ande annotbox. Vad jag menar med att annoteringen fl¨ot iv¨ag, ¨ar att annoteringen verkar f˚a en h¨ojd som ¨ar st¨orre ¨an vad som ryms p˚a sidan den befinner sig i. Jag kunde inte hitta n˚agon orsak till varf¨or det beter sig s˚a ibland, utan jag f˚ar vara n¨ojd med att det finns en l¨osning p˚a problemet.

Ett annat typ av makro som ¨ar ¨onskv¨art ¨ar ett makro som kan l¨opa ¨over fler rader, men utan begr¨asningen att s¨attas i en box. I LA_{TEX finns det m˚anga} makron som redan fungerar p˚a det viset och de b¨orjar d˚a med \begin{makro} . . . \end{makro}. D¨arf¨or vore det p˚a sin plats med ett \begin{annot} med tillh¨orande slut. Tyv¨arr lyckades jag aldrig skapa ett s˚adant makro. Jag spen-derade mycket tid p˚a att prova olika l¨osningar och det n¨armaste jag kom var ett ord-f¨or-ord annoterande makro. Det makrot l¨aste tecken f¨or tecken och n¨ar det hade l¨ast ett helt ord, skapade det en annotering f¨or ordet. Denna l¨osning ¨ar inte bra, d˚a den skapar ett stort ¨overfl¨od av annoteringar, samt att den inte klarade av svenska tecken. Koden f¨or det h¨ar makrot finns kvar i paketet ifall n˚agon verkligen m˚aste anv¨anda det eller om n˚agon vill f¨ors¨oka l¨osa dess problem.

Orsaken till att den h¨ar typen av makron ¨ar s˚a sv˚ara att skapa i LA_{TEX, ¨ar} att det inte finns n˚agot s¨att att veta vart p˚a en rad man befinner sig. LA_TEX laborerar sj¨alv med hur m˚anga ord den ska ha p˚a varje rad och hur mycket utrymme olika typer av ”whitespace” kr¨aver.

4.3

Annoteringens f¨

arg

Det var m˚anga fr˚agetecken kring hur f¨arger skulle hanteras fr˚an b¨orjan. De exempel (rubrik 3.1) som fanns anv¨ande sig endast av en gul f¨arg, vilket inte ¨

ar speciellt diskret. Det ¨ar ganska troligt att folk som anv¨ander paketet inte vill ha en s˚a utm¨arkande f¨arg, s˚a d¨arf¨or m˚aste paketet ˚atminstone ha n˚agra fler f¨argalternativ.

F¨orst t¨ankte jag anv¨anda ett antal f¨ordefinierade f¨arger. Det k¨andes som en l¨osning som inte innebar speciellt mycket jobb och det skulle g¨ora det enkelt att anv¨anda. Det finns ocks˚a en klar nackdel, d˚a anv¨andaren kanske inte ¨ar n¨ojd med de f¨arger som skulle finnas att v¨alja p˚a. En annan nackdel ¨ar att det skapar flera oanv¨anda objekt i pdf-filen, beroende p˚a att valet av f¨arg g¨ors i pdf-filens grafiska objekt och varje f¨arg kommer att beh¨ova sitt eget objekt. F¨or att minimera antalet on¨odiga objekt, b¨or man d¨arf¨or begr¨ansa antalet f¨arger.

4.4. SKRIVA UT METADATA 31 K¨allkod 9 Annotering f¨or mer ¨an en rad

\newcommand\annotcapbox[2][\textwidth]{% \setbox0 = \hbox{#2}% \ifdim\wd0>#1% \raisebox{-\height+0.7em}{\annotthis{\parbox[b]{#1}{#2}}}% \else% \raisebox{-\height+0.62em}{\annotthis{\parbox[b]{\wd0}{#2}}}% \fi% } \newcommand\annotbox[2][\textwidth]{% \setbox0 = \hbox{#2}% \ifdim\wd0>#1% \raisebox{-\height+0.7em}{\annotthis{\parbox[b]{#1}{#2}}}% \else% \annotthis{#2}% \fi% }

f¨arg. Eftersom ett grafiskt objekt m˚aste finnas f¨or varje f¨arg, kr¨avs det att anv¨andaren skapar en f¨arg innan den kan anv¨andas. Detta l¨agger lite mer arbe-te p˚a anv¨andaren, men ger denne ocks˚a full flexibilitet i sitt f¨argval. Det h¨ar blev min slutgiltiga l¨osning, tillsammans med n˚agra paketval som l˚ater anv¨andaren skapa f¨arger som finns f¨ardigdefinierade, se k¨allkod 10. De f¨ardigdefinierade f¨argerna trycks ut direkt i pdf-filen, om de skickas som argument till \usepackage. K¨allkod 10 F¨argen r¨od skapas och v¨aljs h¨ar till aktiv f¨arg

\newcounter{myred}

\createowlcolor{myred}{1 0 0 rg} \setowlcolor{myred}

En r¨aknare anv¨ands h¨ar f¨or att h˚alla reda p˚a vilket grafiskt objekt som f¨argen representeras av. Den k¨anns ¨aven ganska intuitiv, d˚a man kan se det som en referens till sin f¨arg, om man inte ¨ar insatt i vad som p˚ag˚ar under ytan! \owlcolor ¨ar det makro som skapar det grafiska objektet och det s˚ag slutligen ut enligtk¨allkod 11.

4.4

Skriva ut metadata

Vid kompilering av dokumentet s˚a skrivs metadata ut till en separat fil. Denna fil inkluderas sedan vid slutet av dokumentet via \AtEndDocument. Metadatan till ett stort dokument kan bli v¨aldigt stor, d¨arf¨or ¨ar det en f¨ordel att mellanlagra metadatan p˚a fil. Det var oklart f¨or mig hur stor data LA_{TEX skulle klara av att} hantera, d¨arf¨or tycker jag det h¨ar ¨ar det s¨akra valet. Vid fortsatt utveckling av

32 KAPITEL 4. SKAPANDE AV PAKETET K¨allkod 11 Skapandet av ett grafiskt objekt i createowlcolor makrot

\newcommand\createowlcolor[2]{% \immediate\pdfobj stream attr{

/Subtype /Form /Type /XObject

/Resources<</ProcSet[/PDF/Text]

/ExtGState <</GS1<</Type/ExtGState/ca 1.0/BM/Darken>>>>>> /BBox [0 0 100 100]

/FormType 1

}{q /GS1 gs 1 1 0 RG #2 0 0 100 100 re f Q}% \setcounter{#1}{\the\pdflastobj}%

}

paketet kan det vara intressant att internt lagra datan ist¨allet och g¨ora tester p˚a stora dokument.

Ett problem som uppst˚ar n¨ar man skriver ut till fil ¨ar att vissa tecken kan tolkas felaktigt. Jag har hittills p˚atr¨affat tv˚a olika situationer d¨ar detta intr¨affar. Det ena ¨ar att svenska tecken skrivs ut med LA_{TEX-koden, f¨or att generera} teck-net ist¨allet f¨or att tecknet skrivs ut. Detta var ett problem som aldrig blev l¨ost och jag hittade ingen hj¨alpande information p˚a omr˚adet. Det andra problemet jag uppt¨ackte var att # tecknet dupliceras vid utskrift. Detta problem har jag kunnat l¨osa genom att ¨andra dess catcode. Catcode ¨ar en kod som avg¨or hur LA_{TEX ska tolka just det tecknet. Jag skapade d¨arf¨or ett makro som jag kallar} \owlHash, som kan anv¨andas ist¨allet f¨or #, sek¨allkod 12. Notera hur koden ¨ar innesluten i en grupp f¨or att inte ¨andringen ska p˚averkas globalt och hur \gdef anv¨ands f¨or att f˚a makrodefinitionen att g¨alla globalt.

K¨allkod 12 Makrot owlHash som l¨oser problemet med duplicerade # \begingroup

\catcode‘\#=11 \gdef\owlHash{#} \endgroup

4.5

Autogenererad metadata

Ifr˚an f¨orsta b¨orjan var det t¨ankt att paketet skulle erbjuda ett antal vanligt f¨orekommande makron, som automatiskt skulle skapa annoteringar och gene-rera metadata. Men under utvecklandets g˚ang s˚ag jag bristerna i ett s˚adant paket. Dels skulle det hj¨alpa anv¨andaren f¨oga, om han beh¨over n˚agon form av metadata som det inte finns support f¨or i paketet. sedan ins˚ag jag att det ur underh˚allssynpunkt ¨and˚a vore bra om koden till paketet ¨ar s˚a flexibelt, att det ¨

4.5. AUTOGENERERAD METADATA 33 att metadatan som beh¨ovde genereras f¨or olika delar av dokumentet hade stora delar gemensamt. D¨arf¨or skapade jag makrot \owlPartOut (k¨allkod 13), som en mall f¨or alla annoteringar som r¨or vanliga dokumentdelar. Det h¨ar makrot ser f¨ormodligen ganska "r¨origt" ut f¨or den som inte arbetat med koden. Det ¨ar inte l¨att att skriva snygg owl-kod inom LA_{TEX. Det som g¨or att det h¨ar} mak-rot bidrar till flexibiliteten ¨ar argument #5. Argument #5 ligger inom Docpart (figur 5.1) elementet och man kan d¨arf¨or f¨ora in precis hur m˚anga element till ett Docpart man vill. Detta g¨or det mycket enkelt att skapa fler makron som ¨ar av typen Docpart. F¨or att se ett exempel p˚a hur detta makro kan anv¨andas, se

k¨allkod 14.

K¨allkod 13 Makrot owlPartOut \newcommand\owlPartOut[5][Docpart]{% \stepcounter{owlAnnotationNumber}% \xdef\owlPartList{\owlPartList% \owlTab<Annotations rdf:resource=% "\owlHash Annotation_\theowlAnnotationNumber"/>^^J% \owlTab<Docparts rdf:resource="\owlHash #4"/>^^J% }% \owlWriteOut{% <Annotation rdf:ID="Annotation_\theowlAnnotationNumber">^^J% \owlTab<Target>^^J% \owlTabb<#1 rdf:ID="#4">^^J% \owlTabbb<Caption rdf:datatype="&xsd;string">^^J% \owlTabbbb#3^^J% \owlTabbb</Caption>^^J% \owlTabbb<ShortCaption rdf:datatype="&xsd;string">^^J% \owlTabbbb#2^^J% \owlTabbb</ShortCaption>^^J% #5\owlTabbb<Doc rdf:resource="\owlHash\@pdftitle"/>^^J% \owlTabb</#1>^^J% \owlTab</Target>^^J% \owlTab<UniqueID rdf:datatype="&xsd;string">^^J% \owlTabb\owl@objid^^J% \owlTab</UniqueID>^^J% </Annotation>^^J% }% }

Efter att jag hade gjort makrot \owlPartOut, ins˚ag jag att man kan g¨ora det ¨annu mer flexibelt f¨or anv¨andaren, utan att det st¨or n˚agon av den befintliga koden. Med \owlPartOut som mall gjorde jag makrot \addannotmetadata, se

k¨allkod 15. Makrot tar tv˚a stycken argument. Det f¨orsta argumentet ¨ar namnet p˚a elementet man skapar och det andra ¨ar den metadata man vill inf¨ora ut¨over den som s¨atts automatiskt. P˚a det h¨ar viset kan en anv¨andare skapa en ny typ av Docpart utan att k¨anna till n˚agra implementeringsdetaljer. Koden till mak-rot ¨ar snarlikt \owlPartOut, d¨ar den stora skillnaden hittas i mitten. Det ¨ar

34 KAPITEL 4. SKAPANDE AV PAKETET K¨allkod 14 Annotsection \def\annotsection{% \setlength{\owl@width}{\textwidth}\addtolength{\owl@width}{-2em}% \@ifnextchar[{\owlAnnotSectionOpt}{\owlAnnotSection}% } \def\owlAnnotSection#1{% \section[#1]{\annotcapbox[\owl@width]{#1}}% \owlPartOut{#1}{#1}{Section_\thesection} {\owlChapter} } \def\owlAnnotSectionOpt[#1]#2{% \section[#1]{\annotcapbox[\owl@width]{#2}}% \owlPartOut{#1}{#2}{Section_\thesection} {\owlChapter} }

koden som g¨or att anv¨andaren kan anv¨anda tecken som # eller \\ ist¨allet f¨or att ange kod som ¨ar implementeringsspecifik. Den ser n¨amligen till att tabin-denteringen passar in i mallen, utan att anv¨andaren beh¨over fundera p˚a det. Det ¨ar ocks˚a mycket praktiskt n¨ar den interna koden uppdateras i framtiden, d˚a kan anv¨andaren fortfarande ha kvar sin egendefinierade kod f¨or metadata.

Den h¨ar flexibiliteten r¨acker dock inte riktigt till. Om anv¨andaren ska ha riktigt stor nytta av att kunna l¨agga till nya element inuti en Docpart, d˚a m˚aste han ocks˚a kunna skapa sina egna egenskaper (properties). F¨or detta ¨andam˚al skapade jag makrot \insertmetadata (k¨allkod 16). Det h¨ar makrot trycker i princip ut ren owlkod direkt i ontologin. F¨orutom att tecknen # och \\ ¨andras till utskriftsrepresentanten av samma tecken. Koden hamnar p˚a exakt den plats i ontologin som makrot anropas, d¨arf¨or ¨ar det l¨ampligt att skapa nya klasser och egenskaper tidigt i dokumentet. Man kan dock inte inf¨ora n˚agon metadata innan man har k¨ort \begin{document}, eftersom owl-paketet ¨oppnar filstr¨ommen i \AtBeginDocument. Jag har ¨overv¨agt att l˚ata den h¨ar koden k¨oras direkt man laddat paketet. Om man g¨or p˚a det viset, s˚a inneb¨ar det att man h˚aller en filstr¨om ¨oppen, medan andra paket eventuellt laddas in. Jag ¨ar os¨aker p˚a om det skulle vara ¨onskv¨art eller ej, s˚a jag har l¨amnat det i \AtBeginDocument tills vidare.

4.6

Annotering av referenslista

Referenser i LA_{TEX hanteras av det externa programmet bibTEX, serubrik 2.6.} BibTEX anv¨ander sig av en databasfil (bib) f¨or att l¨asa information och en stilfil (bst) f¨or att avg¨ora utseendet p˚_{a en referensentitet. BibTEX producerar sen en fil} (bbl) inneh˚allande LA_{TEX-milj¨on thebibliography. Den sistn¨amnda filen ¨ar riktig} LA_{TEX-kod och de makron som finns i den, processas p˚a samma s¨att som alla} andra makron. F¨or att f˚a all den data som beh¨ovs till att generera metadata

4.6. ANNOTERING AV REFERENSLISTA 35

K¨allkod 15 Makrot addannotmetadata \newcommand\addannotmetadata[2]{%

% make metatada part of the document \stepcounter{owlAnnotationNumber}% \xdef\owlPartList{\owlPartList% \owlTab<Annotations rdf:resource= "\owlHash Annotation_\theowlAnnotationNumber"/>^^J% \owlTab<Docparts rdf:resource="\owlHash #1"/>^^J% }% \def\owlOutput{#2} \@ifpackageloaded{toolbox}{% % clean up the output

\toolboxReplace{\#}{\owlHash}\owlOutput \toolboxReplace{\\}{^^J\owlTabbb}\owlOutput }{}

% insert user metadata into docpart template \xdef\owlOutput{% <Annotation rdf:ID="Annotation_\theowlAnnotationNumber">^^J% \owlTab<Target>^^J% \owlTabb<Docpart rdf:ID="#1">^^J% \owlTabbb<Doc rdf:resource="\owlHash\@pdftitle"/>^^J% \owlTabbb\owlOutput^^J% \owlTabb</Docpart>^^J% \owlTab</Target>^^J% \owlTab<UniqueID rdf:datatype="&xsd;string">^^J% \owlTabb\owl@objid^^J% \owlTab</UniqueID>^^J% </Annotation>^^J% }% \immediate\write\owlwrite{\owlOutput}% }

K¨allkod 16 Insertmetadata makrot \newcommand\insertmetadata[1]{% \def\owlOutput{#1} \@ifpackageloaded{toolbox}{% \toolboxReplace{\#}{\owlHash}\owlOutput \toolboxReplace{\\}{^^J}\owlOutput }{} \immediate\write\owlwrite{\owlOutput}% }

36 KAPITEL 4. SKAPANDE AV PAKETET och skapa annoteringen, s˚a m˚aste makron in i sistn¨amnda filen. Inf¨orandet av egna makron i filen kr¨aver att stilfilen modifieras.

Vid skapandet av annoteringen beh¨over man omsluta en entitet med makrot \annotbib, som jag skapat specifikt f¨or det ¨andam˚alet. I de stilfiler som f¨oljer med paketet natbib s˚a b¨orjar alla entiteter med funktionen output.bibitem och avslutas med fin.entry. Det g¨or modifieringen v¨aldigt enkel, jag inf¨or f¨oljande rad i slutet p˚a output.bibitem:

"\annotbib{" write$

Sedan inf¨or jag f¨oljande rad innan radbrytningen i fin.entry: "}" write$

Formateringen av olika delar av en referens sker i olika funktioner i stilfilerna. De stilfiler jag modifierat f¨or att fungera, har jag lagt till funktionerna: owltitle, owlauthor, owldate och owlkey. Alla dessa funktioner byggs upp p˚a samma s¨att, sek¨allkod 17f¨or ett exempel. Mina nyskapade funktioner kan sedan anv¨andas p˚a de funktioner som st˚ar f¨or formateringen av de olika delarna av en referens. K¨allkod 17 Stilfunktioner FUNCTION {owltitle} { duplicate$ empty$ { pop$ "" } { "\owlTitleRef{" swap$ * "}" * } if$ }

Om man tittar p˚a k¨allkoden, ¨ar alla de funktioner jag lagt till likadana och beter sig enligt f¨oljande m¨onster:

• H¨amta data fr˚an stacken.

• Omslut det h¨amtade v¨ardet med ett makro. • Stoppa tillbaka data p˚a stacken.

Om ytterligare metadata fr˚an referenserna ¨onskas fram¨over, ¨ar det bara att skapa fler funktioner efter denna mall och inf¨ora dem p˚a ¨onskv¨arda st¨allen i stilfilerna. Efter det som presenterats i det h¨ar stycket ska det vara ganska enkelt att modifiera vilken stilfil som helst till att fungera med owl-paketet.

Kapitel 5

Dokumentation

Dokumentation ¨ar alltid viktigt, d˚a det ofta st˚ar f¨or anv¨andarnas f¨orsta intryck. Det ¨ar ocks˚a viktigt f¨or att underl¨atta vid ut¨okning av paketet och f¨or underh˚all. Man kan tycka att ontologidelen inte riktigt passar in h¨ar. Orsaken ¨ar att den ¨ar v¨aldigt tunn och inte speciellt utvecklad. Jag r¨aknar d¨arf¨or med att den kommer att beh¨ova ers¨attas eller byggas ut och d˚a ¨ar det l¨ampligt att den befinner sig i dokumentationsdelen.

5.1

Ontologi

Arbetet kr¨aver tv˚a ontologier, en f¨or ett specifikt dokument och en generell f¨or alla dokument. Den generella skapar klasser f¨or dokumentstrukturen och inneh˚aller egenskaper f¨or att l¨anka samman klasser. Sefigur 5.1f¨or ett klassdi-agram ¨over den generella ontologin. Koden f¨or ontologin hittas ibilaga A. Den dokumentspecifika ontologin genereras vid kompilering av LA_TEX.

Figur 5.1: Klassdiagram ¨over pdfontologin

38 KAPITEL 5. DOKUMENTATION

5.2

Ut¨

okning och underh˚

all

Paketet ¨ar designat med ut¨okning i ˚atanke. I rubrik 4.5 g˚ar jag igenom flera makron som ¨ar specifikt designade f¨or att underl¨atta ut¨okning. Jag ser det h¨ar som en v¨aldigt viktig punkt, d˚a det h¨ar kan vara f¨orsta steget mot betydligt mer avancerad anv¨andning av metadatan. Mer avancerad anv¨andning inneb¨ar med st¨orsta sannolikhet att nya krav beh¨over inf¨oras och ¨aven krav p˚a att befintlig kod ¨ar l¨att att modifiera. Jag har d¨arf¨or under utvecklandet av paketet varit noga med strukturen p˚a koden. Kod som kommer att p˚averka hela paketet har separerats fr˚an ¨ovrig kod. Det g¨or att man kan inf¨ora ¨andringar som ska p˚averka hela paketet genom att ¨andra p˚a ett enda st¨alle i koden.

Jag har ocks˚a f¨ors¨okt att h˚alla mig till en syntaxstil som ska underl¨atta f¨or l¨asaren. Jag har anv¨ant konventionen att b¨orja alla interna makron med pre-fixet owl och f¨oljt av flera ord med b¨orjan p˚a stor bokstav. Makron som ¨ar avsedda f¨or anv¨andaren skrivs alltid med sm˚a bokst¨aver och inleds inte med prefixet owl. Alla ”rena” annoteringsmakron har ocks˚a namnkonventionen att b¨orja med annot i sina namn. Med ”ren”menar jag att makrot skapar en anno-tering via de generella makron som finns definierade i paketet. F¨or att ett makro inte ska vara ”rent”, s˚a kan det vara konstruerat via \annotit och har d¨arf¨or f¨orbipasserat \annotthis. Det kan h¨anda att anv¨andaren kommer i kontakt med makron som b¨orjar med owl prefixet, trots att det ¨ar ett internt makro. Detta f¨orekommer vid avancerad anv¨andning, d˚a det blir tvunget att anv¨anda en mera intern syntax f¨or att m¨ojligg¨ora vissa funktioner. Ett exempel p˚a ett makro som f¨orekommer bland anv¨andaren ¨ar \owlTab, som anv¨ands internt f¨or att f˚a r¨att tabindentering. Det ¨ar m¨ojligt att anv¨anda \space ist¨allet, men d˚a finns risken att storleken p˚a indenteringen skiljer sig fr˚an den interna.

5.3

Manual

I LA_{TEX finns det ett system f¨or att skapa dokumentation till sin k¨allkod.} Forma-tet kallas doc och har idag ¨andelsen dtx. Till mycket gamla system kan ¨andelsen f¨orekomma som doc. Tanken bakom docsystemet ¨ar att kod och dess manual ska skrivas i samma fil. Utifr˚an dtx-filen kan sedan en vanlig paketfil (sty) genereras och ¨aven en manual. Det h¨ar formatet s¨ags vara bra f¨or stora paket och paket d¨ar flera personer arbetar med samma kod (Clsguide).

Ingen av ovann¨amnda f¨ordelar g¨aller i mitt fall. Jag f¨oredrar personligen att ha en bra ¨overblick p˚a den kod jag arbetar med och det anser jag att jag inte f˚ar, om dokumentationen befinner sig i samma dokument som k¨allkoden. Det h¨ar argumentet v¨ager tungt med tanke p˚a hur mycket tid jag sj¨alv skulle spendera med k¨allkoden under arbetets g˚ang.

Ist¨allet f¨or doc modellen att f¨ora dokumentation p˚a, skapar jag en pdf-manual. Notera att alla som ska kunna ha n˚agon nytta av mitt paket, m˚aste ha en pdf-l¨asare. Det st¨aller d¨arf¨or inga nya krav p˚a anv¨andaren. Jag vill ocks˚a un-derl¨atta distributionen av paketet och har d¨arf¨or best¨amt mig f¨or att inkludera k¨allkod och n˚agra exempelfiler till manualen. D˚a beh¨over bara en fil distribueras

5.3. MANUAL 39 f¨or hela paketet.

Jag anser personligen att manualen till ett paket ¨ar oerh¨ort viktig. Jag tror att f¨orsta intrycket spelar stor roll f¨or f¨ortroendet som folk f˚ar f¨or paketet. D¨arf¨or har jag lagt ner ganska mycket energi p˚a att f˚a manualen att k¨annas professionell och v¨alstrukturerad.

F¨or att f˚a manualen s˚a bra som m¨ojligt, b¨orjade jag med att bilda mig en uppfattning om hur en manual kan anv¨andas. Jag har sj¨alv l¨ast v¨aldigt m˚anga manualer till olika LA_{TEX-paket under arbetets g˚ang och tror mig d¨arf¨or ha en} ganska bra uppfattning om hur man brukar anv¨anda dem. H¨ar ¨ar en lista p˚a olika utg˚angsl¨agen en anv¨andare kan ha, innan han/hon b¨orjar l¨asa om paketet.

1. Anv¨andaren vill l¨asa om n˚agra specifika makron.

2. Anv¨andaren ¨ar intresserad av en eller flera implementeringsdetaljer. 3. Anv¨andaren vill veta vad det ¨ar fr˚agan om!

4. Anv¨andaren ¨ar nyfiken p˚a paketet i helhet.

5. Anv¨andaren ¨ar genuint intresserad av paketet i helhet.

F¨or att underl¨atta f¨or anv¨andaren vid punkt ett, ¨ar det viktigt att det g˚ar snabbt att hitta ett specifikt makro. D¨arf¨or har jag noggrant valda rubriknamn, som g¨or att han/hon snabbt kan ta sig till r¨att typ av makro. I texten har jag valt att visa makron med en tydlig bl˚a f¨arg, f¨or att det snabbt ska g˚a att hitta vart i texten som ett specifikt makro behandlas. Det finns ocks˚a en lista ¨

over alla befintliga makron, d¨ar man snabbt ¨aven kan se till vilken kategori ett specifikt makro tillh¨or. Listan, best˚aende av l¨ankar i b¨orjan p˚a dokumentet kan vara v¨aldigt anv¨andbart om man ¨ar ute efter att se ett exempel p˚a hur ett visst makro anv¨ands.

Om anv¨andaren ¨ar intresserad av implementeringsdetaljer, finns det en egen sektion f¨or det. Sektionen klipper in delar av koden och kommenterar vad den ¨

ar till f¨or och hur l¨osningen fungerar. De svagt lila boxarna ramar in koden p˚a ett tydligt s¨att och kompletteras med en marginalnotering, som beskriver vad koden handlar om. Marginalnoteringar g¨or det mycket snabbare att hitta i koden, avsett f¨or de som vet vad de letar efter.

Anv¨andare av kategori tv˚a ¨ar oftast en anv¨andare som bara snubblat ¨over paketet eller rekommenderats dit av n˚agon. Denna anv¨andare har eventuellt ingen aning om vad han/hon ger sig in i och kommer d¨arf¨or f¨ormodligen att b¨orja fr˚an b¨orjan p˚a dokumentet. F¨or den h¨ar anv¨andaren finns ett kort intro-duktionsstycke med referenser till information om den semantiska webben och owl. Det presenterar ocks˚a paketets syfte och kort om hur paketet fungerar.

En anv¨andare som ¨ar nyfiken b¨orjar f¨ormodligen att l¨asa manualen fr˚an b¨orjan till slut, s˚avida det inte blir f¨or tr˚akigt och avancerat. D¨arf¨or p˚apekas det f¨or l¨asaren innan manualen g˚ar in p˚a mera avancerade makron, att det kan vara l¨ampligt att hoppa ¨over resten av stycket.

Anv¨andare av kategori fem ¨ar f¨ormodligen intresserad av att ut¨oka eller ¨

40 KAPITEL 5. DOKUMENTATION avsett. F¨orutom detta specifika stycke, ¨ar troligen merparten av manualen av intresse, m¨ojligen introduktionen undantagen.

Kapitel 6

Testning

I det h¨ar kapitlet sammanfattar jag arbetet runt testningen som gjorts av pa-ketet. Resultat av test sammanfattar vad som kom fram under testningen och ¨

ovriga stycken g˚ar igenom vad jag vidtagit f¨or ˚atg¨arder efter testningen.

6.1

Resultat av test

En test av paketet utf¨ordes med hj¨alp av tv˚a frivilliga LA_{TEX-anv¨andare. Jag} f¨orklarade kort f¨or en av dem hur det ¨ar t¨ankt att fungera. Sedan skickades en tidig version av manualen via epost. Efter att de har testat paketet f˚ar jag feedback tillbaka via epost.

Testens syfte ¨ar att uppt¨acka brister och f˚a ˚asikter om paketet. H¨ar ¨ar en sammanfattande lista p˚a intressanta brister som kom fram vid testningen:

• Paketen toolbox och lcg finns inte i standard-LA_TEX. • Annoteringar med indexpaketet ¨ar ¨onskv¨art. • Integrering med emacs+AUCTEX.

• Nyckelord f¨or ett dokument.

Orsaken till att icke standardpaket har anv¨ants, ¨ar att de f¨oljt med min distribution av LA_{TEX (mikTEX). Testpersonen har uppt¨ackt detta problem tack} vare att han anv¨ant en annan distribution (teTEX).

6.2

Emacs

Integrering med emacs kommer jag inte att f¨ors¨oka mig p˚a, d˚a det ligger i utkanten f¨or jobbets ramar. Dessutom ¨ar mina erfarenheter av emacs ganska bristf¨alliga och riskerar d¨arf¨or att ta upp mera tid ¨an n¨odv¨andigt f¨or arbetet.

42 KAPITEL 6. TESTNING

6.3

Koppla loss paket

Det f¨orsta jag tog itu med efter testerna var de paket som inte levereras med standard-LA_{TEX. Det ¨ar h¨ogprioriterat att paketet kan k¨oras utan att f¨or m˚anga} externa paket beh¨over h¨amtas hem. Lcg-paketet hade jag redan innan funde-rat p˚a att koppla loss, d˚a dess funktionalitet b˚ade var ganska simpel och jag misst¨ankte att pdfTEX inneh¨oll liknande funktionalitet. Det visade sig att en-dast en rad i koden beh¨ovde ers¨attas, f¨or att koppla loss lcg-paketet.

Att koppla loss toolbox blev ett betydligt st¨orre projekt. Jag hade anv¨ant paketet f¨or att underl¨atta vid skapande av nya makron, vilket gjorde att det anv¨andes p˚a stora delar av paketet. Jag b¨orjade med att byta ut vissa makron, som jag l¨att kunde ers¨atta genom att skapa nya egna eller hitta motsvarigheter i standard-LA_{TEX. Makrot \owlharmless (k¨allkod 18) fick jag skapa f¨or att skydda} metadata fr˚an att f˚a in makron/tecken, som kan orsaka kompileringsfel. Detta makrot ers¨atter ett makro med deras namn ist¨allet f¨or deras inneh˚all, exempel: \LaTeX{} beh˚aller sitt utseende ist¨allet f¨or att ers¨attas med LA_TEX.

K¨allkod 18 Kod f¨or att skydda metadata

\def\owlHarmless#1{\edef#1{\owlNearverbatim#1}} \def\owlNearverbatim{\expandafter\owlMeaning\meaning} \long\def\owlMeaning#1>{}

Slutligen fanns det ett makro jag inte klarade av att ers¨atta och det var \toolboxReplace. Definitionen p˚a makrot var f¨or komplicerat, f¨or att jag skulle kunna skapa en ers¨attare till det och jag hade sedan tidigare f¨ors¨okt mig p˚a lik-nande makron sj¨alv, utan framg˚ang. Problemen med den h¨ar typen av makron ¨

ar att det finns ganska m˚anga tecken/makron som LA_{TEX hanterar annorlunda,} vilket g¨or det sv˚art att ta h¨ansyn till alla m¨ojligheter. Problemet l¨oses slutli-gen med kompromissen att viss funktionalitet i paketet st¨angs av om inte filen toolbox.sty kan hittas. Om anv¨andaren f¨ors¨oker anv¨anda denna funktionalitet kommer han att f˚a en varning som ber¨attar vad problemet ¨ar. Makron som ¨ar p˚averkade av detta ¨ar de som kan ta in metadata via anv¨andaren och p˚averkar allts˚a inga av de automatiska makron som finns.

I samband med frig¨orandet fr˚an toolbox, ins˚ag jag att jag borde koppla bort paketet natbib p˚a samma s¨att. Om anv¨andaren f¨ors¨oker anv¨anda sig av natbib-funktionalitet utan att ha laddat paketet kommer en varning att ges.

6.4

Annotering av index

N¨ar jag l¨aste f¨orslagen p˚a index, fick det mig att t¨anka igenom anv¨andningsomr˚aden f¨or metadatan. Metadatan ¨ar t¨ankt att anv¨andas f¨or att f˚a detaljerad informa-tion om dokumentets inneh˚all. Det st˚ar d˚a klart att just index ¨ar en oerh¨ort viktig del. Se rubrik 7.2f¨or flera av de saker jag kom fram till, som jag tycker ¨