- 1_8_6_287 (0)
- 1_8_7_72 (0)
- 1_8_7_330 (0)
- 1_9_1_378
- 1_9_2_180
- 1_9_3_125
- 1_9_3_392
- What's this?
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% 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.
Constants
BLANK = %{ }
INDEX = %{
METHOD_INDEX = FILE_INDEX
CLASS_INDEX = FILE_INDEX
FILE_INDEX = %{
END:entries }
FR_INDEX_BODY = %{ !INCLUDE! }
SRC_PAGE = %{ %code%
}
METHOD_LIST = %{ IF:includes
START:methods %type% %category% methods
IF:m_desc %name%%params% IF:codeurl src ENDIF:codeurl
CLASS_PAGE = %{
%classmod%
%full_name%
IF:parent In: START:infiles HREF:full_path_url:full_path: IF:cvsurl (CVS) ENDIF:cvsurl END:infiles ENDIF:parent Parent: IF:par_url ENDIF:par_url %parent% IF:par_url ENDIF:par_url
}
FILE_PAGE = <<_FILE_PAGE_
File
%short_name%
Path: %full_path% IF:cvsurl (CVS) ENDIF:cvsurl Modified: %dtm_modified%
_FILE_PAGE_
BODY = %{
ENDIF:diagram IF:description %diagram%
Required files
Subroutines and Functions
Arguments
START:attributes
ENDIF:attributes IF:classlist IF:rw END:attributes [%rw%] ENDIF:rw IFNOT:rw ENDIF:rw %name% %a_desc%
Modules
%classlist%
ENDIF:classlist !INCLUDE! }
STYLE = %{ body,p { font-family: Verdana, Arial, Helvetica, sans-serif; color: #000040; background: #BBBBBB; } td { font-family: Verdana, Arial, Helvetica, sans-serif; color: #000040; } .attr-rw { font-size: small; color: #444488 } .title-row {color: #eeeeff; background: #BBBBDD; } .big-title-font { color: white; font-family: Verdana, Arial, Helvetica, sans-serif; font-size: large; height: 50px} .small-title-font { color: purple; font-family: Verdana, Arial, Helvetica, sans-serif; font-size: small; } .aqua { color: purple } .method-name, attr-name { font-family: monospace; font-weight: bold; } .tablesubtitle { width: 100%; margin-top: 1ex; margin-bottom: .5ex; padding: 5px 0px 5px 20px; font-size: large; color: purple; background: #BBBBCC; } .tablesubsubtitle { width: 100%; margin-top: 1ex; margin-bottom: .5ex; padding: 5px 0px 5px 20px; font-size: medium; color: white; background: #BBBBCC; } .name-list { font-family: monospace; margin-left: 40px; margin-bottom: 2ex; line-height: 140%; } .description { margin-left: 40px; margin-bottom: 2ex; line-height: 140%; } .methodtitle { font-size: medium; text_decoration: none; padding: 3px 3px 3px 20px; color: #0000AA; } .column-title { font-size: medium; font-weight: bold; text_decoration: none; padding: 3px 3px 3px 20px; color: #3333CC; } .variable-name { font-family: monospace; font-size: medium; text_decoration: none; padding: 3px 3px 3px 20px; color: #0000AA; } .row-name { font-size: medium; font-weight: medium; font-family: monospace; text_decoration: none; padding: 3px 3px 3px 20px; } .paramsig { font-size: small; } .srcbut { float: right } }
FONTS = "Verdana, Arial, Helvetica, sans-serif"
BLANK = %{ }
INDEX = %{
METHOD_INDEX = FILE_INDEX
CLASS_INDEX = FILE_INDEX
FILE_INDEX = %{
END:entries }
FR_INDEX_BODY = %{ !INCLUDE! }
SRC_PAGE = %{ %code%
}
METHOD_LIST = %{ IF:includes
START:methods %type% %category% methods
IF:m_desc IF:callseq %callseq% ENDIF:callseq IFNOT:callseq %name%%params% ENDIF:callseq IF:codeurl src ENDIF:codeurl %sourcecode%
ENDIF:sourcecode END:methods ENDIF:methods END:method_list ENDIF:method_list }
CLASS_PAGE = %{
%classmod%
%full_name%
IF:parent In: START:infiles HREF:full_path_url:full_path: IF:cvsurl (CVS) ENDIF:cvsurl END:infiles ENDIF:parent Parent: IF:par_url ENDIF:par_url %parent% IF:par_url ENDIF:par_url
}
FILE_PAGE = <<_FILE_PAGE_
File
%short_name%
Path: %full_path% IF:cvsurl (CVS) ENDIF:cvsurl Modified: %dtm_modified%
_FILE_PAGE_
BODY = %{ STYLE = %{ body,td,p { font-family: %fonts%; color: #000040; } .attr-rw { font-size: xx-small; color: #444488 } .title-row { background-color: #CCCCFF; color: #000010; } .big-title-font { color: black; font-weight: bold; font-family: %fonts%; font-size: large; height: 60px; padding: 10px 3px 10px 3px; } .small-title-font { color: black; font-family: %fonts%; font-size:10; } .aqua { color: black } .method-name, .attr-name { font-family: font-family: %fonts%; font-weight: bold; font-size: small; margin-left: 20px; color: #000033; } .tablesubtitle, .tablesubsubtitle { width: 100%; margin-top: 1ex; margin-bottom: .5ex; padding: 5px 0px 5px 3px; font-size: large; color: black; background-color: #CCCCFF; border: thin; } .name-list { margin-left: 5px; margin-bottom: 2ex; line-height: 105%; } .description { margin-left: 5px; margin-bottom: 2ex; line-height: 105%; font-size: small; } .methodtitle { font-size: small; font-weight: bold; text-decoration: none; color: #000033; background-color: white; } .srclink { font-size: small; font-weight: bold; text-decoration: none; color: #0000DD; background-color: white; } .paramsig { font-size: small; } .srcbut { float: right } } FONTS = "Verdana, Arial, Helvetica, sans-serif" ONE_PAGE = %{ CONTENTS_XML = %{ IF:description %description% ENDIF:description IF:requires CONTENTS_XML = %{ IF:description %description% ENDIF:description IF:requires INDEX = %{ METHOD_INDEX = FILE_INDEX CLASS_INDEX = FILE_INDEX FILE_INDEX = %{ FR_INDEX_BODY = %{ !INCLUDE! } SRC_PAGE = %{ CLASS_PAGE = %{ FILE_PAGE = <<_FILE_PAGE_ BODY = HEADER + %{ !INCLUDE! } + CONTEXT_CONTENT + METHOD_LIST + %{
ENDIF:diagram IF:description %diagram%
Required files
Methods
%sectitle%
IF:seccomment
Attributes
START:attributes
ENDIF:attributes IF:classlist IF:rw END:attributes [%rw%] ENDIF:rw IFNOT:rw ENDIF:rw %name% %a_desc%
Classes and Modules
%classlist%
ENDIF:classlist !INCLUDE! END:sections }
File: %short_name%
} + CONTENTS_XML + %{ END:files IF:classes Path: %full_path% Modified: %dtm_modified% Classes
START:classes IF:parent %classmod% %full_name% < HREF:par_url:parent:
ENDIF:parent IFNOT:parent %classmod% %full_name%
ENDIF:parent IF:infiles (in files START:infiles HREF:full_path_url:full_path: END:infiles ) ENDIF:infiles } + CONTENTS_XML + %{ END:classes ENDIF:classes }Requires:
START:requires IF:aref
ENDIF:requires IF:attributes Attributes
START:attributes
ENDIF:attributes IF:includes END:attributes %name% %rw% %a_desc% Includes
START:includes IF:aref
ENDIF:includes IF:method_list Methods
START:method_list IF:methods START:methods %type% %category% method: IF:callseq %callseq% ENDIF:callseq IFNOT:callseq %name%%params%
ENDIF:callseq IF:m_desc %m_desc% ENDIF:m_desc IF:sourcecode
ENDIF:sourcecode END:methods ENDIF:methods END:method_list ENDIF:method_list } %sourcecode%
Requires:
START:requires IF:aref
ENDIF:requires IF:attributes Attributes
START:attributes
ENDIF:attributes IF:includes END:attributes %name% %rw% %a_desc% Includes
START:includes IF:aref
ENDIF:includes IF:method_list Methods
START:method_list IF:methods START:methods %type% %category% method: %name%%params%
IF:m_desc %m_desc% ENDIF:m_desc IF:sourcecode
ENDIF:sourcecode END:methods ENDIF:methods END:method_list ENDIF:method_list } %sourcecode%
END:entries }%code%
}
} %classmod% %full_name%
IF:parent In: START:infiles IF:full_path_url ENDIF:full_path_url %full_path% IF:full_path_url ENDIF:full_path_url IF:cvsurl (CVS) ENDIF:cvsurl
END:infiles ENDIF:parent Parent: IF:par_url ENDIF:par_url %parent% IF:par_url ENDIF:par_url
_FILE_PAGE_ %short_name%
Path: %full_path% IF:cvsurl (CVS) ENDIF:cvsurl Modified: %dtm_modified%
