1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
<html><head><title>Troubleshooting - Natural Docs</title><link rel=stylesheet type="text/css" href="styles.css"><style type="text/css"><!--
.FAQSummary a:link,
.FAQSummary a:visited,
.FAQSummary a:hover,
.FAQSummary a:active {
color: #000000;
--></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 class=PageTable float=center><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><span class=SideMenuEntry id=SelectedSideMenuEntry>Troubleshooting</span></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>Troubleshooting</div><div class=FAQSummary><div class=FAQSummaryGroup>Natural Docs Issues</div><ul><li><a href="#NoDocs" class=FAQSummaryEntry>I don’t get any documentation.</a></li><li><a href="#MissingTopics" class=FAQSummaryEntry>Some of my topics don’t show up.</a></li><li><a href="#BadFormatting" class=FAQSummaryEntry>Some of my topics aren’t formatting correctly.</a></li><li><a href="#NoPrototypes" class=FAQSummaryEntry>I’m not getting prototypes.</a></li><li><a href="#LinksDontResolve" class=FAQSummaryEntry>My links aren’t working.</a></li></ul><div class=FAQSummaryGroup>Windows Issues</div><ul><li><a href="#CantFindPerl" class=FAQSummaryEntry>I get the message “Bad command or file name” or “perl is not recognized”.</a></li><li><a href="#CantFindND" class=FAQSummaryEntry>I get the message “Can’t open perl script NaturalDocs”.</a></li></ul></div><div class=FAQGroup>Natural Docs Issues</div><div class=FAQEntry><div class=FAQEntryTitle><a name=NoDocs></a>I don’t get any documentation</div><div class="First SubTopic">Is it recognizing your source files?</div><p>If Natural Docs has never said “Parsing <i>n</i> files...” when you run it, or <i>n</i> was way too low a number, it is not finding your source files.</p><p>If it has, try this test. Run Natural Docs once. Edit one of your source files and save it. Run Natural Docs again. If it doesn’t say “Parsing 1 file...” it is not recognizing your file.</p><div class=SubTopic>No, it’s not recognizing them</div><p>The most likely scenario is that Natural Docs doesn’t associate the file extension you’re using with your programming language. Open <code>Languages.txt</code> in Natural Docs’ Config directory and find your language. Underneath it you should see a line that says something like “<code>Extensions: c cpp cxx h hpp hxx</code>”. Add the file extensions you use and try again.</p><p>If you use extensionless or .cgi files, do the same thing but instead look for a line that says something like “<code>Shebang Strings: tclsh wish expect</code>”. If it is not there, you may need to add it yourself. Edit it to include whatever appears in your shebang (<code>#!</code>) line that would say this file belongs to your language.</p><p>Otherwise just make sure you included the directory or one of its parents with <a href="running.html#CommandLine"><code>-i</code> on the command line.</a></p><div class=SubTopic>Yes, it’s recognizing them</div><p>First note that unless you have <a href="languages.html">full language support</a>, Natural Docs will only include <a href="documenting.html">what you write for it.</a> It will not be able to scan your code and pick out all the classes and functions on its own.</p><p>If the problem is with text files, the most likely scenario is that you’re not <a href="documenting/reference.html#TextFiles">including topic lines.</a> Like in comments, only things that appear under “<code>keyword: name</code>” lines count as Natural Docs content.</p><p>If it’s still not working, note that Natural Docs can only read ASCII or UTF-8 encoded files that use Windows (CR+LF) or Unix (LF) line endings. If you use UTF-16 encoded files and/or classic Mac (CR) line endings you need to convert the files. These are due to limitations in Perl. Natural Docs 2.0 won’t have these problems.</p></div><div class=FAQEntry><div class=FAQEntryTitle><a name=MissingTopics></a>Some of my topics don’t show up</div><ul><li><a href="keywords.html">Check the list of keywords</a> to see if the one you’re using is there and you spelled it correctly. Note that the web page only has the default set of keywords. You may need to check <code>Topics.txt</code> in Natural Docs’ Config directory and your project directory if you’ve edited them</li><li>If the topics appear in code, make sure that the comments are alone on a line. You cannot put Natural Docs content on the same line as code. This includes having anything appear after a closing block comment symbol.</li><li>Make sure that if you have more than one topic in a comment, there is a blank line above the topic line.</li><li>If you have text boxes or lines, make sure they are completely unbroken. You can also try removing them completely.</li><li>If the topics appear in a text file, make sure you included topic lines. Like in comments, only things that appear after “<code>keyword: name</code>” lines count as Natural Docs content. You could just add a <code>Title:</code> line to the top of the file to fix this.</li></ul></div><div class=FAQEntry><div class=FAQEntryTitle><a name=BadFormatting></a>Some of my topics aren’t formatting correctly</div><ul><li><a href="documenting/reference.html#Headings">Headings</a> must have a blank line above them.</li><li>Lines directly after <a href="documenting/reference.html#BulletLists">bullet</a> or <a href="documenting/reference.html#DefinitionLists">definition</a> lines are part of the previous bullet or definition, even if it’s not indented. Skip a line first to do something else</li><li>If you’re getting symbols scattered throughout your text, make sure any text boxes or lines are completely unbroken. You can also try removing them altogether.</li><li>If your example source code is getting mangled, remember to use the <a href="documenting/reference.html#CodeAndTextDiagrams">example code syntax</a>.</li><li>If a line’s becoming a <a href="documenting/reference.html#Headings">heading</a> but shouldn’t, either get rid of the colon at the end or break it into two lines so the colon appears on the second line</li><li>If a line’s becoming a <a href="documenting/reference.html#DefinitionLists">definition</a> but shouldn’t, either get rid of the space-dash-space (use two dashes or remove one of the spaces) or break it into two lines so that the space-dash-space is on the second line.</li></ul><p>I realize the last two aren’t great. If you have any ideas as to how to reliably detect these kinds of false positives, <a href="#" onClick="location.href='mai' + 'lto:' + 'gregv' + 'alure' + '@' + 'natural' + 'docs.org'; return false;">e-mail me</a>.</p></div><div class=FAQEntry><div class=FAQEntryTitle><a name=NoPrototypes></a>I’m not getting prototypes</div><ul><li>The topic must appear directly above the thing it’s documenting.</li><li>Topics <a href="documenting/reference.html#DefinitionLists">documented in lists</a> will not get prototypes, even if the list break apart in the output.</li><li>The topic name must be present in the prototype somewhere. Make sure the topic title has the same case as in the prototype and that it’s not misspelled. This applies even if your language isn’t case sensitive.</li><li>If you’re documenting something with a new topic type you <a href="customizingtopics.html">added to <code>Topics.txt</code></a>, you must also <a href="customizinglanguages.html#Prototypes">edit <code>Languages.txt</code></a> to tell it how to detect prototypes for that type.</li></ul></div><div class=FAQEntry><div class=FAQEntryTitle><a name=LinksDontResolve></a>My links aren’t working</div><p>If your links appear in the output as “<code><text></code>” instead of being converted to links, do the following:</p><ul><li>Make sure the target appears in the output. The easiest way is to see if it appears in the Everything index.</li><li>Make sure the link is spelled correctly and has the same case as what you’re linking to. This applies even if your language isn’t case sensitive.</li><li>If the topic your link appears in and the link target are not in the same class (or are not both global) make sure you include the class in the link with <code>class.target</code>, <code>class::target</code>, or <code>class->target</code>. You can check which classes topics appear in with the Everything index. If your topics are appearing in the wrong classes, fix the documentation remembering the <a href="documenting/reference.html#KeywordsTopicsAndScope">topic scoping rules</a>.</li></ul></div><div class=FAQGroup>Windows Issues</div><div class=FAQEntry><div class=FAQEntryTitle><a name=CantFindPerl></a>I get the message “Bad command or file name” or “perl is not recognized”</div><p>What’s happening is that NaturalDocs.bat can’t find Perl. You need Perl installed to run Natural Docs, so if you haven’t done so already, you can download and install <a href="http://www.activestate.com/Products/activeperl/">ActiveState’s ActivePerl</a> for free.</p><p>If you already have Perl, it’s bin directory is either not in your path or the path isn’t being used by whatever you’re running it from, which happens on some IDEs. Edit NaturalDocs.bat and on the line that says “<code>perl NaturalDocs %NaturalDocsParams%</code>”, change <code>perl</code> to be the full path to perl.exe, such as <code>“C:\perl\bin\perl.exe”</code>. You need to include the quotes if there are spaces in the path.</p></div><div class=FAQEntry><div class=FAQEntryTitle><a name=CantFindND></a>I get the message “Can’t open perl script NaturalDocs”</div><p>What’s happening is that Perl can’t find the Natural Docs script file. This happens when the working directory or “start in” folder isn’t the directory Natural Docs was installed to. If changing that doesn’t work, or if you don’t have the option to set that, edit NaturalDocs.bat and find the line that says “<code>perl NaturalDocs %NaturalDocsParams%</code>”. Change <code>NaturalDocs</code> to include the full path Natural Docs was installed to, such as <code>“C:\Program Files\Natural Docs\NaturalDocs”</code>. You need to include the quotes if there are spaces in the path.</p></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-2010 Greg Valure</td></tr></table><script language=JavaScript><!--
ClosingBrowserTags();// --></script></body></html>
|
