From 61bfe2d70cae6be8c4086a210a5451135ccca9ea Mon Sep 17 00:00:00 2001 From: Magnus Auvinen Date: Sat, 2 Aug 2008 08:21:29 +0000 Subject: added doc tool --- docs/tool/Help/customizinglanguages.html | 52 +++ docs/tool/Help/customizingtopics.html | 74 ++++ docs/tool/Help/documenting.html | 58 +++ docs/tool/Help/documenting/reference.html | 146 +++++++ docs/tool/Help/documenting/walkthrough.html | 180 ++++++++ docs/tool/Help/example/Default.css | 528 ++++++++++++++++++++++++ docs/tool/Help/example/NaturalDocs.js | 204 +++++++++ docs/tool/Help/examples.css | 90 ++++ docs/tool/Help/images/header/background.png | Bin 0 -> 229 bytes docs/tool/Help/images/header/leftside.png | Bin 0 -> 1215 bytes docs/tool/Help/images/header/logo.png | Bin 0 -> 12146 bytes docs/tool/Help/images/header/overbody.png | Bin 0 -> 283 bytes docs/tool/Help/images/header/overbodybg.png | Bin 0 -> 141 bytes docs/tool/Help/images/header/overleftmargin.png | Bin 0 -> 188 bytes docs/tool/Help/images/header/overmenu.png | Bin 0 -> 244 bytes docs/tool/Help/images/header/overmenubg.png | Bin 0 -> 141 bytes docs/tool/Help/images/header/rightside.png | Bin 0 -> 1186 bytes docs/tool/Help/images/logo.gif | Bin 0 -> 8221 bytes docs/tool/Help/images/menu/about.png | Bin 0 -> 397 bytes docs/tool/Help/images/menu/background.png | Bin 0 -> 187 bytes docs/tool/Help/images/menu/bottomleft.png | Bin 0 -> 235 bytes docs/tool/Help/images/menu/bottomright.png | Bin 0 -> 234 bytes docs/tool/Help/images/menu/community.png | Bin 0 -> 507 bytes docs/tool/Help/images/menu/customizing.png | Bin 0 -> 575 bytes docs/tool/Help/images/menu/using.png | Bin 0 -> 390 bytes docs/tool/Help/index.html | 9 + docs/tool/Help/javascript/BrowserStyles.js | 77 ++++ docs/tool/Help/javascript/PNGHandling.js | 72 ++++ docs/tool/Help/keywords.html | 38 ++ docs/tool/Help/languages.html | 32 ++ docs/tool/Help/menu.html | 79 ++++ docs/tool/Help/output.html | 84 ++++ docs/tool/Help/running.html | 40 ++ docs/tool/Help/styles.css | 290 +++++++++++++ docs/tool/Help/styles.html | 52 +++ docs/tool/Help/troubleshooting.html | 18 + 36 files changed, 2123 insertions(+) create mode 100644 docs/tool/Help/customizinglanguages.html create mode 100644 docs/tool/Help/customizingtopics.html create mode 100644 docs/tool/Help/documenting.html create mode 100644 docs/tool/Help/documenting/reference.html create mode 100644 docs/tool/Help/documenting/walkthrough.html create mode 100644 docs/tool/Help/example/Default.css create mode 100644 docs/tool/Help/example/NaturalDocs.js create mode 100644 docs/tool/Help/examples.css create mode 100644 docs/tool/Help/images/header/background.png create mode 100644 docs/tool/Help/images/header/leftside.png create mode 100644 docs/tool/Help/images/header/logo.png create mode 100644 docs/tool/Help/images/header/overbody.png create mode 100644 docs/tool/Help/images/header/overbodybg.png create mode 100644 docs/tool/Help/images/header/overleftmargin.png create mode 100644 docs/tool/Help/images/header/overmenu.png create mode 100644 docs/tool/Help/images/header/overmenubg.png create mode 100644 docs/tool/Help/images/header/rightside.png create mode 100644 docs/tool/Help/images/logo.gif create mode 100644 docs/tool/Help/images/menu/about.png create mode 100644 docs/tool/Help/images/menu/background.png create mode 100644 docs/tool/Help/images/menu/bottomleft.png create mode 100644 docs/tool/Help/images/menu/bottomright.png create mode 100644 docs/tool/Help/images/menu/community.png create mode 100644 docs/tool/Help/images/menu/customizing.png create mode 100644 docs/tool/Help/images/menu/using.png create mode 100644 docs/tool/Help/index.html create mode 100644 docs/tool/Help/javascript/BrowserStyles.js create mode 100644 docs/tool/Help/javascript/PNGHandling.js create mode 100644 docs/tool/Help/keywords.html create mode 100644 docs/tool/Help/languages.html create mode 100644 docs/tool/Help/menu.html create mode 100644 docs/tool/Help/output.html create mode 100644 docs/tool/Help/running.html create mode 100644 docs/tool/Help/styles.css create mode 100644 docs/tool/Help/styles.html create mode 100644 docs/tool/Help/troubleshooting.html (limited to 'docs/tool/Help') diff --git a/docs/tool/Help/customizinglanguages.html b/docs/tool/Help/customizinglanguages.html new file mode 100644 index 00000000..593e77ab --- /dev/null +++ b/docs/tool/Help/customizinglanguages.html @@ -0,0 +1,52 @@ + + +Customizing Natural Docs Languages + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Customizing Languages
Languages.txt · File Extensions · Adding Languages · Prototypes
Index Prefixes · Special Languages · Syntax Reference
Languages.txt

Natural Docs has two files called Languages.txt: one in its Config directory, and one in your project directory.  These control the language, index prefix, and prototype features of Natural Docs.

You should edit the one in your project directory whenever possible.  It keeps your changes separate and easier to manage, plus you don’t have to reapply them whenever you upgrade.  Editing the one in Natural Docs’ Config directory would be better only if you’re using Natural Docs with a lot of projects and would like the changes to apply everywhere.

Note that unlike other Natural Docs configuration files, comments can only appear on their own lines.  They cannot appear after something else on a line because settings may need to use the # symbol.  Also, all lists are space-separated instead of comma-separated, again because some settings may need to use the comma symbol.

File Extensions

If Natural Docs doesn’t recognize a file extension you use for your code, it’s not a problem.  You can alter the language definition from your project file to add them.

Alter Language: [your language]
+   Add Extensions: cxx hxx

On the other hand, if it’s scanning some files you don’t want it to scan, you can exclude extensions as well.  Just add this to the top of your file:

Ignore Extensions: c cpp

In this example, Natural Docs will ignore C++ source files, thus only scanning the headers.

Adding Languages

You can add basic language support for any programming language just by editing these configuration files.  Here are the most important settings:

Language: Fictional
+
+   Extensions: fsrc fhdr
+   Shebang Strings: fictional
+   Line Comment: //
+   Block Comment: /* */
+   Package Separator: ::

