This document covers the following topics:
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.
NATdoc is generated using a wizard.
To generate NATdoc
In the Navigator view or in the Natural Navigator view, select the project, library or source file for which you want to generate NATdoc.
From the Project menu, choose Generate NATdoc.
The following dialog box appears.
Select all types for which NATdoc is to be generated.
Specify the following information:
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.
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.
Choose the button to proceed to the next page.
Specify all required information as described below.
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.
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.
When enabled, an index is generated.
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).
When enabled, the text from the :author tag is
available in the generated documentation.
When enabled, the text from the :deprecated tag is
available in the generated documentation.
When enabled, the list of programs, subroutines etc. that are not to be used is generated into the documentation.
When enabled, the generated index file is automatically opened in the browser when the generation is completed.
Choose the 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.
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").
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.
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 |
|---|---|
 |
Go back to the previous object. |
 |
Go forward to the next object. |
 |
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. |
 |
Open the corresponding Natural object in the source editor. |
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.
NATdoc makes use of the following special comment files:
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>
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.
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:
A field tag starts with a colon (:). It is only possible to define a single field tag in each comment line.
:author
nameAdds the string "Author" with the specified name to the generated document.
Example:
/** :author John Doe
:deprecated
textIndicates 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
textPertains 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
textAdds 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
referenceAdds 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
textAdds 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
textAdds 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 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.
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 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:
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.
When you unzip, for example, the file NATdoc_de.zip, you will find the following directory structure in your file system:
Important:
Do not delete or rename any file or subdirectory. Do not
change the encoding of the files, which is "UTF-8 without
BOM".
You can quickly change the look-and-feel of the generated pages as described in the following topics:
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.
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 */
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>
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>
All templates are based on HTML. Each template contains HTML tags, data and placeholder variables.
The following topics are covered below:
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.
|
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:
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.
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.
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.
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.
The following topics are covered below:
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 |
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 |
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 |
allsources-noframe.html | Overview page for all source files if frames are not used. |
|
natdoc-index-all.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 |
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 |
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. |
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 |
library-frame.html | Summary for this library. Left lower frame. |
|
natdoc-natlibrary-summary.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 |
<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. |
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:
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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"). |
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. |
The following topics are covered below:
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. |
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.
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.
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. |
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.