Natural Docs 2.2 development release 4
December 2nd, 2021

I really need to start wrapping up 2.2.  So what's new in development release 4?

Simpler Options for Custom Home Pages

In development release 1 I added the ability to have your own HTML file to serve as the home page instead of the default one.  It required creating an advanced style, adding a HTML file to the style's folder, and adding "Home Page: [file name]" to Style.txt.  This approach lets you include images, CSS, and JavaScript if you want to since those are all supported in advanced styles.  However, just like there's a simple way to create a style with a single CSS file, there are now simpler ways to make your own home page.

You can now add "Home Page: [file name]" to Project.txt as well.  One option is to point it to a documented source file which lets you create a home page in Natural Docs' syntax.  Just create a .txt file in your source tree, add Natural Docs content, and point Project.txt to it.

Another option is to point it to a .html file and that will be used as the home page instead.  It doesn't have to appear in the source tree so you can put it in your project configuration folder if you want.  However, it's a standalone file so you'd have to embed any CSS it needs directly in it.

Like before, you can put these strings anywhere in the HTML file and Natural Docs will replace them with the project information.  This is useful if you wanted to add a build timestamp that updates automatically.

  • %NaturalDocs_Title%

  • %NaturalDocs_Subtitle%

  • %NaturalDocs_Copyright%

  • %NaturalDocs_Timestamp%

As a reminder, custom home pages replace this part of the site:

The title, search box, and side menu will still be visible.  If you use a source file as the home page the left side menu will still show the starting menu instead of jumping to that page.  This feature isn't documented on the web site yet but will be once 2.2 is released.

Character Encodings

Natural Docs expects Unicode source files 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?

Now you can manually specify character encodings for your source files.  You do this by adding Encoding lines to Project.txt:

Encoding: Windows-1252

This sets the default encoding for all files to Windows 1252 (Western European).  If it appears in the project information section it will be the default for all source folders.  If you put it under a Source Folder heading it will be the default for just that folder.

Encoding: Macintosh *.mac

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

Encoding: iso-8859-1 C:\My Project\Source\Module1

This sets the encoding for all files in the Module1 folder to ISO 8859-1.  This rule takes precedence over any rules for parent folders, so all .mac files appearing in Module1 are also ISO 8859-1.  You can only put Encoding lines that specify folders like this under Source Folder headings.

Encoding: shift_jis C:\My Project\Source\Module1\*.txt

This sets the encoding for all .txt files in the Module1 folder to Shift JIS.  If you needed to reapply the .mac rule for this folder you could also include "Encoding: Macintosh C:\My Project\Source\Module1\*.mac".  Since these rules specify folders they can only appear under Source Folder headings.

All operating systems may not support the same encodings.  You can see which ones are available on yours by running Natural Docs with the --list-encodings command line option.  You can use either the name or the code page number (the second and third columns) in Project.txt but not the description (the first column.)

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.

Tweaks and Fixes
  • Improved the SQL parser to support more modifiers and documenting type members.

  • Fixed a bug that could prevent image links from working when they are relative to image folders which are contained in source folders.

  • Fixed a bug that could cause an infinite loop on inaccessible files (though not on files in inaccessible folders.)

  • Fixed bugs that could happen when class attributes can be mistaken for parameters.


This won't mean much to you right now but it lays the groundwork for the future.  How hierarchies are handled internally has been refactored, which means it will be much easier to add new ones going forward.  Instead of hard-coded logic for classes and databases there's a more generic system that can handle those plus other future ones.  They aren't configurable through text files like the rest of Natural Docs, and that may or may not change in the future, but it's the last piece that needed to be put in place to start on full SystemVerilog support.

Earlier Discuss Share Later
Natural Docs 2.1.1 releasedNatural Docs 2.2 release candidate 1
FacebookTwitterE-MailCopy Link