Overview files are a simple way to give an introduction to a viewer of your IDLdoc’ed library. The main overview file is simple to specify when you run IDLdoc. For example, to specify the file “overview” in the current directory, use:

idldoc, root=my_root, overview='overview'

when you IDLdoc your library. There are also directory specific overview files, but first consider the contents of the main overview file.

What’s in the overview file and how is it used? Here is the current overview file for my library.

Library routines for the personal library of Michael Galloy.

@dir collection Objects implementing various types of collections.
@dir envi user functions for ENVI
@dir math miscellaneous mathematical routines
@dir objectgraphics helper routines and classes for using object graphics
@dir sorting searching and sorting routines
@dir sparklines routines involving sparklines (simple word-size graphics originated by Edward Tufte)
@dir utility utility routines
@dir web world wide web related routines
@dir widgets tools and components for making widget (GUI) programs

The overview file starts off with free-form comments that can include HTML. IDLdoc copies these comments directly to the overview page (the first page you see when you look at an IDLdoc’ed library). Then the first @ sign starts the tag section (this is just like the IDLdoc comments before a routine). The only tag currently accepted for overview files is the “dir” tag that specifies comments to include for the directory listed immediately after the dir tag. These directory comments are placed into a table of the directories in the library directly below the free-form comments above.

The directory overviews are constructed from the @file_comments tags of the individual files in the directory. It’s handy to put at least a one sentence description of the contents of the file into the header for one of the routines in the file (it doesn’t matter to IDLdoc which routine it is).

Next up for the IDLdoc series of articles is an explanation of the template system in IDLdoc 2.0. This is one part of IDLdoc that I would like to somehow release it as a separate package to download. It allows you to write some type of text output (like HTML, XML, LaTeX, DocBook, etc) that has place holders for data that are filled in when the template is parsed. In IDLdoc, all the output is “templatized” so that it can be changed without modifying any of IDLdoc’s code.