Natural Docs News

Natural Docs 1.5 released

2010-07-22T00:00:00Z

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 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 released

2008-05-08T00:00:00Z

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.

Natural Docs 1.4 release candidate 3

2008-03-18T00:00:00Z

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.

Natural Docs 1.4 release candidate 2

2008-01-12T00:00:00Z

Another release candidate. All changes are minor except for one: I removed the Note and Notes keywords. I've actually been meaning to do this for a while because they're often the source of false positives. If someone starts a paragraph with "Note: blah blah blah" the first line will be seen as the start of a new topic, causing all kinds of problems in the output. If you actually used those keywords you can add them back into Topics.txt yourself.

Support for nullable types was added to C#. I also finally recreated the Small and Roman styles.

I went through the entire bug list in SourceForge and picked all the low hanging fruit, since 1.4 may be out for some time while 2.0 is worked on. Fixed a bug where the Perl parser could get tripped up when using anonymous functions that have prototypes. Fixed a bug where horizontal lines could be taken out of code sections. Fixed a bug in the search JavaScript that could cause an error message to show in Internet Explorer.

That's it. Hopefully this is the last release candidate.

Natural Docs 1.4 release candidate

2007-12-07T00:00:00Z

I found some time to tie up the loose ends of the development releases. I now consider the latest one to be a release candidate for 1.4. It has a few bug fixes and tweaks, plus I reverted some of the more arbitrary CSS changes so the people who stuck with 1.35 won't have to update any custom styles as drastically.

C# support is much improved. Since I'm obviously using it more I keep running into the places where it was deficient, mainly because it was originally written for the 1.1 language specification. I added support for enums (why didn't I have this before?) static classes, generics, and fixed the using statement support, though it still doesn't support aliases. It's enough to get by, a more comprehensive update will have to wait.

Beat up on this one so we can finally put the development releases to bed for the people who have been patiently waiting for a stable one.

Where we stand

2007-10-02T00:00:00Z

It's been a while so I guess I owe you an update.

For the last few months I've been taking a hiatus from Natural Docs, so if you e-mailed me or posted in the forum and didn't get a response that's why. I know that kind of sucks of me but I really needed to not think about it at all for a while. I've been getting burned out on it which is why it's been taking longer and longer to put out even small releases. I've been doing this since November 2002 after all.

I'm feeling much better now, but there are going to be changes. I'm not going to keep banging my head against the old Perl codebase anymore. The engine has needed a big overhaul for some time now — it just can't do some of the things I want it to do without a major rewrite. I'm also tired of dealing with Perl. It was great for the little thrown together version I made for myself years ago, but it's deficient in pretty fundamental areas: classes, inheritance, even function parameters. I've worked around them pretty well, but Natural Docs has grown too complex and I can't bring myself to do a major rewrite in Perl. If I'm going to be rebuilding most of it anyway, I'm taking the opportunity to switch languages.

So for the last few weeks I've been working on 2.0, and it's where I'm going to spend all my time going forward. It's being written in C# with .NET 2.0 and Mono for a lot of reasons I won't go into here. I know .NET often implies being tied to Windows but I'm designing it to be cross-platform from the very beginning. I already have it running on Linux with Mono and will be testing it there every step of the way. I'm building the back end on top of SQLite, which I also have running on both platforms already. Managing everything Natural Docs was pulling out of the code and all its cross-referencing was getting hairy with in-memory structures, and it would just get dramatically worse with the things I have planned for 2.0.

I have to say I think I made the right choice. So far this has been a lot more interesting and enjoyable for me. It's not a trudge through old code that I know I'm just going to have to rip out someday. It's fun learning a new language and framework. Natural Docs is actually being brought into this century with Unicode, multithreading, localizations, etc. Features I've had in my head for a long time can actually get built instead of being held back by assumptions I made years ago. And doing some things in a modern language is just so much damn easier than trying to approximate it in Perl. I love how cleanly some things can be done now. I now think my burnout was due to the fact that working on Natural Docs was just objectively starting to suck and it was time for a change.

