Natural Docs News

Natural Docs 2.4 Development Release 2: Repository Links and Speeeed!

2026-01-20T00:00:00Z

New update time. Let's see what I've been up to.

Repository Links

You can now add links to web-based repository sites like GitHub to your documentation. After you do, whenever you hover over a prototype a tab will pop up with a link to its source code:

It works for class prototypes too:

But what if more than one file defines something, like how C++ has header and source files? I got you:

You can see it working live on Natural Docs' own documentation.

To add this to your project, edit Project.txt and add "[Site Name] Repository: [Project URL]" under the Source Folder heading. If you have multiple Source Folder lines they would each need their own:

Source Folder: C:\My Project\src

   GitHub Repository: https://github.com/MyUserName/MyProject/

If you're using GitHub, Codeberg, or Gitea that's all you need. If you're using GitLab or you want links to go to a specific branch, add the line "Branch: [Branch Name]" underneath it. (GitLab doesn't have a way to link to the trunk without knowing its name, so you have to specify whether it's "master" or "main".)

If you use a different site you have to tell Natural Docs how to link to source files. Add a "Link Template: [URL]" line underneath with {File} and {LineNumber} used to represent where the file path and line number should go. For example:

Source Folder: C:\My Project\src

   Repository: https://mysite.com/repo
      Link Template: https://mysite.com/repo/src/{File}#L{LineNumber}

The repository name and project link aren't otherwise used yet, but they'll probably be added to the menu somewhere in a later release.

Are there any other major repository sites you use? Building in support would mean people wouldn't have to define the link template manually. I know there are others like Azure Repos but I couldn't find public projects to test them out. E-mail me if you use one; there's only three or four questions I would need answered and they're pretty straightforward.

Speeeed!

So... I may have undersold the speed increase of moving to native binaries when I announced development release 1. I only tested macOS, and the source and output folders were on network shares which muted the results. I ran them again with everything local and, well, Natural Docs 2.4 DR1 actually cuts 73% off the run time when doing a full rebuild. Yes, running a native binary on Apple silicon without Mono and Rosetta removes almost three quarters of the run time.

It's faster on Windows too! Running a native x64 binary cuts 41% off the run time versus running it through the .NET Framework.

Things were tweaked a bit further for development release 2. I moved from .NET 8 to .NET 10, which has new compiler optimizations, and I made a customized build of SQLite that cut out a bunch of things I don't use. The results are a tiny additional speed bump over DR1, most pronounced on Windows.

The only tradeoff is that Natural Docs now requires macOS 12 Monterey. Development release 1 supported back to macOS 10.15 Catalina, but the move from .NET 8 to .NET 10 bumped up the requirements.

So yeah, if you aren't already using the development releases I would highly recommend doing so!

Quick Documentation

As I mentioned last time, I was thinking about requiring Javadoc or XML comment symbols for quick documentation, since that would prevent it from being triggered accidentally. It's only one extra character, and it more clearly shows that the comment is intended to be documentation. It's been implemented, so now you use it like this:

/* Enum: Colors
 */
public enum Colors {
   Red,   /// The color of apples
   Green, /// The color of grass, but also some apples
   Blue } /** The color of the sky, but not apples */

Note that this is only for the comment symbols, meaning you have to use /// or /** and */. It does not mean you have to format the comment contents in Javadoc or XML, so you can still use Natural Docs formatting like *bold* and <links>.

Language Improvements

C# has minor parser fixes, now supporting nullable appearing after array brackets like "int[]?", a comma trailing the last value in an enum like "enum X { A, B, C, }", and using enums with the Documented Only setting.
PowerShell function prototype formatting has been fixed. It also detects types like [string].
PowerShell now supports <# #> block comments.

Odds and Ends

Prototype parameters that have multiple metadata blocks get formatted better, breaking them out into their own lines. This is useful for PowerShell where each parameter can potentially have several modifiers, but it can happen in other languages as well.
Other smaller fixes and improvements.

