This program generates HTML-documentation files of linoleum source files.
The linodoc information will be stored between parenthesis, '(' and ')', where also normal linoleum comments will be stored. This way it will be fully compatible with the linoleum compiler. To mark the comments as linodoc information, the opening 'tag' is:"(**" and the closing 'tag' is: "*)".There are three main sections to comment:
prog: used for programs lib: used for libraries fun: used for routines One file can have only one of the sections Program or Library, but can have several routine-sections. The sections are marked by special keywords, which are marked by an ampersand (&). These three sections can contain other keywords to describe certain information. The next keywords exist:
prog, lib, fun, param, authors, include, prototype, copyright, license, commandline, rem.
Besides the keywords, there are two other options which can be used to describe code:
- @P[number]: Used in the fun section, where @P[number] references a parameter in the parameter section of the same fun.
f.e.:
&fun Swap:This fun swaps the values in @P1 and @P2.
¶m 1 in reg a:value 1
2 in reg b:value 2 This will generate the following code:
This fun swaps the values in Input Register a and Input Register b.- @R[fun]: Can be used throughout the complete file, to reference a fun in the same file. When the fun has spaces in its name, the name has to be included between quotes, like: @R"copy string". It generates a link to the fun.
Program:&prog NAME [:DESCRIPTION]
NAME: The name of the prog. DESCRIPTION: Optional description or short manuel of the prog. This keyword marks the document as a program. The name of the program has to be specified, because it will be used in other parts of the documentation. The description is optional. In a program, the following other keywords may be used: fun, authors, include, copyright, license, commandline, rem.
Library:&lib NAME [:DESCRIPTION]
NAME: The name of the library. DESCRIPTION: Optional description of the library. This keyword marks the document as a library. The name of the library has to be specified, because it will be used in other parts of the documentation. The description is optional. In a library, the following other keywords may be used: fun, authors, include, copyright, license, rem.
Routine:&fun NAME [:DESCRIPTION]
NAME: The name of the routine. DESCRIPTION: Optional description of the routine. This keyword marks the next section as routine documentation. The name of the routine has to be specified. The description of the routine is optional, but it's highly encouraged to include a short description. Before the routines will be included in the documentation, a table with all the routine names and -where specified- the description will be included. This table will contain links to the actual documentation of the routines.
In the documentation of a routine, special codes can be used to include parameters:
@P NMB: The number has to follow the "@P" directly. Whereever this string exists, it will be replaced with:"input/output register/variable NAME".The following keywords may be used in a fun section: param, authors, prototype, rem.
Parameters:¶m NMB IN/OUT REG/VAR NAME: DESCRIPTION [, NMB IN/OUT REG/VAR NAME: DESCRIPTION] ...
NMB: The number of the parameter. IN/OUT: Specifies if used as input or output parameter. REG/VAR: Specifies the type of the parameter. NAME: The name of the parameter. DESCRIPTION: Optional description of the parameter. This keyword describes the parameters of a fun.
The number of the parameter is of no importance, but the '@P'-option uses the number of the parameter in the row, with @P1 being the first one. So it is clear to number the param starting by one. It's best to start with the input parameters and end with the output parameters.
Note that none of the fields are optional, they all have to be specified.
Rem:&rem TEXT
TEXT: Text which will just be included. This includes a new section with a remark. Only the text will be included.
Prototype:&prototype TEXT
TEXT: Text which will just be included.
Authors:&authors AUTHOR [: E-MAIL] [, AUTHOR [: E-MAIL]] ...
AUTHOR: Name of the author. : Optional E-mail adress of the author. This section is used to mention the authors of the document, or of the current fun. Optionally an e-mail address can be included, to make a "mailto:"-link in the document.
Include:&include LIBRARY [: DOCUMENTATION] [, LIBRARY [: DOCUMENTATION]] ...
LIBRARY: Name of the lib. DOCUMENTATION: Optional name of documentation file. Here included libraries can be mentioned, with optional links to the documentation files. If no documentation-file is specified, the link will point to the name of the source-file, extended with ".html".
Copyright:©right YEAR and COPYRIGHT HOLDER(S)
YEAR and COPYRIGHT HOLDER(S): Text of copyright notice. This is used to include a copyright paragraph in the document.
License:&license NAME: NOTICE
NAME: Name of license. NOTICE: Text of license. This is used to insert a license-paragraph.
Commandline:&commandline TEXT
TEXT: Text to include. This is used to describe the command line of the prog and the param passed through it.
HTML-tags can be included in the text, to change the layout of the documentation, for example to generate lists or tables.
Linoleum source files to generate documentation for. When no files are passed, nothing happens.
Peterpaul Klein Haneveld
© 2003 by Peterpaul Klein Haneveld
LGPL
This lib is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.This lib is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.You should have received a copy of the GNU Lesser General Public
License along with this lib; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA