Der Leitfaden der Pragmatischen Programmierer

Eingebettete Dokumentation

Figur 0A.1 rd-Quelldatei

Figur 0A.2 Ausgabe von A1 als HTML

Du hast also ein Meisterstück geschrieben, eine Klasse, die eine Klasse für sich selber ist, und nun möchtest du sie der Welt zeigen. Aber, als verantwortungsbewusster Entwickler, fühlst du doch die Notwendigkeit, deine Schöpfung zu dokumentieren. Wie machst du das? Am einfachsten ist es, Rubys eingebautes Dokumentations-Format, RD, zu benutzen sowie rdtool, eine Ruby-Utility-Suite, die diese Dokumentation in eine Vielzahl von Ausgabe-Formaten konvertiert.

rdtool sucht eine Datei nach =begin...=end-Paaren ab und extrahiert den Text dazwischen. Von diesem Text wird angenommen, dass er im RD-Format vorliegt. Der Text wird dann nach einem Satz von einfachen Regeln bearbeitet:

Textzeilen, die über den linken Rand laufen, werden zu Absätzen konvertiert.
Zeilen, die mit einem bis vier Gleichheitszeichen beginnen, sind Überschriften. ``='' ist eine Überschrift der ersten Ebene, ``=='' der zweiten und so weiter. Wenn es wirklich nötig ist, kann man ``+'' und ``++'' für Überschriften der fünften und sechsten Ebene nehmen.
= Überschrift erste Ebene == Überschrift zweite Ebene ...
Zeilen, bei denen das erste Zeichen (nach Leerzeichen) ein Sternchen ist, zeigen eine Aufzählung an. Fortgeführte Zeilen für eine Aufzählung sollten wie der Text in der ersten Zeile beginnen. Aufzählungen dürfen verschachtelt werden.
This is normal text * start of a multiline bullet item * and another * nested item * second nested * third item at top level
Zeilen mit eingeklammerten Zahlen als erste Zeichen (nach Leerzeichen) bedeuten nummerierte Aufzählungslisten. Die tatsächlichen Zahlen werden ignoriert. Auch hier dürfen die Listen verschachtelt werden.
(1) A numbered item * subitem in a bulleted list * subitem (2) Second numbered item (9) This will actually be labeled '3.'

Zeilen, die mit einem Doppelpunkt anfangen, bedeuten eine Liste mit Überschriften. Der Text auf der Zeile mit dem Doppelpunkt ist die Überschrift. Der direkt darauf folgende Text (der nicht weiter links stehen darf als die Überschrift) ist der beschreibende Text. Auch hier darf jeder Typ von Liste verschachtelt werden.

: red
  when the light is red, you
  must stop
: amber
  the amber light means that things are about to change. Either:
  * step on the gas, or
  * slam on the brakes
: green
  green means GO

Zeilen, die mit drei Minus-Zeichen anfangen, sind eine spezielle Sorte von überschriebenen Aufzählungslisten. Die Quelle in Figur A.1 auf Seite 518 zeigt ein paar davon in Aktion.

eingerückter Text, der nicht Teil einer Liste ist, wird wörtlich übernommen (wie der Kram unter ``Synopsis'' in Figur A.1 und A.2).

Inline-Formatierung

Innerhalb von Text-Blöcken oder Überschriften kann man spezielle Inline-Sequenzen benutzen, um Text zu formatieren. Alle Sequenzen werden in doppelte Klammern eingeschlossen.

Sequenz	Beispiel	gewünschter Nutzen
((emphasis))	emphasis	Hervorhebung (normalerweise Schrägschrift)
(({code stuff}))	`code stuff`	Code
((\|variable\|))	variable	Variablen-Name
((%type me%))	`type me`	Keyboard-Input
((:index term:))	index term	etwas, das man indizieren will
((<reference>))	reference	Hyperlink-Referenz
((-footnote-))	text.⁴	Fußnoten-Text. Eine Referenz wird im Text eingefügt, der Text der Fußnote erscheint am unteren Rand der Seite.
(('verb'))	verb	wörtlicher Text

