mirror of
https://github.com/ddnet/ddnet.git
synced 2024-11-14 20:18:19 +00:00
14 lines
13 KiB
HTML
14 lines
13 KiB
HTML
|
|
|
|
<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><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><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="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>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>Platform 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><li><a href="#IESucks" class=FAQSummaryEntry>Internet Explorer gives me security warnings.</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> 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 <code>-i</code> on the command line.</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 what you write for it. 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 including topic lines. Like in comments, only things that appear under “<code>keyword: name</code>” lines count as Natural Docs content.</p><p>If this is happening in code, remember that comments must appear alone on a line. You cannot put Natural Docs comments on the same line as code. This includes having anything appear after a closing block comment symbol.</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.</li></ul></div><div class=FAQEntry><div class=FAQEntryTitle><a name=BadFormatting></a>Some of my topics aren’t formatting correctly</div><ul><li>Headers must have a blank line above them.</li><li>Lines directly after bullet or definition 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.html#Code">example code syntax</a>.</li><li>If a line’s becoming a header but shouldn’t, either get rid of the colon or break it into two lines so the colon appears on the second line</li><li>If a line’s becoming a definition 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 documented in lists 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></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.html#Topics">topic scoping rules</a>.</li></ul></div><div class=FAQGroup>Platform 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>. If you have spaces in any of the directories you need to surround it with quotes.</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>. If you have spaces in any of the directories you need to surround it with quotes.</p></div><div class=FAQEntry><div class=FAQEntryTitle><a name=IESucks></a>Internet Explorer gives me security warnings</div><p><i>“To help protect your security, Internet Explorer has restricted this file from showing active content that could access your computer.”</i></p><p>This is a problem with Internet Explorer and Windows XP Service Pack 2. In their infinite wisdom, Microsoft decided that instead of monitoring JavaScript to see if it actually <i>does</i> anything questionable, they just prevent it from running at all if the page is on your hard drive.</p><p>To fix it, <a href="http://www.naturaldocs.org/download.html">upgrade your copy of Natural Docs.</a> The HTML generated by Natural Docs 1.3 or higher can get around this issue.</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-2005 Greg Valure</td></tr></table><script language=JavaScript><!--
|
|
ClosingBrowserTags();// --></script></body></html> |