<html><head><title>Customizing Natural Docs Languages</title><link rel=stylesheet type="text/css" href="styles.css"><link rel=stylesheet type="text/css" href="examples.css"><style type="text/css"><!--
.InMainFile {
padding: 1ex 2ex;
margin: 1em 0;
font: italic 9pt Verdana, sans-serif;
line-height: 150%;
background-color: #F8F8F8;
}
.InMainFile code {
font-size: 9pt;
}
.EnumTable {
margin: .5em 5ex;
}
.EnumOption {
font-weight: bold;
padding-right: 2ex;
}
--></style><script language=JavaScript src="javascript/PNGHandling.js"></script><script language=JavaScript src="javascript/BrowserStyles.js"></script></head><body marginwidth=0 marginheight=0 leftmargin=0 topmargin=0><script language=JavaScript><!--
OpeningBrowserTags();// --></script>
<!-- saved from url=(0026)http://www.naturaldocs.org -->
<table width=100% border=0 cellspacing=0 cellpadding=0 class=PageTable float=center><tr><td colspan=3 class=Header><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td><img src="images/header/leftside.png" width=30 height=75><a href="index.html"><img src="images/header/logo.png" width=524 height=75 alt="Natural Docs"></a></td><td align=right><img src="images/header/rightside.png" width=30 height=75></td></tr></table></td></tr><tr><td><img src="images/header/overleftmargin.png" width=10 height=6></td><td class=SideMenuTop><img src="images/header/overmenu.png" width=14 height=6></td><td class=BodyTop><img src="images/header/overbody.png" width=24 height=6></td></tr><tr><td></td><td class=SideMenu nowrap><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/about.png" width=52 height=13 alt="About"></div><div class=SideMenuBody><a href="languages.html" class=SideMenuEntry>Language Support</a><a href="output.html" class=SideMenuEntry>Output Formats</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/using.png" width=45 height=13 alt="Using"></div><div class=SideMenuBody><a href="documenting.html" class=SideMenuEntry>Documenting<br>Your Code</a><a href="keywords.html" class=SideMenuEntry>Keywords</a><a href="running.html" class=SideMenuEntry>Running</a><a href="troubleshooting.html" class=SideMenuEntry>Troubleshooting</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/customizing.png" width=96 height=13 alt="Customizing"></div><div class=SideMenuBody><a href="menu.html" class=SideMenuEntry>Organizing the Menu</a><a href="styles.html" class=SideMenuEntry>CSS Styles</a><a href="customizingtopics.html" class=SideMenuEntry>Topics and Keywords</a><span class=SideMenuEntry id=SelectedSideMenuEntry>Languages, Indexes,<br>and Prototypes</span></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/community.png" width=86 height=13 alt="Community"></div><div class=SideMenuBody><a href="http://www.naturaldocs.org/" class=SideMenuEntry>Web Site</a><a href="http://www.naturaldocs.org/mailinglist.html" class=SideMenuEntry>Mailing Lists</a><a href="http://www.naturaldocs.org/messageboards.html" class=SideMenuEntry>Message Boards</a><a href="http://www.naturaldocs.org/bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Customizing Languages</div><div class=TOC><a href="#LanguagesTxt">Languages.txt</a> · <a href="#FileExtensions">File Extensions</a> · <a href="#AddingLanguages">Adding Languages</a> · <a href="#Prototypes">Prototypes</a><br><a href="#IndexPrefixes">Index Prefixes</a> · <a href="#SpecialLanguages">Special Languages</a> · <a href="#SyntaxReference">Syntax Reference</a></div><div class=Topic><a name="LanguagesTxt"></a><div class=TopicTitle>Languages.txt</div><p>Natural Docs has two files called <code>Languages.txt</code>: one in its Config directory, and one in <a href="running.html#CommandLine">your project directory.</a> These control the language, index prefix, and prototype features of Natural Docs.</p><p>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. Editing the one in Natural Docs’ Config directory would be better only if you’re using Natural Docs with a lot of projects and would like the changes to apply everywhere.</p><p>Note that unlike other Natural Docs configuration files, comments can only appear on their own lines. They cannot appear after something else on a line because settings may need to use the <code>#</code> symbol. Also, all lists are space-separated instead of comma-separated, again because some settings may need to use the comma symbol.</p></div><div class=Topic><a name=FileExtensions></a><div class=TopicTitle>File Extensions</div><p>If Natural Docs doesn’t recognize a file extension you use for your code, it’s not a problem. You can alter the language definition from your project file to add them.</p><pre class=Example>Alter Language: <i>[your language]</i>
Add Extensions: cxx hxx</pre><p>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:</p><pre class=Example>Ignore Extensions: c cpp</pre><p>In this example, Natural Docs will ignore C++ source files, thus only scanning the headers.</p></div><div class=Topic><a name=AddingLanguages></a><div class=TopicTitle>Adding Languages</div><p>You can add <a href="languages.html">basic language support</a> for any programming language just by editing these configuration files. Here are the most important settings:</p><pre class=Example>Language: Fictional
Extensions: fsrc fhdr
Shebang Strings: fictional
Line Comment: //
Block Comment: /* */
Package Separator: ::</pre><p>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 (<code>#!</code>) line are part of it as well. Line comments start with <code>//</code> and block comments appear between <code>/*</code> and <code>*/</code>. The default package separator is <code>::</code>. Not too hard, huh?</p><p>You can also add settings to <a href="#IndexPrefixes">ignore prefixes in the index</a> and <a href="#Prototypes">detect prototypes</a>, but those are dealt with in their own sections on this page.</p></div><div class=Topic><a name=Prototypes></a><div class=TopicTitle>Prototypes</div><p>So you’ve <a href="#AddingLanguages">added a new language</a> and want to detect prototypes. Or perhaps you <a href="customizingtopics.html#AddingTopicTypes">added a custom topic type</a> and want to detect prototypes for that as well. Here’s an example of the properties you need:</p><pre class=Example>Function Prototype Enders: ; {
Variable Prototype Enders: ; =</pre><p>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.</p><p>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 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) leaving us with the name, parameters, and return type.</p><p>You can do this with any topic type, including custom ones. Any prototypes that look like they have parameters will be formatted as such automatically.</p><div class=SubTopic>Line Breaks</div><p>For some languages, line breaks are significant. To have them end a prototype, use <code>\n</code>. If it has an extender symbol that allows the code to continue on the next line, you can specify that as well.</p><pre class=Example>Function Prototype Ender: \n
Variable Prototype Ender: \n =
Line Extender: _</pre><div class=SubTopic>Colors</div><p>If you’re collecting prototypes for a custom topic type, they will not automatically get their own background color like the other types have. <a href="styles.html#CommonCustomizations">You have to define it via CSS.</a></p></div><div class=Topic><a name=IndexPrefixes></a><div class=TopicTitle>Index Prefixes</div><p>Natural Docs has the ability to ignore prefixes in the indexes. This is necessary because in certain languages, variables are prefixed with <code>$</code> 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.</p><div class=NDIndex><table border=0 cellspacing=0 cellpadding=0><tr><td class=IHeading id=IFirstHeading>A</td><td></td></tr><tr><td class=ISymbolPrefix id=IFirstSymbolPrefix> </td><td class=IEntry><span class=ISymbol>AddProperty</span>, <span class=IParent>SomeClass</span></td></tr><tr><td class=ISymbolPrefix>$</td><td class=IEntry><span class=ISymbol>amount</span></td></tr><tr><td class=ISymbolPrefix id=ILastSymbolPrefix> </td><td class=IEntry><span class=ISymbol>Average</span></td></tr></table></div><p>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:</p><pre class=Example>Alter Language: <i>[your language]</i>
Add Ignored Class Prefix in Index: C</pre><p>Now C is ignored in your indexes:</p><div class=NDIndex><table border=0 cellspacing=0 cellpadding=0><tr><td class=IHeading id=IFirstHeading>A</td><td></td></tr><tr><td class=ISymbolPrefix id=IFirstSymbolPrefix>C</td><td class=IEntry><span class=ISymbol>Account</span></td></tr><tr><td class=ISymbolPrefix>C</td><td class=IEntry><span class=ISymbol>AccountHolder</span></td></tr><tr><td class=ISymbolPrefix> </td><td class=IEntry><span class=ISymbol>AddProperty</span>, <span class=IParent>SomeClass</span></td></tr><tr><td class=ISymbolPrefix>$</td><td class=IEntry><span class=ISymbol>amount</span></td></tr><tr><td class=ISymbolPrefix id=ILastSymbolPrefix> </td><td class=IEntry><span class=ISymbol>Average</span></td></tr></table></div><p>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 <code>COM_</code> and <code>DB_</code>, you can ignore them too:</p><pre class=Example>Alter Language: <i>[your language]</i>
Add Ignored Class Prefix in Index: C
Add Ignored Function Prefixes in Index: COM_ DB_</pre></div><div class=Topic><a name=SpecialLanguages></a><div class=TopicTitle>Special Languages</div><p>There are two languages with special properties: Shebang Script and Text File.</p><p>Shebang Script allows you to define the file extensions where the language is really determined by the shebang (<code>#!</code>) 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 parse it’s shebang line. It then searches it for substrings defined by other languages’ <code>Shebang String</code> settings to find out what language it really is. Files with no extension are always treated this way.</p><p>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 <code>Extensions</code>.</p><p>However, since it is possible to document classes, functions, etc. in text files, they also have their own <code>Package Separator</code> and <code>Ignored <i>[type]</i> Prefixes in Index</code> 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.</p></div><div class=Topic><a name=SyntaxReference></a><div class=TopicTitle>Syntax Reference</div><p>Unlike other Natural Docs configuration files, comments can only appear on their own lines. They cannot appear after something else on a line because settings may need to use the <code>#</code> symbol. Likewise, lists are separated with spaces instead of commas because commas themselves may need to appear on the list.</p><p>Singular and plural forms are generally both supported, so you can write <code>Extension</code> or <code>Extensions</code>. It doesn’t matter if they match how many items are set. Also, you can use either <code>Ignore</code> or <code>Ignored</code>.</p><pre class=Example>Ignore Extensions: <i>[extension] [extension]</i> ...</pre><p>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. “<code>Ignore Extensions: cvs txt</code>”</p><pre class=Example>Language: <i>[name]</i>
Alter Language: <i>[name]</i></pre><p>Creates a new language or alters an existing one. Names can use any characters. Note the <a href="#SpecialLanguages">special behavior for languages named Shebang Script and Text File</a>.</p><p>If you’re altering an existing language and a property has an <code>[Add/Replace]</code> form, you have to specify whether you’re adding to or replacing the list if that property has already been defined.</p><div class=SubTopic>General Language Properties</div><pre class=Example>Extensions: <i>[extension] [extension]</i> ...
<i>[Add/Replace]</i> Extensions: <i>[extension] [extension]</i> ...</pre><p>Defines file extensions for the language’s source files. The list is space-separated. ex. “<code>Extensions: c cpp</code>”. You can use extensions that were previously used by another language to redefine them. You can use <code>*</code> to specify all undefined extensions.</p><pre class=Example>Shebang Strings: <i>[string] [string]</i> ...
<i>[Add/Replace]</i> Shebang Strings: <i>[string] [string]</i> ...</pre><p>Defines a list of strings that can appear in the shebang (<code>#!</code>) line to designate that it’s part of this language. They can appear anywhere in the line, so <code>php</code> will work for “<code>#!/user/bin/php4</code>”. You can use strings that were previously used by another language to redefine them.</p><pre class=Example>Ignore Prefixes in Index: <i>[prefix] [prefix]</i> ...
Ignore <i>[type]</i> Prefixes in Index: <i>[prefix] [prefix]</i> ...
<i>[Add/Replace]</i> Ignored Prefixes in Index: <i>[prefix] [prefix]</i> ...
<i>[Add/Replace]</i> Ignored <i>[type]</i> Prefixes in Index: <i>[prefix] [prefix]</i> ...</pre><p>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 <code>ADO_</code> for functions will mean that <code>ADO_DoSomething</code> will appear under D instead of A.</p><div class=SubTopic>Basic Language Support Properties</div><p>These attributes are only available for languages with basic language support.</p><pre class=Example>Line Comments: <i>[symbol] [symbol]</i> ...</pre><p>Defines a space-separated list of symbols that are used for line comments, if any. ex. “<code>Line Comment: //</code>”.</p><pre class=Example>Block Comments: <i>[opening symbol] [closing symbol] [o.s.] [c.s.]</i> ...</pre><p>Defines a space-separated list of symbol pairs that are used for block comments, if any. ex. “<code>Block Comment: /* */</code>”.</p><pre class=Example>Enum Values: <i>[global|under type|under parent]</i></pre><p>Defines the behavior of enum values. The default is global.</p><table border=0 cellspacing=0 cellpadding=0 class=EnumTable><tr><td class=EnumOption>Global</td><td>Enum values are always global and will be referenced as “Value”.</td></tr><tr><td class=EnumOption>Under Type</td><td>Enum values appear under the type and will be referenced as “Package.Enum.Value”.</td></tr><tr><td class=EnumOption>Under Parent</td><td>Enum values appear under the parent and will be referenced as “Package.Value”</td></tr></table><pre class=Example><i>[type]</i> Prototype Enders: <i>[symbol] [symbol]</i> ...</pre><p>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 <code>\n</code> to specify a line break. ex. “<code>Function Prototype Enders: { ;</code>”, “<code>Variable Prototype Enders: = ;</code>”. </p><pre class=Example>Line Extender: <i>[symbol]</i></pre><p>Defines the symbol that allows a prototype to span multiple lines if normally a line break would end it.</p><pre class=Example>Perl Package: <i>[perl package]</i></pre><p>Specifies the Perl package used to fine-tune the language behavior in ways too complex to do in this file.</p><div class=SubTopic>Full Language Support Properties</div><p>These attributes are only available for languages with full language support.</p><pre class=Example>Full Language Support: <i>[perl package]</i></pre><p>Specifies the Perl package that has the parsing routines necessary for full language support.</p></div></td></tr><tr><td></td><td class=SideMenuBottom><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td class=SideMenuBottomLeft><img src="images/menu/bottomleft.png" width=18 height=19></td><td class=SideMenuBottomRight><img src="images/menu/bottomright.png" width=18 height=19></td></tr></table></td><td class=BodyBottom>Copyright © 2003-2010 Greg Valure</td></tr></table><script language=JavaScript><!--
ClosingBrowserTags();// --></script></body></html>
