<!-- saved from url=(0026)http://www.naturaldocs.org -->
<tablewidth=100%border=0cellspacing=0cellpadding=0><tr><tdcolspan=3class=Header><tablewidth=100%border=0cellspacing=0cellpadding=0><tr><td><imgsrc="images/header/leftside.png"width=30height=75><ahref="index.html"><imgsrc="images/header/logo.png"width=524height=75alt="Natural Docs"></a></td><tdalign=right><imgsrc="images/header/rightside.png"width=30height=75></td></tr></table></td></tr><tr><td><imgsrc="images/header/overleftmargin.png"width=10height=6></td><tdclass=SideMenuTop><imgsrc="images/header/overmenu.png"width=14height=6></td><tdclass=BodyTop><imgsrc="images/header/overbody.png"width=24height=6></td></tr><tr><td></td><tdclass=SideMenunowrap><divclass=SideMenuSection><divclass=SideMenuTitle><imgsrc="images/menu/about.png"width=52height=13alt="About"></div><divclass=SideMenuBody><ahref="languages.html"class=SideMenuEntry>Language Support</a><ahref="output.html"class=SideMenuEntry>Output Formats</a></div></div><divclass=SideMenuSection><divclass=SideMenuTitle><imgsrc="images/menu/using.png"width=45height=13alt="Using"></div><divclass=SideMenuBody><ahref="documenting.html"class=SideMenuEntry>Documenting<br>Your Code</a><ahref="keywords.html"class=SideMenuEntry>Keywords</a><ahref="running.html"class=SideMenuEntry>Running</a><ahref="troubleshooting.html"class=SideMenuEntry>Troubleshooting</a></div></div><divclass=SideMenuSection><divclass=SideMenuTitle><imgsrc="images/menu/customizing.png"width=96height=13alt="Customizing"></div><divclass=SideMenuBody><ahref="menu.html"class=SideMenuEntry>Organizing the Menu</a><ahref="styles.html"class=SideMenuEntry>CSS Styles</a><ahref="customizingtopics.html"class=SideMenuEntry>Topics and Keywords</a><spanclass=SideMenuEntryid=SelectedSideMenuEntry>Languages, Indexes,<br>and Prototypes</span></div></div><divclass=SideMenuSection><divclass=SideMenuTitle><imgsrc="images/menu/community.png"width=86height=13alt="Community"></div><divclass=SideMenuBody><ahref="http://www.naturaldocs.org/"class=SideMenuEntry>Web Site</a><ahref="http://www.naturaldocs.org/mailinglist.html"class=SideMenuEntry>Mailing Lists</a><ahref="http://www.naturaldocs.org/messageboards.html"class=SideMenuEntry>Message Boards</a><ahref="http://www.naturaldocs.org/bugs.html"class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><tdclass=Bodywidth=100%><divclass=PageTitle>Customizing Languages</div><divclass=TOC><ahref="#LanguagesTxt">Languages.txt</a>·<ahref="#FileExtensions">File Extensions</a>·<ahref="#AddingLanguages">Adding Languages</a>·<ahref="#Prototypes">Prototypes</a><br><ahref="#IndexPrefixes">Index Prefixes</a>·<ahref="#SpecialLanguages">Special Languages</a>·<ahref="#SyntaxReference">Syntax Reference</a></div><divclass=Topic><aname="LanguagesTxt"></a><divclass=TopicTitle>Languages.txt</div><p>Natural Docs has two files called <code>Languages.txt</code>: one in its Config directory, and one in <ahref="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><divclass=Topic><aname=FileExtensions></a><divclass=TopicTitle>File Extensions</div><p>If Natural Docs doesn’t recognize a file extension you use for your code, it
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><preclass=Example>Ignore Extensions: c cpp</pre><p>In this example, Natural Docs will ignore C++ source files, thus only scanning the headers.</p></div><divclass=Topic><aname=AddingLanguages></a><divclass=TopicTitle>Adding Languages</div><p>You can add <ahref="languages.html">basic language support</a> for any programming language just by editing these configuration files. Here are the most important settings:</p><preclass=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 <ahref="#IndexPrefixes">ignore prefixes in the index</a> and <ahref="#Prototypes">detect prototypes</a>, but those are dealt with in their own sections on this page.</p></div><divclass=Topic><aname=Prototypes></a><divclass=TopicTitle>Prototypes</div><p>So you’ve <ahref="#AddingLanguages">added a new language</a> and want to detect prototypes. Or perhaps you <ahref="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><preclass=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><divclass=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><preclass=Example>Function Prototype Ender: \n
Variable Prototype Ender: \n =
Line Extender: _</pre><divclass=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. <ahref="styles.html#CommonCustomizations">You have to define it via CSS.</a></p></div><divclass=Topic><aname=IndexPrefixes></a><divclass=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><divclass=NDIndex><tableborder=0cellspacing=0cellpadding=0><tr><tdclass=IHeadingid=IFirstHeading>A</td><td></td></tr><tr><tdclass=ISymbolPrefixid=IFirstSymbolPrefix> </td><tdclass=IEntry><spanclass=ISymbol>AddProperty</span>, <spanclass=IParent>SomeClass</span></td></tr><tr><tdclass=ISymbolPrefix>$</td><tdclass=IEntry><spanclass=ISymbol>amount</span></td></tr><tr><tdclass=ISymbolPrefixid=ILastSymbolPrefix> </td><tdclass=IEntry><spanclass=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><preclass=Example>Alter Language: <i>[your language]</i>
Add Ignored Class Prefix in Index: C</pre><p>Now C is ignored in your indexes:</p><divclass=NDIndex><tableborder=0cellspacing=0cellpadding=0><tr><tdclass=IHeadingid=IFirstHeading>A</td><td></td></tr><tr><tdclass=ISymbolPrefixid=IFirstSymbolPrefix>C</td><tdclass=IEntry><spanclass=ISymbol>Account</span></td></tr><tr><tdclass=ISymbolPrefix>C</td><tdclass=IEntry><spanclass=ISymbol>AccountHolder</span></td></tr><tr><tdclass=ISymbolPrefix> </td><tdclass=IEntry><spanclass=ISymbol>AddProperty</span>, <spanclass=IParent>SomeClass</span></td></tr><tr><tdclass=ISymbolPrefix>$</td><tdclass=IEntry><spanclass=ISymbol>amount</span></td></tr><tr><tdclass=ISymbolPrefixid=ILastSymbolPrefix> </td><tdclass=IEntry><spanclass=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><preclass=Example>Alter Language: <i>[your language]</i>
Add Ignored Class Prefix in Index: C
Add Ignored Function Prefixes in Index: COM_ DB_</pre></div><divclass=Topic><aname=SpecialLanguages></a><divclass=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><divclass=Topic><aname=SyntaxReference></a><divclass=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><preclass=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><preclass=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 <ahref="#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><divclass=SubTopic>General Language Properties</div><preclass=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><preclass=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><preclass=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> ...
