[idldoc] IDLdoc 3.0 beta 1

[Michael Galloy]

IDLdoc beta testers,

Grab the IDLdoc 3.0 beta from here:

   http://michaelgalloy.com/wp-content/uploads/2007/11/idldoc-3.0b1.zip

Listed below are release notes and known issues. Please let me know  
(by replying to me or this list) any feedback you have. If you are  
reporting a bug, it will speed up the process greatly if you send  
along a minimal example that demonstrates the bug.

Thanks for your help!

Mike
--
www.michaelgalloy.com


Release notes
-------------

* IDLdoc 3.0 is completely rewritten from scatch. It is released under a
   BSD-style open source license (see COPYING file for legal details).  
Feel
   free to make modifications to the source code. If you add something  
cool
   that you think others would be interested, please send me a patch!

* Comments inside ;+/;- that are not immediately before or after a  
routine
   header are considered file level comments. (The file_comments tag  
is still
   used, but is no longer needed.) There are also file-level tags now:
   "hidden," "private", "author", "copyright", "history", "version",
   "examples", and "property".

* Routine comments can be immediately before or *after* the routine  
header.

* Comments can now contain basic restructured text markup. Separating  
lines
   of text with a blank line will create separate paragraphs. Ending a  
line with
   two colons (::) and then indenting will format the indented section  
like a
   block of code.

* It is now feasible to create your own library of templates for  
output. The
   TEMPLATE_PREFIX keyword specifies a prefix before the template  
names. The
   TEMPLATE_LOCATION keyword specifies a directory for the templates  
to use.
   The easiest way to get started with this is to copy the provided  
templates
   to a new location, specify that location with the TEMPLATE_LOCATION  
keyword,
   and start modifying those templates.

   Also the COMMENT_STYLE keyword specifies a classname of the class  
to handle
   outputting other types of comments besides HTML (i.e. LaTeX, rst,  
etc.).

* The style of the documentation can be changed with the FORMAT_STYLE  
and
   MARKUP_STYLE keywords for an IDLdoc run. These styles can also be  
changed on
   a file-by-file basis with a docformat comment on the first line of  
the file
   like::

       ; docformat = 'rst'

   Available with IDLdoc 3.0 are the default IDLdoc style, the IDL  
standard
   template, and a new restructured text based style.

* Uses "requires" tag on routines to find the highest version of IDL  
required
   by a project. Simply put the IDL version required as the first  
match to the
   regular expression::

       [[:digit].]+

   IDLdoc will automatically find it and compare it to other versions
   required. The warnings page will display the highest version  
required and
   list all the routines that require that version.

* The source link is always available (in IDLdoc 2.0 it was only  
active if the
   OUTPUT keyword was not used). There is a NOSOURCE keyword to  
explicitly
   disable this if required.

* Ability to generate output for the IDL Assistant has not been  
reimplemented
   since IDL has a new help system in IDL 7.0. For now, only HTML  
designed for
   a normal browser is provided with IDLdoc (though with the  
TEMPLATE_* keywords,
   users could now do these customizations themselves).

* Requires IDL 6.1. IDLdoc runs on all platforms supported by IDL.


Known issues
------------

* Search is not implemented yet.

* Complexity statistics are not implemented yet.

* The ASSISTANT keyword is obsolete now (and probably will be for the  
release).
   The IDL Assistant is only going to be around for a while longer, so  
it didn't
   seem worth it to reimplement assistant formatted output.

* Defining two classes in one file can lead to name conflicts.

* The help is not complete yet.