Module: 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 strin 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 classes 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
%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.