Languages.txt

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:

    Language: Fictional

       Extensions: fsrc fhdr
       Shebang Strings: fictional
       Line Comments: //
       Block Comments: /* */
       Member Operator: ::

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:

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

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 parentheses, 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.

    // Function: Multiply
    // Multiplies two integers and returns the result.
    int Multiply (int x, int y)
        {  return x * y;  }

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.

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

Colors

If you're collecting prototypes for a custom comment type, they will not automatically get their own background color like the other types have. You have to define it via CSS.

Special Languages

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.

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

Defines the file extensions of the language's source files. If using Alter Language you can add to or replace the list of extensions for that language.

    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 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.

    Aliases: [alias] [alias] ...
    [Add/Replace] Aliases: [alias] [alias] ...

Defines alternative names for the language that can be used to start a code block. When using Alter Language you can add to or replace the list of aliases for that language.

Properties for Basic Language Support Only

If you're adding your own language to Natural Docs you must define these.

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

Defines a space-separated list of symbols that are used for line comments, if any.

    Block Comments: [opening sym] [closing sym] [opening sym] [closing sym] ...

Defines a space-separated list of symbol pairs that are used for block comments, if any.

    Member Operator: [symbol]

Defines the member operator symbol. The default is a dot.

    Line Extender: [symbol]

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

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

Defines how enum values are referenced. The default is under type.

global | Values are always global, referenced as "value".
under type | Values are under the enum type, referenced as "class.enum.value".
under parent | Values are under the enum's parent, referenced as "class.value".

    Case Sensitive: [yes|no]

Defines whether the language's identifiers are case sensitive. The default is yes.

    Block Comments Nest: [yes|no]

Defines whether the language's block comments can nest. The default is no.

    [Comment Type] Prototype Enders: [symbol] [symbol] ...

When defined, Natural Docs will attempt to get a prototype from the code immediately following the comment type. It stops when it reaches one of these symbols. Use \n for line breaks.