At some point I'll tie up the development releases and call it 1.4, but not right away. Plans can change, but right now as far as I'm concerned that's the end of the road for the Perl codebase. I'll start posting the 2.0 code, a roadmap, and an explanation of its features when I have more to show for it. It's too early now, and it will still be a while before you have something to play with even in pre-alpha form. I also don't want to talk about specific features just yet in case some of them don't pan out. But they will be cool. Have they not been cool thus far?

I've gone through my backlog of messages and responded to anything that came in within the past two months. If you sent me something earlier than that and are still interested in a response, send it to me again. I figure most people aren't by that point. Also, if I ever take another hiatus in the future where I don't even do support I promise I'll put some sort of notice up first instead of just falling off the face of the earth.

So that's where we stand. Feel free to e-mail me if you have any thoughts or questions.

February 10th development release

2007-02-10T00:00:00Z

So all the major features of 1.4 are done now. Image support is finally completed. You can use -img [directory] on the command line to specify where images are stored, rather than putting them in your source tree and having relative paths from the source files. If you do keep the images there, you can use -img */[directory] to specify relative paths as well, so -img */images means you can just write (see image.jpg) instead of (see images/image.jpg). You can even back up with ../ so long as it doesn't back out of the source tree specified with -i altogether.

ActionScript 3 support is done too. Custom namespaces are supported and affect scope, meaning you have to link to them with <class.namespace.function>.

There's a minor tweak in that underscores are supported in image links. They're also supported in e-mail addresses and URLs that appear without brackets.

Consider this a release candidate for all the major features. There will be one more development release (hopefully not three months from now) with some minor tweaks to other things that will serve as the proper release candidate. If no issues pop up with that it will be stamped 1.4.

November 19th development release

2006-11-19T00:00:00Z

Another development release is finally done.

Search is done. The most important thing is that it works with framed HTML now. It's also much more structurally sound behind the scenes so it doesn't fall back to completely reloading the results frame nearly as often, making it faster. I fixed the IE issue of results not expanding correctly if two of them only differ in case. There are some smaller tweaks but that's the important stuff.

In C++, struct prototypes now format nicely like function prototypes do, provided you didn't document any of the members individually. Many people were asking for that. Also, enum constants are now scoped correctly.

If you put an image reference in the middle of a paragraph instead of on its own line, it will now appear after the paragraph instead of becoming a pop-up. The file name becomes a caption and the reference in the paragraph links to it.

Fixed a bug in the development releases where links would appear with their brackets in tooltips. Fixed a bug in all releases where file names would sometimes get cut down to just their extension in the menu. If Natural Docs automatically adds a file name heading to your output file, it won't include part of the path anymore. Fixed a crash bug in Menu.pm.

That's it. We're almost done with this process so it will hopefully be tied up and stamped 1.4 soon.

So what's going on?

2006-10-18T00:00:00Z

So I start the whole development releases thing with some fanfare, and then I disappear for two and a half months. What gives?

Well, part of that time was spent experimenting with what could become Natural Docs 2.0. I don't know if it's going to pan out or not at this point — it's far too early to tell and it can honestly go either way — so I'm not going to go into the details just yet. It's going to take a while if it does so there's still plenty more life in the current code base. I'm going to be dividing my time between the two based on whichever captures my interest at the moment. I'm not paid to do this (other than donations) so that's the best way to stay motivated, to work on what I want to work on at the moment.

I'm probably going to jump back into the current code base for a while, though, to tie up the loose ends in the current development release and to try to satisfy the big donations that came in for full JavaScript and PHP support. I have to bite the bullet and push C++ back, because that always required a couple of features from the 2.0 engine and I don't want to keep delaying some of the easier languages in favor of it.

So that's it. Maybe next update I'll have something new for you to play with.

July 30th development release: ActionScript 3

2006-07-30T00:00:00Z