Kreuz-Referenzen

Der Inhalt der Überschriften, die Überschriften einer Liste mit Überschriften und die Namen von Methoden werden automatisch als potentielle Ziele für Kreuz-Referenzen aufgenommen. Von woanders im Dokument kann man Links auf sie setzen, indem man ihren Inhalt im ((<...>))-Konstrukt benutzt.

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

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

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

Falls eine Referenz mit ``URL:'' anfängt, versucht rdtool das als externen Hyperlink zu formatieren.

Die Referenz ((<display part|label>)) erzeugt einen Link auf label, setzt in den Text jedoch ``display part'' ein. Dies wird im Beschreibungs-Abschnitt des Beispiels in Figur A.1 auf Seite 518 benutzt, um Methoden-Namen zu referenzieren:

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

Dieses Konstrukt zeigt das Wort ``new'' im Code-Zeichensatz an, benutzt es aber als Hyperlink auf die Methode Tempfile.new.

Methoden-Namen

rdtool macht bestimmte Annahmen über das Format von Methoden-Namen. Klassen- oder Modul-Methoden solten als Class.method auftauchen, Instanz-Methoden als Class#method und Klassen- oder Modul-Konstanten als Class::Const.

--- 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
    ..

Andere Dateien einbinden

Der Inhalt von filename wird überall dort eingefügt, wo das Dokument

<<< filename

enthält.

Falls die Datei mit einer .rd oder .rb-Extension angegeben ist, wird sie als RD-Dokumentation interpretiert.

Falls der Dateiname keine Extension besitzt, sucht rdtool nach einer Datei mit einer Extension, die dem gewünschten Output entspricht (.html bei HTML-Dateien, .man bei Manual-Dateien und so weiter) und interpoliert den Dateiinhalt in den output-Stream. Damit kann eine Zeile wie diese:

<<< header

benutzt werden, um eine Kopf abhängig von Output-Typ in das Dokument einzufügen.

rdtool benutzen

RD-Dokumentation kann direkt in das Ruby-Quell-Programm geschrieben werden oder auch in eine seperate Datei (die dann laut Konvention die Extension .rd haben solle). Diese Dateien werden mit dem rd2-Kommando bearbeitet, um den passend formatierten Output zu erzeugen.

rd2  [options]inputfile[ >outputfile]

Einige gebräuchliche Optionen beinhalten:

`-r`format	Wähle ein Output-Format. `-rrd/rd2html-lib.rb` erzeugt HTML-Output (Default). `-rrd/rd2man-lib.rb` erzeugt Unix-Man-Page-Output.
`-o`name	Setzt den Namen der Output-Datei (ohne Extension).
`--help`	Zeigt alle Optionen an.

Haftungs-Ausschluss

Während wir dies noch schreiben wird RD und rdtool laufend weiter entwickelt. Es ist wahrscheinlich, dass einige der hier angegebenen Dateils schon überholt sind (oder einfach nur falsch), wenn du dies liest.

Zusammen mit der rdtool-Distribution gibt es die Datei README.rd. Wir empfehlen, diese zu lesen, damit hat man einen aktuellen Zugang dazu, wie man Ruby-Dokumentationen erstellt.

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Übersetzung: Jürgen Katins
Für das englische Original:
© 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0. That reference is available for download.
Diese Lizenz sowie das Original vom Herbst 2001 bilden die Grundlage der Übersetzung
Es wird darauf hingewiesen, dass sich die Lizenz des englischen Originals inzwischen geändert hat.
Für die deutsche Übersetzung:
© 2002 Jürgen Katins
Der Copyright-Eigner stellt folgende Lizenzen zur Verfügung:
Nicht-freie Lizenz:
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.
Freie Lizenz:
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Programmierung in Ruby