| Name: | makehelp - Extracts documentation from a source file
|
| Synopsis: | string makehelp -> -
|
| Description: |
The function scans the file specified by the argument and generates
plain text online help information for all functions documented in
this file. A separate file with the extension specified by variable
HelpExtension is generated for each function. The help information can
be viewed in a terminal by function help. The generated files are the
source from which the hypertext online help is generated by an
undocumented function in a next step.
The start of documentation for a function in the source file is
indicated by the string
"slash-asterisk [white]BeginDocumentation"
(without the quotation marks), where slash-star is the character "/"
immediately followed by "*" (with the quotation marks in both cases).
The end of the documentation is indicated by the same two characters
in reverse order. Thus, the documentation of a function is enclosed in
a C-style comment.
The help files are created in the directory specified by variable
CPPHelpRoot or by variable SLIHelpRoot depending on the type of the
source file. The makehelp function recognizes the keyword "name:" in
uppercase letters. The rest of the line containing this keyword
defines the name of the function the documentation refers to followed
by a short characterization of its purpose. The two components are
separated by a the three character string " - ". More formally,
makehelp extracts help information if the source file matches
[any][slash-star[[white]BeginDocumentation[any]\n
[white] name: [any][space]-[space][any]\n[any]star-slash]]
Function makehelp appends a line to the help file starting with the
keyword "source:" in uppercase letters followed by the absolute path
to the source file. This backward reference enables the help system
of NEST to direct an editor and validation tools to the implementation
of the documented function.
The generator of hypertext online help operating on the help file
recognizes many more keywords for structuring and cross linking
the documentation.
|
| Parameters: |
The argument specifies the name of the source file by an absolute path.
If no absolute path is provided all directories listed in the variable
MakeHelpSearchPath are searched for the file.
|
| Examples: |
(sli-init.sli) makehelp
(/home/user/slifunctions/MySli.sli) makehelp
|
| Author: | Hehl, docu edited by Sirko Straube
|
| FirstVersion: | 14.4.1999
| SeeAlso: | help helpindex :makeallhelp :makehelpindex |
|
| Source: | /home/abuild/rpmbuild/BUILD/nest-2.4.1/lib/sli/helpinit.sli
|