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

You should edit the one in your project configuration folder whenever possible. It keeps your changes separate and easier to manage, plus you don't have to reapply them whenever you upgrade. Editing the one in Natural Docs' Config folder would be better only if you're using Natural Docs with a lot of projects and would like the changes to apply everywhere.

File Extensions

If Natural Docs doesn't recognize a file extension you use for your code, you can alter the language definition from your project configuration file to add them:

Alter Language: C/C++ Add Extensions: cxx hxx

On the other hand, 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 and only scan the headers.

Adding Languages

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

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 member operator is ::, which means classes appear as A::B::C instead of A.B.C.

This is enough to allow Natural Docs to find the comments in your source code. However, there are more settings if you also want prototypes.

Adding Prototypes

Prototypes are the snippets of code that appear in your documentation, such as the gray box below:

Multiply

int Multiply (

int

x,

int

y

)

Multiplies two integers and returns the result.

You can use Languages.txt to make Natural Docs collect them for a custom language you added. It's controlled by lines like these:

The algorithm for finding prototypes with basic language support is very simple, yet it works really well in practice. All the code following the comment is collected 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 comment title, the code is accepted as the prototype.

So in the configuration above, variables end at semicolons (the end of the declaration) or equals signs (the default value expression, which we don't want to include.) Since the comment 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.) In the example below, that leaves us with the return type, name, and parameters.

You need a separate set of enders for each comment type. Any prototypes that look like they have parameters will be formatted as such automatically. Any prototypes for classes that have a C++ or Java-like syntax, such as "class A extends B" or "class A : public B", will be used to build inheritance diagrams.

Line Breaks

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.

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

Shebang Script allows you to define the file extensions where the language is really determined by the shebang (#!) line within it. For example, .cgi files. If Natural Docs finds a .cgi file, it sees that it's a Shebang Script so it opens it up to read the first line. If it's a shebang line it then searches it for substrings defined by all the other languages' Shebang String settings to find out what language it really is. Files with no extension are always treated this way.

With Text File, 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.

Syntax Reference

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

Ignores file extensions so that they're not scanned by Natural Docs anymore.

Language: [name]Alter Language: [name]

Defines a new language or alters an existing one. You can use the project configuration folder's Languages.txt to change languages found in the system one.

The language Shebang Script is special. It's entry is only used for extensions, and files with those extensions have their shebang (#!) lines read to determine the real language of the file. Extensionless files are always treated this way.

The language Text File is also special. It's treated as one big comment so you can put Natural Docs content in them without special symbols.

Defines a list of strings that can appear in the shebang (#!) line to designate that it's part of the language. If using Alter Language you can add to or replace the list of shebang strings for that language.

Simple Identifier: [name]

The name of the language using only the letters A to Z. No spaces, numbers, symbols, or Unicode allowed. Defaults to the language name minus any unacceptable characters. This is used to generate things like CSS class names.