RDoc::Page

This is how you define the HTML that RDoc generates. Simply create a file in rdoc/generators/html_templates that creates the module RDoc::Page and populate it as described below. Then invoke rdoc using the —template <name of your file> option, and your template will be used.

The constants defining pages use a simple templating system:

• The templating system is passed a hash. Keys in the hash correspond to tags on this page. The tag %abc% is looked up in the hash, and is replaced by the corresponding hash value.
• Some tags are optional. You can detect this using IF/ENDIF

     IF: title
     The value of title is %title%
     ENDIF: title
  

• Some entries in the hash have values that are arrays, where each entry in the array is itself a hash. These are used to generate lists using the START: construct. For example, given a hash containing

     { 'people' => [ { 'name' => 'Fred', 'age' => '12' },
                     { 'name' => 'Mary', 'age' => '21' } ]
  

  You could generate a simple table using

     <table>
     START:people
       <tr><td>%name%<td>%age%</tr>
     END:people
     </table>
  

  These lists can be nested to an arbitrary depth

• the construct HREF:url:name: generates <a href="%url%">%name%</a> if url is defined in the hash, or %name% otherwise.

Your file must contain the following constants

FONTS

a list of fonts to be used

STYLE

a CSS section (without the <style> or comments). This is used to generate a style.css file

BODY

The main body of all non-index RDoc pages. BODY will contain two !INCLUDE!s. The first is used to include a document-type specific header (FILE_PAGE or CLASS_PAGE). The second include is for the method list (METHOD_LIST). THe body is passed:

%title%:	the page‘s title
%style_url%:	the url of a style sheet for this page
%diagram%:	the optional URL of a diagram for this page
%description%:	a (potentially multi-paragraph) string containing the description for th file/class/module.
%requires%:	an optional list of %aref%/%name% pairs, one for each module required by this file.
%methods%:	an optional list of %aref%/%name%, one for each method documented on this page. This is intended to be an index.
%attributes%:	An optional list. For each attribute it contains: %name%: the attribute name %rw%: r/o, w/o, or r/w %a_desc%: description of the attribute
%classlist%:	An optional string containing an already-formatted list of classes and modules documented in this file

For FILE_PAGE entries, the body will be passed

%short_name%:	The name of the file
%full_path%:	The full path to the file
%dtm_modified%:	The date/time the file was last changed

For class and module pages, the body will be passed

%classmod%:	The name of the class or module
%files%:	A list. For each file this class is defined in, it contains: %full_path_url%: an (optional) URL of the RDoc page for this file %full_path%: the name of the file
%par_url%:	The (optional) URL of the RDoc page documenting this class‘s parent class
%parent%:	The name of this class‘s parent.

For both files and classes, the body is passed the following information on includes and methods:

%includes%:	Optional list of included modules. For each, it receives %aref%: optional URL to RDoc page for the module %name%: the name of the module
%method_list%:	Optional list of methods of a particular class and category.

Each method list entry contains:

%type%:	public/private/protected
%category%:	instance/class
%methods%:	a list of method descriptions

Each method description contains:

%aref%:	a target aref, used when referencing this method description. You should code this as <a name="%aref%">
%codeurl%:	the optional URL to the page containing this method‘s source code.
%name%:	the method‘s name
%params%:	the method‘s parameters
%callseq%:	a full calling sequence
%m_desc%:	the (potentially multi-paragraph) description of this method.

CLASS_PAGE

Header for pages documenting classes and modules. See BODY above for the available parameters.

FILE_PAGE

Header for pages documenting files. See BODY above for the available parameters.

METHOD_LIST

Controls the display of the listing of methods. See BODY for parameters.

INDEX

The top-level index page. For a browser-like environment define a frame set that includes the file, class, and method indices. Passed

%title%:	title of page
%initial_page% :	url of initial page to display

CLASS_INDEX

Individual files for the three indexes. Passed:

%index_url%:	URL of main index page
%entries%:	List of %name%: name of an index entry %href%: url of corresponding page

METHOD_INDEX

Same as CLASS_INDEX for methods

FILE_INDEX

Same as CLASS_INDEX for methods

FR_INDEX_BODY

A wrapper around CLASS_INDEX, METHOD_INDEX, and FILE_INDEX. If those index strings contain the complete HTML for the output, then FR_INDEX_BODY can simply be !INCLUDE!

SRC_PAGE

Page used to display source code. Passed %title% and %code%, the latter being a multi-line string of code.