mirror of
https://github.com/ddnet/ddnet.git
synced 2024-11-15 04:28:20 +00:00
59 lines
14 KiB
HTML
59 lines
14 KiB
HTML
|
|
||
|
|
|
||
|
|
<html><head><title>Customizing Natural Docs Languages</title><link rel=stylesheet type="text/css" href="styles.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;
|
||
|
|
}
|
||
|
|
|
||
|
|
.ScopeTable {
|
||
|
|
margin: .5em 5ex;
|
||
|
|
}
|
||
|
|
.ScopeOption {
|
||
|
|
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><table width=100% border=0 cellspacing=0 cellpadding=0><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><span class=SideMenuEntry id=SelectedSideMenuEntry>Topics and Keywords</span><a href="customizinglanguages.html" class=SideMenuEntry>Languages, Indexes,<br>and Prototypes</a></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="messageboards.html" class=SideMenuEntry>Message Boards</a><a href="bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Customizing Topics and Keywords</div><div class=TOC><a href="#TopicTypesVsKeywords">Topic Types vs. Keywords</a> · <a href="#AddingTopicTypes">Adding Topic Types</a><br><a href="#ChangingKeywords">Changing Keywords</a> · <a href="#AlteringBehavior">Altering Behavior</a> · <a href="#SyntaxReference">Syntax Reference</a></div><div class=Topic><p>Natural Docs has two files called <code>Topics.txt</code>: one in its Config directory, and one in your project directory. These control the topic behavior and keywords 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. Natural Docs will keep an up-to-date list of all the topic types defined in the main file in it so you can override their settings easily.</p><p>However, if you’re using Natural Docs with a lot of projects and would like the changes to apply everywhere, you can edit the one in Natural Docs’ Config directory instead.</p></div><div class=Topic><a name=TopicTypesVsKeywords></a><div class=TopicTitle>Topic Types vs. Keywords</div><p>It’s important to understand the difference between topic types and keywords. Topic types have their own indexes and behavior settings. You’ll reference them by name when dealing with indexes in the <a href="menu.html">menu file</a> or prototype detection in the <a href="customizinglanguages.html">language file</a>, but not when documenting your code unless you make their names keywords as well.</p><p>You use keywords when documenting your code. The
|
||
|
|
|
||
|
|
Plural: Sound Effects
|
||
|
|
Keywords:
|
||
|
|
sound
|
||
|
|
sound effect</pre><p>Sound effects can now be documented with the <code>sound</code> or <code>sound effect</code> keywords, and they’ll get their own index. The <code>Plural</code> line just specifies the plural name of the topic type. It isn’t required, but Natural Docs will use it in some places where the plural would sound more natural, like when grouping topics or naming indexes on the menu.</p><p>Here are a couple of other things you may want to add:</p><pre class=Example>Topic Type: Sound Effect
|
||
|
|
|
||
|
|
Plural: Sound Effects
|
||
|
|
Scope: Always Global
|
||
|
|
Keywords:
|
||
|
|
sound, sounds
|
||
|
|
sound effect, sound effects</pre><p>You can set the scope behavior of the topic type. Your options are:</p><table border=0 cellspacing=0 cellpadding=0 class=ScopeTable><tr><td class=ScopeOption>Normal</td><td>Topics stay within the current scope.</td></tr><tr><td class=ScopeOption>Start</td><td>Topics start a new scope for all the topics beneath it, like class topics.</td></tr><tr><td class=ScopeOption>End</td><td>Topics reset the scope back to global for all the topics beneath it.</td></tr><tr><td class=ScopeOption>Always Global</td><td>Topics are defined as global, but do not change the scope for any other topics.</td></tr></table><p>Here we set it to <code>Always Global</code> so that if we document one as part of a class, it will still be global yet will not break the class’ scope. In other words, we can always link to it with just its name instead of needing something like <code><Class.Sound></code>.</p><p>The other thing we did was add plural keywords, which you do by using a comma after an existing keyword. These keywords are used for <a href="documenting.html#Topics">list topics</a> so we don’t have to document each one individually with the full syntax.</p><p>There are more options, these are just the most important ones. See the <a href="#SyntaxReference">full syntax reference</a> for the rest.</p><div class=SubTopic>Prototypes</div><p>If you’d like to collect prototypes for your new topic type, you have to do that through <code>Languages.txt</code> as explained in the <a href="customizinglanguages.html#Prototypes">Prototypes section</a> of the <a href="customizinglanguages.html">Customizing Languages page</a>.</p></div><div class=Topic><a name=ChangingKeywords></a><div class=TopicTitle>Changing Keywords</div><div class="First SubTopic">Adding and Changing</div><p>If you’re <a href="#AddingTopicTypes">defining your own topic type</a> or editing the main topics file, you simply add to the keywords list:</p><pre class=Example>Topic Type: Sound Effect
|
||
|
|
|
||
|
|
Keywords:
|
||
|
|
sound, sounds
|
||
|
|
sound effect, sound effects</pre><p>It doesn’t matter if the keyword was previously defined for a different topic type. Just define it again and the definition will change.</p><p>If you want to add keywords to one of the main topic types from the user file so that your changes stay separate, just use <code>Alter Topic Type</code> instead:</p><pre class=Example>Alter Topic Type: General
|
||
|
|
|
||
|
|
Keywords:
|
||
|
|
note
|
||
|
|
notes</pre><p>Natural Docs will keep a list of the topic types defined in the main file in your project file so that you can do this easily.</p><div class=SubTopic>Ignoring</div><p>Sometimes a keyword just gets in the way. It’s too common in your comments and Natural Docs keeps accidentally picking them up as topics when that isn’t what you wanted. You can get rid of keywords completely by either deleting them from the main file or putting this in your project file:</p><pre class=Example>Ignore Keywords:
|
||
|
|
note
|
||
|
|
notes
|
||
|
|
title</pre><p>If you only have a few, you can use this syntax as well:</p><pre class=Example>Ignore Keywords: note, notes, title</pre></div><div class=Topic><a name=AlteringBehavior></a><div class=TopicTitle>Altering Behavior</div><p>You can alter the behavior of any topic type defined in the main file via your project file. You just use <code>Alter Topic Type</code> and redefine any property.</p><pre class=Example>Alter Topic Type: Constant
|
||
|
|
|
||
|
|
Scope: Always Global</pre><p>Natural Docs will keep a list of all the topic types defined in the main file in your project file so you can do this easily. See the <a href="#SyntaxReference">syntax reference</a> below for a full list of your options.</p></div><div class=Topic><a name=SyntaxReference></a><div class=TopicTitle>Syntax Reference</div><pre class=Example>Ignore Keywords: <i>[keyword]</i>, <i>[keyword]</i> ...
|
||
|
|
<i>[keyword]</i>
|
||
|
|
<i>[keyword]</i>, <i>[keyword]</i>
|
||
|
|
...</pre><p>Ignores the keywords so that they’re not recognized as Natural Docs topics anymore. Can be specified as a list on the same line and/or following like a normal Keywords section.</p><pre class=Example>Topic Type: <i>[name]</i>
|
||
|
|
Alter Topic Type: <i>[name]</i></pre><p>Creates a new topic type or alters an existing one. The name can only contain letters, numbers, spaces, and these characters: <code>. - ‘ /</code>. It isn’t case sensitive, although the original case is remembered for presentation.</p><p>The name General is reserved. There are a number of default types that must be defined in the main file as well, but they will be listed there since it may change between versions. The default types can have their keywords or behaviors changed, though, either by editing the default file or by overriding them in the user file.</p><div class=SubTopic>Properties</div><pre class=Example>Plural: <i>[name]</i></pre><p>Specifies the plural name of the topic type. Defaults to the singular name. Has the same restrictions as the topic type name.</p><pre class=Example>Index: <i>[yes|no]</i></pre><p>Whether the topic type gets an index. Defaults to yes.</p><pre class=Example>Scope: <i>[normal|start|end|always global]</i></pre><p>How the topic affects scope. Defaults to normal.</p><table border=0 cellspacing=0 cellpadding=0 class=ScopeTable><tr><td class=ScopeOption>Normal</td><td>Topics stay within the current scope.</td></tr><tr><td class=ScopeOption>Start</td><td>Topics start a new scope for all the topics beneath it, like class topics.</td></tr><tr><td class=ScopeOption>End</td><td>Topics reset the scope back to global for all the topics beneath it.</td></tr><tr><td class=ScopeOption>Always Global</td><td>Topics are defined as global, but do not change the scope for any other topics.</td></tr></table><pre class=Example>Class Hierarchy: <i>[yes|no]</i></pre><p>Whether the topic is part of the class hierarchy. Defaults to no.</p><pre class=Example>Page Title if First: <i>[yes|no]</i></pre><p>Whether the title of this topic becomes the page title if it is the first topic in a file. Defaults to no.</p><pre class=Example>Break Lists: <i>[yes|no]</i></pre><p>Whether list topics should be broken into individual topics in the output. Defaults to no.</p><pre class=Example>Can Group With: <i>[topic type]</i>, <i>[topic type]</i>, ...</pre><p>Lists the topic types that can be grouped with this one in the output. If two or more topic types often appear together, like Functions and Properties, this will allow them to be grouped together under one heading if it would cause too many groups otherwise.</p><pre class=Example>Keywords:
|
||
|
|
<i>[keyword]</i>
|
||
|
|
<i>[keyword]</i>, <i>[plural keyword]</i>
|
||
|
|
...</pre><p>A list of the topic type’s keywords. Each line after the heading is the keyword and optionally its plural form. This continues until the next line in “<code>keyword: value</code>” format.</p><ul><li>Keywords can only have letters and numbers. No punctuation or spaces are allowed.</li><li>Keywords are not case sensitive.</li><li>Subsequent keyword sections add to the list. They don’t replace it.</li><li>Keywords can be redefined by other keyword sections.</li></ul></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-2005 Greg Valure</td></tr></table><script language=JavaScript><!--
|
||
|
|
ClosingBrowserTags();// --></script></body></html>
|