Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Mail Systems
Eclipse Documentation

How To Guides
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Problem Solutions
Privacy Policy




Ruby Programming
Previous Page Home Next Page

Embedded Documentation

Figure not available...

Figure not available...

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).
Ruby Programming
Previous Page Home Next Page

  Published under the terms of the Open Publication License Design by Interspire