Modifying IDLdoc's output

This guide discusses how to modify the output from IDLdoc by modifying the template files (*.tt) that are provided with IDLdoc. Currently, only the templates directly documenting *.pro files (pro-file.tt), templates included by pro-file.tt (navbar.tt and tagline.tt) and objects implementing the template interface used by pro-file.tt (IDLdocRoutine and IDLdocParam) are documented for user customization. The plans is to release the documentation for other templates as they become more stable in future releases of IDLdoc.

In general, if one of the below variables is not defined/not-appropriate it will be set to '' or -1.

navbar.tt

This template is included by many other templates requiring those templates to provide the following variables:

title: title of the IDLdoc library
subtitle: subtitle of the IDLdoc library
categories_href: relative link to the categories page
categories_selected: boolean on whether the current page is the categories page
dir_overview_href: relative link to the directory overview page
dir_overview_selected: boolean on whether the current page is the directory overview page
etc_selected: boolean on whether the current page is an "Etc" page
file_selected: boolean on whether the current page is documentation of a PRO or SAV file
help_href: relative link to the help page
help_selected: boolean on whether the current page is the help page
index_href: relative link to the full index
index_selected: boolean on whether the current page is the full index page
overview_href: relative link to the library overview page
overview_selected: boolean on whether the current page is the library overview page
search_href: relative link to the search page
search_selected: boolean on whether the current page is the search page
source_href: relative link to the source code of a PRO file
source_selected: boolean on whether the current page is a source code page
user: boolean on whether the current documentation is generated for a user (as opposed to a developer)
prev_file_href: relative link to the previous PRO or SAV file page
next_file_href: relative link the next PRO or SAV file page
view_single_page_href: link to the current page
view_frames_href: link to the library index.html page
summary_fields_href: internal link to the fields summary; '' if no fields
summary_routine_href: internal link to the routine summary, '' if only one routine
details_routine_href: internal link to the start of the routine details

tagline.tt

This template is included by many other templates requiring those templates to provide the following variables:

version: IDLdoc version as a string
date: string containing date of file creation

pro-file.tt

This file produces the output for the documentation of IDL source code files. Variables provided to this template are all those required by the navbar.tt and tagline.tt templates and those listed below:

has_fields: base filename
is_class: boolean on whether this file corresponds to a class definition (and class variable is present)
class: IDLdocClass object
fields: base filename
pro_file: base filename
pro_dir: directory for file
root: relative path to the root of the library
last_modified: date last modified as a string
file_comments: file level comments
nroutines: number of IDLdocRoutine objects in routines array
routines: array of IDLdocRoutine objects; see below for variables in these objects
nonavbar: set to 1 to indicate no navbar, otherwise set to 0
navbar_filename: filename of navbar template; appropriate for INCLUDE_TEMPLATE directive
embed: 0 for link to CSS, 1 for embed CSS
css_location: if embed then string filename of CSS file location, o/w href to CSS file; for all media types
print_css_location: if embed then string filename of CSS file location, o/w href to CSS file; for printing only
footer: filename of user-created footer to insert; appropriate for the INCLUDE directive
separator: correct path separator, / or \ depending on Unix or Windows system
tagline_filename: name of template for the bottom of the file; appropriate for the INCLUDE_TEMPLATE directive

IDLdocRoutine objects in pro-file.tt

routine_name: string name of the routine
routine_url: internal url to the start of the routine details
is_func: boolean on whether the routine is a function
obsolete: boolean on whether the routine is marked obsolete
abstract: boolean on whether the routine is abstract (i.e. not implemented)
private: boolean on whether the routine is private (i.e. not visible in USER mode)
categories_present: boolean on whether the routine is marked with categories
categories: string array of list of categories as listed in the source
ntotalparams: total number of positional parameters and keywords
nparams: number of positional parameters
params: array of IDLdocParam objects
nkeywords: number of keywords
keywords: array of IDLdocParam objects
short_comment: first sentence of the routine comments
statistics: boolean on whether the McCabe complexity statistics have been calculated
mccabe_cyclic: McCabe Cyclic complexity (computed)
mccabe_essential: McCabe Essential complexity (computed)
mccabe_mod_design: McCabe Modular Design complexity (computed)
routine_comments: string array of comments for the routine
preformat: true if the comments are to be stripped from the source code and placed in the output with the same line breaks and formatting as the source code
returns_present: boolean on whether the returns tag is present
returns: documents the return value of a function
examples_present: boolean on whether the examples tag is present
examples: string array of example code using the routine
author_present: boolean on whether the author tag is present
author: author(s) of the routine
version_present: boolean on whether the version tag is present
version: version of the routine
history_present: boolean on whether the history tag is present
history: string array of history of the routine
copyright_present: boolean on whether the copyright tag is present
copyright: string array of copyright information about the routine
obsolete_comments_present: boolean on whether the obsolete tag is present
obsolete_comments: comments following the obsolete tag and further explaining the status of the routine (and alternatives)
bugs_present: boolean on whether the bugs tag is present
bugs: string array describing known issues with the routine
todo_present: boolean on whether the todo tag is present
todo: string array of items that still need to be done for the routine
restrictions_present: boolean on whether the restrictions tag is present
restrictions: restrictions on the use of the routine
inherits_present: boolean on whether the inherits tag is present
inherits: desribes other classes the class inherits from (this is not needed any longer)
requires_present: boolean on whether the requires tag is present
requires: which IDL verion is necessary to run this routine
uses_present: boolean on whether the uses tag is present
uses: which routines this routine calls
common_blocks_present: boolean on whether the common block information is present
common_blocks: names of common blocks used by routine
precondition_present: boolean on whether the routine is marked with a precondition tag
precondition: condition that should be satisfied before the routine is executed
postcondition_present: boolean on whether the routine is marked with a postcondition tag
postcondition: condition that should be satisfied after the routine is executed

IDLdocParam objects in pro-file.tt

name: name of the parameter
in: true if parameter is an input to the routine
out: true if the parameter is an output to the routine
optional: true if parameter is optional
required: true if parameter is required
private: hidden if parameter is supposed to be hidden from users of the routine, but visible to developers
hidden: true if parameter is supposed to be hidden
type: data type of the parameter
boolean: true if the param is a switch
default: default value of the parameter
comments: string array of comments for parameter
delim: appropriate delimiter preceeding parameter in a syntax listing of the routine (i.e. always a comma unless it's the first parameter of a function call)

[% IF footer NE '' %][% END %] [% INCLUDE_TEMPLATE tagline_filename %]