Natural Docs has two files called Languages.txt: one in its Config directory, and one in your project directory.  These control the language and index prefix features of Natural Docs.

You should edit the one in your project directory whenever possible.  It keeps your changes separate and easier to manage, plus you don’t have to reapply them whenever you upgrade.  Natural Docs will keep an up-to-date list of all the languages defined in the main file in it so you can override their settings easily.

However, if you’re using Natural Docs with a lot of projects and would like the changes to apply everywhere, you can edit the one in Natural Docs’ Config directory instead.  Most of the text here will assume you’re editing the project one, so be sure to read the boxes at the end that explain the differences.

Note that unlike other Natural Docs configuration files, comments can only appear on their own lines.  They cannot appear after content on the same line because settings may need to use the # symbol.  Also, all lists are space-separated instead of comma-separated, again because some settings may need to use the , symbol.

Natural Docs has the ability to ignore prefixes in the indexes.  This is necessary because in certain languages, variables are prefixed with $ or other symbols and we don’t want them to get all grouped together under the symbols heading.  Instead, they appear in the sidebar and are sorted as if they’re not there.

However, we can take advantage of this simply to get around coding conventions.  Suppose you prefix all your class names with C.  They’d all form one gigantic group under C in the index.  If you want, you can have it ignored so CCat, CDog, and CMouse get filed under C, D, and M instead.  Just add this to your languages file:

Alter Language: [your language]
   Add Ignored Class Prefix in Index: C

Now C is ignored in your indexes:

You can include any number of prefixes and can do this for any topic type.  So if you have a bunch of functions that start with COM_ and DB_, you can ignore them too:

Alter Language: [your language]
   Add Ignored Class Prefix in Index: C
   Add Ignored Function Prefixes in Index: COM_ DB_

Note that only one prefix will ever be removed, so if you have variable names that start with $ and want to remove m, you have to write “Ignore Variable Prefix: $m” instead of just m.

One last tip: Do this for common hierarchy levels.  For example, all of Natural Docs’ internal packages are under a top-level NaturalDocs package, so it’s package index ignores “NaturalDocs::” to stay useful.

To do this in the main languages file instead of the user one, find the existing definition and either edit the “Ignored [type] Prefixes in Index” line or add one if it’s not there.

You can add basic language support for any programming language just by editing these configuration files.  Here are the most important settings:

Language: Fictional

   Extensions: fsrc fhdr
   Shebang Strings: fictional
   Line Comment: //
   Block Comment: /* */
   Package Separator: ::