This tells Natural Docs that any files with the .fsrc or .fhdr extensions are part of our fictional programming language.  Also, any .cgi or extensionless files that have “fictional” in the shebang (#!) line are part of it as well.  Line comments start with // and block comments appear between /* and */.  The default package separator is ::.  Not too hard, huh?

You can also add settings to ignore prefixes in the index and detect prototypes, but those are dealt with in their own sections on this page.

Prototypes

So you’ve added a new language and want to detect prototypes.  Or perhaps you added a custom topic type and want to detect prototypes for that as well.  Here’s an example of the properties you need:

Function Prototype Enders: ; {
+Variable Prototype Enders: ; =

The algorithm for finding prototypes is very simple, yet it works really well in practice.  All the code following the comment is grabbed until it reaches an ender symbol or another comment.  Ender symbols appearing inside parenthesis, brackets, braces, or angle brackets don’t count.  If it reaches an ender symbol and somewhere in that code is the topic title, the code is accepted as the prototype.

So in the example above, variables end at semicolons (the end of the declaration) or equal signs (the default value expression, which we don’t want to include.)  Since the Natural Docs comment for the variable should have appeared right before the definition, that leaves us with the name and type.  Functions are handled similarly: they end at a semicolon (the end of a predeclaration) or an opening brace (the beginning of the body) leaving us with the name, parameters, and return type.

You can do this with any topic type, including custom ones.  Any prototypes that look like they have parameters will be formatted as such automatically.

Line Breaks

For some languages, line breaks are significant.  To have them end a prototype, use \n.  If it has an extender symbol that allows the code to continue on the next line, you can specify that as well.

Function Prototype Ender: \n
+Variable Prototype Ender: \n =
+Line Extender: _
Colors

If you’re collecting prototypes for a custom topic type, they will not automatically get their own background color like the other types have.  You have to define it via CSS.

Index Prefixes

Natural Docs has the ability to ignore prefixes in the indexes.  This is necessary because in certain languages, variables are prefixed with $ or other symbols and we don’t want them to get all grouped together under the symbols heading.  Instead, they appear in the sidebar and are sorted as if they’re not there.

A
 AddProperty, SomeClass
$amount
 Average

However, we can take advantage of this simply to get around coding conventions.  Suppose you prefix all your class names with C.  They’d all form one gigantic group under C in the index.  If you want, you can have it ignored so CCat, CDog, and CMouse get filed under C, D, and M instead.  Just add this to your languages file:

Alter Language: [your language]
+   Add Ignored Class Prefix in Index: C

Now C is ignored in your indexes:

A
CAccount
CAccountHolder
 AddProperty, SomeClass
$amount
 Average

You can include any number of prefixes and can do this for any topic type.  So if you have a bunch of functions that start with COM_ and DB_, you can ignore them too:

Alter Language: [your language]
+   Add Ignored Class Prefix in Index: C
+   Add Ignored Function Prefixes in Index: COM_ DB_
Special Languages

There are two languages with special properties: Shebang Script and Text File.

Shebang Script allows you to define the file extensions where the language is really determined by the shebang (#!) line within it.  For example, .cgi files.  If Natural Docs finds a .cgi file, it sees that it’s a Shebang Script so it opens it up to parse it’s shebang line.  It then searches it for substrings defined by other languages’ Shebang String settings to find out what language it really is.  Files with no extension are always treated this way.

With Text File, the entire file is treated like a comment.  There are no comment symbols required, you can just put Natural Docs content there in plain text.  The most important setting is Extensions.

However, since it is possible to document classes, functions, etc. in text files, they also have their own Package Separator and Ignored [type] Prefixes in Index settings.  To make things easier on you, by default it copies these settings from whichever language has the most source files in your project.  You can override this by manually setting them, but you shouldn’t need to.

Syntax Reference

Unlike other Natural Docs configuration files, comments can only appear on their own lines.  They cannot appear after something else on a line because settings may need to use the # symbol.  Likewise, lists are separated with spaces instead of commas because commas themselves may need to appear on the list.

Singular and plural forms are generally both supported, so you can write Extension or Extensions.  It doesn’t matter if they match how many items are set.  Also, you can use either Ignore or Ignored.

Ignore Extensions: [extension] [extension] ...

Causes the listed file extensions to be ignored, even if they were previously defined to be part of a language.  The list is space-separated.  ex. “Ignore Extensions: cvs txt”

Language: [name]
+Alter Language: [name]

Creates a new language or alters an existing one.  Names can use any characters.  Note the special behavior for languages named Shebang Script and Text File.

If you’re altering an existing language and a property has an [Add/Replace] form, you have to specify whether you’re adding to or replacing the list if that property has already been defined.

General Language Properties
Extensions: [extension] [extension] ...
+[Add/Replace] Extensions: [extension] [extension] ...

Defines file extensions for the language’s source files.  The list is space-separated.  ex. “Extensions: c cpp”.  You can use extensions that were previously used by another language to redefine them.  You can use * to specify all undefined extensions.

Shebang Strings: [string] [string] ...
+[Add/Replace] Shebang Strings: [string] [string] ...

Defines a list of strings that can appear in the shebang (#!) line to designate that it’s part of this language.  They can appear anywhere in the line, so php will work for “#!/user/bin/php4”.  You can use strings that were previously used by another language to redefine them.

Ignore Prefixes in Index: [prefix] [prefix] ...
+Ignore [type] Prefixes in Index: [prefix] [prefix] ...
+
+[Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ...
+[Add/Replace] Ignored [type] Prefixes in Index: [prefix] [prefix] ...

Specifies prefixes that should be ignored when sorting symbols for an index.  Can be specified in general or for a specific topic type.  The prefixes will still appear, the symbols will just be sorted as if they’re not there.  For example, specifying ADO_ for functions will mean that ADO_DoSomething will appear under D instead of A.

Basic Language Support Properties

These attributes are only available for languages with basic language support.

Line Comments: [symbol] [symbol] ...

Defines a space-separated list of symbols that are used for line comments, if any.  ex. “Line Comment: //”.

Block Comments: [opening symbol] [closing symbol] [o.s.] [c.s.] ...

Defines a space-separated list of symbol pairs that are used for block comments, if any.  ex. “Block Comment: /* */”.

Enum Values: [global|under type|under parent]

Defines the behavior of enum values.  The default is global.

GlobalEnum values are always global and will be referenced as “Value”.
Under TypeEnum values appear under the type and will be referenced as “Package.Enum.Value”.
Under ParentEnum values appear under the parent and will be referenced as “Package.Value”
[type] Prototype Enders: [symbol] [symbol] ...

When defined, Natural Docs will attempt to collect prototypes from the code following the specified topic type.  It grabs code until the first ender symbol or the next Natural Docs comment, and if it contains the topic name, it serves as its prototype.  Use \n to specify a line break.  ex. “Function Prototype Enders: { ;”, “Variable Prototype Enders: = ;”. 

Line Extender: [symbol]

Defines the symbol that allows a prototype to span multiple lines if normally a line break would end it.

Perl Package: [perl package]

Specifies the Perl package used to fine-tune the language behavior in ways too complex to do in this file.

Full Language Support Properties

These attributes are only available for languages with full language support.

Full Language Support: [perl package]

Specifies the Perl package that has the parsing routines necessary for full language support.

Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/customizingtopics.html b/docs/tool/Help/customizingtopics.html new file mode 100644 index 00000000..89602aa5 --- /dev/null +++ b/docs/tool/Help/customizingtopics.html @@ -0,0 +1,74 @@ + + +Customizing Natural Docs Topics + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Customizing Topics
Topics.txt · Topic Types vs. Keywords · Adding Topic Types
Changing Keywords · Altering Behavior · Syntax Reference
Topics.txt

Natural Docs has two files called Topics.txt: one in its Config directory, and one in your project directory.  These control the topic behavior and keywords Natural Docs uses.

You should edit the one in your project directory whenever possible.  It keeps your changes separate and easier to manage, plus you don’t have to reapply them whenever you upgrade.  Editing the one in Natural Docs’ Config directory would be better only if you’re using Natural Docs with a lot of projects and would like the changes to apply everywhere.

Topic Types vs. Keywords

It’s important to understand the difference between topic types and keywords.  Topic types have their own indexes and behavior settings.  You’ll reference them by name when dealing with indexes in the menu file or prototype detection in the language file, but not when documenting your code unless you make their names keywords as well.

You use keywords when documenting your code.  There can be many keywords per topic type, and they are completely interchangable.

Suppose you document a class with the Class keyword and a struct with Struct.  They are both keywords for the Class topic type by default, so they will appear in the same index.  If you wanted structs to have their own index, you would add a topic type for structs and change the Struct keyword to point to it.

Adding Topic Types

If you want to be able to document something in Natural Docs doesn’t handle by default, you want to create your own topic type for it.  Let’s say you’re working on a video game and you want to document all the sound effects because you want to keep track of what each one is for and have an index of them.  You’d add this to your topics file:

Topic Type: Sound Effect
+   Plural: Sound Effects
+   Keywords:
+      sound
+      sound effect
+

Sound effects can now be documented with the sound or sound effect keywords, and they’ll get their own index.  The Plural line just specifies the plural name of the topic type.  It isn’t required, but Natural Docs will use it in some places where the plural would sound more natural, like when grouping topics or naming indexes on the menu.

Here are a couple of other things you may want to add:

Topic Type: Sound Effect
+   Plural: Sound Effects
+   Scope: Always Global
+   Keywords:
+      sound, sounds
+      sound effect, sound effects
+

You can set the scope behavior of the topic type.  Your options are:

NormalTopics stay within the current scope.
StartTopics start a new scope for all the topics beneath it, like class topics.
EndTopics reset the scope back to global for all the topics beneath it.
Always GlobalTopics are defined as global, but do not change the scope for any other topics.

Here we set it to Always Global so that if we document one as part of a class, it will still be global yet will not break the class’ scope.  In other words, we can always link to it with just its name instead of needing something like <Class.Sound>.

The other thing we did was add plural keywords, which you do by using a comma after an existing keyword.  These keywords are used for list topics so we don’t have to document each one individually with the full syntax.

There are more options, these are just the most important ones.  See the full syntax reference for the rest.

Prototypes

If you’d like to collect prototypes for your new topic type, you have to do that by editing Languages.txt.

Changing Keywords
Adding and Changing

If you’re defining your own topic type or editing the main topics file, you simply add to the keywords list:

Topic Type: Sound Effect
+   Keywords:
+      sound, sounds
+      sound effect, sound effects
+

It doesn’t matter if the keyword was previously defined for a different topic type.  Just define it again and the definition will change.

If you want to add keywords to one of the main topic types from the project file, use Alter Topic Type instead:

Alter Topic Type: General
+   Keywords:
+      note
+      notes
+

Natural Docs will keep a list of the main file’s topic types in your project file so that you can do this easily.

Ignoring

Sometimes a keyword just gets in the way.  It’s too common in your comments and Natural Docs keeps accidentally picking them up as topics when that isn’t what you wanted.  You can get rid of keywords completely by either deleting them from the main file or putting this in your project file:

Ignore Keywords:
+   about
+   title
+

If you only have a few, you can use this syntax as well:

Ignore Keywords: note, notes, title
+
Altering Behavior

You can change the behavior of any topic type defined in the main file via your project file.  Just use Alter Topic Type and redefine any property.

Alter Topic Type: Constant
+   Scope: Always Global
+

Natural Docs will keep a list of the main file’s topic types in your project file so you can do this easily.  See the syntax reference below for a full list of your options.

Syntax Reference
Ignore Keywords: [keyword], [keyword] ...
+   [keyword]
+   [keyword], [keyword]
+   ...
+

Ignores the keywords so that they’re not recognized as Natural Docs topics anymore.  Can be specified as a list on the same line and/or following like a normal Keywords section.

Topic Type: [name]
+Alter Topic Type: [name]
+

Creates a new topic type or alters an existing one.  The name can only contain letters, numbers, spaces, and these characters: . - ‘ /.  It isn’t case sensitive, although the original case is remembered for presentation.

There are a number of default types that must be defined in the main file, but they will be listed there since it may change between versions.  The default types can have their keywords or behaviors changed, though, either by editing the default file or by overriding them in the user file.

Properties
Plural: [name]
+

Specifies the plural name of the topic type.  Defaults to the singular name.  Has the same restrictions as the topic type name.

Index: [yes|no]
+

Whether the topic type gets an index.  Defaults to yes.

Scope: [normal|start|end|always global]
+

How the topic affects scope.  Defaults to normal.

NormalTopics stay within the current scope.
StartTopics start a new scope for all the topics beneath it, like class topics.
EndTopics reset the scope back to global for all the topics beneath it.
Always GlobalTopics are defined as global, but do not change the scope for any other topics.
Class Hierarchy: [yes|no]
+

Whether the topic is part of the class hierarchy.  Defaults to no.

Page Title if First: [yes|no]
+

Whether the title of this topic becomes the page title if it is the first topic in a file.  Defaults to no.

Break Lists: [yes|no]
+

Whether list topics should be broken into individual topics in the output.  Defaults to no.

Can Group With: [topic type], [topic type], ...
+

Lists the topic types that can be grouped with this one in the output.  If two or more topic types often appear together, like Functions and Properties, this will allow them to be grouped together under one heading if it would cause too many groups otherwise.

Keywords:
+   [keyword]
+   [keyword], [plural keyword]
+   ...
+

A list of the topic type’s keywords.  Each line after the heading is the keyword and optionally its plural form.  This continues until the next line in “keyword: value” format.

  • Keywords can only have letters, numbers, and spaces.  No punctuation or symbols are allowed.
  • Keywords are not case sensitive.
  • Subsequent keyword sections add to the list.  They don’t replace it.
  • Keywords can be redefined by appearing in later keyword sections.
Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/documenting.html b/docs/tool/Help/documenting.html new file mode 100644 index 00000000..2999f431 --- /dev/null +++ b/docs/tool/Help/documenting.html @@ -0,0 +1,58 @@ + + +Documenting Your Code - Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Documenting Your Code
Walkthrough
Reference

Here’s a quick example of how to document your code for Natural Docs.  If you’re a new user, we have a walkthrough to get you started.  Otherwise, visit the reference for the full details.

/*
+   Function: Multiply
+
+   Multiplies two integers.
+
+   Parameters:
+
+      x - The first integer.
+      y - The second integer.
+
+   Returns:
+
+      The two integers multiplied together.
+
+   See Also:
+
+      <Divide>
+*/
+int Multiply (int x, int y)
+   {  return x * y;  };
Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/documenting/reference.html b/docs/tool/Help/documenting/reference.html new file mode 100644 index 00000000..269ede89 --- /dev/null +++ b/docs/tool/Help/documenting/reference.html @@ -0,0 +1,146 @@ + + +Documenting Your Code: Reference - Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Documenting Your Code
Comments · Text Files · Keywords, Topics, and Scope · Linking
Formatting and Layout · Page Titles · Summaries · Javadoc Compatibility
int Add (int x,
int y)
Adds two integers.
int Subtract (int x,
int y)
Subtracts two integers.
int Multiply (int x,
int y)
Multiplies two integers.
int Divide (int x,
int y)
Divides two integers.
bool IsEqual (int x,
int y)
Returns whether two integers are equal.
Comments

There is no special comment style for Natural Docs.  You just embed Natural Docs topics into regular comments, and it’s pretty tolerant as far as style goes.  You can use block comments or string together line comments.  The only requirement is that the comments are not on the same line as code.

/* Function: Multiply
+   Multiplies two integers and returns the result. */
+
+// Function: Multiply
+// Multiplies two integers and returns the result.
+

Note that when stringing line comments together, blank lines that you want to include in the documentation must start with the comment symbol as well.  If a line is completely blank, it’s considered the end of the comment and thus the end of the Natural Docs topic.

Boxes and Horizontal Lines

Natural Docs can also handle comment boxes and horizontal lines.  It doesn’t matter what symbols they use.  The boxes don’t need to be closed on the right side, and they can have different symbols for the edges and corners.

/*
+ * Function: Multiply
+ * Multiplies two integers and returns the result.
+ */
+
+/* +-------------------------------------------------+
+   | Function: Multiply                              |
+   | Multiplies two integers and returns the result. |
+   +-------------------------------------------------+ */
+
+//////////////////////////////////////////////////////////////
+//
+//  Function: Multiply
+//  ------------------
+//
+//  Multiplies two integers together and returns the result.
+//
+//////////////////////////////////////////////////////////////
+
Javadoc Style

If you have full language support, you can also use Javadoc-style comments to write Natural Docs documentation.  To do this you repeat the last symbol on the first line of the comment once.  The comment must appear directly above what it’s documenting, and you can omit the topic line if you want (the “Function: Multiply” part.)

/**
+ * Multiplies two integers and returns the result.
+ */
+
+///
+// Multiplies two integers together and returns the result.
+

If you omit the topic line and include any Javadoc tags in the comment, like @param, the entire comment will be treated as Javadoc and can only use Javadoc formatting.  Otherwise it’s treated as a Natural Docs comment and you can use all the formatting options described on this page.  You can have both styles in the same source file, but not in the same comment.

Perl POD

Perl users can also use POD to do block comments.

=begin nd
+
+Function: Multiply
+Multiplies two integers and returns the result.
+
+=cut
+

You can also use NaturalDocs or Natural Docs in place of ND.  None of them are case sensitive.  If for some reason you want to go back to POD documentation instead of using =cut, you can write =end nd.

There’s a second form of just =nd which is offered as a convenience.  However, it is not valid POD.  Perl will skip over it and execute fine, but POD parsers will give errors and possibly include the unformatted text in the output.  Use the longer, valid form unless you know for certain that no one will ever try to run POD on your code.

=nd
+
+Function: Multiply
+Multiplies two integers and returns the result.
+
+=cut
+
Text Files

Documentation can also be included in text files.  Any file with a .txt extension appearing in the source tree and starting with a topic line will included in the documentation.  It will be treated the same as a source file, meaning it will appear in the menu, its topics will be in the indexes, and its topics can be linked to from anywhere in the documentation.  The only difference is you don’t need comment symbols.

Remember that the topic line is required to be the first line of content.  If the first non-blank line is not in the “Function: Multiply” format the file will be ignored.  An easy way to do this is to use the Title keyword, although all of the other ones will work as well.

Title: License
+
+This project is licensed under the GPL.
+

This method is convenient for documenting file formats, configuration settings, the general program architecture, or anything else that isn’t directly tied to a source file.

Keywords, Topics, and Scope

A topic in Natural Docs starts with a topic line in the format “keyword: name”.  You can have multiple topics per comment as long as you separate them with a blank line.  The keywords aren’t case sensitive.

The list of keywords is pretty predictable: Function, Class, Variable, etc.  Just use what you’re documenting.  There are many synonyms as well, so you can use keywords like Func, Procedure, Proc, Method and Constructor.  Look at the full list of keywords to see everything that’s available.

The list of keywords is separated into topic types.  Each type gets its own index, and which specific keyword you use doesn’t matter.  Some also have scoping rules or other behavior as noted.

Scope

Like the code it’s documenting, Natural Docs topics have scope.  This mostly has to do with linking: if you’re in a class you can link to its members by their name alone, but if you’re not, you have to use a notation like class.member or class::member.

If you have full language support and are documenting something that appears in the code, the scope will be handled automatically.  If you’re using text files, have basic language support, or are including a topic that doesn’t correspond to something in the code, scoping follows these rules:

List Topics

If you looked at the list, you saw that most of the keywords have plural forms.  That’s for list topics, which let you document many small things without using the full syntax.  Anything that appears in definition lists within that topic will be treated as if it had its own topic.  It will appear in the indexes and be linkable, just like normal topics.

Function list topics will automatically break apart in the output as well, so it will look the same as if you documented each one individually.

Linking

Linking is the one place where Natural Docs has some negative effect on the readability of the comments.  The alternative would be to automatically guess where links should be, but systems that do that can sometimes pepper your sentences with unintentional links to functions called “is” or “on”.  However, the Natural Docs syntax is still as minimal as possible.  Simply surround any topic you want to link to with angle brackets.  Natural Docs will keep track off all the topics and where they are defined, so you don’t need to use HTML-like syntax or remember what file anything is in.  Also, if the link can’t be resolved to anything, Natural Docs leaves the angle brackets in the output so if something wasn’t intended to be a link (such as #include <somefile.h>) it won’t be mangled.

Let's link to function <Multiply>.
+

Let’s link to function Multiply.

Links and topic names are case sensitive, regardless of whether the language is or not.

When linking to functions, it doesn’t matter if you include empty parenthesis or not.  Both <Function> and <Function()> will work.  However, if you documented the function with parameters as part of the name, you will need to include those parameters whenever linking to it.  It is recommended that you only include parameters in the topic name if you need to distinguish between two functions with the same name.

If the topic has a summary sentence, hovering over the link will give it to you as a tooltip.  If the topic has a prototype, that will be included as well.  You can try it above.

Scope

If a topic is considered part of a class, they can be linked to using any of the three most common class/member notations:  class.member, class::member, and class->member.  Natural Docs will not be confused by <class->member>.  Like in the language itself, if the topic you’re writing is in that class’ scope you can link to it simply as <member>.

If you have multi-level classes and packages, links can be relative as well.  So if you’re in Project::UI::Window::Base and you want to link to Project::UI::Button::Base, just using <Button::Base> will work.

Plurals and Possessives

To make the documentation easier to write and easier to read in the source file, you can include plurals and possessives inside the angle brackets.  In other words, you don’t have to use awkward syntax like <Object>s, although that’s supported as well.  You can simply write <Objects> and it will link to the symbol Object just fine.  It can handle any plural and/or possessive form you can throw at it.  I’m not kidding: Foxes, Fox’s, Foxes’, Children, Mice, Alumni, Indices, Amoebae, Teeth, just try to trip it up.

URLs and E-Mail

You can also link to URLs and e-mail addresses.  It will detect them automatically, but you can also put them in angle brackets if you like.

Visit <http://www.website.com> or send messages to
+email@address.com.
+

Visit http://www.website.com or send messages to em.nosp@m.ail@addre.nosp@m.ss.com.

E-mail addresses are protected in a way that should avoid spam crawlers.  Although the link above looks and acts like a regular link (try it) the HTML code actually looks like this:

<a href="#"
+ onClick="location.href='mai' + 'lto:' + 'em' + 'ail' + '@'
+          + 'addre' + 'ss.com'; return false;">
+    em<span style="display: none">.nosp@m.</span>ail
+    <span>@</span>
+    addre<span style="display: none">.nosp@m.</span>ss.com
+</a>
+
Formatting and Layout

You can apply additional formatting and layout to your Natural Docs content, all in ways that will appear very natural in the source code.

Paragraphs

You can break paragraphs by leaving blank lines between them.  So we have this in our content:

The first paragraph blah blah blah blah blah blah blah blah
+blah blah blah blah blah blah blah blah blah blah blah blah
+blah blah blah blah.
+
+The second paragraph blah blah blah blah blah blah blah
+blah blah blah blah blah blah blah blah blah blah blah blah
+blah blah blah blah.
+

and we get this in our output:

The first paragraph blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah.

The second paragraph blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah.

Bold and Underline

You can apply bold to a stretch of text by surrounding it with asterisks.  You can apply underlining by surrounding it with underscores instead.  With underlining, it doesn’t matter if you use an underscore for every space between words or not; they’ll be converted to spaces if you do.

Some *bold text* and some _underlined text_
+and yet _more_underlined_text_.
+

Some bold text and some underlined text and yet more underlined text.

Headings

You can add headings to your output just by ending a line with a colon and having a blank line above it.

Some text before the heading.
+
+Heading:
+Some text under the heading.
+

Some text before the heading.

Heading

Some text under the heading.

You must have a blank line above the heading or it will not work.  You can skip the blank after it but not before.

Bullet Lists

You can add bullet lists by starting a line with a dash, an asterisk, an o, or a plus.  Bullets can have blank lines between them if you want, and subsequent lines don’t have to be indented.  You end a list by skipping a line and doing something else.

- Bullet one.
+- Bullet two.
+  Bullet two continued.
+- Bullet three.
+
+Some text after the bullet list.
+
+o Spaced bullet one.
+
+o Spaced bullet two.
+Spaced bullet two continued.
+
+o Spaced bullet three.
+
+Some text after the spaced bullet list.
+
  • Bullet one.
  • Bullet two.  Bullet two continued.
  • Bullet three.

Some text after the bullet list.

  • Spaced bullet one.
  • Spaced bullet two.  Spaced bullet two continued.
  • Spaced bullet three.

Some text after the spaced bullet list.

Definition Lists

You can add a definition list by using the format below, specifically “text space dash space text”.  Like bullet lists, you can have blank lines between them if you want, subsequent lines don’t have to be indented, and you end the list by skipping a line and doing something else.

First  - This is the first item.
+Second - This is the second item.
+         This is more of the second item.
+Third  - This is the third item.
+This is more of the third item.
+
+Some text after the definition list.
+
FirstThis is the first item.
SecondThis is the second item.  This is more of the second item.
ThirdThis is the third item.  This is more of the third item.

Some text after the definition list.

Remember that with definition lists, if you’re using the plural form of the keywords each entry can be linked to as if it had its own topic.

Code and Text Diagrams

You can add example code or text diagrams by starting each line with >, |, or :.  If you have a vertical line or text box with the comment, you must separate these symbols from it with a space.

: a = b + c;
+
+>   +-----+     +-----+
+>   |  A  | --> |  B  |
+>   +-----+     +-----+
+>                  |
+>               +-----+
+>               |  C  |
+>               +-----+
+
a = b + c;
+-----+     +-----+
|  A  | --> |  B  |
+-----+     +-----+
               |
            +-----+
            |  C  |
            +-----+

For long stretches, this may be too tedious.  You can start a code section by placing (start code) or just (code) alone on a line.  You end it with either (end code) or just (end).  You can’t put any other content on these lines.

(start code)
+
+if (x == 0) {
+   DoSomething();
+}
+
+return x;
+
+(end)
+
if (x == 0) {
   DoSomething();
}

return x;

You can also use example, diagram, or table instead of code.  Just use whatever’s appropriate.  Always flexible, it will accept begin for start and it will accept finish or done for end so you don’t have to remember the exact word.

Images

You can include images in your documentation by writing “(see filename)”.  If you put it alone on a line it will be embedded in place.

This is the first paragraph.
+
+(see logo.gif)
+
+This is the second paragraph.
+

This is the first paragraph.

This is the second paragraph.

If it’s not alone on a line the image will appear after the end of the paragraph, the text will become a link to it, and the file name will be used as a caption.

This is the first paragraph (see logo.gif)  This is
+more of the first paragraph.
+

This is the first paragraph (see logo)  This is more of the first paragraph.

logo

The image file names are relative to the source file the comment appears in or any directories specified with the -img command line option.  You can use relative paths like (see images/logo.gif) and (see ../images/logo.gif), but you cannot use absolute paths, URLs, or specify a file that’s not in a folder included by -i or -img.

Natural Docs supports gif, jpg, jpeg, png, and bmp files.

Page Titles

Natural Docs automatically determines the page title as follows:

  • If there’s only one topic in the file, that topic’s title becomes the page title.
  • Otherwise, if the first topic in the file is a class, section, or file, that topic’s title becomes the page title.
  • Otherwise, the file name becomes the page title.

This should be enough for most people.  However, if you don’t like the page title Natural Docs has chosen for you, add a “Title: [name]” comment to the top of the file to override it.  Title is a synonym of Section, so that will satisfy the second rule and make it the page title.

Summaries

Summaries are automatically generated for every file, class, and section.  You don’t have to do anything special to get them.

There are two things you may want to keep in mind when documenting your code so that the summaries are nicer.  The first is that they use the first sentence in the topic as the description, so long as it’s plain text and not something like a bullet list.  It will also appear in the tooltip whenever that topic is linked to.

The second is that you may want to manually add group topics to divide long lists and make the summaries easier to navigate.  Natural Docs will automatically group them by type if you do not, but sometimes you want to be more specific.  You don’t need to provide a description, just adding a “Group: [name]” comment is sufficient.  Note that once you manually add a group automatic grouping is completely turned off for that class.

Here’s an example summary.  Note that as before, when you hover over a link, you’ll get the prototype and summary line as a tooltip.

Summary
Example Class
A example class that does arithmetic with functions for people scared of operators.
Arithmetic Functions
Add
Adds two integers.
Subtract
Subtracts two integers.
Multiply
Multiplies two integers.
Divide
Divides two integers.
Comparison Functions
IsEqual
Returns whether two integers are equal.
Javadoc Compatibility

If you have full language support Natural Docs will also extract documentation from actual Javadoc comments, not just Natural Docs comments written with the Javadoc comment symbols.  This provides you with a good method of migrating to Natural Docs as you don’t have to convert all of your existing documentation.

/**
+ * Multiplies two integers.
+ *
+ * @param x The first integer.
+ * @param y The second integer.
+ * @return The two integers multiplied together.
+ * @see Divide
+ */
+

Multiply

int Multiply (int x,
int y)

Multiplies two integers.

Parameters

xThe first integer.
yThe second integer.

Returns

The two integers multiplied together.

See Also

Divide

While most Javadoc tags and simple HTML formatting are supported, Natural Docs is not a full Javadoc parser and may not support some advanced tags and HTML.  See this page for a list of what’s supported and what isn’t.

A source file can contain both Natural Docs and Javadoc comments.  However, you cannot mix the two within a single comment.  For example, you can’t use asterisks for bold in a @param line.  If a comment is written with the Javadoc comment symbols (repeat the last symbol of the first line once) doesn’t have a topic line (like “Function: Multiply”) and uses Javadoc tags (like @param) the comment is treated as Javadoc.  If any of those conditions aren’t true it’s treated as a Natural Docs comment.

Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/documenting/walkthrough.html b/docs/tool/Help/documenting/walkthrough.html new file mode 100644 index 00000000..7a638ed6 --- /dev/null +++ b/docs/tool/Help/documenting/walkthrough.html @@ -0,0 +1,180 @@ + + +Documenting Your Code - Walkthrough - Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Documenting Your Code
Our First Function · Classes and Scope · More Formatting
More on Linking · Extra Documentation · Abbreviated Syntax
Our First Function

So you downloaded Natural Docs, you figured out the command line, and now it’s time to start documenting your code.  Natural Docs tries to make this very straightforward and painless, so let’s just dive right in:

/*
+   Function: Multiply
+   Multiplies two integers and returns the result.
+*/
+int Multiply (int x, int y)
+   {  return x * y;  };
+

That’s all you need.  Run Natural Docs and here’s what appears in your output:

Multiply

int Multiply (int x,
int y)

Multiplies two integers and returns the result.

Okay, so that’s all you need, but probably not all you want.  After all, you’ve got some real functions to document, not little one-liners.  Here’s something more elaborate:

/*
+   Function: Multiply
+
+   Multiplies two integers.
+
+   Parameters:
+
+      x - The first integer.
+      y - The second integer.
+
+   Returns:
+
+      The two integers multiplied together.
+
+   See Also:
+
+      <Divide>
+*/
+int Multiply (int x, int y)
+   {  return x * y;  };
+

Multiply

int Multiply (int x,
int y)

Multiplies two integers.

Parameters

xThe first integer.
yThe second integer.

Returns

The two integers multiplied together.

See Also

Divide

int Add (int x,
int y)
Adds two integers.
int Subtract (int x,
int y)
Subtracts two integers.
int Multiply (int x,
int y)
Multiplies two integers.
int Divide (int x,
int y)
Divides two integers.
bool IsEqual (int x,
int y)
Returns whether two integers are equal.

Still not too scary, huh?  Notice the comments are just as readable as the output.  No tags littered about, and the structure is very natural.  You probably get it just by looking at it, but let’s go through the details anyway.

Function: Multiply
+

Every one of these comments you write (called topics) are going to start with a topic line in the format “keyword: title”.  There are a lot of keywords, but they’re exactly what you’d expect: Function, Class, Variable, etc.  There are also a lot of synonyms so instead of Function you could use Func, Procedure, Proc, Method, Constructor, etc.  It’s designed so you can just use whatever it is you’re describing without memorizing anything.  You can glance over the keyword list but you shouldn’t have to consult it very often.

The other part of the topic line is the title.  It should match whatever it is you’re documenting, in this case the function name Multiply.  Natural Docs is case sensitive even if your programming language isn’t, so make sure you match it closely or you might not get the prototype in your output, which is the little gray box.  You don’t need to include the parameters in the title.  In fact, it’s better if you don’t.

Parameters:
+
+Returns:
+
+See Also:
+

You can also define headings by skipping a line and ending the text with a colon.  If you’re used to other documentation systems you may think there’s only a handful of headings to choose from, but any text formatted this way will become one.  If you want a heading called Dependencies you can go right ahead and add it.

x - The first integer.
+y - The second integer.
+

This is what’s called a definition list.  You can use more than one line to finish the definition, as it won’t stop until you skip a line.

x - The first integer.
+y - The second integer with a long description.
+    This is still part of the description.
+
+This is a new paragraph because we skipped a line.
+

Indentation doesn’t matter either, so even if the second description line wasn’t indented to match the first, it would still be considered part of it.

<Divide>
+

This is how we link in Natural Docs, with angle brackets.  There will be a lot more to say about this later, but for now I’ll just show you something cool.  Hover over it in the output below:

Divide

You get that everywhere in your generated documentation.

Classes and Scope

So that’s good for our one function of questionable usefulness, but what if we have a whole class of questionable usefulness?  We can document the class and it’s members the same way we documented the individual function, with a Natural Docs comment right above each element.  We’ll go back to short descriptions to keep the example manageable.

/*
+   Class: Counter
+   A class that manages an incrementing counter.
+*/
+class Counter
+   {
+   public:
+
+      /*
+         Constructor: Counter
+         Initializes the object.
+      */
+      Counter()
+         {  value = 0;  };
+
+      /*
+         Function: Value
+         Returns the value of the counter.
+      */
+      int Value()
+         {  return value;  };
+
+      /*
+         Function: Increment
+         Adds one to the counter.
+      */
+      void Increment()
+         {  value++;  };
+
+   protected:
+
+      /*
+         Variable: value
+         The counter's value.
+      */
+      int value;
+   };
+

Everything’s the same, we just substituted Class and Variable for the Function keyword when it was appropriate.  We also used Constructor, but we could have just as easily used Function there too.  They’re both keywords for the same thing so it doesn’t matter.

Scope

Like the source code itself, Natural Docs topics have scope.  Value and Increment are seen as part of class Counter, just like they are in the code.  Why is this important?  Linking.  Linking from one topic to another has similar rules to how one function can call another.  Since Value is in the same class as Increment, it’s topic can link to it with just <Increment>.  However, linking to Increment from a different class would require <Counter.Increment> instead.  You can actually use any of the three most common class/member notations: <Counter.Increment>, <Counter::Increment>, and <Counter->Increment>.

If your programming language has full language support, the scope is determined by the code and applied automatically.  However, if you only have basic language support it follows these rules:

  • Any topic that appears under a Class topic (or anything that says Starts Scope) is part of that class.
  • Any topic that appears under a Section topic (or anything that says Ends Scope) is global again.
  • Any File topic (or anything that says Always Global) is global no matter what and doesn’t affect any other topics.

Chances are you would have written the same thing even if you didn’t know this and it would have just worked.  You usually won’t need to think about them at all.  However, it’s still good to be aware of them in case something doesn’t behave the way you expected it to.

You actually know enough to go start documenting now.  I know Mr. ScrollBar says there’s more on this page you can learn, but if you want to skip out early, you can.  Really.  I don’t mind.

More Formatting

Okay then.  On we go.

Paragraphs, Bold, and Underline

The syntax for these three is exactly what you would expect it to be.

*Bold text*
+
+_Underlined text_
+
+Paragraphs are broken by skipping lines.  So the two
+lines above each have their own paragraph, but these
+three lines are all part of the same one.
+

Bold text

Underlined text

Paragraphs are broken by skipping lines.  So the two lines above each have their own paragraph, but these three lines are all part of the same one.

When underlining multiple words, you can use an underscore for each space or only put them at the edges like we did above.  Both ways will work.

Bullet Lists

You can add bullet lists by starting a line with a dash, an asterisk, an o, or a plus.  Like definition lists, bullets can span multiple lines and indentation doesn’t matter.  To end a bullet you have to skip a line before doing something else.

- Bullet one.
+- Bullet two.
+  Bullet two continued.
+- Bullet three.
+
+Some text after the bullet list.
+
  • Bullet one.
  • Bullet two.  Bullet two continued.
  • Bullet three.

Some text after the bullet list.

Code and Text Diagrams

You can add example code or text diagrams by starting each line with >, |, or :.

> a = b + c;
+> b++;
+
a = b + c;
b++;

If you have a long stretch, you can use (start code) and (end) instead.

(start code)
+
+if (x == 0) {
+   DoSomething();
+}
+
+return x;
+
+(end)
+
if (x == 0) {
   DoSomething();
}

return x;

You can also use example, diagram, or table instead of code.  Just use whatever’s appropriate.

As I mentioned before, we don’t want you to worry about memorizing minor details, so in that spirit it will also accept begin for start and finish or done for end.  You can also write (end code) instead of just (end).

Images

You can include images in your documentation by writing “(see filename)”.  If you put it alone on a line it will be embedded in place, or if you put it in a paragraph it will appear after it using the file name as a caption.

This is the first paragraph.
+
+(see logo.gif)
+
+This is the second paragraph (see logo.gif)  This
+is more of the second paragraph.
+

This is the first paragraph.

This is the second paragraph (see logo)  This is more of the second paragraph.

logo

The image file names are relative to the source file the comment appears in, so if your file is C:\Project\SourceFile.cpp and your image is C:\Project\Images\Logo.gif, you would write (see Images/Logo.gif).  However, you can also specify image directories in the command line with -img, so if all your source files are in C:\Project\Source and all your images are in C:\Project\Images, you can put “-img C:\Project\Images” on the command line and just use (see logo.gif) again.

More on Linking

Yes, there’s still more to linking.  You can link to URLs and e-mail addresses, but in this case the angle brackets are optional.

Visit <http://www.website.com> or send messages to
+email@address.com.
+

Visit http://www.website.com or send messages to em.nosp@m.ail@addre.nosp@m.ss.com.

E-mail addresses are protected from spam crawlers.  They look and act like regular links (try it above) but you can see the actual HTML that’s generated for them here.

As for regular links, to help them fit into sentences easily you can actually include plurals and possessives inside the angle brackets.  In other words, you don’t have to use awkward syntax like <Object>s, although that’s supported as well.  You can simply write <Objects> and it will link to the symbol Object just fine.  It can handle any plural and/or possessive form you can throw at it.  I’m not kidding: Foxes, Fox’s, Foxes’, Children, Mice, Alumni, Indices, Amoebae, Teeth, just try to trip it up.

Extra Documentation

Sometimes you want to include documentation that doesn’t correspond directly to a code element.  Maybe you want to include license information or architecture notes.  There are two ways to do this.

Freestanding Topics

Just because most of the things you write will directly correspond to an element of your source code doesn’t mean they have to.  You can pick any of the available keywords and create a freestanding comment with it.  For example:

/*
+   Class: Counter
+   A class that manages an incrementing counter.
+*/
+class Counter
+   {
+   public:
+
+      /*
+         About: License
+         This file is licensed under the GPL.
+      */
+
+      /*
+         Constructor: Counter
+         Initializes the object.
+      */
+      Counter()
+         {  value = 0;  };
+   ...
+

The extra license topic will be added to the output just like the functions.

License

This file is licensed under the GPL.

Remember that because of scope, the License topic will actually be considered part of Counter the way it’s listed above.  You’d link to it from outside Counter with <Counter.License>.  That idea may take some getting used to, but if an extra topic only applies to one class that’s actually the most appropriate way to do it.  In this case it’s a license, so if it applies to the entire project instead you could put the comment above the class to make it global, just like moving a function there would.

Text Files

You can also add additional documentation with text files.  If you put a file with a .txt extension in your source tree and start it with a topic line, it’s contents will be treated the same as if it were in a comment in your source code.  That means you can define multiple topics within it, you can link between them and topics in your source code, and you can use all available formatting options.

Title: License
+
+This file is licensed under the GPL.
+
+I can link to <Counter> and <Counter.Increment>, and
+the documentation in that class can even link back
+with <License>.
+
+
+About: Second Topic
+
+I can create a *second* topic in here too, complete
+with formatting.
+

The thing some people forget though is that you must start it with a topic line, like “Title: License” above.  This is how Natural Docs tells it apart from regular text files.

Abbreviated Syntax

Here’s another useful thing you may want to know about.  Suppose you have a lot of little things to document, like constants.  Writing a separate topic for each one can be very tedious, no matter how much you compress it:

// Constant: COUNTER_NORMAL
+// Causes the counter to increment normally.
+#define COUNTER_NORMAL 0
+
+// Constant: COUNTER_ODD
+// Causes the counter to only increment in odd numbers.
+#define COUNTER_ODD 1
+
+// Constant: COUNTER_EVEN
+// Causes the counter to only increment in even numbers.
+#define COUNTER_EVEN 2
+

One thing you may have noticed in the keyword list is that they almost all have plural forms.  These are used to create what are called list topics.  You define a topic using a plural keyword, and then anything appearing in a definition list within it creates a linkable symbol as if they each had their own topic.  For example:

/*
+   Constants: Counter Modes
+
+   COUNTER_NORMAL - Causes the counter to increment normally.
+   COUNTER_ODD    - Causes the counter to only increment in odd numbers.
+   COUNTER_EVEN   - Causes the counter to only increment in even numbers.
+*/
+#define COUNTER_NORMAL 0
+#define COUNTER_ODD 1
+#define COUNTER_EVEN 2
+

I would now be able to write <COUNTER_ODD> and have it work the same as it would with the first example.

Using the enum or enumeration keyword is special because it automatically behaves in a similar manner.  This allows both the enum and its values to be documented in the same place.

/*
+   Enum: CounterMode
+
+   NORMAL - Causes the counter to increment normally.
+   ODD    - Causes the counter to only increment in odd numbers.
+   EVEN   - Causes the counter to only increment in even numbers.
+*/
+enum CounterMode { NORMAL, ODD, EVEN };
+

That’s it, you’re done with this walkthrough.  You should know enough now to make very good use of Natural Docs.  If you still want to know more, you can look in the reference for some of the smaller details we may have skipped over.  Also, look at the Customizing pages on this web site for even more you can do.

Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/example/Default.css b/docs/tool/Help/example/Default.css new file mode 100644 index 00000000..7318fdcd --- /dev/null +++ b/docs/tool/Help/example/Default.css @@ -0,0 +1,528 @@ +/* + IMPORTANT: If you're editing this file in the output directory of one of + your projects, your changes will be overwritten the next time you run + Natural Docs. Instead, copy this file to your project directory, make your + changes, and you can use it with -s. Even better would be to make a CSS + file in your project directory with only your changes, which you can then + use with -s [original style] [your changes]. + + On the other hand, if you're editing this file in the Natural Docs styles + directory, the changes will automatically be applied to all your projects + that use this style the next time Natural Docs is run on them. + + This file is part of Natural Docs, which is Copyright © 2003-2004 Greg Valure + Natural Docs is licensed under the GPL +*/ + +body { + font-family: Verdana, Arial, sans-serif; + color: #000000; + margin: 0px; padding: 0px } + +body.UnframedPage { + background-color: #E8E8E8 } + + +a:link, +a:visited { color: #900000; text-decoration: none } +a:hover { color: #900000; text-decoration: underline } +a:active { color: #FF0000; text-decoration: underline } + +td { + vertical-align: top } + +/* + Comment out this line to use web-style paragraphs (blank line between + paragraphs, no indent) instead of print-style paragraphs (no blank line, + indented.) +*/ +p { + text-indent: 5ex; margin: 0 } + + +/* Can't use something like display: none or it won't break. */ +.HB { + font-size: 1px } + + + + +body.FramedMenuPage, +.MenuSection { + font-size: 9pt; + background-color: #E8E8E8; + padding: 10px 0 0 0 } + +.MenuSection { + width: 27ex } + + + .MTitle { + font-size: 16pt; font-weight: bold; font-variant: small-caps; + text-align: center; + padding: 5px 10px 15px 10px; + border-bottom: 1px dotted #000000; + margin-bottom: 15px } + + .MSubTitle { + font-size: 9pt; font-weight: normal; font-variant: normal; + margin-top: 1ex; margin-bottom: 5px } + + + .MEntry a:link, + .MEntry a:hover, + .MEntry a:visited { color: #606060; margin-right: 0 } + .MEntry a:active { color: #A00000; margin-right: 0 } + + + .MGroup { + font-variant: small-caps; font-weight: bold; + margin: 1em 0 1em 10px } + + /* Konqueror just can't do margins. */ + .KHTML .MGroup { + margin-bottom: 0; padding-bottom: 1em } + + .MGroupContent { + font-variant: normal; font-weight: normal } + + .MGroup a:link, + .MGroup a:hover, + .MGroup a:visited { color: #545454; margin-right: 10px } + .MGroup a:active { color: #A00000; margin-right: 10px } + + + .MFile, + .MText, + .MLink, + .MIndex { + padding: 1px 17px 2px 10px; + margin: .25em 0 .25em 0 } + + .MText { + font-size: 8pt; font-style: italic } + + .MLink { + font-style: italic } + + #MSelected { + color: #000000; background-color: #FFFFFF; + /* Replace padding with border. */ + padding: 0 10px 0 10px; + border-width: 1px 2px 2px 0; border-style: solid; border-color: #000000; + margin-right: 5px } + + /* Close off the left side when its in a group. */ + .MGroup #MSelected { + padding-left: 9px; border-left-width: 1px } + + /* A treat for Mozilla users. Blatantly non-standard. Will be replaced with CSS 3 attributes when finalized/supported. */ + .Gecko #MSelected { + -moz-border-radius-topright: 10px; + -moz-border-radius-bottomright: 10px } + .Gecko .MGroup #MSelected { + -moz-border-radius-topleft: 10px; + -moz-border-radius-bottomleft: 10px } + + + + +body.FramedContentPage, +.ContentSection { + background-color: #FFFFFF; + padding-bottom: 15px } + +.ContentSection { + border-width: 0 0 1px 1px; border-style: solid; border-color: #000000 } + + + .CTopic { + font-size: 10pt; + /* This should be a margin but Konq 3.1.1 sucks. */ + padding-bottom: 3em } + + + .CTitle { + font-size: 12pt; font-weight: bold; + border-width: 0 0 1px 0; border-style: solid; border-color: #A0A0A0; + margin: 0 15px .5em 15px } + + .CGroup .CTitle { + font-size: 16pt; font-variant: small-caps; + padding-left: 15px; padding-right: 15px; + border-width: 0 0 2px 0; border-color: #000000; + margin-left: 0; margin-right: 0 } + + .CClass .CTitle, + .CInterface .CTitle, + .CDatabase .CTitle, + .CDatabaseTable .CTitle, + .CSection .CTitle { + font-size: 18pt; + color: #FFFFFF; background-color: #A0A0A0; + padding: 10px 15px 10px 15px; + border-width: 2px 0; border-color: #000000; + margin-left: 0; margin-right: 0 } + + #MainTopic .CTitle { + font-size: 20pt; + color: #FFFFFF; background-color: #7070C0; + padding: 10px 15px 10px 15px; + border-width: 0 0 3px 0; border-color: #000000; + margin-left: 0; margin-right: 0 } + + .CBody { + margin-left: 15px; margin-right: 15px } + + + .CToolTip { + position: absolute; visibility: hidden; + left: 0; top: 0; max-width: 50%; + background-color: #FFFFE0; + padding: 5px; + border-width: 1px 2px 2px 1px; border-style: solid; border-color: #000000; + font-size: 8pt } + + /* Opera 6 gives it a huge height otherwise. */ + .Opera6 .CTooltip, .Opera5 .CTooltip { + max-width: 100% } + + .CHeading { + font-weight: bold; font-size: 10pt; + margin-top: 1.5em; margin-bottom: .5em } + + .CCode { + font: 10pt "Courier New", Courier, monospace; + overflow: auto; + } + + .CBulletList { + /* I don't know why CBody's margin doesn't apply, but it's consistent across browsers so whatever. + Reapply it here as padding. */ + padding-left: 15px; padding-right: 15px; + margin: .5em 5ex .5em 5ex; + } + + .CDescriptionList { + margin: .5em 5ex 0 5ex } + + /* IE 4 and Konqueror always makes it too long. */ + .IE4 .CDescriptionList, + .KHTML .CDescriptionList { + width: 85% } + + .CDLEntry { + font: 10pt "Courier New", Courier, monospace; color: #808080; + padding-bottom: .25em; + white-space: nowrap } + + .CDLDescription { + font-size: 10pt; /* For browsers that don't inherit correctly, like Opera 5. */ + padding-bottom: .5em; padding-left: 5ex } + + .CTopic img { + text-align: center; + display: block; + margin: 1em auto; + } + .CImageCaption { + font-variant: small-caps; + font-size: 8pt; + color: #808080; + text-align: center; + position: relative; + top: 1em; + } + + .CImageLink { + color: #808080; + font-style: italic; + } + a.CImageLink:link, + a.CImageLink:visited, + a.CImageLink:hover { color: #808080 } + + + +.Prototype { + font: 10pt "Courier New", Courier, monospace; + padding: 5px 3ex; + border-width: 1px; border-style: solid; + margin: 0 5ex 1.5em 5ex; + } + + .Prototype td { + font-size: 10pt; + } + + .PDefaultValue, + .PTypePrefix { + color: #8F8F8F; + } + .PTypePrefix { + text-align: right; + } + + .IE .Prototype table { + padding: 0; + } + + .CFunction .Prototype { + background-color: #F4F4F4; border-color: #D0D0D0 } + .CProperty .Prototype { + background-color: #F4F4FF; border-color: #C0C0E8 } + .CVariable .Prototype { + background-color: #FFFFF0; border-color: #E0E0A0 } + + .CDatabaseIndex .Prototype, + .CConstant .Prototype { + background-color: #D0D0D0; border-color: #000000 } + .CType .Prototype { + background-color: #FFF8F8; border-color: #E8C8C8 } + .CDatabaseTrigger .Prototype, + .CEvent .Prototype, + .CDelegate .Prototype { + background-color: #F0FCF0; border-color: #B8E4B8 } + + .CToolTip .Prototype { + margin: 0 0 .5em 0; + white-space: nowrap; + } + + + + + +.Summary { + margin: 1.5em 5ex 0 5ex } + + .STitle { + font-size: 12pt; font-weight: bold; + margin-bottom: .5em } + + + .SBorder { + background-color: #FFFFF0; + padding: 15px; + border: 1px solid #C0C060 } + + /* Let's observe the evolution of IE's brokeness, shall we? + IE 4 always makes them too long, there's no way around it. */ + .IE4 .SBorder { + width: 85% } + /* IE 5 will make them too long unless you set the width to 100%. Isn't this implied for a div? */ + .IE5 .SBorder { + width: 100% } + /* IE 6 behaves like 5 when it's in a frame, but without frames it will be correct without a width or slightly too long + (but not enough to scroll) with a width. This arbitrary weirdness simply astounds me. */ + body.FramedContentPage .IE6 .SBorder { + width: 100% } + + /* A treat for Mozilla users. Blatantly non-standard. Will be replaced with CSS 3 attributes when finalized/supported. */ + .Gecko .SBorder { + -moz-border-radius: 20px } + + + .STable { + font-size: 9pt; width: 100% } + + .SEntrySize { + width: 30% } + .SDescriptionSize { + width: 70% } + + + .SMarked { + background-color: #F8F8D8 } + + + .SEntry .SIndent1 { + margin-left: 1.5ex } + .SEntry .SIndent2 { + margin-left: 3ex } + .SEntry .SIndent3 { + margin-left: 4.5ex } + .SEntry .SIndent4 { + margin-left: 6ex } + .SEntry .SIndent5 { + margin-left: 7.5ex } + + .SDescription { + padding-left: 3ex } + + .SDescription a { color: #800000} + .SDescription a:active { color: #A00000 } + + + .SGroup { + margin-top: .5em; margin-bottom: .25em } + + .SGroup .SEntry { + font-weight: bold; font-variant: small-caps } + + .SGroup .SEntry a { color: #800000 } + .SGroup .SEntry a:active { color: #F00000 } + + + .SMain .SEntry, + .SClass .SEntry, + .SDatabase .SEntry, + .SDatabaseTable .SEntry, + .SSection .SEntry { + font-weight: bold; font-size: 10pt; + margin-bottom: .25em } + + .SClass, + .SDatabase, + .SDatabaseTable, + .SSection { + margin-top: 1em } + + .SMain .SEntry a, + .SClass .SEntry a, + .SDatabase .SEntry a, + .SDatabaseTable .SEntry a, + .SSection .SEntry a { color: #000000 } + + .SMain .SEntry a:active, + .SClass .SEntry a:active, + .SDatabase .SEntry a:active, + .SDatabaseTable .SEntry a:active, + .SSection .SEntry a:active { color: #A00000 } + + + + + +.ClassHierarchy { + margin: 0 15px 1em 15px } + + .CHEntry { + border-width: 1px 2px 2px 1px; border-style: solid; border-color: #A0A0A0; + margin-bottom: 3px; + padding: 2px 2ex; + font-size: 10pt; + background-color: #F4F4F4; color: #606060; + } + + .Gecko .CHEntry { + -moz-border-radius: 4px; + } + + .CHCurrent .CHEntry { + font-weight: bold; + border-color: #000000; + color: #000000; + } + + .CHChildNote .CHEntry { + font-style: italic; + font-size: 8pt; + } + + .CHIndent { + margin-left: 3ex; + } + + .CHEntry a:link, + .CHEntry a:visited, + .CHEntry a:hover { + color: #606060; + } + .CHEntry a:active { + color: #800000; + } + + + + + +body.FramedIndexPage, +.IndexSection { + background-color: #FFFFFF; + font-size: 10pt; + padding: 15px } + +.IndexSection { + border-width: 0 0 1px 1px; border-style: solid; border-color: #000000 } + + .IPageTitle { + font-size: 20pt; font-weight: bold; + color: #FFFFFF; background-color: #7070C0; + padding: 10px 15px 10px 15px; + border-width: 0 0 3px 0; border-color: #000000; border-style: solid; + margin: -15px -15px 0 -15px } + + .INavigationBar { + text-align: center; + background-color: #FFFFF0; + padding: 5px; + border-bottom: solid 1px black; + margin: 0 -15px 15px -15px } + + .INavigationBar a { + font-weight: bold } + + .IHeading { + font-size: 16pt; font-weight: bold; + padding: 2.5em 0 .5em 0; + text-align: center; + width: 3.5ex; + } + #IFirstHeading { + padding-top: 0; + } + + .IEntry { + padding-left: 1ex; } + + .ISubIndex { + padding-left: 3ex; padding-bottom: .5em } + + /* While it may cause some entries to look like links when they aren't, I found it's much easier to read the + index if everything's the same color. */ + .ISymbol { + font-weight: bold; color: #900000 } + + .ISymbolPrefix { + text-align: right; + color: #C47C7C; + background-color: #F8F8F8; + border-right: 3px solid #E0E0E0; + border-left: 1px solid #E0E0E0; + padding: 0 1px 0 2px; + } + #IFirstSymbolPrefix { + border-top: 1px solid #E0E0E0; + } + #ILastSymbolPrefix { + border-bottom: 1px solid #E0E0E0; + } + #IOnlySymbolPrefix { + border-top: 1px solid #E0E0E0; + border-bottom: 1px solid #E0E0E0; + } + + a.IParent, + a.IFile { + display: block; + } + + + + +.Footer { + font-size: 8pt; color: #909090 } + +body.UnframedPage .Footer { + text-align: right; + margin: 2px } + +body.FramedMenuPage .Footer { + text-align: center; + margin: 5em 10px 0 10px} + + .Footer a:link, + .Footer a:hover, + .Footer a:visited { color: #909090 } + .Footer a:active { color: #A00000 } diff --git a/docs/tool/Help/example/NaturalDocs.js b/docs/tool/Help/example/NaturalDocs.js new file mode 100644 index 00000000..2af84cf5 --- /dev/null +++ b/docs/tool/Help/example/NaturalDocs.js @@ -0,0 +1,204 @@ + +// +// Browser Styles +// ____________________________________________________________________________ + +var agt=navigator.userAgent.toLowerCase(); +var browserType; +var browserVer; + +if (agt.indexOf("opera") != -1) + { + browserType = "Opera"; + + if (agt.indexOf("opera 5") != -1 || agt.indexOf("opera/5") != -1) + { browserVer = "Opera5"; } + else if (agt.indexOf("opera 6") != -1 || agt.indexOf("opera/6") != -1) + { browserVer = "Opera6"; } + else if (agt.indexOf("opera 7") != -1 || agt.indexOf("opera/7") != -1) + { browserVer = "Opera7"; } + } + +else if (agt.indexOf("khtml") != -1 || agt.indexOf("konq") != -1 || agt.indexOf("safari") != -1) + { + browserType = "KHTML"; + } + +else if (agt.indexOf("msie") != -1) + { + browserType = "IE"; + + if (agt.indexOf("msie 4") != -1) + { browserVer = "IE4"; } + else if (agt.indexOf("msie 5") != -1) + { browserVer = "IE5"; } + else if (agt.indexOf("msie 6") != -1) + { browserVer = "IE6"; } + } + +else if (agt.indexOf("gecko") != -1) + { + browserType = "Gecko"; + } + +// Opera already taken care of. +else if (agt.indexOf("mozilla") != -1 && agt.indexOf("compatible") == -1 && agt.indexOf("spoofer") == -1 && + agt.indexOf("webtv") == -1 && agt.indexOf("hotjava") == -1) + { + browserType = "Netscape"; + + if (agt.indexOf("mozilla/4") != -1) + { browserVer = "Netscape4"; } + } + + +// +// Menu +// ____________________________________________________________________________ + + +function ToggleMenu(id) + { + if (!window.document.getElementById) + { return; }; + + var display = window.document.getElementById(id).style.display; + + if (display == "none") + { display = "block"; } + else + { display = "none"; } + + window.document.getElementById(id).style.display = display; + } + + +// +// Tooltips +// ____________________________________________________________________________ + + +var tooltipTimer = 0; + +function ShowTip(event, tooltipID, linkID) + { + if (tooltipTimer) + { clearTimeout(tooltipTimer); }; + + var docX = event.clientX + window.pageXOffset; + var docY = event.clientY + window.pageYOffset; + + var showCommand = "ReallyShowTip('" + tooltipID + "', '" + linkID + "', " + docX + ", " + docY + ")"; + + // KHTML cant handle showing on a timer right now. + + if (browserType != "KHTML") + { tooltipTimer = setTimeout(showCommand, 1000); } + else + { eval(showCommand); }; + } + +function ReallyShowTip(tooltipID, linkID, docX, docY) + { + tooltipTimer = 0; + + var tooltip; + var link; + + if (document.getElementById) + { + tooltip = document.getElementById(tooltipID); + link = document.getElementById(linkID); + } + else if (document.all) + { + tooltip = eval("document.all['" + tooltipID + "']"); + link = eval("document.all['" + linkID + "']"); + } + + if (tooltip) + { + var left = 0; + var top = 0; + + // Not everything supports offsetTop/Left/Width, and some, like Konqueror and Opera 5, think they do but do it badly. + + if (link && link.offsetWidth != null && browserType != "KHTML" && browserVer != "Opera5") + { + var item = link; + while (item != document.body) + { + left += item.offsetLeft; + item = item.offsetParent; + } + + item = link; + while (item != document.body) + { + top += item.offsetTop; + item = item.offsetParent; + } + top += link.offsetHeight; + } + + // The fallback method is to use the mouse X and Y relative to the document. We use a separate if and test if its a number + // in case some browser snuck through the above if statement but didn't support everything. + + if (!isFinite(top) || top == 0) + { + left = docX; + top = docY; + } + + // Some spacing to get it out from under the cursor. + + top += 10; + + // Make sure the tooltip doesnt get smushed by being too close to the edge, or in some browsers, go off the edge of the + // page. We do it here because Konqueror does get offsetWidth right even if it doesnt get the positioning right. + + if (tooltip.offsetWidth != null) + { + var width = tooltip.offsetWidth; + var docWidth = document.body.clientWidth; + + if (left + width > docWidth) + { left = docWidth - width - 1; } + } + + // Opera 5 chokes on the px extension, so it can use the Microsoft one instead. + + if (tooltip.style.left != null && browserVer != "Opera5") + { + tooltip.style.left = left + "px"; + tooltip.style.top = top + "px"; + } + else if (tooltip.style.pixelLeft != null) + { + tooltip.style.pixelLeft = left; + tooltip.style.pixelTop = top; + } + + tooltip.style.visibility = "visible"; + } + } + +function HideTip(tooltipID) + { + if (tooltipTimer) + { + clearTimeout(tooltipTimer); + tooltipTimer = 0; + } + + var tooltip; + + if (document.getElementById) + { tooltip = document.getElementById(tooltipID); } + else if (document.all) + { tooltip = eval("document.all['" + tooltipID + "']"); } + + if (tooltip) + { tooltip.style.visibility = "hidden"; } + } + diff --git a/docs/tool/Help/examples.css b/docs/tool/Help/examples.css new file mode 100644 index 00000000..f61d06b6 --- /dev/null +++ b/docs/tool/Help/examples.css @@ -0,0 +1,90 @@ +@import URL(example/Default.css); + + +.NDContent { + color: #000000; background-color: #FFFFFF; + padding: 15px 0; + border-style: solid; + border-width: 1px 3px 3px 1px; + border-color: #c0c0c0 #808080 #808080 #c0c0c0; + margin: 1em 5ex; + -moz-border-radius: 12px; + } + + .NDContent p, + .NDContent li, + .NDContent td, + .NDMenu td, + .NDSummary td, + .NDIndex td { + font-size: 10pt; + line-height: normal; + } + .NDContent .CTopic { + padding-bottom: 0; + } + .Prototype td { + font: 10pt Courier New, monospace; + } + .NDIndex .IHeading { + font-size: 16pt; + } + + +.NDMenu { + font: 9pt Verdana, Arial, sans-serif; + color: #000000; background-color: #E8E8E8; + width: 27ex; + padding: 10px 0; + border-style: solid; + border-width: 1px 3px 3px 1px; + border-color: #808080 #606060 #606060 #808080; + margin: 1em 0 1em 5ex; + -moz-border-radius: 12px; + } + + +.NDFooter { + font: 8pt Verdana, Arial, sans-serif; + color: #909090; background-color: #E8E8E8; + border-style: solid; + border-width: 1px 3px 3px 1px; + border-color: #808080 #606060 #606060 #808080; + margin: 1em 0 1em 5ex; + -moz-border-radius: 12px; + } +.NDFooter td { + font-size: 8pt; + padding: 0 2ex; + } + + .NDFooter a:link, + .NDFooter a:hover, + .NDFooter a:visited { color: #909090 } + .NDFooter a:active { color: #A00000 } + + +.NDSummary { + padding: 15px; + border-style: solid; + border-width: 1px 3px 3px 1px; + border-color: #c0c0c0 #808080 #808080 #c0c0c0; + margin: 1em 5ex; + -moz-border-radius: 12px; + } + + .NDSummary .Summary { + margin-top: 0; + } + + +.NDIndex { + color: #000000; background-color: #FFFFFF; + padding: 15px; + border-style: solid; + border-width: 1px 3px 3px 1px; + border-color: #c0c0c0 #808080 #808080 #c0c0c0; + margin: 1em 5ex; + -moz-border-radius: 12px; + } + diff --git a/docs/tool/Help/images/header/background.png b/docs/tool/Help/images/header/background.png new file mode 100644 index 00000000..09a2ea46 Binary files /dev/null and b/docs/tool/Help/images/header/background.png differ diff --git a/docs/tool/Help/images/header/leftside.png b/docs/tool/Help/images/header/leftside.png new file mode 100644 index 00000000..7d093865 Binary files /dev/null and b/docs/tool/Help/images/header/leftside.png differ diff --git a/docs/tool/Help/images/header/logo.png b/docs/tool/Help/images/header/logo.png new file mode 100644 index 00000000..9317a1b6 Binary files /dev/null and b/docs/tool/Help/images/header/logo.png differ diff --git a/docs/tool/Help/images/header/overbody.png b/docs/tool/Help/images/header/overbody.png new file mode 100644 index 00000000..6b86af15 Binary files /dev/null and b/docs/tool/Help/images/header/overbody.png differ diff --git a/docs/tool/Help/images/header/overbodybg.png b/docs/tool/Help/images/header/overbodybg.png new file mode 100644 index 00000000..b4284ec1 Binary files /dev/null and b/docs/tool/Help/images/header/overbodybg.png differ diff --git a/docs/tool/Help/images/header/overleftmargin.png b/docs/tool/Help/images/header/overleftmargin.png new file mode 100644 index 00000000..3d02af7f Binary files /dev/null and b/docs/tool/Help/images/header/overleftmargin.png differ diff --git a/docs/tool/Help/images/header/overmenu.png b/docs/tool/Help/images/header/overmenu.png new file mode 100644 index 00000000..d720d986 Binary files /dev/null and b/docs/tool/Help/images/header/overmenu.png differ diff --git a/docs/tool/Help/images/header/overmenubg.png b/docs/tool/Help/images/header/overmenubg.png new file mode 100644 index 00000000..69339d8c Binary files /dev/null and b/docs/tool/Help/images/header/overmenubg.png differ diff --git a/docs/tool/Help/images/header/rightside.png b/docs/tool/Help/images/header/rightside.png new file mode 100644 index 00000000..f8ef976a Binary files /dev/null and b/docs/tool/Help/images/header/rightside.png differ diff --git a/docs/tool/Help/images/logo.gif b/docs/tool/Help/images/logo.gif new file mode 100644 index 00000000..2fa571ee Binary files /dev/null and b/docs/tool/Help/images/logo.gif differ diff --git a/docs/tool/Help/images/menu/about.png b/docs/tool/Help/images/menu/about.png new file mode 100644 index 00000000..ca65ea4e Binary files /dev/null and b/docs/tool/Help/images/menu/about.png differ diff --git a/docs/tool/Help/images/menu/background.png b/docs/tool/Help/images/menu/background.png new file mode 100644 index 00000000..db8b557b Binary files /dev/null and b/docs/tool/Help/images/menu/background.png differ diff --git a/docs/tool/Help/images/menu/bottomleft.png b/docs/tool/Help/images/menu/bottomleft.png new file mode 100644 index 00000000..0f608c8b Binary files /dev/null and b/docs/tool/Help/images/menu/bottomleft.png differ diff --git a/docs/tool/Help/images/menu/bottomright.png b/docs/tool/Help/images/menu/bottomright.png new file mode 100644 index 00000000..10c9e029 Binary files /dev/null and b/docs/tool/Help/images/menu/bottomright.png differ diff --git a/docs/tool/Help/images/menu/community.png b/docs/tool/Help/images/menu/community.png new file mode 100644 index 00000000..0021013a Binary files /dev/null and b/docs/tool/Help/images/menu/community.png differ diff --git a/docs/tool/Help/images/menu/customizing.png b/docs/tool/Help/images/menu/customizing.png new file mode 100644 index 00000000..d56d25b3 Binary files /dev/null and b/docs/tool/Help/images/menu/customizing.png differ diff --git a/docs/tool/Help/images/menu/using.png b/docs/tool/Help/images/menu/using.png new file mode 100644 index 00000000..1de988d2 Binary files /dev/null and b/docs/tool/Help/images/menu/using.png differ diff --git a/docs/tool/Help/index.html b/docs/tool/Help/index.html new file mode 100644 index 00000000..8a5fe021 --- /dev/null +++ b/docs/tool/Help/index.html @@ -0,0 +1,9 @@ + + +Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Version 1.4

This is the Natural Docs help file, a subset of the documentation available at the web site.  Everything you need is on the menu to the left.

Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/javascript/BrowserStyles.js b/docs/tool/Help/javascript/BrowserStyles.js new file mode 100644 index 00000000..71666418 --- /dev/null +++ b/docs/tool/Help/javascript/BrowserStyles.js @@ -0,0 +1,77 @@ + +// +// Browser Styles +// ____________________________________________________________________________ + +var agt=navigator.userAgent.toLowerCase(); +var browserType; +var browserVer; + +if (agt.indexOf("opera") != -1) + { + browserType = "Opera"; + + if (agt.indexOf("opera 5") != -1 || agt.indexOf("opera/5") != -1) + { browserVer = "Opera5"; } + else if (agt.indexOf("opera 6") != -1 || agt.indexOf("opera/6") != -1) + { browserVer = "Opera6"; } + else if (agt.indexOf("opera 7") != -1 || agt.indexOf("opera/7") != -1) + { browserVer = "Opera7"; } + } + +else if (agt.indexOf("khtml") != -1 || agt.indexOf("konq") != -1 || agt.indexOf("safari") != -1) + { + browserType = "KHTML"; + } + +else if (agt.indexOf("msie") != -1) + { + browserType = "IE"; + + if (agt.indexOf("msie 4") != -1) + { browserVer = "IE4"; } + else if (agt.indexOf("msie 5") != -1) + { browserVer = "IE5"; } + else if (agt.indexOf("msie 6") != -1) + { browserVer = "IE6"; } + else if (agt.indexOf("msie 7") != -1) + { browserVer = "IE7"; } + } + +else if (agt.indexOf("gecko") != -1) + { + browserType = "Gecko"; + } + +// Opera already taken care of. +else if (agt.indexOf("mozilla") != -1 && agt.indexOf("compatible") == -1 && agt.indexOf("spoofer") == -1 && + agt.indexOf("webtv") == -1 && agt.indexOf("hotjava") == -1) + { + browserType = "Netscape"; + + if (agt.indexOf("mozilla/4") != -1) + { browserVer = "Netscape4"; } + } + + +function OpeningBrowserTags() + { + if (browserType) + { + document.write('
'); + + if (browserVer) + { document.write('
'); } + } + }; + +function ClosingBrowserTags() + { + if (browserType) + { + document.write('
'); + + if (browserVer) + { document.write('
'); } + } + }; diff --git a/docs/tool/Help/javascript/PNGHandling.js b/docs/tool/Help/javascript/PNGHandling.js new file mode 100644 index 00000000..ab47a538 --- /dev/null +++ b/docs/tool/Help/javascript/PNGHandling.js @@ -0,0 +1,72 @@ +// Parts derived from: +// Opacity Displayer, Version 1.0 +// Copyright Michael Lovitt, 6/2002. +// Distribute freely, but please leave this notice intact. +// http://www.alistapart.com/articles/pngopacity/ + +// Parts derived from: +// Natural Docs +// Copyright (C) 2003-2004 Greg Valure +// http://www.naturaldocs.org/ + + +var pngTransform; +var pngNormal; + +var agt=navigator.userAgent.toLowerCase(); + +if (agt.indexOf("opera") != -1) + { + if ( (agt.indexOf("opera 5") != -1 || agt.indexOf("opera/5") != -1) && + agt.indexOf("mac") != -1) + { + pngNormal = 1; + } + else if (agt.indexOf("opera 6") != -1 || agt.indexOf("opera/6") != -1 || + agt.indexOf("opera 7") != -1 || agt.indexOf("opera/7") != -1) + { + pngNormal = 1; + } + } + +else if (agt.indexOf("msie") != -1) + { + if (agt.indexOf("msie 5.5") != -1 || agt.indexOf("msie 6") != -1) + { + if (agt.indexOf("mac") != -1) + { pngNormal = 1; } + else if (agt.indexOf("win") != -1) + { pngTransform = 1; }; + } + + else if (agt.indexOf("msie 5") != -1) + { + if (agt.indexOf("mac") != -1) + { pngNormal = 1; }; + } + + else if (agt.indexOf("msie 7") != -1) + { pngNormal = 1; } + } + +else if (agt.indexOf("gecko") != -1) + { + pngNormal = 1; + } + + +function PNGGIF(strPath, intWidth, intHeight, strAlt, strID) + { + if (pngTransform) + { + document.write('
'); + } + else if (pngNormal) + { + document.write(''+strAlt+''); + } + else + { + document.write(''+strAlt+''); + } + }; diff --git a/docs/tool/Help/keywords.html b/docs/tool/Help/keywords.html new file mode 100644 index 00000000..42c16c90 --- /dev/null +++ b/docs/tool/Help/keywords.html @@ -0,0 +1,38 @@ + + +Natural Docs Topics and Keywords + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Topics and Keywords
General Topics · Code Topics · Database Topics · Miscellaneous Topics

Keywords are not case sensitive and are interchangable within their topic type.  The plural forms denote list topics where every item in its definition lists are treated like they have their own topic.

General Topics
Generic
topictopics
aboutlist
Section
Ends Scope
section
title
Group
group
File
Always Global
filefiles
programprograms
scriptscripts
documentdocuments
docdocs
headerheaders
Code Topics
Class
Starts Scope
classclasses
structurestructures
structstructs
packagepackages
namespacenamespaces
Interface
Starts Scope
interfaceinterfaces
Type
typetypes
typedeftypedefs
Constant
constantconstants
constconsts
Enumeration
Topic indexed under Types
Members indexed under Constants
enumerationenumerations
enumenums
Function
List topics break apart
functionfunctions
funcfuncs
procedureprocedures
procprocs
routineroutines
subroutinesubroutines
subsubs
methodmethods
callbackcallbacks
constructorconstructors
destructordestructors
operatoroperators
Property
propertyproperties
propprops
Event
eventevents
Delegate
delegatedelegates
Macro
macromacros
definedefines
defdefs
Variable
variablevariables
varvars
integerintegers
intints
uintuints
longlongs
ulongulongs
shortshorts
ushortushorts
bytebytes
ubyteubytes
sbytesbytes
floatfloats
doubledoubles
realreals
decimaldecimals
scalarscalars
arrayarrays
arrayrefarrayrefs
hashhashes
hashrefhashrefs
boolbools
booleanbooleans
flagflags
bitbits
bitfieldbitfields
fieldfields
pointerpointers
ptrptrs
referencereferences
refrefs
objectobjects
objobjs
charactercharacters
wcharacterwcharacters
charchars
wcharwchars
stringstrings
wstringwstrings
strstrs
wstrwstrs
handlehandles
Database Topics
Database
databasedatabases
dbdbs
Database Table
Starts Scope
tabletables
database tabledatabase tables
db tabledb tables
Database View
Starts Scope
viewviews
database viewdatabase views
db viewdb views
Database Cursor
cursorcursors
database cursordatabase cursors
db cursordb cursors
Database Index
indexindexes
indices
database indexdatabase indexes
database indices
db indexdb indexes
db indices
keykeys
database keydatabase keys
db keydb keys
primary keyprimary keys
database primary keydatabase primary keys
db primary keydb primary keys
Database Trigger
triggertriggers
database triggerdatabase triggers
db triggerdb triggers
Miscellaneous Topics
Cookie
Always global
cookiecookies
Build Target
targettargets
build targetbuild targets
Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/languages.html b/docs/tool/Help/languages.html new file mode 100644 index 00000000..cab7e6fe --- /dev/null +++ b/docs/tool/Help/languages.html @@ -0,0 +1,32 @@ + + +Natural Docs Language Support + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Language Support
Full Language Support · Basic Language Support
Full Language Support

The following languages have full language support, which means you get:

Full code documentation.  All functions, variables, and classes will appear in the output regardless of whether you wrote anything for them.  This can be turned off with the -do command line option.

Inheritance diagrams.  They will appear in the output wherever appropriate.

Javadoc compatibility.  Natural Docs can read most Javadoc comments and include them in the output.  You can also write Natural Docs documentation without topic lines by using the Javadoc comment symbols.

Auto-scoping.  The class a topic is part of is determined by the source code rather than class and section topics.

  • C# (1.1, some 2.0)
  • Perl
  • ActionScript (2 and 3)
Basic Language Support

The following languages have basic language support, which means you have:

Explicit documentation only.  Only things you write Natural Docs documentation for will appear in the output.

No inheritance diagrams.

Natural Docs comments only.  They also need to include a topic line.

Topic scoping.  The class a topic is part of is determined by the topic scoping rules.

  • C/C++
  • Java
  • PHP
  • Python
  • PL/SQL
  • Visual Basic
  • Pascal/Delphi
  • Ada
  • JavaScript
  • Ruby
  • Tcl
  • ColdFusion
  • Assembly
  • Fortran (free-format only)
  • R
  • Makefiles
  • Plain Text
  • Custom Languages
Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/menu.html b/docs/tool/Help/menu.html new file mode 100644 index 00000000..37c43654 --- /dev/null +++ b/docs/tool/Help/menu.html @@ -0,0 +1,79 @@ + + +Organizing the Menu - Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Organizing the Menu
Order and Titles · Grouping · Indexes and Search · Automatic Changes
Extras · Errors · Portability and Versioning Systems

Natural Docs creates a file called Menu.txt in your project directory that you can edit to organize the menu.  It normally takes care of this on its own, but you have the option of improving it manually if you want to.

Order and Titles

If you’ve never looked in it before, the menu file will have some comments explaining its syntax and a list like you see below.

File: ClassA  (ClassA.h)
+File: ClassB  (ClassB.h)
+File: Globals  (Globals.h)
+

The list gets turned into a menu that looks like this:

ClassA
ClassB
Globals

The lines are in the format “File: [title] ([filename])”.  When Natural Docs made the menu, it decided on its own what the title of each file should be and then put them in alphabetical order.  However, suppose we don’t want this.  We want Globals above the classes and we want spaces in the menu titles.  So we edit the file.

File: Globals  (Globals.h)
+File: Class A  (ClassA.h)
+File: Class B  (ClassB.h)
+

Run Natural Docs again and the menu is updated.

Globals
Class A
Class B

However, open the menu file again and you’ll see something interesting.

File: Globals  (Globals.h)
+File: Class A  (no auto-title, ClassA.h)
+File: Class B  (no auto-title, ClassB.h)
+

Natural Docs noticed that you changed a couple of the titles and added a no auto-title attribute to each one.  This tells it to never change them on it’s own in the future, so your changes won’t be lost.  You don’t have to worry about adding this, Natural Docs will always do it automatically.  However, to go back to automatic titles you’d have to manually remove it.

Grouping

This menu is good for our example, but in the real world they get much, much longer.  We can add groups to organize it further.  Natural Docs will create them automatically based on the each file’s directory, but once again you can improve it manually if that’s not good enough.

You can add groups as shown below.

File: Globals  (Globals.h)
+Group: Classes {
+   File: Class A  (no auto-title, ClassA.h)
+   File: Class B  (no auto-title, ClassB.h) }
+
Globals
Classes

You can also nest them inside each other.

File: Globals  (Globals.h)
+Group: Classes {
+   File: Class A  (no auto-title, ClassA.h)
+   Group: Nested Group {
+      File: Class B  (no auto-title, ClassB.h)  }
+   }
+
Globals
Classes

We’ll get rid of the nested group because it doesn’t make sense for our example.  Run Natural Docs, open up the menu file again and take a look.

File: Globals  (Globals.h)
+
+Group: Classes  {
+
+   File: Class A  (no auto-title, ClassA.h)
+   File: Class B  (no auto-title, ClassB.h)
+   }  # Group: Classes
+

Natural Docs reformatted it.  When you’re organizing the menu, you don’t have to worry about the indentation or otherwise keeping it neat.  The file is reformatted every time it changes, so you can make quick and dirty edits and Natural Docs will keep it readable.

Besides breaking up long lists, groups also serve another purpose.  Clicking on them will make it expand and collapse.  Go ahead and try it in the examples above.  When the menu gets too long its groups will start being collapsed by default, allowing easier navigation on large projects where it would just be impractical to show everything at once.

Indexes and Search

Natural Docs will automatically determine what indexes your project needs and add them to the menu.  Anything indexed will also be used for the search feature.  The entries will look like this:

Group: Index {
+
+   Index: Everything
+   Class Index: Classes
+   Function Index: Functions
+   }  # Group: Index
+

Like the file entries we saw before, you can rename them by editing the title and reorder them by cutting and pasting.  However, if you decide you don’t want a particular index to be generated, just delete its entry and it will go away.  Just like before, Natural Docs will detect this and add something new:

Don't Index: Functions
+

As with no auto-title, Natural Docs adds this automatically to make sure it doesn’t later undo your changes.

Automatic Changes

Natural Docs tries to manage the menu on its own as much as possible so you don’t have to worry about it.  This is just a peek into some of the things it does so you know what to expect.

You already saw that by default Natural Docs tries to guess what title should be for each file.  If you leave it this way, Natural Docs will always update the menu for you if the file’s content changes significantly enough to change its guess, such as if you rename the first class defined in it.  If you’d like to take advantage of this to define the menu title in each source file instead of in the menu itself, add a “Title: [title]” comment to the top of the file.

When you add and delete source files, Natural Docs will automatically add and remove them from the menu file.  When adding one it will look for the best group to put it in by directory.  If your grouping mirrors the source tree somewhat, this will be a lot more accurate.  Also, if the group it’s putting it in is alphabetized, Natural Docs will put it in the correct place to maintain that alphabetization.  In fact, even if an existing file’s automatic title changes, it will change it’s position to make sure a previously alphabetized group stays that way.

There are exceptions in alphabetization for the indexes.  If a group only contains indexes, it can be the last item on the menu or in its parent group without making it count as unsorted.  Also, within groups that only contain indexes, the general index can be first, also without making the group count as unsorted.

Finally, if Natural Docs adds some files to a group that causes it to become too long, it will attempt to sub-group it based on directory.  However, it will only do this when its adding files on its own, so you don’t have to worry about it constantly messing up your groups.  Since new files aren’t added to a project that often, if you change the menu manually it should stay that way for quite some time.

Extras

There’s more you can do with the menu than just renaming and reorganizing its entries.  Natural Docs has a few extras you can add to it as well.

Title and Subtitle

You can add a title and subtitle to your menu.

Title: My Project
+SubTitle: Something That Does Something
+
+File: Globals  (Globals.h)
+Group: Classes
+   File: Class A  (no auto-title, ClassA.h)
+   File: Class B  (no auto-title, ClassB.h)
+
My Project
Something That Does Something
Globals
Classes

In addition to adding the title to the menu, the Title tag will also change the HTML page titles from “Class A” to “Class A - My Project”, making bookmarks clearer.

Text and Web Links

You can also add arbitrary text and web links to your menu.

File: Globals  (Globals.h)
+Group: Classes  {
+   Text: I couldn't think of good names for these classes.
+   File: Class A  (no auto-title, ClassA.h)
+   File: Class B  (no auto-title, ClassB.h)
+   }
+Link: Built with Natural Docs  (http://www.naturaldocs.org)
+
Globals
Classes
Built with Natural Docs

Even though comments use the # character, adding an anchor to a link (such as “http://www.website.com/page.html#anchor”) will still work.

Footers

Finally, you can add a footer to all your pages, such as a copyright notice.  Natural Docs will change any (c)’s it finds into real copyright symbols.

Footer: Copyright (C) 2008 Me
+
Copyright © 2008 Me  ·  Generated by Natural Docs

You can also add a timestamp in any format you want.  The tokens you can use in building it are:

mOne or two digit month.January is “1”
mmAlways two digit month.January is “01”
monShort month word.January is “Jan”
monthLong month word.January is “January”
dOne or two digit day.1 is “1”
ddAlways two digit day.1 is “01”
dayDay with letter extension.1 is “1st”
yyTwo digit year.2008 is “08”
yyyyFour digit year.2008 is “2008”
yearFour digit year.2008 is “2008”

Everything else appears literally, so we can add:

Timestamp: Updated month day, year
+

and get:

Copyright © 2008 Me  ·  Updated January 1st, 2008  ·  Generated by Natural Docs
Errors

If there’s ever an error in the menu file, Natural Docs will tell you when it’s run.  It also adds a comment for each one in the menu file itself so that you can search for them in a text editor.

# There is an error in this file.  Search for ERROR to find it.
+
+File: Globals  (Globals.h)
+Group: Classes  {
+# ERROR: Txet is not a valid keyword.
+   Txet: I couldn't think of good names for these classes.
+   File: Class A  (no auto-title, ClassA.h)
+   File: Class B  (no auto-title, ClassB.h)
+   }
+

Remember that Natural Docs reformats the menu file whenever it’s run, so you only need to correct the error.  Natural Docs will remove the error comments on its own.

Portability and Versioning Systems

If you only use one input directory, all the files in the menu will have relative paths.  However, if you have more Natural Docs will use the absolute path instead.

This is not a problem.  The menu file can still be shared between machines even if they don’t keep the source tree in the exact same location.  As long as you have the same layout within the source tree and point to the same base directories in the command line, Natural Docs will be able to convert the paths automatically for the new machine.

However, if you’re putting the menu file in a versioning system like Subversion or SourceSafe, it might be very desirable to only have relative paths so anybody can check it in and only the real changes show.  In that case, instead of using multiple input directories, see if it’s possible to only have one input directory and use the -xi command line option to exclude the subdirectories you don’t want scanned.

That’s It!

And we’re done.  The syntax to do all of this is included in the menu file itself, so you don’t need to memorize everything.  You shouldn’t need to organize the menu very often, just after a lot of new files have been added and if you don’t like the default.

Note that if you’re using the non-framed HTML output format, changing the menu does require every output file to be updated.  However, Natural Docs has a special process just for this so it won’t take nearly as long as if it were rebuilding them all from scratch.  Still, if you’re working on a large project, it may be worth considering the framed HTML output format.

Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/output.html b/docs/tool/Help/output.html new file mode 100644 index 00000000..b2b6f354 --- /dev/null +++ b/docs/tool/Help/output.html @@ -0,0 +1,84 @@ + + +Output Formats - Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Output Formats

These are the output formats that are currently implemented in Natural Docs.

HTMLHTML output.  Each page is self-contained.  Linking to specific pages is easy, but every file has to be updated whenever the menu changes.
FramedHTMLHTML output based on frames.  The menu is updated quickly, but linking to individual pages is difficult and some people just plain hate frames.
HTML Compatibility

These are the browsers Natural Docs’ HTML output has been tested with.  All browsers will be able to view and navigate it, some of the older ones just may not be able to use advanced features like search correctly.

FireFoxTested with 1.0, 1.5, and 2.0.
Internet ExplorerTested with 6 and 7.
SafariTested with 2 and 3.  Search doesn’t work with unframed HTML in 2.
OperaTested with 7.0, 7.5, 8.0, 8.5, and 9.0.  Search doesn’t work with 7.0, and sometimes tooltips.
KonquerorTested with 3.5.5.  Search doesn’t work.
Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/running.html b/docs/tool/Help/running.html new file mode 100644 index 00000000..492bb3ae --- /dev/null +++ b/docs/tool/Help/running.html @@ -0,0 +1,40 @@ + + +Running Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Running Natural Docs
How and When · Command Line · Examples
 
How and When

Probably the best way to run Natural Docs is as part of the build process.  This way every time you compile your code, your documentation is updated as well and you always have a current reference.  Natural Docs has a differential build process so it will not rebuild the entire set of documentation every time it’s run.

If you’d like to run it manually instead, you should determine the command line you need and save it as a shortcut, batch file, or script since you should be running it often and will rarely need to fiddle with the parameters.

Command Line
NaturalDocs -i [input (source) directory]
+            -o [output format] [output directory]
+            -p [project directory]
+            [options]
Required Parameters:
-i [dir]
--input [dir]
--source [dir]

The input (source) directory.  Natural Docs will build the documentation from the files in this directory and all its subdirectories.  You can specify it multiple times to include multiple directories.  See the list of supported programming languages.

-o [fmt] [dir]
--output [fmt] [dir]

The output format and directory.  This can also be specified multiple times, so you can build the documentation in multiple formats in a single run.  See the list of supported output formats.

-p [dir]
--project [dir]

The project directory.  Natural Docs needs a place to store configuration and data files for each project it’s run on, so this is where it will put them.  No two projects should share the same directory.

Optional Parameters:
-xi [dir]
--exclude-input [dir]
--exclude-source [dir]

Excludes a subdirectory from being scanned.  The output and project directories are automatically excluded.

-img [dir]
--images [dir]

Adds a directory to search for image files when using (see [file]).

-s [style] ([style] ...)
--style [style] ([style] ...)

Selects the CSS style for HTML output.  See the default list of styles.

You can use any CSS file in your project directory or Natural Docs’ Styles directory just by using its name without the .css extension.  If you include more than one, they will all be included in the HTML that order.

-r
--rebuild

Rebuilds everything from scratch.  All source files will be rescanned and all output files will be rebuilt

-ro
--rebuild-output

Rebuilds all output files from scratch.

-t [len]
--tab-length [len]

Sets the number of spaces tabs should be expanded to.  This only needs to be set if you use tabs in example code or text diagrams.  The default is 4.

-do
--documented-only

Tells Natural Docs to only include what you explicitly document in the output, and not to find undocumented classes, functions, and variables.  This option is only relevant if you have full language support.

-oft
--only-file-titles

Tells Natural Docs to only use the file name for its menu and page titles.  It won’t try to determine one from the contents of the file.

-nag
--no-auto-group

Tells Natural Docs to not automatically create group topics if you don’t add them yourself.

-cs [charset]
--charset [charset]
--character-set [charset]

Sets the character set property of the generated HTML, such as UTF-8 or Shift_JIS.  The default leaves it unspecified.

-q
--quiet

Suppresses all non-error output.

-?
-h
--help

Prints the syntax reference.

No Longer Supported:
These parameters were part of previous Natural Docs releases, but are no longer supported.
-ho
--headers-only

This used to check only the headers and not the source files in C and C++.  Edit Languages.txt instead and add the line “Ignore Extensions: c cpp cxx”.

-s Custom
--style Custom

This used to tell Natural Docs not to alter the CSS file in the output directory.  Copy your custom CSS file to your project directory and use it with -s instead.

-ag [level]
--auto-group [level]

This used to set the level of auto-grouping between Full, Basic, and None.  The algorithm was improved so there’s no need for separate levels anymore.  You can use -nag if you want to turn it off completely.

Examples
NaturalDocs -i C:\My Project\Source
+            -o FramedHTML C:\My Project\Docs
+            -p C:\My Project\Natural Docs
+
+NaturalDocs -i /project/src1
+            -i /project/src2
+            -o HTML /project/doc
+            -p /project/nd
+            -s Small -t 3
Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/styles.css b/docs/tool/Help/styles.css new file mode 100644 index 00000000..f9bc8d0a --- /dev/null +++ b/docs/tool/Help/styles.css @@ -0,0 +1,290 @@ + +body { + background: #FFFFFF; + margin: 18px 15px 25px 15px !important; + } + +body, +td, +li { + font: 9pt Verdana, sans-serif; + } +p, +td, +li { + line-height: 150%; + } + +p { + text-indent: 4ex; + margin: 0; + } + +td { + vertical-align: top; + } + +a:link, +a:visited { color: #900000; text-decoration: none } +a:hover { color: #900000; text-decoration: underline } +a:active { color: #FF0000; text-decoration: underline } + +.Opera wbr:after { + content: "\00200B"; + } + +.NoIndent p + { text-indent: 0; } + +img { + border: none; + } + +.First { + margin-top: 0 !important; + padding-top: 0 !important; + } +.Last { + margin-bottom: 0 !important; + padding-bottom: 0 !important; + } + +.Header { + background-image: URL("images/header/background.png"); + background-color: #7070C0; + } +.SideMenuTop { + background: URL("images/header/overmenubg.png"); + } +.SideMenuBottom { + vertical-align: bottom; + } +.BodyTop { + background: URL("images/header/overbodybg.png"); + text-align: right; + } +.BodyBottom { + vertical-align: bottom; + text-align: right; + font: italic 8pt Georgia, serif; + color: #C0C0C0; + padding-right: 10px; + } + +.Body { + padding: 15px 20px 0 25px; + } + +#SourceForgeLogo { + border: 1px solid #D8D8D8; + margin-top: 2em; + } + + + +pre, code, .Example { + font: 10pt Courier New, Courier, monospace; + color: #606060; + } +a code { + color: #C06060; + } +.Example { + overflow: auto; + } + +.PageTitle { + font: bold italic 21pt Trebuchet MS, sans-serif; letter-spacing: .5ex; text-transform: uppercase; + margin-bottom: .5em } +.IE .PageTitle { + letter-spacing: 1.25ex; + } + + +.Topic { + margin-bottom: 2em } + + +.TopicTitle { + font: 18pt Georgia, serif; + border-width: 0 0 1px 0; border-style: solid; border-color: #C0C0C0; + margin-bottom: .5em + } +#SubscribeTopicTitle { + margin-bottom: 0; + } +.Subscribe { + font-size: 8pt; + margin-bottom: 2em; + color: #909090; + } + +.Subscribe a:link, +.Subscribe a:hover, +.Subscribe a:visited { + color: #909090 } + + +.SubTopic { + font-weight: bold; font-size: 10pt; + padding-top: 1.5em; padding-bottom: .5em; + } + +.MiniTopic { + font-weight: bold; + padding-top: 1em; padding-bottom: 0em; + } + + +.TOC { + text-align: center; + font: 8pt Verdana, sans-serif; + text-transform: uppercase; + background-color: #F8F8F8; + border-width: 1px; border-style: solid; border-color: #C0C0C0; + margin-bottom: 1.5em; + padding: 2px 0; + -moz-border-radius: 14px; + } + + .TOC a { + margin: 0 0.75ex; } + + .TOC a:link, + .TOC a:hover, + .TOC a:visited { + color: #404040 } + + +.Example { + background-color: #FDFDFD; + padding: 15px; + border: 1px solid #C0C0C0; + border-width: 1px 1px 1px 6px; + border-style: dashed dashed dashed solid; + color: #707070; + margin: 15px 5ex; + } + + +.LastUpdated { + font: italic 10pt Georgia, serif; + color: #A0A0A0; + margin: 1em 0; + } + + + +.FAQSummary { + margin-bottom: 3em; + } +.FAQSummaryGroup { + font: bold 12pt Georgia, serif; + margin: 1em 0 .25em 0; + } +.FAQGroup { + font: 18pt Georgia, serif; + border-bottom: 1px solid #C0C0C0; + margin-bottom: .5em; + margin-top: 1.5em; + } +.FAQSummaryEntry:link, +.FAQSummaryEntry:visited, +.FAQSummaryEntry:hover, +.FAQSummaryEntry:active { + } + +.FAQEntry { + margin-bottom: 3em; + } +.FAQEntryTitle { + font: bold 12pt Georgia, serif; + margin-bottom: .5em; + } +.FAQEntry .SubTopic { + font: italic 9pt Verdana, sans-serif; + } + + + +.SideMenu { + width: 175px; /* 195 minus padding */ + text-align: center; + padding-top: 15px; + background-color: #F0F0F0; + } +.SideMenuBottom { + background-color: #F0F0F0; + } +.SideMenuBottomRight { + text-align: right; + } + +.SideMenuSection { + margin-bottom: 3em; + } + +.SideMenuTitle { + padding-bottom: 3px; + border-bottom: 1px solid #D0D0D0; + } + +.SideMenuBody { + padding-top: 1em; + background: URL("images/menu/background.png") repeat-x; + } + +.SideMenuEntry { + font: 8pt Verdana, sans-serif; + margin: 0 10px 1em 10px; + display: block; + } + +a.SideMenuEntry:link, +a.SideMenuEntry:visited { + color: #000000; + padding: 1px 10px 2px 9px; + } +a.SideMenuEntry:hover, +a.SideMenuEntry:active, +#SelectedSideMenuEntry { + border-style: solid; + border-width: 1px 2px 2px 1px; + padding: 0 8px; + text-decoration: none; + -moz-border-radius: 10px; + } +a.SideMenuEntry:hover, +a.SideMenuEntry:active { + color: #000000; + border-color: #C8C8C8; + background-color: #F8F8F8; + } +#SelectedSideMenuEntry { + color: #000000; + border-color: #606060; + background-color: #FFFFFF; + } + +.SideMenuSourceForge { + padding-top: 5px; + } + + + +/* Needed by the release notes for 1.3 */ + +.ExPrototype { + font: 10pt Courier New, Courier, monospace; + padding: 5px 3ex; + background-color: #F4F4F4; + border: 1px solid #D0D0D0; + margin: 1em 0; + } +.ExPrototype td { + font: 10pt Courier New, Courier, monospace; + } +.ExPrototype .Fade { + color: #8F8F8F; + } + diff --git a/docs/tool/Help/styles.html b/docs/tool/Help/styles.html new file mode 100644 index 00000000..ebd8abca --- /dev/null +++ b/docs/tool/Help/styles.html @@ -0,0 +1,52 @@ + + +CSS Styles - Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
CSS Styles
Default Styles · Customizing · Common Customizations
Default Styles

These are the styles that come with Natural Docs.  They all follow the same color scheme and general layout; the choices are more so that you can choose the style of text you want.

You choose which style you want for your project by adding “-s [style name]” to the command line.

DefaultThis is the default style that Natural Docs uses.  Most of the text is 10pt Verdana.
SmallSmaller fonts than Default with most of the text using 8pt Verdana.  Some people like the small fonts because you can fit more on the screen at once.  However, some people hate them and find them hard to read.
RomanSerif fonts with most of the text using 12pt Roman.  Some people prefer Roman fonts, usually those that have decent anti-aliasing displays like Mac OS X or Windows XP with ClearType.
Customizing

There are two ways to customize the CSS files.  One is to build your own file from scratch, and the other is to make a touch-up file that gets applied after one of the default styles.  Either way you want to create your own CSS file in your project directory (the one you use with -p) or if you plan on sharing it between many projects, in Natural Docs’ Styles directory.

To use a custom file, no matter where you put it, you just use it with -s without the CSS extension.  So if you made Red.css, you use “-s Red”.  If you made a touch-up file instead, you use it after one of the default styles, such as with “-s Default Red”.  If you’re so inclined, you can string as many touch-up files together as you want or use one of your own as a base.

The CSS Guide documents the page structure and CSS styles of Natural Docs’ output.  Always remember to check its revisions section every time you upgrade Natural Docs because it may change between releases.

Common Customizations
Web-Style Paragraphs

Natural Docs defaults to print-style paragraphs like the one you are reading.  Each one is indented and there are no blank lines between them.  To switch to web-style paragraphs, which have blank lines and no indents, add this to your custom CSS file:

p {
+   text-indent: 0;
+   margin-bottom: 1em;
+   }
+
Prototype Colors

If you’ve added a custom topic type and have it finding prototypes for you, you may want to have them appear in a different color than the default black and white.  Add this to your custom CSS file:

.C[type] .Prototype {
+   background-color: [color];
+   border-color: [color];
+   }
+

Replace [type] with the name of your topic type, minus any symbols and spaces.  So if you added a type “Sound Effect”, you would apply the style to “.CSoundEffect .Prototype”.

Copyright © 2003-2008 Greg Valure
\ No newline at end of file diff --git a/docs/tool/Help/troubleshooting.html b/docs/tool/Help/troubleshooting.html new file mode 100644 index 00000000..f921606a --- /dev/null +++ b/docs/tool/Help/troubleshooting.html @@ -0,0 +1,18 @@ + + +Troubleshooting - Natural Docs + + + +
Natural Docs
About
Language SupportOutput Formats
Using
Documenting
Your CodeKeywordsRunningTroubleshooting
Customizing
Organizing the MenuCSS StylesTopics and KeywordsLanguages, Indexes,
and Prototypes
Community
Web SiteMailing ListsMessage BoardsBugs and
Feature Requests
Troubleshooting
Natural Docs Issues
Windows Issues
Natural Docs Issues
I don’t get any documentation
Is it recognizing your source files?

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.

No, it’s not recognizing them

The most likely scenario is that Natural Docs doesn’t associate the file extension you’re using with your programming language.  Open Languages.txt in Natural Docs’ Config directory 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.

Yes, it’s recognizing them

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.

Some of my topics don’t show up
  • 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 to fix this.
Some of my topics aren’t formatting correctly
  • Headings 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 heading but shouldn’t, either get rid of the colon at the end 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.

I’m not getting prototypes
  • 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 you’re documenting something with a new topic type you added to Topics.txt, you must also edit Languages.txt to tell it how to detect prototypes for that type.
My links aren’t working

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.
Windows Issues
I get the message “Bad command or file name” or “perl is not recognized”

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”.  You need to include the quotes if there are spaces in the path.

I get the message “Can’t open perl script NaturalDocs”

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”.  You need to include the quotes if there are spaces in the path.

Copyright © 2003-2008 Greg Valure
\ No newline at end of file -- cgit 1.4.1