The configuration file that defines or overrides the language definitions for Natural Docs. One version sits in Natural Docs’ configuration directory, and another can be in a project directory to add to or override them.
# [comments]
Everything after a # symbol is ignored. However, for this particular file, comments can only appear on their own lines. They cannot appear after content on the same line.
Format: [version]
Specifies the file format version of the file.
Sections
Ignore[d] Extension[s]: [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]
Creates a new language. Everything underneath applies to this language until the next one. Names can use any characters.
The languages “Text File” and “Shebang Script” have special meanings. Text files are considered all comment and don’t have comment symbols. Shebang scripts have their language determined by the shebang string and automatically include files with no extension in addition to the extensions defined.
If “Text File” doesn’t define ignored prefixes, a package separator, or enum value behavior, those settings will be copied from the language with the most files in the source tree.
Alter Language: [name]
Alters an existing language. Everything underneath it overrides the previous settings until the next one. Note that if a property has an [Add/Replace] form and that property has already been defined, you have to specify whether you’re adding to or replacing the defined list.
Language Properties
Extension[s]: [extension] [extension] ...
[Add/Replace] Extension[s]: ...
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.
Shebang String[s]: [string] [string] ...
[Add/Replace] Shebang String[s]: ...
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[d] Prefix[es] in Index: [prefix] [prefix] ...
Ignore[d] [Topic Type] Prefix[es] in Index: [prefix] [prefix] ...
[Add/Replace] Ignore[d] Prefix[es] in Index: ...
[Add/Replace] Ignore[d] [Topic Type] Prefix[es] in Index: ...
Specifies prefixes that should be ignored when sorting symbols for an index. Can be specified in general or for a specific TopicType. 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.
Basic Language Support Properties
These attributes are only available for languages with basic language support.
Line Comment[s]: [symbol] [symbol] ...
Defines a space-separated list of symbols that are used for line comments, if any. ex. “Line Comment: //”.
Block Comment[s]: [opening symbol] [closing symbol] [opening symbol] [closing symbol] ...
Defines a space-separated list of symbol pairs that are used for block comments, if any. ex. “Block Comment: /* */”.
Package Separator: [symbol]
Defines the default package separator symbol, such as . or ::. This is for presentation only and will not affect how Natural Docs links are parsed. The default is a dot.
[Topic Type] Prototype Ender[s]: [symbol] [symbol] ...
When defined, Natural Docs will attempt to collect prototypes from the code following the specified TopicType. 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.
Enum Values: [global|under type|under parent]
Defines how enum values are referenced. The default is global.
| global | Values are always global, referenced as ‘value’. |
| under type | Values are under the enum type, referenced as ‘package.enum.value’. |
| under parent | Values are under the enum’s parent, referenced as ‘package.value’. |
Perl Package: [perl package]
Specifies the Perl package used to fine-tune the language behavior in ways too complex to do in this file.
Full Language Support Properties
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.
Revisions
1.32
- Package Separator is now a basic language support only property.
- Added Enum Values setting.
1.3