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]
            -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 -q -m

Options

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

• C++ (.h and .hpp files only)
• Java
• Perl (.pl and .pm files, plus .cgi and extensionless files if “perl” is in the #! line)
• JavaScript (.js files only)
• Text files

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 (gregvalure@naturaldocs.org)

In the main script add a call to NaturalDocs::Languages::Add() after all the rest.  See NaturalDocs::Languages::Add()’s 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. 
• Add a ‘use’ statement for your package after the others in the main script. 
• Document the additional option in Supported Output Formats. 

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. 

• All top-level NaturalDocs:: packages (i.e.  NaturalDocs::Project, NaturalDocs::Languages) have their functions called in Package::Function() notation.  You call NaturalDocs::Project::FilesToBuild(), not NaturalDocs::Project->FilesToBuild(). 
• All output format packages (i.e.  NaturalDocs::Builder::HTML) have their interface functions called in Package->Function() notation because they need to be affected by inheritance.  Since these functions are only called by NaturalDocs::Builder, you don’t need to worry about this unless you’re writing one.  How any other functions in these packages are called depends on the package, since they shouldn’t be called externally anyway. 
• All other lower-level NaturalDocs:: packages (i.e.  NaturalDocs::Project::File, NaturalDocs::Languages::Language) are object packages.  You call New() as Package::Function(), and then everything else is called on the object with Object->Function().