Natural Docs 1.3 released
October 4th, 2004
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
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
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
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
New Topics and Languages
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
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
Much Faster Unframed HTML Generation
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.
New Web Site
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
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
Perl users can now use POD to write Natural Docs comments instead of stringing
Fixed a formatting bug that occurred when using a
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!
|Copyright © 2003-2011 Greg Valure|