mirror of
https://github.com/ddnet/ddnet.git
synced 2024-11-14 20:18:19 +00:00
50 lines
17 KiB
HTML
50 lines
17 KiB
HTML
|
|
|
|
<html><head><title>Organizing the Menu - Natural Docs</title><link rel=stylesheet type="text/css" href="styles.css"><link rel=stylesheet type="text/css" href="examples.css"><script language=JavaScript src="javascript/PNGHandling.js"></script><script language=JavaScript src="javascript/BrowserStyles.js"></script><script language=JavaScript src="example/NaturalDocs.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><span class=SideMenuEntry id=SelectedSideMenuEntry>Organizing the Menu</span><a href="styles.html" class=SideMenuEntry>CSS Styles</a><a href="customizingtopics.html" class=SideMenuEntry>Topics and Keywords</a><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>Organizing the Menu</div><div class=TOC><a href="#OrderAndTitles">Order and Titles</a> · <a href="#Grouping">Grouping</a> · <a href="#Indexes">Indexes</a> · <a href="#AutomaticChanges">Automatic Changes</a><br><a href="#Extras">Extras</a> · <a href="#Errors">Errors</a> · <a href="#Portability">Portability and Versioning Systems</a></div><div class=Topic><p>Natural Docs creates a file called <code>Menu.txt</code> in the project directory that you can edit to organize the menu. Natural Docs will take care of adding and deleting entries as necessary, and it will even attempt to organize them by directory, but you have the option of improving it manually.</p></div><div class=Topic><a name=OrderAndTitles></a><div class=TopicTitle>Order and Titles</div><p>If you’ve never edited it before, the menu file will be some comments explaining how to edit it and a list like you see below.</p><pre class=Example>File: ClassA (ClassA.h)
|
|
File: ClassB (ClassB.h)
|
|
File: Globals (Globals.h)</pre><p>The list gets turned into a menu that looks like this:</p><table class=NDMenu><tr><td><div class=MEntry><div class=MFile><a href="#" onClick="return false;">ClassA</a></div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">ClassB</a></div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Globals</a></div></div></td></tr></table><p>It should be obvious what everything on each line is. When Natural Docs made the menu, it decided on its own what each item should be titled and then put them in alphabetical order. However, suppose we don’t like this. We want Globals above the classes and we want spaces in the menu titles. So we edit the file.</p><pre class=Example>File: Globals (Globals.h)
|
|
File: Class A (ClassA.h)
|
|
File: Class B (ClassB.h)</pre><p>Run Natural Docs again and the menu is updated.</p><table class=NDMenu><tr><td><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Globals</a></div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class A</a></div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class B</a></div></div></td></tr></table><p>However, open the menu file again and you’ll see something interesting.</p><pre class=Example>File: Globals (Globals.h)
|
|
File: Class A (no auto-title, ClassA.h)
|
|
File: Class B (no auto-title, ClassB.h)</pre><p>Natural Docs detected that you edited a couple of the titles and added a <code>no auto-title</code> attribute to each one. This tells it never to change the titles on those entries. You don’t have to worry about adding this attribute, Natural Docs will do it automatically. However, to go back to automatic titles you have to manually delete it.</p></div><div class=Topic><a name=Grouping></a><div class=TopicTitle>Grouping</div><p>This menu is good for our example, but in the real world, they get much much longer. We can add groups to organize them further. Natural Docs will create its own groups by directory, but you can add your own manually if that’s not good enough.</p><p>You can manually add groups as shown below.</p><pre class=Example>File: Globals (Globals.h)
|
|
Group: Classes {
|
|
File: Class A (no auto-title, ClassA.h)
|
|
File: Class B (no auto-title, ClassB.h) }</pre><table class=NDMenu><tr><td><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Globals</a></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MenuGroup11');">Classes</a><div class=MGroupContent id=MenuGroup11><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class A</a></div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class B</a></div></div></div></div></div></td></tr></table><p>You can also nest them inside each other.</p><pre class=Example>File: Globals (Globals.h)
|
|
Group: Classes {
|
|
File: Class A (no auto-title, ClassA.h)
|
|
Group: Nested Group {
|
|
File: Class B (no auto-title, ClassB.h) }
|
|
}</pre><table class=NDMenu><tr><td><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Globals</a></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MenuGroup21');">Classes</a><div class=MGroupContent id=MenuGroup21><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class A</a></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MenuGroup22');">Nested Group</a><div class=MGroupContent id=MenuGroup22><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class B</a></div></div></div></div></div></div></div></div></td></tr></table><p>Open up the menu file again and take a look.</p><pre class=Example>File: Globals (Globals.h)
|
|
|
|
Group: Classes {
|
|
|
|
File: Class A (no auto-title, ClassA.h)
|
|
File: Class B (no auto-title, ClassB.h)
|
|
} # Group: Classes</pre><p>Natural Docs reformatted it. When you’re organizing the menu, you don’t have to worry about the indentation or otherwise keeping it neat. The file is reformatted every time it changes, so you can make quick and dirty edits and Natural Docs will keep it readable.</p><p>Besides making the menu easier to read, groups also serve another purpose. Clicking on a group’s name will make it expand and collapse on modern browsers. Go ahead and try it in the examples. When the menu gets too long, certain groups will start being collapsed by default This allows Natural Docs to work with large projects, where showing the entire menu at once is impractical. For compatibility, this only happens on browsers that support it. If a browser can’t expand or collapse menus, it always defaults to being completely open.</p></div><div class=Topic><a name=Indexes></a><div class=TopicTitle>Indexes</div><p>Natural Docs will automatically determine what indexes your project needs and add them to the menu. The entries will look like this:</p><pre class=Example>Group: Index {
|
|
|
|
Index: Everything
|
|
Class Index: Classes
|
|
Function Index: Functions
|
|
} # Group: Index</pre><p>Like file entries, you can rename them by editing the title and reorder them by cutting and pasting. However, if you decide you don’t want a particular index to be generated, just delete its entry and it will go away. Again, like file entries, Natural Docs will detect this and add something new:</p><pre class=Example>Don't Index: Functions</pre><p>Like <code>no auto-title</code>, you have to delete that to make it automatic again.</p></div><div class=Topic><a name=AutomaticChanges></a><div class=TopicTitle>Automatic Changes</div><p>You already saw that file entries default to being auto-titled. Natural Docs tries to guess what the title of each of these files should be. For example, if the first documented topic is a class, it will use the class name. If you want to override a file’s title in the file itself instead of in the menu, add a “<code>Title: [title]</code>” comment to the top of it. This way the title is stays with the file.</p><p>When Natural Docs needs to add a file to the menu, it will look for the best group to put it in by directory. If your grouping mirrors the source tree somewhat, this will be a lot more accurate. Also, if the group it’s putting it in is alphabetized, Natural Docs will maintain that alphabetization. If an auto-title changes, it will reorganize the group to maintain its previous alphabetization, if any.</p><p>The only exceptions in alphabetization are for the indexes. If a group only contains indexes, it can be the last item on the menu or in its parent group without making it count as unsorted. Also, within groups that only contain indexes, the general index can be first, also without making the group count as unsorted.</p><p>Finally, if Natural Docs adds some files to a group and causes it to become too long, it will attempt to sub-group it based on directory. However, it will <i>only</i> do this when its adding files on its own, so you don’t have to worry about it constantly messing up your groups. Since new files aren’t added to a project that often, if you change the menu manually, it should stay that way for quite some time.</p></div><div class=Topic><a name=Extras></a><div class=TopicTitle>Extras</div><div class=SubTopic>Title and Subtitle</div><p>In addition to files and groups, you can add a title and subtitle to your menu.</p><pre class=Example>Title: My Project
|
|
SubTitle: Something That Does Something
|
|
|
|
File: Globals (Globals.h)
|
|
Group: Classes
|
|
File: Class A (no auto-title, ClassA.h)
|
|
File: Class B (no auto-title, ClassB.h)</pre><table class=NDMenu><tr><td><div class=MTitle>My Project<div class=MSubTitle>Something That Does Something</div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Globals</a></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MenuGroup31');">Classes</a><div class=MGroupContent id=MenuGroup31><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class A</a></div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class B</a></div></div></div></div></div></td></tr></table><p>In addition to adding the title to the menu, the Title tag will also change the HTML page titles from “<i>file title</i>” to “<i>file title - menu title</i>”, making bookmarks clearer.</p><div class=SubTopic>Text and Web Links</div><p>You can also add arbitrary text and web links to your menu.</p><pre class=Example>File: Globals (Globals.h)
|
|
Group: Classes {
|
|
Text: I couldn't think of good names for these classes.
|
|
File: Class A (no auto-title, ClassA.h)
|
|
File: Class B (no auto-title, ClassB.h)
|
|
}
|
|
Link: Built with Natural Docs (http://www.naturaldocs.org)</pre><table class=NDMenu><tr><td><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Globals</a></div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MenuGroup51');">Classes</a><div class=MGroupContent id=MenuGroup51><div class=MEntry><div class=MText>I couldn’t think of good names for these classes.</div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class A</a></div></div><div class=MEntry><div class=MFile><a href="#" onClick="return false;">Class B</a></div></div></div></div></div><div class=MEntry><div class=MLink><a href="#" onClick="return false;">Built with Natural Docs</a></div></div></td></tr></table><p>Even though comments use the # character, adding an anchor to a link (such as “http://www.website.com/page.html#anchor”) will still work.</p><div class=SubTopic>Footers</div><p>Finally, you can add a footer to all your pages, such as a copyright notice. Natural Docs will change any (c)’s to real copyright symbols.</p><pre class=Example>Footer: Copyright (C) 2003 Me</pre><p>You can <a href="http://www.naturaldocs.org/documentation/html/">see an example of a footer</a> on the Natural Docs web site.</p></div><div class=Topic><a name=Errors></a><div class=TopicTitle>Errors</div><p>If there’s ever an error in the menu file, Natural Docs will tell you when it’s run. It follows <a href="http://www.gnu.org/prep/standards_15.html">the GNU standards</a>, so if you’re running it as part of a build process in an IDE, they will be even easier to find.</p><pre>NaturalDocs:Menu.txt:6: txet is not a valid keyword</pre><p>Also, it adds a comment for each error in the menu file so that you can search for them in a text editor.</p><pre class=Example># There is an error in this file. Search for ERROR to find it.
|
|
|
|
File: Globals (Globals.h)
|
|
Group: Classes {
|
|
# ERROR: Txet is not a valid keyword.
|
|
Txet: I couldn't think of good names for these classes.
|
|
File: Class A (no auto-title, ClassA.h)
|
|
File: Class B (no auto-title, ClassB.h)
|
|
}</pre><p>Remember that Natural Docs reformats the menu file whenever it’s run, so you only need to correct the error. Natural Docs will remove the error comments on its own.</p></div><div class=Topic><a name=Portability></a><div class=TopicTitle>Portability and Versioning Systems</div><p>If you only use one input directory, all the files in the menu will have relative paths. However, if you have more, Natural Docs will use the absolute path instead.</p><p>This is not a problem. The menu file can still be shared between machines even if they don’t keep the source tree in the exact same location. As long as you have the same layout within the source tree and point to the same base directories in the command line, Natural Docs will be able to convert the paths automatically to the new machine.</p><p>However, if you’re putting the menu file in a versioning system like CVS or SourceSafe, it might be very desirable to only have relative paths so anybody can check it in and only the real changes show. In that case, instead of using multiple input directories, see if it’s possible to only have one input directory and use the <code>-xi</code> <a href="running.html">command line option</a> to exclude the subdirectories you don’t want scanned.</p></div><div class=Topic><div class=TopicTitle>That’s It!</div><p>And we’re done. The syntax to do all of this is included in the menu file itself, so you don’t need to memorize everything. You shouldn’t need to organize the menu very often, just after a lot of new files have been added and if you don’t like the default.</p><p>Note that if you’re using the non-framed HTML output format, changing the menu does require every output file to be updated. However, Natural Docs has a special process just for this so it won’t take nearly as long as if it were rebuilding them all from scratch. Still, if you’re working on a large project, it may be worth considering the framed HTML output format.</p></div></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> |