Natural Docs

Version 0.9

Copyright © 2003 Greg Valure

http://www.naturaldocs.org

Summary
Version 0.9
Licensed under the GNU General Public License
Adding additional languages is very easy, so don’t worry if yours isn’t here.
In the main script (NaturalDocs.pl) add a call to NaturalDocs::Languages::Add() after all the rest.
Read the CSS Guide to understand the styles Natural Docs uses and how they fit together.

License

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. 

Syntax

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

-i, --input, --sourceThe input (source) directory.  Required. 
-o, --outputThe output format and directory.  Required.  See Supported Output Formats for a list of options.  This can be specified multiple times, but only once per output format. 
-p, --projectThe project directory.  Required.  There should be a unique project directory for each input directory. 
-s, --styleSets the CSS style for HTML output.  It can either be a single value (“Small”) that applies to all HTML output or a series of [format]=[style] lines (“HTML=Small”) separated by spaces to distinguish between them.  If any style is set to “Custom”, it will not sync the project’s CSS file with one from Natural Docs’ style directory.  If not specified, the style is “Default”.  See HTML Styles for options. 
-r, --rebuildRebuilds all output and data files from scratch.  Use whenever you add or change the output formats.  Does not affect the menu file. 
-q, --quietSuppresses all non-error output. 
-h, --helpPrints the syntax reference. 

Supported Code Formats

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

Supported Output Formats

HTMLCreates HTML output.  A directory tree will be created to mirror the source tree, and each source file will have a corresponding HTML file of the same name, only with .html appended.  The files are self-contained and don’t rely on frames.  index.html forwards to the first file on the menu. 

HTML Styles

DefaultThe standard Natural Docs appearence.  You’re looking at it right now. 
SmallFor people who prefer 8pt Verdana, aka people with good eyes.  You get more on the screen at once, but some people hate it when web pages use tiny fonts. 
RomanFor people who prefer Roman fonts, aka people who use OS X, XP with ClearType, or some other decent anti-aliasing system.  Most people don’t and thus prefer Verdana.  It makes the fancy quotes (66 and 99, as opposed to II) look especially nice, though. 
CustomTells Natural Docs that the output directory is using its own custom CSS file.  Natural Docs will not sync the CSS file at all with this option set. 

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

HTML Compatibility

Mozilla (Gecko)Works on 1.0+. Tested on Mozilla 1.0.2 and 1.3, my browser of choice.  Therefore it should be okay with Netscape 7, etc. 
Internet ExplorerWorks on 4+. Tested on 4.0, 5.0 and 6.0.  I don’t have a partition for 5.5 so I’m assuming it works.  4 can’t collapse the menu and has minor layout issues. 
OperaWorks on 5+. Tested on 5.12, 6.05, and 7.02.  Only 7.02 can collapse the menu. 
Konqueror (KHTML)Probably. With the addition of Safari I’d like to be able to test this, but there’s nothing for Windows and I haven’t gotten around to setting up a Linux partition yet.  It should work as it’s not doing anything exceptionally fancy except for the collapsing menu, which is still usable when the browser can’t handle it. 
Netscape 4.xNope. Crashes 4.08 and mangled on 4.8.  Why did they ever drop this for Gecko?  I’ve stopped supporting NS4 in my projects and have found that my quality of life has improved considerably. 

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. 

Contributors

  • Greg Valure (gregvalure@naturaldocs.org)

Extending

How to Add Source Formats

In the main script (NaturalDocs.pl) add a call to NaturalDocs::Languages::Add() after all the rest.  See NaturalDocs::Languages::Add()’s documentation for an explanation of the parameters. 

How to Add Output Formats

How to Add HTML Styles

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. 

Code Conventions