Hey look at that, I’m not dead... again!  First the features, then an update on the project.

The biggest new feature is the addition of syntax highlighting.  Both prototypes and (start code) segments will be highlighted via the integration of Google Prettify.  You can turn this off or extend it to >, :, and | prefixed lines with the -hl command line option.

You can also use named links instead of just raw URLs and e-mail addresses.  This is done with the “at” keyword, which was chosen because it often fits right into the sentence and leaves the source readable: “Visit the <web site at http://www.naturaldocs.org>” becomes “Visit the web site” in the output.

The licensing has been changed.  Natural Docs has moved from version 2 of the GPL to version 3 of the AGPL.  I was planning to do this with 2.0 and leave 1.x alone, but Prettify’s Apache license wouldn’t be compatible otherwise so 1.x gets it too.  I’ve also updated the license text in numerous files to make explicit what I thought was always assumed: any generated documentation you create is your own and not subject to the GPL.  The JavaScript and CSS files bundled with it are still part of Natural Docs, but their licensing doesn’t apply to the documentation as a whole.

A bunch of minor bugs are fixed as always, but I’m not going to go through them except for one.  Natural Docs will now handle files with classic Mac line breaks, which some IDEs apparently still use.  This is more of a problem with Perl sucking than Natural Docs, but I’ve successfully worked around it.  Perl still chokes on UTF-16 files though.

So anyway, on to the project as a whole.  I’ve actually been sidetracked with a different project for the better part of the past year so no real progress has been made in that time.  Now that that’s come to a close I’m ready to get back into it.  I’m still going to be dedicating most of my time to the C# version because all the old reasons still apply: the engine needs an overhaul and I can’t imagine doing it in Perl.  However, unlike before I’m going to occasionally drop back into the Perl code instead of just letting it languish.  If there’s a feature that works into the existing architecture easily I’ll add it, and I might backport a few from 2.0.

1.5 illustrates this well.  Prettify was something that was fairly easy to tack on.  A native highlighter would have been better but isn’t worth the effort at this point.  Named links were backported from 2.0 because they fit into the architecture easily.  And Perl’s inability to handle Unicode and cross-platform line breaks transparently is another example of why it’s better to switch to something more modern.  It wouldn’t be a deal breaker on its own but I have many such examples.

So that’s it for now.  People occasionally ask me when 2.0’s coming I don’t have an answer.  Time isn’t as plentiful as is was years ago when I started Natural Docs and didn’t have a real job yet.  I’ve been sneaking it in where I can, and actually having some time away from the work I’ve already done has been good for me.  While reacquainting myself with the code I got a fresh look at it and saw where it could be better.  The continued evolution of Mono during that time means I can take advantage of newer language features.  And the other project increased my knowledge of JavaScript considerably which bodes well for what I can do with the output in the future.

Natural Docs 1.4 is finally, finally here.  There are no surprises if you’ve been following the development releases, but let’s go through the big new features for those who haven’t.

First we have search support.  If you look at the documentation there’s an inconspicuous little search entry at the bottom of the menu.  If you start typing in there it will pull up results from the index as you type.  What’s nice about it is that it’s all done in DHTML so there’s no special software to install.  You can just upload your output directory to a web server or open it from your hard drive and it will work.  Also, you don’t have to do anything at all to add it to your documentation.  Just run the new version of Natural Docs and it will appear.

Next is Javadoc compatibility.  If you have full language support, Natural Docs will be able to read any existing Javadoc comments you’ve written and incorporate them into the output.  The conversion can sometimes be imperfect but it’s better than rewriting them all by hand.  As a bonus, you can also write Natural Docs comments without the topic line by using the Javadoc comment symbols but otherwise using Natural Docs’ formatting.

We also have image support now.  You can embed images in your documentation just by writing (see image.jpg) so it makes sense when you’re reading it from the source code instead of looking like a HTML tag.  You can tell Natural Docs where to look for images with the -img command line option.

The ActionScript parser has been updated for ActionScript 3, and the C# parser has been updated to include some of the 2.0 language features.  You can now document structs in C++ as a single entry and all its members will appear in a prototype.  You can still use the old method of documenting each member individually if you want.

As for minor tweaks, the Note and Notes keywords have been removed.  These often caused Natural Docs to include comments that weren’t meant for it in the output, so they’re gone.  You can add them back by editing Topics.txt if you need them.  You can also add timestamps to the footer of your documentation by editing Menu.txt.  There’s now an -oft (--only-file-titles) command line option that tells Natural Docs not to guess at what the title of a file should be by its contents and to only use the file name.  The CSS structure of the generated output has changed a bit so check the changelog if you’ve built your own custom style.  There are too many bugs fixed to list.

The web site got a few updates as well, including a walkthrough of the documentation syntax to help new people get started and a RSS feed of the news.

For those of you who didn’t see the news on the web site, this is probably the last major release using the current Perl codebase.  Natural Docs has needed a big overhaul for quite some time now.  I’ve had a number of features in the back of my mind that I just can’t do under the current architecture.  Ripping out the engine has always been planned but it’s a big project and I wasn’t always eager to work on it.

However, I’m currently working on Natural Docs 2.0 which is just that.  Since I would have needed to rebuild most of it anyway I’m taking the opportunity to switch languages, and I settled on C#.  Perl is great for what it is but I don’t think it’s up to what I had planned, and after working on it for a few months I think I made the right choice.

Natural Docs 2.0 will run with .NET on Windows and Mono on Linux and Mac OS X.  It will always be cross-platform; if a feature of .NET doesn’t work with Mono I won’t use it.  It will also incorporate SQLite which runs in all three places as well.  I’m keeping things close to the vest for now but I’ll start putting out code and development releases as it gets usable.  I may start a developer blog talking about why I chose these things and the upcoming features if there’s any interest.  Let me know though, because I don’t know if I’ll bother if I’m just going to be talking to myself, not that that’s ever stopped anyone from blogging before.

So there you go.  Shiny new 1.4 now, 2.0 in the works.

Yet another release candidate.  Mostly this fixes various language parsing issues:

• Allow generics in base classes in C#.
• Allow angle brackets in function names in C# to support explicitly implementing generic interfaces.
• Allow * as ActionScript function return type.
• Fixed enum property parsing in Languages.txt, which fixes enum handling in C#, Java, JavaScript, VB, and Ruby.
• Allow $, #, and _ before “as” or “is” in PL/SQL prototypes.
• Allow _ before “is” in Ada prototypes.

There’s also a few minor changes such as being able to put * or _ immediately before or after links, such as *<link>*.  “operator” and “operators” are now keywords for functions, and it won’t stop with an error message if it can’t open extensionless files, which is useful in case Natural Docs mistakenly tries to open a system file it shouldn’t be looking at.