<html><head><title>Organizing the Menu - Natural Docs</title><linkrel=stylesheettype="text/css"href="styles.css"><linkrel=stylesheettype="text/css"href="examples.css"><styletype="text/css"><!--
<!-- 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><spanclass=SideMenuEntryid=SelectedSideMenuEntry>Organizing the Menu</span><ahref="styles.html"class=SideMenuEntry>CSS Styles</a><ahref="customizingtopics.html"class=SideMenuEntry>Topics and Keywords</a><ahref="customizinglanguages.html"class=SideMenuEntry>Languages, Indexes,<br>and Prototypes</a></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>Organizing the Menu</div><divclass=TOC><ahref="#OrderAndTitles">Order and Titles</a>·<ahref="#Grouping">Grouping</a>·<ahref="#IndexesAndSearch">Indexes and Search</a>·<ahref="#AutomaticChanges">Automatic Changes</a><br><ahref="#Extras">Extras</a>·<ahref="#Errors">Errors</a>·<ahref="#PortabilityAndVersioningSystems">Portability and Versioning Systems</a></div><divclass=Topic><p>Natural Docs creates a file called <code>Menu.txt</code> in your <ahref="running.html#CommandLine">project directory</a> that you can edit to organize the menu. It normally takes care of this on its own, but you have the option of improving it manually if you want to.</p></div><divclass=Topic><aname="OrderAndTitles"></a><divclass=TopicTitle>Order and Titles</div><p>If you’ve never looked in it before, the menu file will have some comments explaining its syntax and a list like you see below.</p><preclass=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><tableclass=NDMenu><tr><td><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">ClassA</a></div></div><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">ClassB</a></div></div><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Globals</a></div></div></td></tr></table><p>The lines are in the format “<code>File: <i>[title]</i> (<i>[filename]</i>)</code>”. When Natural Docs made the menu, it decided on its own what the title of each file should be and then put them in alphabetical order. However, suppose we don’t want this. We want Globals above the classes and we want spaces in the menu titles. So we edit the file.</p><preclass=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><tableclass=NDMenu><tr><td><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Globals</a></div></div><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class A</a></div></div><divclass=MEntry><divclass=MFile><ahref="#"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><preclass=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 noticed that you changed a couple of the titles and added a <code>no auto-title</code> attribute to each one. This tells it to never change them on it’s own in the future, so your changes won’t be lost. You don’t have to worry about adding this, Natural Docs will always do it automatically. However, to go back to automatic titles you’d have to manually remove it.</p></div><divclass=Topic><aname="Grouping"></a><divclass=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 it further. Natural Docs will create them automatically based on the each file’s directory, but once again you can improve it manually if that’s not good enough.</p><p>You can add groups as shown below.</p><preclass=Example>File: Globals (Globals.h)
Group: Classes {
File: Class A (no auto-title, ClassA.h)
File: Class B (no auto-title, ClassB.h) }
</pre><tableclass=NDMenu><tr><td><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Globals</a></div></div><divclass=MEntry><divclass=MGroup><ahref="javascript:ToggleMenu('MenuGroup11');">Classes</a><divclass=MGroupContentid=MenuGroup11><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class A</a></div></div><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class B</a></div></div></div></div></div></td></tr></table><p>You can also nest them inside each other.</p><preclass=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><tableclass=NDMenu><tr><td><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Globals</a></div></div><divclass=MEntry><divclass=MGroup><ahref="javascript:ToggleMenu('MenuGroup21');">Classes</a><divclass=MGroupContentid=MenuGroup21><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class A</a></div></div><divclass=MEntry><divclass=MGroup><ahref="javascript:ToggleMenu('MenuGroup22');">Nested Group</a><divclass=MGroupContentid=MenuGroup22><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class B</a></div></div></div></div></div></div></div></div></td></tr></table><p>We’ll get rid of the nested group because it doesn’t make sense for our example. Run Natural Docs, open up the menu file again and take a look.</p><preclass=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 breaking up long lists, groups also serve another purpose. Clicking on them will make it expand and collapse. Go ahead and try it in the examples above. When the menu gets too long its groups will start being collapsed by default, allowing easier navigation on large projects where it would just be impractical to show everything at once.</p></div><divclass=Topic><aname="IndexesAndSearch"></a><divclass=TopicTitle>Indexes and Search</div><p>Natural Docs will automatically determine what indexes your project needs and add them to the menu. Anything indexed will also be used for the search feature. The entries will look like this:</p><preclass=Example>Group: Index {
Index: Everything
Class Index: Classes
Function Index: Functions
} # Group: Index
</pre><p>Like the file entries we saw before, 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. Just like before, Natural Docs will detect this and add something new:</p><preclass=Example>Don't Index: Functions
</pre><p>As with <code>no auto-title</code>, Natural Docs adds this automatically to make sure it doesn’t later undo your changes.</p></div><divclass=Topic><aname="AutomaticChanges"></a><divclass=TopicTitle>Automatic Changes</div><p>Natural Docs tries to manage the menu on its own as much as possible so you don’t have to worry about it. This is just a peek into some of the things it does so you know what to expect.</p><p>You already saw that by default Natural Docs tries to guess what title should be for each file. If you leave it this way, Natural Docs will always update the menu for you if the file’s content changes significantly enough to change its guess, such as if you rename the first class defined in it. If you’d like to take advantage of this to define the menu title in each source file instead of in the menu itself, add a “<code>Title: [title]</code>” comment to the top of the file.</p><p>When you add and delete source files, Natural Docs will automatically add and remove them from the menu file. When adding one 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 put it in the correct place to maintain that alphabetization. In fact, even if an existing file’s automatic title changes, it will change it’s position to make sure a previously alphabetized group stays that way.</p><p>There are exceptions in alphabetization 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 that 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><divclass=Topic><aname="Extras"></a><divclass=TopicTitle>Extras</div><p>There’s more you can do with the menu than just renaming and reorganizing its entries. Natural Docs has a few extras you can add to it as well.</p><aname="TitleAndSubtitle"></a><divclass="SubTopic">Title and Subtitle</div><p>You can add a title and subtitle to your menu.</p><preclass=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><tableclass=NDMenu><tr><td><divclass=MTitle>My Project<divclass=MSubTitle>Something That Does Something</div></div><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Globals</a></div></div><divclass=MEntry><divclass=MGroup><ahref="javascript:ToggleMenu('MenuGroup31');">Classes</a><divclass=MGroupContentid=MenuGroup31><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class A</a></div></div><divclass=MEntry><divclass=MFile><ahref="#"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>Class A</i>” to “<i>Class A - My Project</i>”, making bookmarks clearer.</p><aname="TextAndWebLinks"></a><divclass="SubTopic">Text and Web Links</div><p>You can also add arbitrary text and web links to your menu.</p><preclass=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><tableclass=NDMenu><tr><td><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Globals</a></div></div><divclass=MEntry><divclass=MGroup><ahref="javascript:ToggleMenu('MenuGroup51');">Classes</a><divclass=MGroupContentid=MenuGroup51><divclass=MEntry><divclass=MText>I couldn’t think of good names for these classes.</div></div><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class A</a></div></div><divclass=MEntry><divclass=MFile><ahref="#"onClick="return false;">Class B</a></div></div></div></div></div><divclass=MEntry><divclass=MLink><ahref="#"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><aname="Footers"></a><divclass="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 it finds into real copyright symbols.</p><preclass=Example>Footer: Copyright (C) 2008 Me
