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.

Get the new version [here][IDLdoc downloads].

[IDLdoc downloads]: “IDLdoc downloads”

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]: “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 Downloads]:

[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.
3. Adding links to parent items in index entries.
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.4]: “IDLdoc downloads”

[IDLdoc 3.3.1]( fixes a couple memory leaks and a bug where hidden/private routines would show up in the categories listing when they shouldn’t.

IDLdoc 3.3 has been released! To download, head over to []( New features in this release are:

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,
copyright, and history.

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

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


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.

9. Added author, copyright, history, and version tags to the overview

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

11. Small changes to ensure compatible with IDL 8.0.

12. Miscellaneous bug fixes.

If you are interested in the next version of IDLdoc, check out the [downloads page]( for a preview of IDLdoc 3.3 including what’s new and the link to download. This is an early release; an official 3.3 release will be made soon.

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

IDLdoc 3.2 has been released! Head over to []( 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]( (IDLdoc 3.2) will be coming out soon. Make sure you are on the [mailing list]( 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](

« newer postsolder posts »