Natural Docs 2.2 is done!  Let's recap for those who weren't following the development releases.

The first new feature is custom home pages.  You can now replace this part of the documentation with anything you want:

One option is to set it to a source file using the new Home Page setting in Project.txt.  This can be a regular source file or you can create a text file with Natural Docs content and use that.  Both of these options will let you compose it in Natural Docs' syntax and easily link to code elements.

Another option is to create your own HTML file.  If it's self-contained, meaning any CSS and JavaScript it needs is embedded directly in it, you can also use it with the Home Page setting in Project.txt.  If you need to include images and other external files you can instead create an advanced style, add a home page to it, and then apply that style to your project.

HTML files can have these strings anywhere in them and they'll be replaced by the values from Project.txt, which allows you to have an automatically updating timestamp in your custom HTML file:

• %NaturalDocs_Title%

• %NaturalDocs_Subtitle%

• %NaturalDocs_Copyright%

• %NaturalDocs_Timestamp%

In all cases the header, search box, and side menu will still be visible so people can navigate.  The custom home page will only replace the area highlighted in red.

I updated the default style of the generated documentation.  The fundamental design is still the same; if you're looking at it on Windows with a standard DPI display you might not even notice much unless you were comparing a before and after.  However, it now looks nicer on high DPI displays and Macs.

I switched to the default UI font for each operating system, which provides better readability and comfort.  On Windows the difference is more noticeable on high DPI displays, and on Macs it should just look nicer all around.  The icons were replaced with SVG versions so they no longer get blurry at high resolutions.

The footer with the copyright and timestamp was moved from a too small line across the bottom of the entire page to a panel at the bottom of the leftmost menu.  You can see it in the home page screenshot above.  This provides a little more vertical space for the content panel and lets me increase the font size to something more readable.

Other than that there were a lot of obsessive little tweaks to make sure everything lines up and is spaced well.  I also removed a lot of cruft that was there to support ancient browsers.  Did you know Natural Docs 2.0 originally had Internet Explorer 8 as its baseline?  Plus some tweaks to make IE6 and IE7 at least usable?  While it was fun to see comments referencing Firefox 4, that's a lot of old stuff that could be ripped out.

Natural Docs expects source files to be encoded in Unicode by default.  It will automatically detect and handle all forms of UTF-8, UTF-16, and UTF-32.  But what if you have something different?  Not interpreting your files correctly could make any accented characters appear wrong in the output.  Well, now you can specify other encodings in Project.txt.  For example:

Encoding: Windows-1252

This would set the default encoding for all files to Windows 1252 (Western European).  You can put it near the top of Project.txt to have it apply to all source folders, or under a Source Folder heading to apply to just that one.  You can also specify it on the command line with -e.

If you have a mix of encodings, you can also set them for just certain file extensions:

Encoding: Macintosh *.mac

This sets the encoding for only .mac files to Macintosh (Roman/Western European).  Like before, if it appears under a Source Folder heading it will only apply in that folder.

You can also set character encodings per folder, or for file extensions within that folder:

Encoding: iso-8859-1 C:\My Project\Source\Module1
Encoding: shift_jis  C:\My Project\Source\Module1\*.txt

These rules take precedence over any rules for parent folders, so all .mac files appearing in Module1 are ISO 8859-1.  You can only put Encoding lines that specify folders like this under Source Folder headings.

All operating systems may not support the same character encodings.  You can see which ones are available on yours by running Natural Docs with the --list-encodings command line option.  You can specify them by name or code page number.

The C# parser had fallen out of date so I went through the language specification and updated it to support all the changes through C# 9.0.  That means Natural Docs can properly handle:

• Records, including automatically generating properties for parameterized ones like "record MyRecord (int X, int Y);"

• Tuples

• Init setters in properties

• Expression-bodied constructors, finalizers, and conversion operators.  It was already supported for functions, properties, and other operators.

• Function pointers

• Newer keywords and modifiers

• Syntax highlighting for interpolated strings and constants with digit separators

Plus some other smaller things.  Most of these features already worked fine if they appeared in a function body but might have thrown things off if they appeared in a prototype.  Now they'll work everywhere.

Of course, since this was done C# 10 was released.  Alas.

The SQL parser was also improved to support more modifiers and documenting type members, plus several bug fixes.

• Language-Specific Keywords: So the issue is that "Record" means one thing in C# and another thing in SQL.  "Module" means one thing in SystemVerilog and another thing in Perl.  So while there is still only one set of comment types in Comments.txt, you can now add keywords for them that only apply to certain languages.  This probably doesn't mean much to you because if you're customizing Natural Docs for the languages you use it doesn't matter if you step on the ones you don't.  However, it's good for Natural Docs itself because now these distinctions can be supported out of the box without any customizations.

  Consequently, "Record" only serves as a keyword for "Class" in C# to prevent unexpected behavior in other languages.

  This also means all the database keywords can now be used without a prefix in SQL files.  You can just use "Table" or "Field" instead of "Database Table" or "DB Field".

• XML Links: Natural Docs now supports <a href=""> and <see href=""> links in XML comments.  It will also detect bare URLs and e-mail addresses and convert them to links as well.

• Bug Fixes: Fixed a bug related to resolving links with parameters, so something like <MyFunction(int, int)> will go to the correct definition.  Also fixed bugs related to embedding images, inaccessible files, and when class attributes can be mistaken for parameters.

There was some discussion about Natural Docs' licensing, specifically how parts of it get included in your documentation, such as JavaScript and CSS files.  Those files are licensed under the AGPL, but bundling them doesn't require the project you're documenting to be AGPL.  I tried to make this explicit in the license but now the web site has a license page to make it even more clear.

Still, some people thought businesses would be spooked, so if you need to have it licensed under different terms or have some sort of open source indemnity clause contact me and we can work something out.  I've written all of Natural Docs' source code so I can relicense it as I see fit, with the exception of SQLite which is public domain.

It would have to come with a support contract, so if your business needs one of those I can oblige.  If you're working for a large company that uses Natural Docs this would be a good way to fund its development.

If you feel like sponsoring Natural Docs' development as an individual you can now do so through GitHub.

I'm going to start looking at full SystemVerilog support in earnest.  Natural Docs seems to have a bit of a following there and this release laid some of the internal groundwork it would need.  I'm not familiar with hardware design though so if you want to be part of a group I can bounce questions off of e-mail me.  A handful of people already have, so even if it was a while ago or you didn't get a response don't worry, I saved it.

Some other things I'm planning to do are adding a dark theme, probably with the ability to switch between them live, and updating the C# parser to version 10 of the language.  There will be more besides that but I don't want to over-promise in case something doesn't pan out.  If you want to keep up with what's coming down the pike make sure you're subscribed to the Development Releases mailing list.  I try to make sure all the development releases are stable enough to use, but even if you don't it still lets you follow along with development.