Natural Docs 2.4 Development Release 1: Native Binaries and Quick Documentation

2025-10-22T00:00:00Z

It's time for a new development release. What's been going on behind the scenes?

Native Binaries

I've migrated Natural Docs from the .NET Framework to precompiled .NET 8 binaries. What does that mean for you?

The biggest benefit is that Apple-silicon Macs and Windows Snapdragon PCs will be faster and more efficient. They're ARM64 chips, and now we have ARM64 binaries! My testing showed the "resolving links" stage on an M1 Mac takes 30% less time this way. The parsing and building stages won't see as big an improvement but that's because they're more I/O-bound.

Up until now I've relied on Mono to run Natural Docs on Macs, but Mono only emits x64 instructions (at least the version on mono-project.com anyway.) That means it must then also be run through translation layers like Apple's Rosetta. Having a native ARM64 version allows it to skip all that and run at full speed. Also, Apple will be discontinuing Rosetta in a couple of years so this had to happen eventually.

So now you can just download and run the new macOS and Linux binaries without installing anything else. You don't need Mono anymore. You don't need to install anything for .NET either, all the components it needs are compiled into Natural Docs itself.

But wait, isn't bundling .NET going to bloat Natural Docs? I was worried about that, not wanting it to turn into a 100MB download or become heavy like Electron apps, but I was pleasantly surprised. The libraries get stripped down to only the parts you actually use, and Natural Docs has a very light footprint, so the downloads are all less than 5MB in size.

The web site will automatically detect your system and select the correct download for you. However, only Chrome and Edge allow it to detect the processor type so you may need to double check it if you're using Safari or Firefox. All downloads are available by clicking "Other Platforms and Options". I didn't make any 32-bit builds because I assume no one needs them, but you can let me know if I'm wrong.

An Experiment with Quick Documentation

So I alluded to a potential new feature in the last update, and it's something that's currently only implemented for enums in C#, but it has the potential to expand beyond that.

Suppose you're documenting enum values. You have to duplicate them in the comment:

/* Enum: Colors
 *
 * Values:
 *    Red   - The color of apples
 *    Green - The color of grass, but also some apples
 *    Blue  - The color of the sky, but not apples
 */
public enum Colors {
   Red,
   Green,
   Blue }

What if you could just document them with a quick comment inline?

/* Enum: Colors
 */
public enum Colors {
   Red,   // The color of apples
   Green, // The color of grass, but also some apples
   Blue } // The color of the sky, but not apples

This is already implemented and working for C# enums. You can just put a regular comment after any value on the same line and it will be pulled into the documentation. It doesn't need a keyword or any other kind of header. You can extend the comment to multiple lines if it needs to be longer, and you can choose to only document some values if the others are self-explanatory.

It doesn't seem like that big a deal above, but when lists get to be a dozen or more values the duplication is more of an issue. Also, when this idea was first suggested to me it was for documenting simple structs where there would be more space and effort savings. You could replace this:

/* Struct: Point
 * Represents a point on an X/Y axis.
 */
public struct Point {

   /* Variable: X
    * The horizontal position.
    */
    public int X;

    /* Variable: Y
     * The vertical position.
     */
    public int Y;
    }

with this:

/* Struct: Point
 * Represents a point on an X/Y axis.
 */
public struct Point {
    public int X; // The horizontal position.
    public int Y; // The vertical position.
    }

So C# enums were a proof-of-concept, with other potential applications being simple structs like above, module ports in SystemVerilog, and maybe even function parameters.

However, getting something that works predictably is a bit tricky. Ideally I'd like both of the struct comment styles above to Just Work™ without needing any special syntax to distinguish between the two approaches. That might be doable, but the second method is potentially fragile when you try to do it with basic language support. For example, it wouldn't work once you add a function to the struct, if the parent isn't documented, or if it's longer than a certain length. If a feature doesn't behave predictably and in ways that are obvious (it doesn't matter if I document the conditions somewhere, people aren't going to memorize them) then it's potentially unreliable, which makes it a bad feature. It's more robust with full language support but that limits its reach. So I'm left between "leave it as a niche feature for enums but don't expand it to areas where it can be flaky" and "don't scrap a feature that could be nice in certain conditions just because it wouldn't work in all of them."

