### Category "IDLdoc"

The new [IDLdoc 3.4.2 release][IDLdoc downloads] changes one small aspect of the .sav file in the distribution (the source distribution is example the same as the 3.4.1 release): it removes the IDL library routines from the .sav file, i.e., it doesn’t do a RESOLVE_ALL when constructing the .sav file.

Currently, IDLdoc is built with IDL 6.4 to maximize who can use it, but this means any included IDL library routines could conflict with the routines provided by the user’s IDL distribution. IDLdoc is intended to be run from the command line, i.e., a full version of IDL, not a runtime or VM environment, so the IDL library routines should be provided by the user’s IDL distribution.

David Fanning recently used IDLdoc to generate [documentation][docs] for his Coyote Graphics library:

> On-line documentation is now available for all 41 of the Coyote Graphics programs. (These are a subset of the programs in the Coyote Library.) This will make it much easier to use these Coyote Graphics programs.

[docs]: http://www.idlcoyote.com/idldoc/cg/index.html “Coyote graphics documentation”

There was a bug in IDLdoc 3.4 which caused crashes with certain content in the Requires tag. The fix is in IDLdoc 3.4.1, get it [here][IDLdoc Downloads].

Also, I have confirmation that IDLdoc will run on *big* libraries, i.e., over 4000 files, 7700 routines, and 850,000 lines of code!

[IDLdoc 3.4][idldoc_3.4] was released today. This is mostly a bug fix version, but there is on big feature: LaTeX equation formatting. To use LaTeX equations in your docs, just use standard LaTeX syntax anywhere plain text is allowed. For example, here is an example of using an equation in the main description:

;+
; Inverse hyperbolic cosine. Uses the formula:
;
; $$\text{acosh}(z) = \ln(z + \sqrt{z + 1} \sqrt{z – 1})$$
;
; :Returns:
; float, double, complex, or double complex depending on the input
;
; :Params:
; z : in, required, type=numeric
; input
;-

The equation should be typeset like (results depend on browser):

$$\text{acosh}(z) = \ln(z + \sqrt{z + 1} \sqrt{z – 1})$$

Inline equations are also allowed. Both can appear in the main description and inside most tags (anywhere comments are just copied over to the output).

Here are the full release notes:

1. Allow LaTeX equation formatting.
2. Fix for bug where links to routines, files, etc. in directory overview
comments on the overview page were not correct.
4. Changes to HTML output styling including larger type size.
5. Fixed bug where DLM contents could not be references using backtick notation
in rst markup syntax.
6. Added private and hidden attributes to directory names in overview file.
7. Not showing warnings page when USER keyword is set.
8. Fixed bug where parsing rst Requires tag would cause IDLdoc to crash.
9. Fixed bug where Warnings page showed items from private or hidden items.
10. UPDATED 11/22: New color scheme.