Got another development release for you. The big change in this one is the ActionScript parser has been upgraded to support version 3. It has support for regular expressions, XML literals, constants, and other goodies as described on the development page. It even supports .mxml files in addition to .as files, so you can use Natural Docs in <mx:Script> blocks or even in plain XML comments.

The other features are pretty minor. There's an -oft (--only-file-titles) command line option that lets you force the source file name to always be the page and menu title. The search results will try to dynamically update rather than reloading the page every time. The search box was tested and tweaked for IE 6 and 7, Firefox 1.5, Opera 9, 8.5, and 8, and Konqueror 3.5. You can now use braces and parenthesis in your file names without killing the menu.

Natural Docs development release and project changes

2006-07-10T00:00:00Z

Hey look at that, I'm not dead!

I know it's been a while. I know you thought I packed up and moved to Zimbabwe or something, but I'm still here. After a bit of a hiatus and a few false starts, Natural Docs is back in active development.

I'm changing the development process around a bit. Rather than queuing up features for big, monolithic releases and having them just appear without warning, I'm opening it up considerably. New features will now be available in development releases as soon as they're in a usable state, even if every aspect of them isn't fully complete. New features will also be released individually, so right after a stable release you'll see another development release as soon as the first new feature is added and usable.

Everybody wins. The more adventurous of you get to use new features sooner and have a much faster release cycle. The more cautious of you will have better tested stable releases. And all of you will know exactly what's going on and can comment on the new features, even if you don't actually use the development releases.

And that's what I get out of it: more feedback while I'm working on the features, which is when it's easiest to incorporate it, and more testing so I can more confidently label the full releases as stable.

If you're interested in using the development releases or even just following them, you should sign up for the Development Releases mailing list to keep up. I will NOT announce them on the regular New Releases list, which will be reserved for stable releases going forward.

There's a new development page that explains the new features, what their current state is, and lists any questions you can help me out with.

The first one is already out, so here's what's in it. Go to the development page for the full details.

Javadoc Support

Natural Docs will read Javadoc comments and incorporate them into the documentation. Full language support only.

Headerless Comments

Since I had to add this capability for Javadoc, you can skip the "Function: Name" line for Natural Docs too. Just use the Javadoc style for the comment symbols but use Natural Docs formatting for the actual content. Full language support only.

Image Support

Embed images in your documentation.

Search Support

Now this is cool. Head over to this page and play with that nice little inconspicuous link at the bottom of the menu. Maybe type a random letter or two. It's actually more of a quick index lookup than a full search, but still. It also shows how I'm going to be pushing further into dynamic HTML going forward.

Again, sign up for the Development Releases list to keep up with this. I won't be announcing them on the regular New Releases list.

Have fun!

Natural Docs 1.35 released

2005-03-20T00:00:00Z

Another bug fix release, nothing exciting. Sorry if I've been less responsive than usual in responding to e-mail, bugs, and forum posts, I'm still adjusting to a new job.

I tweaked the definition list syntax so now the first line of the list can't be after a plain text line. The line above it has to be blank or something else like a heading. This should cut down on the number of false positives that happen, so accidentally including a “ - ” in the middle of a sentence will be less likely to screw up the output. It's still not perfect, but it sucks less.

Fixed merging with full language support. Now you can document something with parenthesis (like MyFunction(2) or MyFunction(int, int)) and it will still match correctly in the output. Also, you can document with partial names (like "Class: MyClass" for Package.Package.MyClass) and it will do the same. These were already supported with basic language support.

Fixed a SymbolTable crash that I think only happens if you're using full language support with -do.

Plenty of fixes for some of the more obscure Perl language elements. You'll no longer have problems when using $/ and $?, prototypes that end in $), or regular expressions that use # as the delimiter. Also added support for here doc syntax such as <<EOF.

Corrected minor spacing issues on prototypes with grayed out type prefixes.

Indexes won't be added to the Don't Index line in the menu file if you delete the file itself.

Files that start with a dot but don't otherwise have an extension will be treated as extensionless.

The percentages in status messages will be correct when using multiple output directories.