If Natural Docs has never said “Parsing n files...” when you run it, or n was way too low a number, it is not finding your source files.

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.

The most likely scenario is that Natural Docs doesn’t associate the file extension you’re using with your programming language.  Open Languages.txt and find your language.  Underneath it you should see a line that says something like “Extensions: c cpp cxx h hpp hxx”.  Add the file extensions you use and try again.

If you use extensionless or .cgi files, do the same thing but instead look for a line that says something like “Shebang Strings: tclsh wish expect”.  If it is not there, you may need to add it yourself.  Edit it to include whatever appears in your shebang (#!) line that would say this file belongs to your language.

Otherwise just make sure you included the directory or one of its parents with -i on the command line.

First note that unless you have full language support, 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.

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 “keyword: name” lines count as Natural Docs content.

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.

• Check the list of keywords 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 Topics.txt in Natural Docs’ Config directory and your project directory if you’ve edited them
• 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.
• Make sure that if you have more than one topic in a comment, there is a blank line above the topic line.
• If you have text boxes or lines, make sure they are completely unbroken.  You can also try removing them completely.
• If the topics appear in a text file, make sure you included topic lines.  Like in comments, only things that appear after “keyword: name” lines count as Natural Docs content.  You could just add a Title: line to the top of the file.

• Headers must have a blank line above them.
• 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
• 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.
• If your example source code is getting mangled, remember to use the example code syntax.
• 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
• 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.

I realize the last two aren’t great.  If you have any ideas as to how to reliably detect these kinds of false positives, e-mail me.

• The topic must appear directly above the thing it’s documenting.
• Topics documented in lists will not get prototypes, even if the list break apart in the output.
• 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.

If your links appear in the output as “<text>” instead of being converted to links, do the following:

• Make sure the target appears in the output.  The easiest way is to see if it appears in the Everything index.
• 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.
• 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 class.target, class::target, or class->target.  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 topic scoping rules.

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 ActiveState’s ActivePerl for free.

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 “perl NaturalDocs %NaturalDocsParams%”, change perl to be the full path to perl.exe, such as C:\perl\bin\perl.exe.  If you have spaces in any of the directories you need to surround it with quotes.

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 “perl NaturalDocs %NaturalDocsParams%”.  Change NaturalDocs to include the full path Natural Docs was installed to, such as C:\Program Files\Natural Docs\NaturalDocs.  If you have spaces in any of the directories you need to surround it with quotes.

“To help protect your security, Internet Explorer has restricted this file from showing active content that could access your computer.”

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 does anything questionable, they just prevent it from running at all if the page is on your hard drive.

To fix it, upgrade your copy of Natural Docs.  The HTML generated by Natural Docs 1.3 or higher can get around this issue.