ddnet/docs/tool/Help/running.html
2008-08-02 08:21:29 +00:00

40 lines
10 KiB
HTML

<html><head><title>Running Natural Docs</title><link rel=stylesheet type="text/css" href="styles.css"><style type="text/css"><!--
.OptionTable { margin: 1em 3ex 0 3ex }
.OptionTable td { padding-bottom: 1em }
.Option { font: 10pt Courier New, Courier, monospace; color: #808080; white-space: nowrap }
.Description { padding-left: 4ex }
.Description ul { margin: 0 0 0 5ex; padding: 0 }
.ParameterGroup {
font: bold 10pt Verdana, sans-serif;
padding-top: 1em;
}
.ParameterGroupExtra {
font: italic 8pt Verdana, sans-serif;
color: #808080;
}
--></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><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><span class=SideMenuEntry id=SelectedSideMenuEntry>Running</span><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><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="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>Running Natural Docs</div><div class=TOC><a href="#HowAndWhen">How and When</a> &middot; <a href="#CommandLine">Command Line</a> &middot; <a href="#Example">Examples</a></div></div><div class=Topic><a name=HowAndWhen></a>&nbsp; <div class=TopicTitle>How and When</div><p>Probably the best way to run Natural Docs is as part of the build process.&nbsp; This way every time you compile your code, your documentation is updated as well and you always have a current reference.&nbsp; Natural Docs has a differential build process so it will not rebuild the entire set of documentation every time it&rsquo;s run.</p><p>If you&rsquo;d like to run it manually instead, you should determine the command line you need and save it as a shortcut, batch file, or script since you should be running it often and will rarely need to fiddle with the parameters.</p><p></p></div><div class=Topic><a name=CommandLine></a><div class=TopicTitle>Command Line</div><pre>NaturalDocs -i [input (source) directory]
-o [output format] [output directory]
-p [project directory]
[options]</pre><table class=OptionTable border=0 cellspacing=0 cellpadding=0><tr><td colspan=2 class="First ParameterGroup">Required Parameters:</td></tr><tr><td class=Option>-i <i>[dir]</i><br>--input <i>[dir]</i><br>--source <i>[dir]</i></td><td class=Description><p>The input (source) directory.&nbsp; Natural Docs will build the documentation from the files in this directory and all its subdirectories.&nbsp; You can specify it multiple times to include multiple directories.&nbsp; <a href="languages.html">See the list of supported programming languages.</a></p></tr><tr><td class=Option>-o <i>[fmt] [dir]</i><br>--output <i>[fmt] [dir]</i></td><td class=Description><p>The output format and directory.&nbsp; This can also be specified multiple times, so you can build the documentation in multiple formats in a single run.&nbsp; <a href="output.html">See the list of supported output formats.</a></p></td></tr><tr><td class=Option>-p <i>[dir]</i><br>--project <i>[dir]</i></td><td class=Description><p>The project directory.&nbsp; Natural Docs needs a place to store configuration and data files for each project it&rsquo;s run on, so this is where it will put them.&nbsp; No two projects should share the same directory.</p></td></tr><tr><td colspan=2 class=ParameterGroup>Optional Parameters:</td></tr><tr><td class=Option>-xi <i>[dir]</i><br>--exclude-input <i>[dir]</i><br>--exclude-source <i>[dir]</i></td><td class=Description><p>Excludes a subdirectory from being scanned.&nbsp; The output and project directories are automatically excluded.</p></td></tr><tr><td class=Option>-img <i>[dir]</i><br>--images <i>[dir]</i></td><td class=Description><p>Adds a directory to search for image files when using <a href="documenting/reference.html#Images"><code>(see <i>[file]</i>)</code></a>.</p></td></tr><tr><td class=Option>-s <i>[style] (<i>[style]</i> ...)</i><br>--style <i>[style]</i> (<i>[style]</i> ...)</td><td class=Description><p>Selects the CSS style for HTML output.&nbsp; <a href="styles.html">See the default list of styles.</a></p><p>You can use any CSS file in your project directory or Natural Docs&rsquo; Styles directory just by using its name without the .css extension.&nbsp; If you include more than one, they will all be included in the HTML that order.</p></td></tr><tr><td class=Option>-r<br>--rebuild</td><td class=Description><p>Rebuilds everything from scratch.&nbsp; All source files will be rescanned and all output files will be rebuilt</p></td></tr><tr><td class=Option>-ro<br>--rebuild-output</td><td class=Description><p>Rebuilds all output files from scratch.</p></td></tr><tr><td class=Option>-t <i>[len]</i><br>--tab-length <i>[len]</i></td><td class=Description><p>Sets the number of spaces tabs should be expanded to.&nbsp; This only needs to be set if you use tabs in example code or text diagrams.&nbsp; The default is 4.</p></td></tr><tr><td class=Option>-do<br>--documented-only</td><td class=Description><p>Tells Natural Docs to only include what you explicitly document in the output, and not to find undocumented classes, functions, and variables.&nbsp; This option is only relevant if you have <a href="languages.html">full language support</a>.</p></td></tr><tr><td class=Option>-oft<br>--only-file-titles</td><td class=Description><p>Tells Natural Docs to only use the file name for its menu and page titles.&nbsp; It won&rsquo;t try to determine one from the contents of the file.</p></td></tr><tr><td class=Option>-nag<br>--no-auto-group</td><td class=Description><p>Tells Natural Docs to not automatically create group topics if you don&rsquo;t add them yourself.</p></td></tr><tr><td class=Option>-cs <i>[charset]</i><br>--charset <i>[charset]</i><br>--character-set <i>[charset]</i></td><td class=Description><p>Sets the character set property of the generated HTML, such as UTF-8 or Shift_JIS.&nbsp; The default leaves it unspecified.</p></td></tr><tr><td class=Option>-q<br>--quiet</td><td class=Description><p>Suppresses all non-error output.</p></td></tr><tr><td class=Option>-?<br>-h<br>--help</td><td class=Description><p>Prints the syntax reference.</p></td></tr><tr><td colspan=2 class=ParameterGroup>No Longer Supported:<div class=ParameterGroupExtra>These parameters were part of previous Natural Docs releases, but are no longer supported.</div></td></tr><tr><td class=Option>-ho<br>--headers-only</td><td class=Description><p>This used to check only the headers and not the source files in C and C++.&nbsp; <a href="customizinglanguages.html">Edit <code>Languages.txt</code> instead</a> and add the line <code>&ldquo;Ignore Extensions: c cpp cxx&rdquo;</code>.</p></td></tr><tr><td class=Option>-s Custom<br>--style Custom</td><td class=Description><p>This used to tell Natural Docs not to alter the CSS file in the output directory.&nbsp; Copy your custom CSS file to your project directory and use it with <code>-s</code> instead.</p></td></tr><tr><td class=Option>-ag <i>[level]</i><br>--auto-group <i>[level]</i></td><td class=Description><p>This used to set the level of auto-grouping between Full, Basic, and None.&nbsp; The algorithm was improved so there&rsquo;s no need for separate levels anymore.&nbsp; You can use <code>-nag</code> if you want to turn it off completely.</p></td></tr></table></div><div class=Topic><a name=Examples></a><div class=TopicTitle>Examples</div><pre>NaturalDocs -i C:\My Project\Source
-o FramedHTML C:\My Project\Docs
-p C:\My Project\Natural Docs
NaturalDocs -i /project/src1
-i /project/src2
-o HTML /project/doc
-p /project/nd
-s Small -t 3</pre></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 &copy; 2003-2008 Greg Valure</td></tr></table><script language=JavaScript><!--
ClosingBrowserTags();// --></script></body></html>