[IDLdoc 3.3.1](http://idldoc.idldev.com/wiki/Downloads) fixes a couple memory leaks and a bug where hidden/private routines would show up in the categories listing when they shouldn’t.

1. Created tutorial and reference manual documentation.

2. Added embed directive to embed SVG or other graphics formats. For the
“latex” comment style, .svg will be replaced with .pdf.

3. Directory overview comments can be picked up from a .idldoc file in
each directory. Tags include private and hidden to control the level
of visibility of the directory and its contents, as well as author,

4. Added ROUTINE_LINE_CUTOFFS keyword to control level of warning for
number of lines in a routine (only used when STATISTICS is set). Set
ROUTINE_LINE_CUTOFFS to a two-element array indicating the number of
lines that needs to be exceeded before the routine has a warning or is
flagged.

5. McCabe complexity computed for each routine when STATISTICS set.
Added COMPLEXITY_CUTOFFS keyword to control level of warning for
complexity. Set COMPLEXITY_CUTOFFS to a two-element array indicating
the complexity that needs to be exceeded before the routine has a
warning or is flagged.

6. Added a link in each routine’s details to its source code.

7. Improved rst markup style. Headings can be created by underlining with
“=” (for level 1 headings), “-” (level 2), or “~” (level 3). Links can
be done explicitly via

my website

or looked up in the scope of the comment’s context, like

my_routine

Also, added title directive so that .idldoc files can have a
separate title to display (instead of just their filename).

8. Added a preformatted markup style which is nearly equivalent to
verbatim, but also makes HTML output respect line-breaks.

file.

10. Allow properties of a class to be marked as hidden or private in rst
format.

11. Small changes to ensure compatible with IDL 8.0.

12. Miscellaneous bug fixes.

If you try this out, please let me know (via email or submitting a ticket on the [IDLdoc project site](idldoc.idldev.com)) if you encounter an issue.

IDLdoc 3.2 has been released! Head over to [idldoc.idldev.com](http://idldoc.idldev.com) or automatically update with the Workbench update mechanism. What’s new in IDLdoc 3.2 follows:

1. Added ability to create LaTeX output. Use the TEMPLATE_PREFIX keyword to the IDLDOC command to specify that the LaTeX templates should be used and the COMMENT_STYLE keyword to specify that markup in comments in the source code should be converted to LaTeX in the output:

idldoc, ..., template_prefix='latex-', comment_style='latex'
 

IDLdoc is now completely setup for users to generate documentation in any text-based format they want.

2. Added ability to create documentation for DLM files. IDLdoc will automatically find .dlm files in the ROOT subdirectories and create documentation for them. No special comments in the .dlm file are necessary (or used).

3. Added INDEX_LEVEL keyword to IDLDOC command to control the granularity of the index: 0 for no index; 1 for directories, classes, files, and routines; 2 for level 1 items plus parameters, keywords, fields, properties, and sav file variables

4. Adds links to names of routines and classes found in the Uses section for routines and files.

5. Added color output in the output log for errors and warnings if the COLOR_OUTPUTLOG keyword is set or if the MG_TERMISTTY routine is present and returns true.

6. Miscellaneous small bug fixes.

A new version of [IDLdoc](http://idldoc.idldev.com/) (IDLdoc 3.2) will be coming out soon. Make sure you are on the [mailing list](http://lists.idldev.com/listinfo.cgi/idldoc-idldev.com) if you want to participate in the beta and be notified of the release.

New features for this release will include:

1. ability to generate printed documentation i.e. LaTeX to PDF
2. generate documentation for DLMs

And, of course, some bug fixes.

I have a set of LaTeX templates for IDLdoc. I’m still polishing them up a bit, but they will be in IDLdoc 3.2; printed documentation in the form of LaTeX and DocBook output will be the major features.

Here’s an example PDF generated by the IDLdoc trunk. Compare to the DocBook output (PDF) [previously mentioned](http://michaelgalloy.com/2008/06/26/docbook-output-from-idldoc.html).

• #### GPULib

GPULib enables IDL developers to access the high-performance capabilities of modern NVIDIA graphics cards without knowledge of CUDA programming.

TaskDL is a task-farming solution for IDL designed for problems with loosely-coupled, parallel applications where no communication between nodes of a cluster is required.

#### mpiDL

mpiDL is a library of IDL bindings for Message Passing Interface (MPI) used for tightly-coupled parallel applications.

#### Remote Data Toolkit

The Remote Data Toolkit is a library of IDL routines allowing for easy access to various scientific data in formats such as OPeNDAP, HDF 5, and netCDF.

• #### Modern IDL

Modern IDL offers IDL programmers one place to look, for beginners and advanced users alike. This book also contains: a thorough tutorial on the core topics of IDL; a comprehensive introduction to the object graphics system; common problems and gotchas with many examples; advanced topics not normally found are discussed throughout the book: regular expressions, object graphics, advanced widget programming, performance, object-oriented programming, etc.

• #### IDLdoc

IDLdoc is an open source utility for generating documentation from IDL source code and specially formatted comments.

#### mgunit

mgunit is an open source unit testing framework for IDL.

#### rIDL

rIDL is an open source IDL command line replacement.

#### mglib

mglib is an open source library of IDL routines in areas of visualization, application development, command line utilities, analysis, data access, etc.