Embedded Documentation
So you've written a masterpiece, a class in a class of its own, and you'd like to share it with the world. But, being a responsible developer, you feel the need to document your creation. What do you do? The simplest solution is to use Ruby's built-in documentation format, RD, and
rdtool, a Ruby utility suite that converts this documentation into a variety of output formats.
rdtool scans a file for
=begin and
=end{=begin...=end@
{=begin pairs, and extracts the text between them all. This text is assumed to be documentation in RD format. The text is then processed according to a simple set of rules:
- Lines of text flush to the left margin are converted to paragraphs.
- Lines starting with one to four equals signs are headings. ``='' is a first-level heading, ``=='' a second-level heading, and so on. ``+'' and ``++'' can be used to signal fifth- and sixth-level headings if you really want to go that deep.
=?Top?Level?Heading
==?Second?Level?Heading
...
|
- Lines in which the first nonspace is an asterisk indicate the beginnings of bullet lists. Continuation lines for each bullet item should line up with the text on the first line. Lists may be nested.
This?is?normal?text
*?start?of?a
??multiline?bullet?item
*?and?another
??*?nested?item
??*?second?nested
*?third?item?at?top?level
|
- Lines where the first nonspace characters are digits between parentheses indicate numbered lists. The actual digits used are ignored. Again, lists may be nested.
(1)?A?numbered?item
????*?subitem?in?a?bulleted?list
????*?subitem
(2)?Second?numbered?item
(9)?This?will?actually?be?labeled?'3.'
|
- Lines starting with a colon indicate labeled lists. The text on the colon line is the label. The immediately following text (which may not be indented less than the label) is the descriptive text. Again, each type of list may be nested.
:?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
|
- Lines starting with three minus signs are a special kind of labeled list, when the labels are method names and signatures. The source in Figure A.1 on page 512 shows a handful of these in action.
Indented text that isn't part of a list is set verbatim (such as the stuff under ``Synopsis'' in Figures A.1 and A.2).
Inline Formatting
Within blocks of text and headings, you can use special
inline sequences to control text formatting. All sequences are nested within a set of double parentheses.
|
Sequence |
Example |
Intended Use |
| ((*emphasis*)) |
emphasis |
Emphasis (normally italic) |
| (({code stuff})) |
code stuff |
Code |
| ((|variable|)) |
variable |
Variable name |
| ((%type me%)) |
type me |
Keyboard input |
| ((:index term:)) |
index term |
Something to be indexed |
| ((<reference>)) |
reference |
Hyperlink reference |
| ((-footnote-)) |
text.4
|
Footnote text. A reference is placed inline, and the text of the footnote appears at the bottom of the page. |
| (('verb')) |
verb |
Verbatim text |
 |
Cross References
The content of headings, the labels of labeled lists, and the names of methods are automatically made into potential cross reference targets. You make links to these targets from elsewhere in the document by citing their contents in the
((<...>)) construct.
=?Synopsis
...
See?((<Return?Codes>))?for?details.
..
==?Instance?Methods
---?Tempfile.open(?filename?)
????Opens?the?file...
==?Return?Codes
..
The?method?((<Tempfile.open>))?raises?an?(({IOException}))...
|
If a reference starts with ``URL:'',
rdtool attempts to format it as an external hyperlink.
The reference
((<display part|label>)) generates a link to
label but places the text ``display part'' in the output document. This is used in the description section of the example in Figure A.1 on page 512 to generate references to the method names:
perspective,?apart?from?the?unusual?((<(({new}))|Tempfile.new>)),
...
|
This construct displays the word ``new'' in code font but uses it as a hyperlink to the method
Tempfile.new.
Method Names
rdtool makes certain assumptions about the format of method names. Class or module methods should appear as
Class.method, instance methods as
Class#method, and class or module constants as
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
????..
|
Including Other Files
The contents of
filename will be inserted wherever the document contains
If the file is specified with an
.rd or
.rb extension, it will be interpreted as RD documentation.
If the filename has no extension,
rdtool will look for a file with an extension that matches the type of output being produced (
.html for HTML files,
.man for man files, and so on) and interpolate that file's contents in the
output stream. Thus, a line such as:
could be used to add an output-dependent header to a document.
Using rdtool
RD documentation can be included directly in a Ruby source program or written into a separate file (which by convention will have the extension
.rd). These files are processed using the
rd2 command to produce appropriately formatted output.
rd2 [
options
] inputfile [ >outputfile ]
|
Some common options include:
-r format |
Select an output format. -rrd/rd2html-lib.rb produces HTML output (the default). -rrd/rd2man-lib.rb produces Unix man page output. |
-o name |
Set the base part of the output filename. |
--help |
List the full set of options. |
Mandatory Disclaimer
As we are writing this, RD and
rdtool are undergoing continuous development. It is likely that some of the details we give here will be out of date (or just plain wrong) by the time you read this.
Included with the
rdtool distribution is the file
README.rd. We suggest you do so, as it will give you the current scoop on producing Ruby documentation.
Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide" Copyright
