Natural Docs

Licensed under the GNU General Public License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, visit http://www.gnu.org/licenses/gpl.txt or write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

NaturalDocs -i [input (source) directory]
           (-i [input (source) directory] ...)
            -o [output format] [output directory]
           (-o [output format] [output directory] ...)
            -p [project directory]
            [options]

Directory names with spaces are fine.  They don’t need quotes on Windows.

Examples

NaturalDocs -i C:\My Project\Source
            -o HTML C:\My Project\Docs
            -p C:\My Project\Natural Docs

NaturalDocs -i /src/project
            -o HTML /doc/project
            -p /etc/naturaldocs/project
            -s Small -t 2 -q

Options

Adding additional languages is very easy, so don’t worry if yours isn’t here.  See How to Add Languages.

• C++
• C#
• Java
• JavaScript (.js files only)
• Perl (.pl and .pm files, plus .cgi and extensionless files if “perl” is in the #! line)
• Python (.py files, plus .cgi and extensionless files if “python” is in the #! line)
• PHP (support isn’t flawless because escapement isn’t handled yet)
• PL/SQL
• Visual Basic
• Pascal (which includes Delphi)
• Assembly
• Tcl
• Ada
• Ruby
• Text files (.txt files only)

Natural Docs is designed to be extended with more output formats, but it requires familiarity with Perl.  See How to Add Output Formats for details.

You can also use any CSS file present in Natural Docs’ styles directory.  Just use its name without the .css extension.  For example, if your style is Blue.css, use “Blue”.

You can check for additional styles at http://www.naturaldocs.org.  If you would like to build your own, see How to Add HTML Styles.

Note that a browser not being able to collapse the menu isn’t a compatibility concern.  The menu defaults to completely open if the browser can’t handle collapsing it, so it’s always usable.  It’s just better on browsers that support it.

Also note that if a browser doesn’t support frames, the user will automatically be forwarded to the menu file when using framed HTML output so it will still be usable.

Greg Valure (gregv.nosp@m.alure@natural.nosp@m.docs.org)

In the main script add a call to NaturalDocs::Languages::Simple->New() after all the rest.  See its documentation for an explanation of the parameters.

• Create a new NaturalDocs::Builder sub-package derived from NaturalDocs::Builder::Base.
• See NaturalDocs::Builder::Base’s documentation for a list of the interface functions that should be implemented and examples of how to do so.
• By placing the file in the Modules/NaturalDocs/Builder directory, it will automatically be included by Natural Docs.  You do not have to add a ‘use’ statement anywhere in the code, which makes it easy to keep custom output formats whenever you upgrade Natural Docs.

• If you’d like to add a synonym for an existing topic type, edit NaturalDocs::Topics::constants.  Note that it must be in all lowercase.
• If you’d like to add a new topic type, read through NaturalDocs::Topics’ source.  It should be obvious what needs to be edited, just don’t skip anything.  You can stop when you reach the functions.

• Create a new NaturalDocs::Extensions sub-package derived from NaturalDocs::Extensions::Base.
• See NaturalDocs::Extensions::Base’s documentation for a list of interface functions can be implemented.
• By placing the file in the Modules/NaturalDocs/Extensions directory, it will automatically be included by Natural Docs.  You do not have to add a ‘use’ statement anywhere in the code, which makes it easy to keep custom extensions whenever you upgrade Natural Docs.

Read the CSS Guide to understand the styles Natural Docs uses and how they fit together.

After you’ve created your own CSS file, drop it in the Natural Docs styles directory.  Then you can reference it via -s in the command line.  Its name is the CSS file name without the extension.  So if your file is Red.css, you use it by specifying “-s Red” in your projects.

If you ever change the CSS file in the Natural Docs styles directory, each project that uses it will get an updated copy automatically the next time Natural Docs is run on it.

Also make sure that whenever you upgrade Natural Docs, you check the Revisions section of the CSS Guide to see if there have been any changes to the generated HTML.  It may require you to update your CSS file.

• All NaturalDocs:: packages have their functions called in Package->Function() notation.  You call NaturalDocs::Project->FilesToBuild(), not NaturalDocs::Project::FilesToBuild().  Note that this was not the case until version 1.14, so any custom modifications done before then probably need to be updated.
• If you’re wondering about some of the line lengths or the strange indentation, it’s because I work on Natural Docs using 8pt Verdana.