Finally!  This is the longest I’ve ever gone between releases, so be prepared for some long release notes.

There’s a new configuration file called Topics.txt.  Now you can add and remove keywords, change topic behavior, or even add new topic types (which get their own indexes) without editing the source code.  So if you need to document something particular to your project or language, such as sound effects for video game developers, you can do so easily.

There’s two of them: one in Natural Docs’ Config directory that applies to everything, and one in your project directory that applies just to your project.  So you can override these settings on a per-project basis, or you can use the project file just to keep your changes separate so they’re more managable and you don’t have to reapply them whenever you upgrade.  As an example, in my own documentation I made types and constants always global and I added a topic type, keywords, and an index for CSS styles.

There’s another new configuration file called Languages.txt which does the same thing with language definitions.  You can add basic support for completely new languages without touching the source code.  Now even the most obscure language can have a powerful documentation generator.  You can make it find prototypes for any topic type, including the new ones you create.  You can also add and remove file extensions, and again, it can all be done globally or per project.

Menu.txt got a nice improvement as well.  If you only use one input directory, the file paths are relative again which lets Menu.txt play nice with versioning systems like CVS and SourceSafe.

Prototype formatting has been much improved.  This is what they looked like in 1.22:  (This is a real example from Cities3D)

And this is what they look like in 1.3:

Types and parameter names are now aligned in their own columns.  Modifiers and default values are as well, and are also faded out to reduce clutter.

Indexes have been able to ignore certain prefixes since 1.14; if you documented $variable in Perl it will appear under V instead of with the symbols.  Well, now that you have Languages.txt and can specify settings per project, you can use this to remove any common prefixes in your code.

Suppose you start all your class names with C.  If you want, you can have it so CCat, CDog, and CMouse appear under C, D, and M instead of all under C.  You can remove common function prefixes like COM_ or common hierarchy levels, like NaturalDocs:: in my code.  They’ll still appear in the index, they’ll just be split off in a gray sidebar and the entries will be sorted as if they weren’t there.

Natural Docs’ list of supported languages grows to eighteen with the addition of Flash ActionScript, ColdFusion, R, and Makefiles.  Expect support was added to the Tcl definition.

New topic types as well: Events, Delegates, Interfaces, Macros, Cookies for web devs, and Targets for makefiles.  These types will be distinguished automatically in C# since it has full language support, or if you used the keywords macro, define, or def.

Many new topic types specifically for database developers.  You can now document Databases, Tables, Views, Indexes, Cursors, and Triggers, and each will get their own index.  In .sql files, indexes and triggers will get prototypes as well.

You can now put custom CSS files in your project directory instead of just Natural Docs’ Styles directory.  In addition, you can specify multiple styles on the command line.  The combination of these two means you can make a custom style sheet that just contains your changes to a main style, keep it in your project directory, and include them both on the command line.  Like with Topics.txt and Languages.txt, this keeps your changes separate and easy to manage, and they don’t need to be reapplied when you upgrade.

When using Cities3D as one of my test projects, I discovered that on large projects, updating the menu takes almost as long as rebuilding all the documentation from scratch.  I had no idea that building the menu could take longer than building the file’s actual content!

So with some intelligent caching and post-markup, the improvement was very dramatic.  So dramatic that instead of being proud of the improvement, I’m almost embarassed that it was so bad before!

With 185 documented files, 6 indexes, basic language support, and no source file changes (meaning no “Parsing n files...” stage), rebuilding the output with -ro took 1:09.  Only updating the menu took 0:55.

After the improvements, rebuilding the output took 0:21 and only updating the menu took 0:07!  That’s 48 seconds off each!

This doesn’t improve the speed of the parsing stage, and the difference won’t be as pronounced with full language support because that needs heavy-duty parsing even in the building stage, but still.  If the only reason you switched to framed HTML was for the generation speed, you may want to give unframed HTML another shot.

All these new features and configuration files are documented on our brand-spankin’-new web site.  NaturalDocs.org got a big face lift, new content like a troubleshooting page, and improvements to most of the existing pages.

Added the -xi (--exclude-input) command line option, so now you can prevent certain subdirectories from being scanned for Natural Docs content.  This is especially good if you want to have Menu.txt use relative paths for CVS; you can use a higher input directory with -i and exclude the ones you don’t want with -xi so you only have one input directory.

Auto-groups can combine now, so if you mix together functions and properties, you won’t get a new heading for every one or two entries.

Function lists break apart now.  They will appear in the output as if you wrote individual topics for them, and thus will have individual entries in the summary as well.  You can apply this property to any topic type through Topics.txt.

Perl users can now use POD to write Natural Docs comments instead of stringing # lines together.  Just use =pod begin nd and =cut.  As a convenience, you can also use just =nd and =cut, but that will cause problems with POD extractors.  It will still run fine, but don’t use it unless no one is ever going to run a POD extractor on your code.

Fixed a formatting bug that occurred when using a (start code) section right after a bullet or definition list.

Long URLs now wrap in the output.

Added an overflow style to example code and text diagrams, so for browsers that support it, they will now scroll instead of making the page too wide.  So far this only works in Mozilla/Firefox and Opera 7.  IE doesn’t support it.

Got around an annoying problem in IE 6 with XP Service Pack 2 that would cause the documentation to generate script security warnings when viewing them from your hard drive.

The .ads and .adb file extensions are now recognized for Ada.

Whew!  That’s it!  Enjoy!