Programmering i Ruby

Den Pragmatiske Programmerers Veiledning

Forrige < Innhold ^
Neste >

Innebakt dokumentasjon



Figur A.1: rd kildefil

Figur A.2: Utput fra kilden i figur A.1

Så sitter du der, med et mesterverk, en klasse av ypperste klasse, og du ønsker å dele ditt arbeid med hele verden. Men siden du er en ansvarsbevisst utvikler, føler du behov for å dokumentere ditt verk. Hva gjør du da? Den enkleste løsningen er å bruke Ruby sitt innebygde dokumentasjonsformat, RD, og rdtool, en samling Ruby verktøy som kan konvertere denne dokumentasjonen til forskjellige format.

rdtool søker gjennom en fil på jakt etter =begin og =end par og tar tak i teksten den finner mellom alle parene. Verktøyet antar at teksten er i RD-format og den blir deretter omformet ut fra et enkelt sett av regler:

Indentert tekst som ikke er del av en liste blir satt urørt inn (slik som teksten under ``Synopsis'' i figur A.1 og A.2).

Inline formatering

Inne i tekstblokker og overskrifter kan du bruke spesielle inline sekvenser for å kontrollere formateringen. Alle sekvensene er nøstet inne i et sett av doble parenteser.

Sekvens Eksempel Brukes til
((*utheving*)) utheving Utheving (vanligvis kursiv)
(({programkode})) programkode Programkode
((|variabel|)) variabel Variabelnavn
((%tast meg%)) tast meg Innput fra tastatur
((:indekseringsterm:)) indekseringsterm Noe som skal indekseres
((<referanse>)) referanse Hypertekstreferanse
((-fotnote-)) tekst.4 Fotnoter. En referanse plasseres i hvor fotnoten forekommer, og selve innholdsteksten til fotnoten befinner seg på bunnen av siden.
(('verb')) verb Verbatim tekst

Kryssreferanser

Innholdet i overskrifter, merkelappene i merkelappslister og metodenavn blir automatisk til kryssreferansemål. Du kan lenke til disse målene fra andre steder i dokumentet ved å sitere innholdet inne i ((<...>)) konstruksjonen.

= Synopsis
...
See ((<Return Codes>)) for details.
..
== Instance Methods

--- Tempfile.open( filename )     Opens the file...

== Return Codes .. The method ((<Tempfile.open>)) raises an (({IOException}))...

Dersom en referanse starter med ``URL:'' vil rdtool forsøke å formatere det som en ekstern hypertekstlenke.

Referansen ((<visningsdel|merkelapp>)) lager en lenke til merkelapp med plasserer teksten ``visningsdel'' i det genererte dokumentet. Dette blir brukt i beskrivelsesdelen av eksempelet i figur A.1 på side 512 for å lage referanse til metodenavnene:

perspective, apart from the unusual ((<(({new}))|Tempfile.new>)),
...

Konstruksjonen viser ordet ``new'' i programkodefonten, men lager en hypertekstlenke til metoden Tempfile.new.

Metodenavn

rdtool gjør visse antagelser om hvordan metodenavn formateres. Klasse- eller modulmetoder bør skrives som Klasse.metode, instansmetoder som Klasse#metode og klasse- eller modulkonstanter som Klasse::Konstant.

--- Tempfile::IOWRITE
    Open the file write-only.
    ...
--- Tempfile.new( filename )
    Constructs a temporary file in the given directory. The file
    ...
--- Tempfile#open
    Reopens ((|aTempfile|)) using mode ``r+'', which allows reading
    ..

Inkludere andre filer

Innholdet til filnavn vil bli satt inn der hvor dokumentet inneholder

<<< filnavn

Dersom filen angis med en endelse på .rd eller .rb vil den bli behandlet som RD-dokumentasjon.

Dersom filnavnet ikke har noen endelse vil rdtool lete etter en fil med en endelse som passer med typen dokumentasjon som generes (.html for HTML-filer, .man for man-filer og så videre) og interpolere den filens innhold i utputstrømmen. Dermed vil en linje som:

<<< hode

kunne brukes til å legge til et utputavhengig hode til det genererte dokumentet.

Bruke rdtool

RD-dokumentasjon kan inkluderes direkte i et Ruby kildeprogram eller skrevet i en separat fil (som konvensjonen sier skal ha endelsen .rd). Disse filene behandles ved hjelp av rd2-kommandoen for å lage passende utput.

rd2  [
            opsjoner
            ]  innputfil   [ >utputfil ]

Noen vanlige opsjoner er:

-r format Velg et utputformat. -rrd/rd2html-lib.rb produserer HTML (og er standardvalget) -rrd/rd2man-lib.rb produserer Unix man-sider.
-o navn Setter stammen til utputfilnavnet.
--help Lister alle opsjonene.

Obligatorisk ansvarsfraskrivelse

Samtidig som vi skriver dette, gjennomgår RD og rdtool stadig utvikling. Det er høyst sannsynlig at noen av detaljene vi har gitt her vil ha gått ut på dato (eller være feil) innen du leser dette.

Inkludert i rdtool-distribusjonen er filen README.rd. Vi foreslår at du gjør som filenavnet ber deg, slik at den kan gi deg siste nytt innen produksjon av Ruby-dokumentasjon.


Forrige < Innhold ^
Neste >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide".
Translation to norwegian by Norway Ruby User Group.
Copyright for the english original authored by David Thomas and Andrew Hunt:
Copyright © 2001 Addison Wesley Longman, Inc.
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at
http://www.opencontent.org/openpub/).

(Please note that the license for the original has changed from the above. The above is the license of the original version that was used as a foundation for the translation efforts.)

Copyright for the norwegian translation:
Copyright © 2002 Norway Ruby User Group.
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at
http://www.opencontent.org/openpub/).
Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.
Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.