There's also the issue of it being triggered unintentionally, but I think I'm going to change it to require Javadoc-style comment symbols (/// or /**) to prevent that. It's only one extra character and it more clearly says "this is supposed to be documentation."

Another issue is it's not easy to integrate this idea into the rest of the code so it's a bit of a time suck when I could be working on features that are more broadly beneficial, like finally adding more languages to basic language support and adding source links to repositories like GitHub.

I think I'm leaning towards expanding it slowly over time with full language support where it's more robust, but not putting a high priority on it. Maybe it can be added to basic language support in a few places where I feel it can be reliable. What are your thoughts? Would you ever use it for, say, documenting function parameters?

Language Improvements

SystemVerilog was reverted to "basic language support with extra formatting code for modules" because it wasn't meaningfully updated while I was sidetracked with this. This allows it to remain usable in this release.
C# will now pull enum values into your documentation whether you write comments for them or not. So you can document them the old way, use the new quick method above, or do neither and you'll still have all values in your output.
C# can now handle raw strings like $"""abc""", including multiline and interpolated ones. It will also now syntax highlight code sections in interpolated strings like $"abc { x + 12 } def".
PowerShell variables now get prototypes.
PowerShell syntax highlighting is improved. This includes highlighting attributes like [string], but it still needs some work when used with function parameters.
Shebang Scripts now include .sh and .command files by default.

Odds and Ends

Console output has been improved so if you're running Natural Docs in a terminal or console window it will show progress as a live-updating percentage. If it's being captured by an IDE or otherwise redirected it will behave closer to how it did before.
Exit codes will now be returned so scripts and automated build processes can more easily tell whether a run succeeded or failed. After running Natural Docs you can check %ErrorLevel% in batch files, $LastExitCode in PowerShell, or $? in bash scripts to see if there was a problem. As is the convention, a value of 0 means it succeeded and anything else means it failed.
Other smaller fixes and improvements.

Natural Docs 2.3.1 released

2025-02-01T00:00:00Z

Hello all. Here's a small release to bundle up all the things that have changed since the last one.

The primary reason is because SystemVerilog is about to move from "basic language support with extra formatting code for modules" to the full language support code path. Once it's on the new path Natural Docs will be able to find modules even if you didn't write comments for them, which is good, but you wouldn't be able to add prototypes for other language constructs via Languages.txt anymore. You'd have to wait until I build out the parser for them. So here's a version to let you use the upgraded basic language support while full language support is worked on in the development releases.

There's more improvements than just that though.

Updated Languages

SystemVerilog will format module prototypes better. It also has dedicated module keywords, and if you use them you'll get a top-level Modules menu next to Files and Classes. If you document the ports using a definition list under a "Ports" or "Parameter Ports" heading it will pull the types into it the same way "Parameters" does for functions.
C# now supports file-scoped namespace declarations ("namespace X;" instead of "namespace X { ... }") from C# 10.
Tcl has improved parameter detection and formatting.
Visual Basic now has property prototypes. They show the type but not whether get/set are defined.

New Languages

PowerShell now has basic language support with custom syntax highlighting. It doesn't support classes though, just functions and line comments.
PowerBuilder now has basic language support with custom syntax highlighting as well.

Odds and Ends

The theme switcher got a facelift. There were minor improvements to how bullet lists are formatted and the black theme's contrast was increased.

Natural Docs can now support languages that have nested block comments. Just add the Block Comments Nest property in Languages.txt. It's already turned on for Pascal/Delphi and PowerBuilder.

That's it for now. Due to some personal issues there wasn't much development for almost a year after 2.3, but things have been picking up again these last few months. I have a new feature I'm going to be attempting plus I'll be continuing to move SystemVerilog towards full support. Follow the development releases if you want to keep up on that.

Natural Docs 2.3 released: Dark Themes

2023-09-11T00:00:00Z

Time for another release. Let's recap what's new for the people who haven't been following the development releases.

Dark Themes

Natural Docs now has dark themes. Rather than just being new styles you can choose for your project, you're able to let the user choose which one they want from the browser. Just click the moon icon next to the search box:

The dark theme is what you'd expect, and the black theme has less color and higher contrast. The auto themes will switch between two automatically based on whether your operating system is in light mode or dark mode, so if you have your OS switch between them on a timer you can have the documentation follow it.

Here's a peek at what the dark theme looks like. You can also see it for yourself here.

How do I apply this to my project?
Just download 2.3 and run it on your project.
What if I have a custom style?
All your existing CSS should apply to the light theme with no changes. The dark and black themes will just recolor it.
Can I customize the other themes too?
Yes, just add additional CSS rules with .DarkTheme and .BlackTheme ahead of them. So in addition to styling ".SHComment" you would also style ".DarkTheme .SHComment" and ".BlackTheme .SHComment".
Can I disable the other themes?
If you're not using a custom style, choose Light as the style in Project.txt or on the command line. If you have a custom style based on Style.txt, edit it to inherit from Light instead of Default. If you just use a CSS file as a style, add "#NDThemeSwitcher { display: none !important; }".
Can I force it to always use dark?
If you're not using a custom style, choose Dark as the style in Project.txt or on the command line. If you have a custom style based on Style.txt, edit it to inherit from Dark instead of Default. You can't do it with just a CSS file because those always inherit from Default.

Better macOS Compatibility

The SQLite binaries are now signed and notarized, so you shouldn't have issues with macOS blocking them saying the developer can't be verified. They should just work without you needing to make an exception in the System Preferences. If Natural Docs has ever crashed complaining about libNaturalDocs.Engine.SQLite.Mac64.so this was why.

SystemVerilog

Work on full language support for SystemVerilog continues but is not ready yet, so 2.3 still has basic language support. There's an entry in Languages.txt for it, but this is just a placeholder so you'll probably still need to fill it out a bit more with your own settings to use it. However, the syntax highlighting has been improved. All of SystemVerilog's keywords will highlight correctly as well as complicated numeric literals like 8'b0011_00zz.

Fully-Qualified Title Fix

Probably because I primarily work in C#, which has full language support, and JavaScript, where I only use pseudo-classes, I didn't realize this wasn't working. Suppose you have this:

namespace MyNamespace {

   // Class: MyNamespace::MyClass
   class MyClass {
      ...
      }
   }

You wouldn't get a prototype for MyClass because the declaration doesn't match the full title of MyNamespace::MyClass. This has been fixed, so it only requires the last segment to exist in the prototype now.

Odds and Ends

HTML Modernization. Just like SQL before it, SystemVerilog caused a big refactor of the prototype handling code due to how different it can be from other languages. As a result, prototype output has been completely rebuilt using CSS's grid feature. This in turn increases the minimum browser requirements for the documentation, but all the major browsers implemented grid support sometime in 2017, so it's still pretty conservative. It just means no more Internet Explorer and no more pre-Chromium Edge.
Better Prototype Formatting. The new prototype code improves formatting for things like C# properties, indexers, and events. Your function and variable prototypes should look almost exactly the same though. There's a few spacing tweaks that may be applied but they're subtle.
Maximum Line Length. This is something I've always been ambivalent about doing. I've always liked text going to whatever window size you choose, but on an ultrawide monitor it does get kind of ridiculous. So now there's a maximum line length for readability, but it only affects plain text. If you have a really wide prototype, code block, or image it will still take as much horizontal space as it needs instead of forcing you to scroll.
If you want to turn it off, make a custom style with this rule:

.CTopic p,
.CTopic li p,
table.CDefinitionList { max-width: none !important }

Other minor bug fixes and tweaks.

Natural Docs 2.3 Release Candidate 1

2023-08-23T00:00:00Z

It's been a while. Time to wrap up the development releases and put something out, so I'm calling this one Release Candidate 1. I think it's pretty much ready.

Dark Themes

I tied up all the loose ends on dark themes. First, your theme choice will now be saved. If you set it to Dark it will still be on Dark the next time you open your documentation. It will also be preserved when you open new tabs or windows.

Second, I added options for Auto Light/Dark and Auto Light/Black. If your browser and operating system support it, it lets the theme follow the system theme automatically.

I was really tempted to make Auto Light/Dark the default, but I think I should follow the Principle of Least Astonishment. Otherwise someone can upgrade their version of Natural Docs and their documentation will look completely different without them expecting it, assuming they didn't read the release notes. So Light remains the default.

Other Improvements

Better macOS Compatibility. The SQLite binaries are now signed and notarized, so you shouldn't have issues with macOS blocking them saying the developer can't be verified. They should just work without you needing to make an exception in the System Preferences.
HTML Modernization. Just like SQL before it, SystemVerilog caused a big refactor of the prototype handling code due to how different it can be from other languages. As a result, prototype output has been completely rebuilt using CSS's grid feature. You shouldn't see any difference for 90% of your prototypes, though there will be improvements for some edge cases like C# indexers.
As a result of switching to grid, the minimum browser requirements have been increased. All the major browsers implemented grid support sometime in 2017, so it's still pretty conservative. It just means no more Internet Explorer and no more pre-Chromium Edge.
Maximum Line Length. This is something I've always been ambivalent about doing. I've always liked text going to whatever window size you choose, but on an ultrawide monitor it does get kind of ridiculous. So now there's a maximum line length for readability, but it only affects plain text. If you have a really wide prototype, code block, or image it will still take as much horizontal space as it needs instead of forcing you to scroll.
If you want to turn it off, make a custom style with this rule:

.CTopic p,
.CTopic li p,
table.CDefinitionList { max-width: none !important }

Other minor bugfixes and tweaks.

What About SystemVerilog?

Work has continued on it, but there's nothing worth showing yet, so the code will behave the same way it did in the previous release. I'm not going to release a broken partial implementation. Work on it chugged along for a while, then I got sidetracked by grid prototypes, plus a period where I didn't have much time to code at all, plus it now getting put on pause so I can wrap up this release. Work will continue on it, but it won't be in 2.3.

Natural Docs 2.3 Development Release 1: Dark Themes

2022-06-23T00:00:00Z

Time to start a new batch of development releases. What do we have so far?

Dark Themes

I originally planned on doing some easy, low-hanging fruit features while I worked on SystemVerilog. Adding dark themes turned out to be a bigger effort than I thought, but I'm pretty happy with the results:

These aren't just additional styles you can choose when you build your documentation. If you use the default style you get all three themes and you can switch between them from the browser. Just click the moon icon next to the search box:

The dark theme is what you expect, plus there's a black theme that's higher contrast. You can give them a look here.

How do I apply this to my project?
Just download the latest development release and run it on your project.
What if I have a custom style?
All your existing CSS should apply to the light theme with no changes. The dark and black themes will just recolor it.
Can I customize the other themes too?
Sure, just add additional CSS rules with .DarkTheme and .BlackTheme ahead of them. So in addition to styling ".SHComment" you would also style ".DarkTheme .SHComment" and ".BlackTheme .SHComment".
Can I disable the other themes?
If you're not using a custom style, choose Light as the style in Project.txt or on the command line. If you have a custom style based on Style.txt, edit it to inherit from Light instead of Default. If you just use a CSS file as a style, add "#NDThemeSwitcher { display: none !important; }".
Can I force it to always use dark?
If you're not using a custom style, choose Dark as the style in Project.txt or on the command line. If you have a custom style based on Style.txt, edit it to inherit from Dark instead of Default. This all works for Black as well. You can't do it with a style that's just a CSS file because those always inherit from Default.

Still to do:

Implement saving your choice. Right now it doesn't so it resets between browser sessions or when you open a new tab.
Auto-light/dark and light/black themes. If you have your browser follow the operating system's theme, there's ways for the documentation to detect that and follow it as well.

SystemVerilog Improvements

SystemVerilog now has an entry in Languages.txt, but this is just a placeholder so you'll probably still need to fill it out a bit more with your own settings to use it. However, a couple of things have been implemented:

Syntax Highlighting. All the SystemVerilog keywords will highlight correctly as well as numeric literals, including complicated ones like 8'b0011_00zz.
Module and Package Hierarchies. In addition to the class and database hierarchies, there are now ones for modules and packages that you can use in Comments.txt. The final set of hierarchies is still in flux but these two exist for now.

Otherwise it's still the same as basic language support. It won't find undocumented code structures yet or do any special formatting for prototypes. More to come.

Fully-Qualified Title Fix

Probably because I primarily work in C#, which has full language support, and JavaScript, where I only use pseudo-classes, I didn't realize this wasn't working. Suppose you have this:

namespace MyNamespace {

   // Class: MyNamespace::MyClass
   class MyClass {
      ...
      }
   }

Other Bug Fixes

Fixed a potential infinite loop in the XML comment parser.
Fixed some minor issues with the C# parser.

Natural Docs 2.2 released

2022-02-21T00:00:00Z

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

Custom Home Pages

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.

HTML Refresh

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.

Character Encodings

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.

Language Improvements

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.

Odds and Ends

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.

Licensing, Support, and Sponsoring Development

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.

What's Next

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.

Natural Docs 2.2 release candidate 1

2022-01-16T00:00:00Z

Wrapping up 2.2.

Fixed a bug related to resolving links with parameters, so something like <MyFunction(int, int)> will go to the correct definition.
Some finishing touches to the updated output style, which are pretty subtle.

That's it, plus some internal cleanup work. Since everything seems pretty stable I'm deeming this a release candidate. If nothing pops up in the next few weeks this will be 2.2.

Natural Docs 2.2 development release 4

2021-12-02T00:00:00Z

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.

Internals

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.

Natural Docs 2.1.1 released

2021-04-13T04:00:01Z

Just uplifting some bug fixes from the development releases into the stable releases so you don't have to wait for 2.2.

SQL: Fixed a crash, something that could cause prototypes to not show up, and something that could cause prototypes to include too much of the code.
Images: Fixed a crash when working with embedded images.

That's it. If you don't use either of those you're safe skipping this one.

Natural Docs 2.2 development release 3

2021-04-13T00:00:00Z

New development release. As I said last time I'm laying some groundwork for the future, so the new features probably won't be very exciting but they're important for Natural Docs going forward.

Language-Specific Keywords

So here's the issue: "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" now only serves as a keyword for "Class" in C# to prevent unexpected behavior in other languages.

However, 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".

Language Modifiers

This is rather niche, but if you really want to you can use a language name as a modifier before a keyword. So you could document a JavaScript class from a C# file just by writing "JavaScript Class: MyClass". This is probably most useful when you're documenting things from a text file.

Bug Fixes and Tweaks

Fixed a bug that could prevent SQL prototypes from appearing.
Fixed a crash that could occur when embedding images.
Errors on the command line or in the configuration files no longer cause a full rebuild the next time Natural Docs is run. It will still do a full rebuild after a crash though, or if it detects changes to the configuration that require it.
I finally tested some old versions of Mono to see what the minimum version Natural Docs needs is. Apparently you need at least Mono 4.0 for it to run without crashing. That was released in 2015, but some Linux distributions have even older versions. Natural Docs will now tell you if you're on a version that's too old and it crashes.

Natural Docs 2.2 development release 2

2021-01-10T00:00:00Z

Updates for C# and SQL users. Everyone else is fine skipping this one.

The C# parser had fallen out of date, so I went through the language specifications 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 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.

I fixed a couple of bugs in the SQL parser as well. Next up are a couple of small features which aren't very exciting but are needed to lay the groundwork for SystemVerilog.