Generating API Documentation with NATdoc

This document covers the following topics:

Quick Start

NATdoc works very similar to Javadoc. As Javadoc, NATdoc is a tool for generating API documentation in HTML format from doc comments in source code.

NATdoc processes the source code from the following Natural object types:

Program
Subprogram
Subroutine
Function
Copycode
Helproutine
Global data area (GDA)
Local data area (LDA)
Parameter data area (PDA)

The processed files must be valid, error-free Natural source files that can be processed by the Natural parser. All sources must be contained in the same project. Sources such as parameter data areas or copycodes must be part of the same Natural library.

NATdoc requires that a specific type of comment is used (/**) and that the comments appear in certain positions (before the first statement and within a DEFINE DATA block). For example: 

* >Natural Source Header 000000
* :Mode S
* :CP windows-1252
* <Natural Source Header
/** Sample Program.
/**
/** :author John Doe
/**
DEFINE DATA PARAMETER
1 #X (I2) /** :in   The 1st operand.
1 #Y (I2) /** :in   The 2nd operand.
1 #R (I2) /** :out  The result.
...
END-DEFINE

To find out how the comments in your applications will turn out, you generate NATdoc as described below. For this purpose, you should prepare an HTML page with a bit of contents such as the following (this is the overview page that you have to specify in the wizard): 

<html>
<body>
<p>This is the text for the overview.</p>
</body>
</html>

If you have not yet inserted any NATdoc-specific comments, you can nevertheless use the generator to find out how the documentation for your existing application will appear, even if you do not yet have prepared an overview page.

Generating NATdoc

NATdoc is generated using a wizard.

Start of instruction setTo generate NATdoc

  1. In the Navigator view or in the Natural Navigator view, select the project, library or source file for which you want to generate NATdoc.

  2. From the Project menu, choose Generate NATdoc.

    The following dialog box appears.

    Generate NATdoc

  3. Select all types for which NATdoc is to be generated.

  4. Specify the following information:

    Destination

    If required, specify a different destination folder. This is the folder into which NATdoc is to be generated. The destination must be within the same project.

    Use standard template / Use custom template

    Specify whether you want to use the standard template or a custom template.

    The standard template is provided with NaturalONE. You can also create your own custom templates, on the basis of the standard template; in this case, you have to specify the path to your custom template. See also Using Custom Templates.

  5. Choose the Next button to proceed to the next page.

    Generate NATdoc

  6. Specify all required information as described below.

    Document title

    When enabled, you can specify the text that is to appear in the title bar of the browser and in any bookmarks/favorites that a user creates for this page.

    Overview

    When enabled, an overview page must exist. It can have any file name. You have to specify the path to this page.

    The overview page has to be provided by the developer as an HTML page. This page contains a brief description of the project. The text from the HTML page will be included near the top of the generated index.html page.

    See also Special Comment Files.

    Generate index

    When enabled, an index is generated.

    Separate index per letter

    When enabled, a separate page is generated for each letter (for example, all entries starting with the letter A are written to a separate page, and all entries starting with the letter B are written to another separate page).

    :author

    When enabled, the text from the :author tag is available in the generated documentation.

    :deprecated

    When enabled, the text from the :deprecated tag is available in the generated documentation.

    deprecated list

    When enabled, the list of programs, subroutines etc. that are not to be used is generated into the documentation.

    Open generated index file in browser

    When enabled, the generated index file is automatically opened in the browser when the generation is completed.

  7. Choose the Finish button to generate NATdoc.

    When your project contains many files, the generation may take quite some time. Information about the generation process is provided in the Console view.

    When the generation is complete and when Open generated index file in browser was enabled, the documentation is automatically opened in a browser.

Location of the NATdoc Files

It is recommended that you switch to the Resource perspective, since the NaturalONE perspective does not show all generated files.

When NATdoc has been generated, the folder that you have defined as the destination folder (by default, a folder called doc is created) contains all generated files. The top-level node of this folder contains the file index.html. This is the starting page for the generated documentation. If you want, you can open it with the web browser.

Natural sources can have names which violate the naming conventions for normal URLs. In the generated files, special characters such as the hash (#) or plus (+) sign are therefore replaced with the name of the character (for example, "hash" or "plus").

Previewing the API Documentation in the NATdoc View

The NATdoc view assists you while entering the NATdoc-specific comments in the source code. The output in this view is similar to the generated NATdoc. However, since this output is generated on the fly, links to other documents may differ from those in the wizard-generated NATdoc.

NATdoc view

Note:
This view is not shown by default when you open the NaturalONE perspective. For information on how to display it, see Showing a View of the NaturalONE Perspective.

The local toolbar of the NATdoc view provides the following icons:

Icon Description
Icon Go back to the previous object.
Icon Go forward to the next object.
Icon When selected, each object that you select in the Navigator view or Natural Navigator view or that you open in the source editor is automatically used in the NATdoc view.
Icon Open the corresponding Natural object in the source editor.

Documentation Comments in the Source Code

The characters /** begin a documentation comment. All text until the end of the line belongs to the comment. The text in a comment can continue onto multiple lines.

In your source code, the documentation comments may appear in the following places:

  • Directly after the source header and before the first statement. Example: 

    * >Natural Source Header 000000
* :Mode S
* :CP windows-1252
* <Natural Source Header
/** Subroutine 01 from LIB04.
/** <h2>A Subroutine</h2>
/** :author John Doe
DEFINE SUBROUTINE Subroutine_01
/* TODO: Enter your code here
IGNORE
END-SUBROUTINE

    Note:
    The first sentence must always end with a period. It is used in an overview table.

  • After the following statements:

    DEFINE DATA GLOBAL
    DEFINE DATA PARAMETER

    Example:

    DEFINE DATA GLOBAL
/** Global Data Area 01 from LIB04.
/** <h2>A Local Data Global</h2>
/** :author John Doe
1 GLOBAL1(A10)
END-DEFINE

  • After the declaration of PARAMETER, GLOBAL or INDEPENDENT variables in a DEFINE DATA block. Example: 

    * >Natural Source Header 000000
* :Mode S
* :CP windows-1252
* <Natural Source Header
/** Subprogram 01 from LIB07.
/** <h2>A Subprogram</h2>
/** :author John Doe
DEFINE DATA 
GLOBAL USING MYGDA
PARAMETER
1 ACTION (A1)       /** :in what to do
1 PARMS (A36)       /** :in action-dependent
1 REDEFINE PARMS    /** :redef if action is 'a'
  2 ERROR (A4)      /** :out error number
1 REDEFINE PARMS    /** :redef if action is 'b'
  2 ERROR2 (A4)     /** :in error number
  2 ERRORTEXT (A32) /** :out error number
INDEPENDENT 
1 +TRACE (L)        /** :in trace flag
END-DEFINE
WRITE ACTION
END

In addition, NATdoc searches each regular comment line which starts with /* and checks whether it contains a documentation comment (/**). This allows you, for example, to use different comments for IDL generation and for NATdoc. Examples:

  • The following comments will be used for NATdoc generation:

    ...
1 MYPARM (A10) /* inout /** :out delivers the new parameter
...
/* a comment /** :since 02/25
FOR #I = 1 TO 10 /* a comment /** :since 02/25

  • The following comments will not be used for NATdoc generation: 

    ...
* 1 MYPARM (A10) /* inout /** :out delivers the new parameter
...
** a comment /** :since 02/25
* a comment /** :since 02/25

Documentation comments within the body of a program are ignored.

You can use HTML tags in your comments (for example, <b> which is used for bold text). The standard template of NATdoc generates HTML 4.0-compliant code.

Leading spaces in a documentation comment (that is blanks and tabs preceding the first character) are not removed.

Even though Natural allows writing programs in reporting mode, NATdoc provides no specific support for this programming mode. It is recommended that you write your programs in structured mode.

Special Comment Files

NATdoc makes use of the following special comment files:

Overview Comment File

Any documentation that applies to the entire application or a set of libraries can be written to the overview comment file, which is a normal HTML file.

The overview comment file can have any name. You specify this name in the wizard when you are about the generate NATdoc. The overview comment file must be part of the project to which it pertains. It is recommended that you put it into the root of the project.

When you generate NATdoc and the corresponding option has been enabled in the wizard, the information from the <body> of the overview comment file is merged into the overview summary page.

Example:

<html>
<body>
<p>This is the text for the overview.</p>
</body>
</html>

Library Comment File

Any documentation that applies to the entire library can be written to a library comment file, which is a normal HTML file.

A library comment file must always have the name library.html, and it must be placed into the root of the library to which it pertains.

When you generate NATdoc and a file with the above name can be found in the library root, the information from the <body> of the library comment file is merged into the library summary page.

Example:

<html>
<body>
This is the 4th test library.
<p><i>Note:</i><br>
It's only a test.</p>
</body>
</html>

Note:
The first sentence must always end with a period. It is used in an overview table. Do not put a title or any other text between <body> and this first sentence.

Overview of NATdoc Tags

Documentation comments may contain tags. They are case-sensitive, that is, a tag must be written as indicated below.

NATdoc distinguishes the following types of tags:

Field Tags

A field tag starts with a colon (:). It is only possible to define a single field tag in each comment line.

:author name

Adds the string "Author" with the specified name to the generated document.

Example:

/** :author John Doe
:deprecated text

Indicates that the API should no longer be used. Your text appears in italics, in front of the main description. It is preceded by the word "Deprecated" in bold. The first sentence of your text also appears in the summary and index.

Example:

/** :deprecated This function has been replaced by <:link SYSEXT/USR2036P>.
:in text, :out text, :inout text

:in pertains to a parameter that is used as input only.

:out pertains to a parameter that is used as output only.

:inout pertains to a parameter that is used as both input and output.

These tags can be used in two different places.

  • After the declaration of a parameter in a DEFINE DATA PARAMETER block. In this case, the syntax is as follows: 

    tag description

    Example:

    1 ch    (A1)        /** :in the character to be tested
1 field (A) dynamic /** :in the string to be converted

  • In front of a DEFINE SUBROUTINE statement. In this case, the syntax is as follows: 

    tag parameter-name description

    Example:

    /** :in ch the character to be tested
/** :in field the string to be converted
DEFINE SUBROUTINE TRANSLATE
:redef text

Pertains to a parameter that is redefined and where the calling program has to fill the data according to the structure.

This tag can be used in the same places as described above for the :in, :out and :inout tags.

:return text

Adds a section which contains the heading "Returns" and your text. This can only be used with a function.

Example:

/** :return all in one.
DEFINE FUNCTION Function_01 RETURNS (A) DYNAMIC
:see reference

Adds a section which contains the heading "See Also" and your reference. All :see tags in a documentation comment are listed under the same heading.

This tag can be used in different forms:

  • :see "string"

    A link is not generated. Example:

    /** :see "The NaturalONE Documentation"

  • :see <a href="url#value">label</a>

    A link is generated. You specify either a relative or absolute URL. Example: 

    /** :see <a href="natlang.html#about">Natural Language</a>
:since text

Adds a section which contains the heading "Since" and your text. This tag indicates that a feature exists since the release specified in your text. Example: 

/** :since 4.2
:version text

Adds a section which contains the heading "Version" and your text. This tag writes the version number you specify to the generated document. Example: 

/** :version 8.1

Inline Tags

Inline tags are written in angle brackets. The tag itself also starts with a colon (:). It is possible to define more than one inline tag within the same comment line.

<:docRoot>

Contains the relative path to the root directory. This is useful if you want to reference a file (such as the copyright page) from all generated pages.

Example:

/** See the <a href="<:docRoot>/copyright.html">Software AG copyright page</a>.
<:link library-name/object-name label>

This is similar to the :see tag. Other than :see, <:link> inserts an inline link in the generated document. This inline link refers to the library and object that you specify. Only your label is visible in the generated document.

Example:

/** Use the <:link SYSEXT/USR2036P USR2036P> user exit.

The generated page contains the following HTML code:

Use the <a href="SYSEXT/USR2036P.html"><code>USR2036P</code></a> user exit.
<:linkplain library-name/object-name label>

This is the same as the :link tag. The only difference is in the generated HTML: the text in the link is not put in <code> tags; plain text is used instead.

Example:

/** Use the <:linkplain SYSEXT/USR2036P USR2036P> user exit.

The generated page contains the following HTML code:

Use the <a href="SYSEXT/USR2036P.html">USR2036P</a> user exit.

Where Can Tags be Used?

The following table shows where the NATdoc tags can be used:

Tag Name Natural Object Description Interface Description Inline
:author X    
:deprecated X    
:in   X  
:inout   X  
:out   X  
:redef   X  
:return   X  
:see X    
:since X    
:version X    
<:docRoot>     X
<:link>     X
<:linkplain>     X

Using Custom Templates

Using a custom template, you can adapt the generated NATdoc files to your requirements. The generated pages may be shown, for example, with different colors or in another language. You specify the path to your custom template in the wizard when you are about the generate NATdoc.

The following topics are covered below:

Location of the Custom Templates

The following files are located in the naturalone/samples directory of your NaturalONE installation:

  • NATdoc_en.zip
    Contains all required custom templates in English. You can use these templates for your own modifications or for translations to other languages.

  • NATdoc_de.zip
    Contains a German translation of the English custom templates.

If you want to use the custom templates from one of the above Zip files, you have to unzip the file. You can unzip it into any directory which can be accessed by the wizard.

Directory Structure

When you unzip, for example, the file NATdoc_de.zip, you will find the following directory structure in your file system:

graphics/use-natdoc-templates-directory.png

Important:
Do not delete or rename any file or subdirectory. Do not change the encoding of the files, which is "UTF-8 without BOM".

Quick Customizations

You can quickly change the look-and-feel of the generated pages as described in the following topics:

Translation into Another Language

Unzip the file NATdoc_en.zip. Rename the resulting directory NATdoc_en, for example, to NATdoc_mylanguage.

Open the file readme_language.txt. This file is located in the top-level directory. It contains a list of all strings that need to be replaced in all NATdoc template files. For example, search for the following string 

>API Help<

and replace it with the appropriate term in the chosen language. Make sure to keep the angle brackets which are part of the enclosing HTML tag.

Color Scheme

To change the colors that are used in the generated pages, modify the corresponding entries in the file stylesheet.css. This file is located in the DOCtemplate subdirectory.

For example, if you want to change the standard green background colors for the navigation bar which is shown at the top and bottom of the generated pages, modify the entries for NavBarCell1 and NavBarCell1Rev: 

.NavBarCell1    { background-color:#F88017 } /* dark orange */
.NavBarCell1Rev { background-color:#7E3117 } /* dark orange3 */

Header Comments

If you want to include additional comments in the headers of the generated pages, modify the file natdoc($GENERATEDCOMMENT$).html. This file is located in the DOCtemplate subdirectory.

The entire content of this file is included in the <head> section of the generated pages. 

<html>
<head>
$GENERATEDCOMMENT$
...
</head>

Body Footers

If you want to include an additional footer in the generated pages, modify the file natdoc($FOOTER$).html. This file is located in the DOCtemplate subdirectory.

The entire content of this file is included at the bottom of the <body> section of the generated pages. 

...
$FOOTER$
</body>
</html>

Detailed Template Descriptions

All templates are based on HTML. Each template contains HTML tags, data and placeholder variables.

The following topics are covered below:

Placeholder Variables

During the generation of NATdoc, a placeholder variable can be replaced either with a single value or with the content of a template which may contain further placeholder variables. Placeholder variables are always surrounded by dollar ($) signs and are case-sensitive. Examples: 

$DO_VALUE$
$NEXTPAGE$

The naming conventions for the different types of placeholder variables are described below.

  • Single Value
    Placeholder variables starting with $DO_ or $IN_ followed by an uppercase name are used to insert a single value. Examples:

    Placeholder Variable Description
    $DO_LEVEL$ Level of a DEFINE DATA parameter.
    $DO_PARAMETER$ Name of a DEFINE DATA parameter.
    $DO_FIRSTSENTENCE$ First sentence in a documentation comment.
    $IN_OBJECTTYPE$ Name of the object type for processing.
    $IN_OBJECTTYPENAME$ Name of the object type for output.

  • Content of a Template
    Placeholder variables with other uppercase names are replaced with the content of a template. Examples:

    Placeholder Variable Description
    $SUMMARY(HELPROUTINE)$ Add summary data for help routines. The corresponding template natdoc-natlibrary-summary($SUMMARY($OBJECTTYPE$)$).html is used.
    $PREVPAGE$ Add template for linking to the previous page, if existing.
    $SUMMARYLINE$ Add summary lines. The corresponding template natdoc-natlibrary-frame($SUMMARYLINE$).html is used.

  • NATdoc Tag Template
    Placeholder variables with lowercase names are used to insert NATdoc tag templates. Examples:

    Placeholder Variable Description
    $in$ Name of a field tag in a template.
    $detail$ Include template for DEFINE DATA field tags.

Template Files for NATdoc Tags

NATdoc tags are used in the documentation comments which are contained in the Natural source files. The DOCtags subdirectory contains a template file for each NATdoc tag.

The following topics are covered below:

Template Files for NATdoc Field Tags

NATdoc defines a set of field tags, but can also handle unknown field tags that obey the field tag syntax. There are different categories of field tags:

  • Field tags that generate output for each occurrence
    This applies to the following tags:

    :in
    :out
    :inout
    :redef
    :return

    A single template is defined for each of these tags. The naming convention for such a template is NATtag-<tagname>.html where tagname is the lowercase name of the tag. For example, NATtag-inout.html.

  • Field tags that generate combined output over all occurrences
    This applies to the following tags:

    :author
    :deprecated
    :see
    :since
    :version

    Two templates are defined for each of these tags.

    The naming convention for the first template is NATtag-<tagname>.html where tagname is the lowercase name of the tag. For example, NATtag-author.html. The first template must contain the $NEXT$ placeholder variable.

    The naming convention for the second template is NATtag-<tagname>_next.html where tagname is the lowercase name of the tag. The string "_next" must also be written in lowercase. For example, NATtag-author_next.html

  • Unknown field tags that generate combined output over all occurrences
    For any unknown field tags which are not listed above, it is either possible not to generate anything, or to generate generic output. Two templates are available for the latter case: NATtag-notag.html and NATtag-notag_next.html.

Template Files for NATdoc Inline Tags

This applies to the following tags:

<:link>
<:linkplain>

A single template is defined for each of these tags. The naming convention for such a template is NATtag-<tagname>.html where tagname is the lowercase name of the tag. For example, NATtag-linkplain.html.

Note:
<:docroot> is a special inline tag for which a template is not required.

Template Files for Summaries

In addition to the above mentioned template files for the different NATdoc tags, the DOCtags subdirectory also contains the following special template files which do not apply to a special tag:

  • NATtag_summary-docu.html for the description of the source.

  • NATtag_summary-detail.html for the description of a single parameter in the parameter area.

These special templates are used by the natdoc-natsource.html template. They are included in each page that is generated for a Natural source.

Template Files for Generated HTML Pages

The template files for the generated HTML pages are located in the DOCtemplate subdirectory. During the generation of NATdoc, one or more template files are used to generate an HTML page.

There are two types of templates with different naming conventions:

  • Main Templates
    The name of a main template does not contain any placeholder variables. For example:

    natdoc-index-all.html

  • Subtemplates
    The name of a subtemplate starts with the name of the main template, followed by a placeholder variable that is enclosed in parentheses and dollar ($) signs. For example, these are the names of the subtemplates that are used by the natdoc-index-all.html main template:

    natdoc-index-all($SOURCEINDEXALL$).html
    natdoc-index-all($LETTERBAR$).html
    natdoc-index-all($INDEXLINE$).html

The following graphic shows the names of the frames that are used in the generated index.html file. The name of the template for this file is natdoc-index.html.

Generated index file

The following topics are covered below:

Contents of the DOCtemplate Subdirectory

The following table lists the template files that are located in the root of the DOCtemplate subdirectory and the names of the generated HTML files. When subtemplates are used, the main template (which does not contain a placeholder variable) is always listed at the top.

Template File Generated HTML File Description

natdoc-index.html

index.html Main page containing the frames mentioned below.

natdoc-overview-summary.html
natdoc-overview-summary($SUMMARYLINE$).html

overview-summary.html Overview page for all libraries. Right frame of the index.html page. Or main file if frames are not used.

natdoc-overview-frame.html

overview-frame.html Overview page for all libraries with the link "All Sources". Left upper frame of the index.html page.

natdoc-allsources-frame.html
natdoc-allsources-frame($SUMMARYLINE$).html

allsources-frame.html Overview page for all source files if frames are used. Left lower frame of the index.html page.

natdoc-allsources-noframe.html
natdoc-allsources-noframe($SUMMARYLINE$).html

allsources-noframe.html Overview page for all source files if frames are not used.

natdoc-index-all.html
natdoc-index-all($SOURCEINDEXALL$).html
natdoc-index-all($LETTERBAR$).html
natdoc-index-all($INDEXLINE$).html

index-all.html Only used if separate index pages are not generated for each letter. In this case, this file contains the entire index.

natdoc-help.html

help-doc.html Help page.

natdoc-deprecated-list.html

deprecated-list.html List of deprecated APIs.

In addition to the files listed in the table above, the DOCtemplate subdirectory also contains the following files:

File Name Description
stylesheet.css During the generation, this file is simply copied. It is not modified.
natdoc($GENERATEDCOMMENT$).html These files contain general replacements which are applied to all generated HTML pages.
natdoc($FOOTER$).html

Contents of the DOCtemplate/index-files Subdirectory

When separate index pages are generated for each letter, a new subdirectory with the name index-files is generated. Each HTML file in this subdirectory is generated with the template files from the DOCtemplate/index-files subdirectory. These template files are listed in the following table. The main template (which does not contain a placeholder variable) is always listed at the top.

Template File Generated HTML File Description

natdoc-index.html
natdoc-index($INDEXLINE$).html
natdoc-index($LETTERBAR$).html
natdoc-index($NEXTPAGE$).html
natdoc-index($NONEXTPAGE$).html
natdoc-index($NOPREVPAGE$).html
natdoc-index($PREVPAGE$).html

index-<n>.html Only used if separate index pages are generated for each letter. n stands for a sequential number within the generated file name. For example, index-0.html, index-1.html and so on.

Contents of the DOCtemplate/library Subdirectory

For each library, a subdirectory is generated which is named after the library.

The following table lists the template files that are located in the DOCtemplate/library subdirectory and the names of the generated HTML files. When subtemplates are used, the main template (which does not contain a placeholder variable) is always listed at the top.

Template File Generated HTML File Description

natdoc-natlibrary-frame.html
natdoc-natlibrary-frame($SUMMARY($IN_OBJECTTYPE$)$).html
natdoc-natlibrary-frame($SUMMARYLINE$).html

library-frame.html Summary for this library. Left lower frame.

natdoc-natlibrary-summary.html
natdoc-natlibrary-summary($NEXTPAGE$).html
natdoc-natlibrary-summary($NONEXTPAGE$).html
natdoc-natlibrary-summary($NOPREVPAGE$).html
natdoc-natlibrary-summary($PREVPAGE$).html
natdoc-natlibrary-summary($SUMMARY($IN_OBJECTTYPE$)$).html
natdoc-natlibrary-summary($SUMMARYLINE$).html

library-summary.html Summary of all source files belonging to this library. Right frame. Or main file if frames are not used.

natdoc-natsource.html
natdoc-natsource($DETAIL($TYPE$)$).html
natdoc-natsource($DETAILLINE$).html
natdoc-natsource($NEXTPAGE$).html
natdoc-natsource($NONEXTPAGE$).html
natdoc-natsource($NOPREVPAGE$).html
natdoc-natsource($PREVPAGE$).html

<sourcename>.html API description for a single Natural source file. sourcename stands for the name of the related Natural source file. For example, MYMAP.html.

Call Hierarchies and Placeholders in the Template Files

The template files use placeholder variables for single values which are replaced during NATdoc generation.

The template files can also use subtemplates, just like a Natural program can include copycodes. However, other than with Natural programs, subtemplates can be included recursively. For example, the main template natdoc-overview-summary.html uses the placeholder variable $SUMMARYLINE$ which is defined by the subtemplate natdoc-overview-summary($SUMMARYLINE$).html. This subtemplate includes itself by also using $SUMMARYLINE$.

This section describes the call hierarchies of the templates and the placeholder variables for single values. The content in the topics below is arranged by the names of the generated HTML pages. The following topics are covered below:

index.html

The following template is used for generating this file:

natdoc-index.html

This template file contains the following placeholder variables:

Placeholder Variable Description
$DO_NATDOCVERSION$ The NATdoc version that is used for generation.
$DO_TIMENOW$ Time stamp that is used during generation.

overview-summary.html

The following template hierarchy is used for generating this file: 

natdoc-overview-summary.html
     natdoc-overview-summary($SUMMARYLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_DESCRIPTIONFIRSTLINE$ First sentence in a documentation comment.
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_MENUDEPRECATED$ Link to deprecated page, if existing.
$DO_MENUINDEX$ Add index menu.
$DO_PROJECTDESCRIPTIONTAGS$ Content of overview file.
$DO_PROJECTNAME$ Project name as specified by the .project file.

overview-frame.html

The following template hierarchy is used for generating this file: 

natdoc-overview-frame.html
     natdoc-overview-frame($SUMMARYLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.

allsources-noframe.html

The following template hierarchy is used for generating this file: 

natdoc-allsources-noframe.html
     natdoc-allsources-noframe($SUMMARYLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_INLINESUBROUTINELINK$ Link to a Natural subroutine.
$DO_INLINESUBROUTINENAME$ Name of a Natural subroutine.
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_SOURCENAME$ Name of a Natural source.
$DO_SOURCENAMEHTML$ Link to a Natural source.

allsources-frame.html

The following template hierarchy is used for generating this file: 

natdoc-allsources-frame.html
     natdoc-allsources-frame($SUMMARYLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_INLINESUBROUTINELINK$ Link to a Natural subroutine.
$DO_INLINESUBROUTINENAME$ Name of a Natural subroutine.
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_SOURCENAME$ Name of a Natural source.
$DO_SOURCENAMEHTML$ Link to a Natural source.

index-all.html

The following template hierarchy is used for generating this file: 

natdoc-index-all.html
     natdoc-index-all($LETTERBAR$).html
     natdoc-index-all($SOURCEINDEXALL$).html
          natdoc-index-all($INDEXLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_DESCRIPTIONFIRSTLINE$ First sentence in a documentation comment.
$DO_INDEXCHAR$ Current index letter.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_LOCATION$ Link to the current object.
$DO_MENUDEPRECATED$ Link to deprecated page, if existing.
$DO_MENUINDEX$ Link to index page.
$DO_NAME$ Name of the current object.
$DO_SOURCENAMEHTML$ Link to a Natural source.
$DO_INLINESUBROUTINELINK$ Link to a Natural subroutine.
$DO_INLINESUBROUTINENAME$ Name of a Natural subroutine.

help-doc.html

The following template is used for generating this file:

natdoc-help.html

This template file contains the following placeholder variables:

Placeholder Variable Description
$DO_MENUDEPRECATED$ Link to deprecated page, if existing.
$DO_MENUINDEX$ Link to index page.
$DO_INDEX$ For a single index, index-all.html is generated. When separate index pages are generated for each letter, the index-files subdirectory is generated containing the files index-0.html, index-1.html and so on.

deprecated-list.html

The following template hierarchy is used for generating this file: 

natdoc-deprecated-list.html
     natdoc-deprecated-list($SUMMARY($OBJECTTYPE$)$).html
          natdoc-deprecated-list($SUMMARYLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_DESCRIPTIONFIRSTLINE$ First sentence in a documentation comment.
$DO_INLINESUBROUTINELINK$ Link to a Natural subroutine.
$DO_INLINESUBROUTINENAME$ Name of a Natural subroutine.
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_SOURCENAME$ Name of a Natural source.
$DO_SOURCENAMEHTML$ Link to a Natural source.
$IN_OBJECTTYPE$ Name of the object type for processing.
$IN_OBJECTTYPENAME$ Name of the object type for output.

<libraryname>/library-frame.html

The following template hierarchy is used for generating this file: 

library/natdoc-natlibrary-frame.html
     library/natdoc-natlibrary-frame($SUMMARY($OBJECTTYPE$)$).html
           library/natdoc-natlibrary-frame($SUMMARYLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_INLINESUBROUTINELINK$ Link to a Natural subroutine.
$DO_INLINESUBROUTINENAME$ Name of a Natural subroutine.
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_SOURCENAME$ Name of a Natural source.
$DO_SOURCENAMEHTML$ Link to a Natural source.
$IN_OBJECTTYPE$ Name of the object type for processing.
$IN_OBJECTTYPENAME$ Name of the object type for output.

<libraryname>/library-summary.html

The following template hierarchy is used for generating this file: 

library/natdoc-natlibrary-summary.html
     library/natdoc-natlibrary-summary($PREVPAGE$).html
     library/natdoc-natlibrary-summary($NOPREVPAGE$).html
     library/natdoc-natlibrary-summary($NONEXTPAGE$).html
     library/natdoc-natlibrary-summary($NEXTPAGE$).html
     library/natdoc-natlibrary-summary($SUMMARY($OBJECTTYPE$)$).html
           library/natdoc-natlibrary-summary($SUMMARYLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_DESCRIPTIONFIRSTLINE$ First sentence in a documentation comment.
$DO_INLINESUBROUTINELINK$ Link to a Natural subroutine.
$DO_INLINESUBROUTINENAME$ Name of a Natural subroutine.
$DO_LIBRARYDESCRIPTIONTAGS$ Content of the library comment file library.html. See also Special Comment Files.
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_MENUDEPRECATED$ Link to deprecated page, if existing.
$DO_MENUINDEX$ Link to index page.
$DO_NEXTHTML$ Link to the next library.
$DO_PREVHTML$ Link to the previous library.
$DO_SOURCENAME$ Name of a Natural source.
$DO_SOURCENAMEHTML$ Link to a Natural source.
$IN_OBJECTTYPE$ Name of the object type for processing.
$IN_OBJECTTYPENAME$ Name of the object type for output.

<libraryname>/<sourcename>.html

The following template hierarchy is used for generating this file: 

library/natdoc-natsource.html
     library/natdoc-natsource($PREVPAGE$).html
     library/natdoc-natsource($NEXTPAGE$).html
     library/natdoc-natsource($NOPREVPAGE$).html
     library/natdoc-natsource($NONEXTPAGE$).html
     library/natdoc-natsource($DETAIL($TYPE$)$).html
           library/natdoc-natsource($DETAILLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_DETAILS$ Detailed parameter description.
$DO_LIBRARYNAME$ Name of a Natural library.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_MENUDEPRECATED$ Link to deprecated page, if existing.
$DO_MENUINDEX$ Link to index page.
$DO_NEXTHTML$ Link to the next source page.
$DO_PREVHTML$ Link to the previous source page.
$DO_SOURCEDESCRIPTIONTAGS$ Add NATdoc tags.
$DO_SOURCEFILENAME$ The long name of the source file.
$DO_SOURCENAME$ Name of a Natural source.
$DO_SOURCENAMEHTML$ Link to a Natural source.
$DO_SOURCETYPE$ Natural object type.
$IN_TYPE$ Type of data area (for example, "Local Data Area").

index-files/index-<n>.html

The following template hierarchy is used for generating this file: 

index-files/natdoc-index.html
     index-files/natdoc-index($PREVPAGE$).html
     index-files/natdoc-index($NEXTPAGE$).html
     index-files/natdoc-index($NOPREVPAGE$).html
     index-files/natdoc-index($NONEXTPAGE$).html
     index-files/natdoc-index($LETTERBAR$).html
     index-files/natdoc-index($INDEXLINE$).html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_INDEX$ For a single index, index-all.html is generated. When separate index pages are generated for each letter, the index-files subdirectory is generated containing the files index-0.html, index-1.html and so on.
$DO_INDEXCHAR$ Current index letter.
$DO_INDEXNUMBER$ Total number of index files.
$DO_MENUDEPRECATED$ Link to deprecated page, if existing.
$DO_NEXTINDEX$ Link to the next index page, if existing.
$DO_PREVINDEX$ Link to the previous index page, if existing.
$DO_LIBRARYNAMEHTML$ Link to a Natural library.
$DO_SOURCENAMEHTML$ Link to a Natural source.
$DO_INLINESUBROUTINELINK$ Link to a Natural subroutine.
$DO_NAME$ Name of the current object.
$DO_LOCATION$ Link to the current object.
$DO_DESCRIPTIONFIRSTLINE$ First sentence in a documentation comment.

Special Generation Options

The following topics are covered below:

Index Link in the Navigation Menu

The following template files are used for generating the Index link in the navigation menu: 

natdoc-menu-index.html
library/natdoc-menu-index.html

These template files contain the following placeholder variables:

Placeholder Variable Description
$DO_INDEX$ For a single index, index-all.html is generated. When separate index pages are generated for each letter, the index-files subdirectory is generated containing the files index-0.html, index-1.html and so on.

Deprecated Link in the Navigation Menu

The following template files are used for generating the Deprecated link in the navigation menu: 

natdoc-menu-deprecated.html
library/natdoc-menu-deprecated.html

These template files do not contain any placeholder variables.

Global Replacements with Template Files

The following template files can be used to add additional comments to the <header> sections of the generated pages to an add individual footer to the <body> sections of the generated pages: 

natdoc($GENERATEDCOMMENT$).html
natdoc($FOOTER$).html

See also Header Comments and Body Footers.

Global Replacements without Template Files

Template files are not necessary for global replacements using the following placeholder variables:

Placeholder Variable Description
$DO_INDEX$ For a single index, index-all.html is generated. When separate index pages are generated for each letter, the index-files subdirectory is generated containing the files index-0.html, index-1.html and so on.
$DO_NATDOCVERSION$ The NATdoc version that is used for generation.
$DO_TIMENOW$ Time stamp that is used during generation.

Stylesheet

The following file defines colors, fonts and other style attributes for the generated pages: 

stylesheet.css

If you want to change the default settings that are applied to the generated pages, modify the corresponding entries in this file.