michaelgalloy.com

IDL Workbench 7.0.3 arrived today via the automatic software update mechanism in the Workbench. It provides HDF and netCDF library udpates, better path support, IDLdoc support (rst format only), and even faster code analysis when the Workbench starts. Everything seems to be working well for me during use this afternoon.

Since I’m most excited about the IDLdoc features, I will describe them in a bit more detail after the jump. IDLdoc 3.1 (download) is required to integrate with the Workbench.

Continue reading “IDL Workbench 7.0.3 arrives.”

I have the framework in place to have IDLdoc produce output besides HTML. This has been a long process beginning in IDLdoc 2.0 when I switched to using templates instead of embedding the HTML code in the IDL code. I have started by writing a set of templates for DocBook output, but intend to write a LaTeX set as well.

Here’s an example PDF of IDLdoc output for a library of routines for visualization I’ve been thinking about.

I just released IDLdoc 3.1 (see full release notes are below). As per this short blog post, IDLdoc is getting integrated into the IDL Workbench. This release adds some rst markup features that the IDL Workbench will use — my favorite is to be able to link to images with:

.. image:: filename

IDLdoc will link to the image and also copy the image file into the output directory (if OUTPUT keyword to IDLDOC routine is used).

1. Added ability to reference images in rst markup. IDLdoc will automatically copy referenced images into the output.
2. In rst markup, illegal characters like < and > are automatically converted to character entities.
3. Added `:Description:` tag for compatibility with IDL Workbench update.
4. Changed default markup parser to rst when format parser is rst.
5. Miscellaneous small bug fixes.

IDLdoc support will be added to the IDL Workbench in an update planned for June. This will add some really cool features for those who use IDLdoc and the Workbench:

1. enhanced hover help on routines with an IDLdoc header
2. content assistant on tag names when writing IDLdoc comments
3. menu item and keyboard shortcut to insert an IDLdoc routine or file header (and preferences to define what tags you want inserted)

The Workbench will recognize comments in the rst format.

There will be an IDLdoc 3.1 release any day now to add some features necessary to support this and fix a couple bugs.

The svn trunk of IDLdoc has a new feature that I'm excited about: the ability to insert images without having to stick ugly HTML in your code header or copying an image manually into the output. This is part of the rst markup style (so it won't work unless you set markup_style='rst' in your IDLdoc call or specify it via the "docformat" comment). My goal for the rst markup style is to eliminate any need to put HTML in the code header. I don't think you should have to make the code header look ugly in order to make the documentation look good.

In the theme river code in the previous article, the header for the routine contains:

IDLdoc grabs themeriver.png (relative to the location of the source code file), copies it to the output, and replaces ".. image:: themeriver.png" with a link to the copy of the image (see output).

If you want to try this, you have to checkout the IDLdoc source code using Subversion:

Put the "src" directory of the checkout in your IDL path.

It's now possible (thanks to some help from engineers at ITT VIS) to get IDLdoc updates via the update mechanism built into the IDL Workbench. This means that you can add a new "Remote update site" that is queried for new updates when you start the Workbench. I think this is a really interesting way to distribute software; I hope I can "subscribe" to other IDL libraries in the future.

For those experienced in getting Eclipse plugins, the URL is

For more detailed instructions, see the Workench Updates page on the IDLdoc project site.

One note: if you already have IDLdoc in your !path, you might have to remove it from your path to see the new version.

I added some more documentation to the "Getting Started" page on the IDLdoc project site. Included is a two minute screencast introducing IDLdoc.

By the way, two minutes of screencast took about two hours of production time. I got a lot of valuable experience doing this though, so I'm hoping to do some more of these (for those things that it makes sense for -- maybe some IDL Workbench topics).

IDLdoc 3.0 is ready! Highlights of this release:

1. IDLdoc 3.0 was rewritten from scratch to allow it to be released under an open source license. Source code is available from the project website.
2. There are multiple formats for entering comments: the normal IDLdoc style, the traditional IDL comment header, and new style based on restructured text.
3. Ability to do some simple formatting of comments without resorted to putting ugly HTML into your comments.

For more information about this release, see the project website download page.

I've given up waiting for ITT VIS to release the source code of IDLdoc 2.0 and rewriting a new version from scratch. I intend to release the source code under a BSD-style license.

I'm using this as an opportunity to make IDLdoc 3.0 much cleaner than the old piecemeal code base of IDLdoc 2.0. I had already been writing many of the underlying libraries used such as array list, hash table, and template classes since I use them for other tasks, so I've got a good foundation to build upon.

I'm not sure of how long this will take since I'm doing it in my spare time, but check out a sneak peak of IDLdoc 3.0 output. There will be new features as well in this release: the biggest being several options on the format for comments (i.e. you won't have to use the "@"-style tags).

If you are interested in keeping up with news about IDLdoc, reporting bugs, asking for features, and general discussion, signup for the mailing list.

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:

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

Continue reading "Overview files for IDLdoc’ed libraries."