This tells Natural Docs that any files with the .fsrc or .fhdr extensions are part of our fictional programming language.  Also, any .cgi or extensionless files that have “fictional” in the shebang (#!) line are part of it as well.  Line comments start with // and block comments appear between /* and */.  The default package separator is ::.  Not too hard, huh?

You can also add settings to ignore prefixes in the index and detect prototypes, but those are dealt with in their own sections on this page.

So Natural Docs doesn’t recognize some file extension you use for your code?  No problem.

Alter Language: [your language]
   Add Extensions: cxx hxx

If it’s scanning some files you don’t want it to scan, you can exclude extensions as well.  Just add this to the top of your file:

Ignore Extensions: c cpp

In this example, Natural Docs will ignore C++ source files, thus only scanning the headers.

To do this in the main languages file instead of the user one, find the existing language definition and add or remove from the existing “Extensions:” line.

So you’ve added a new language and want to detect prototypes.  Or perhaps you added a custom topic type and want to detect prototypes for that as well.  Here’s an example of the properties you need:

Function Prototype Enders: ; {
Variable Prototype Enders: ; =

The algorithm for finding prototypes is very simple, yet it works really well in practice.  All the code following the comment is grabbed until it reaches an ender symbol or another comment.  Ender symbols appearing inside parenthesis, brackets, braces, or angle brackets don’t count.  If it reaches an ender symbol and somewhere in that code is the topic title, the code is accepted as the prototype.

So in the example above, variables end at semicolons (the end of the declaration) or equal signs (the default value expression, which we don’t want to include.)  Since the Natural Docs topic for the variable should have appeared right before the definition, that leaves us with the name and type.  Functions are handled similarly: they end at a semicolon (the end of a predeclaration) or an opening brace (the beginning of the body) leaving us with the name, parameters, and return type.

You can do this with any topic type, including custom ones.  Any prototypes that look like they have parameters will be formatted as such.

For some languages, line breaks are significant.  To have them end a prototype, use \n.  If it has an extender symbol that allows the code to continue on the next line, you can specify that as well.

Function Prototype Ender: \n
Variable Prototype Ender: \n =
Line Extender: _

If you’re collecting prototypes for a custom topic type, they will not automatically get their own background color like the other types have.  You have to define it via CSS, which is explained in the Common Customizations section of the CSS Styles page.

There are two languages with special properties: Shebang Script and Text File.

In Shebang Scripts, the language is not determined by the file extension but by the shebang (#!) line.  The only relevant setting is Extensions.  Files that have those extensions will have their shebang line read and scanned for the substrings specified by the other languages’ Shebang String settings.  Files with no extension are always treated as Shebang Scripts.

In Text Files, the entire file is treated like a comment.  There are no comment symbols required, you can just put Natural Docs content there in plain text.  The most important setting is Extensions.

However, since it is possible to document classes, functions, etc. in text files, they also have their own Package Separator and Ignored [type] Prefixes in Index settings.  To make things easier on you, by default it copies these settings from whichever language has the most source files in your project.  You can override this by manually setting them, but you shouldn’t need to.

Unlike other Natural Docs configuration files, comments can only appear on their own lines.  They cannot appear after content on the same line because settings may need to use the # symbol.

Singular and plural forms are generally both supported, so you can write Extension or Extensions.  It doesn’t matter if they match how many items are set.  Also, you can use either Ignore or Ignored.

Ignore Extensions: [extension] [extension] ...

Causes the listed file extensions to be ignored, even if they were previously defined to be part of a language.  The list is space-separated.  ex. “Ignore Extensions: cvs txt”

Language: [name]
Alter Language: [name]

Creates a new language or alters an existing one.  Names can use any characters.  Note the special behavior for languages named Shebang Script and Text File.

If you’re altering an existing language and a property has an [Add/Replace] form, you have to specify whether you’re adding to or replacing the list if that property has already been defined.

Extensions: [extension] [extension] ...
[Add/Replace] Extensions: [extension] [extension] ...

Defines file extensions for the language’s source files.  The list is space-separated.  ex. “Extensions: c cpp”.  You can use extensions that were previously used by another language to redefine them.  You can use * to specify all undefined extensions.

Shebang Strings: [string] [string] ...
[Add/Replace] Shebang Strings: [string] [string] ...

Defines a list of strings that can appear in the shebang (#!) line to designate that it’s part of this language.  They can appear anywhere in the line, so php will work for “#!/user/bin/php4”.  You can use strings that were previously used by another language to redefine them.

Ignore Prefixes in Index: [prefix] [prefix] ...
Ignore [type] Prefixes in Index: [prefix] [prefix] ...

[Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ...
[Add/Replace] Ignored [type] Prefixes in Index: [prefix] [prefix] ...

Specifies prefixes that should be ignored when sorting symbols for an index.  Can be specified in general or for a specific topic type.  The prefixes will still appear, the symbols will just be sorted as if they’re not there.  For example, specifying ADO_ for functions will mean that ADO_DoSomething will appear under D instead of A.

These attributes are only available for languages with basic language support.

Line Comments: [symbol] [symbol] ...

Defines a space-separated list of symbols that are used for line comments, if any.  ex. “Line Comment: //”.

Block Comments: [opening symbol] [closing symbol] [o.s.] [c.s.] ...

Defines a space-separated list of symbol pairs that are used for block comments, if any.  ex. “Block Comment: /* */”.

Enum Values: [global|under type|under parent]

Defines the behavior of enum values.  The default is global.

[type] Prototype Enders: [symbol] [symbol] ...

When defined, Natural Docs will attempt to collect prototypes from the code following the specified topic type.  It grabs code until the first ender symbol or the next Natural Docs comment, and if it contains the topic name, it serves as its prototype.  Use \n to specify a line break.  ex. “Function Prototype Enders: { ;”, “Variable Prototype Enders: = ;”.

Line Extender: [symbol]

Defines the symbol that allows a prototype to span multiple lines if normally a line break would end it.

Perl Package: [perl package]

Specifies the Perl package used to fine-tune the language behavior in ways too complex to do in this file.

These attributes are only available for languages with full language support.

Full Language Support: [perl package]

Specifies the Perl package that has the parsing routines necessary for full language support.