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)
Produced by IDLdoc 2.0 on Sat Mar 11 21:40:01 2006.