PrologDoc was created in 1999 by:
In october 2004, Bram Adams (bram.adams AT ugent.be) reworked it for own, non-commercial use. He adjusted a number of things:
At the end of the month, it got released on sourceforge.net with version number 1.0RC1 and it started a whole new life. Soon Salvador Fandino (sfandino@yahoo.com) joined.
with as options:
By default, directories $libdir/prologdoc/prolog and $libdir/prologdoc/css are created. $libdir is /usr/local/lib by default, but can also be set: have a look at './configure --help'. The SWI-Prolog executable, if not specified explicitly to './configure', is supposed to be called swipl or pl. If not found on the path, an error message will display. The same holds for the Perl executable, this time with the name perl.
pldoc [options] file1.pl file2.pl ...
with as possible options:
[-v|--verbose] | Toggles verbose mode. |
[-l|--load preload_file] | Should contain the custom operators used in the source code you want to document. These will be preloaded before parsing the source code. |
[-p|--prefix prefix_for_html_elements] | Enables the use of css-stylesheets on other locations than the one specified at configure-time or on remote servers (i.e. --prefix=http://style_sheets/). |
[-s|--side-effects] | Determines whether side effects should be documented. |
[-f|--footer | Should be a string between quotation marks containing a footer which will be displayed on the generated HTML-pages. E.g.: pldoc -f "Copyright (c) 2004. All rights reserved." peanuts.pl |
[-t|--to dest_dir] | Destination directory of the generated documentation. By default, the current working directory is used. |
[-z|--tracer] | Enables GUI-less debugging. |
[-Z|--gui-tracer] | Enables graphical debugging. |
[-?|--help] | Shows usage info. |
Examples:
For extra help, do 'man PrologDoc'.
When documenting a Prolog program "filename", the following information is automatically inserted in PrologDoc documentation, without user intervention:
that "filename" consults.
Example: if "filename" contains
:- [file1,file2].
then file1 and file2 will be included in this list.
that "filename" uses.
Example: if "filename" contains
:- use_module(library(system)).
then system will be included in this list.
encountered when loading "filename".
Example: if "filename" contains
:- foo(bar).
then this predicate will be included in this list.
Note: generation of side effects documentation is toggled off by default. Use
$ pldoc --side-effects ...
to activate it.
defined in "filename".
Note: This list will include only exported predicates if "filename" is defined as a module.
if "filename" is defined as a module.
Using the PrologDoc syntax enables you to extensively document predicates that you define. A PrologDoc predicate
comment is defined within
/** blah, blah, blah... */
It should be placed immediately before the predicate it is
documenting. The PrologDoc syntax is similar to JavaDoc.
The following tags can be used within a predicate comment:
For giving a general description of the predicate
is used to define the general form of the predicate
Used to define constraints on the parameters.
After a @contraints tag there can be a series of:
to define a parameter that must be ground
to define a parameter that can not be ground
to define a parameter that is not restricted
There can be several @constraints tags to define different options of constraining parameters.
Example: the following could be a predicate comment for the member predicate:
/**
@form member(Value,List)
@constraints
@ground Value
@unrestricted List
@constraints
@unrestricted Value
@ground List
@descr True if Value is a member of List
*/
Using PrologDoc you can give a general description to the
file. This enables you to globally document the purpose of
the prolog program defined within. A general file comment
is defined within
/*** blah, blah, blah... */
and may be located anywhere in the file. The following
tags can be used within a predicate comment:
for giving a general description of the file
to specify the name of an author
to specify the date creation of the file
Note: since the values of the tags are copied "as is" into the HTML documentation, HTML tags may be used within these values.
Example:
/***
@descr This file is used for many thing. Among them are:
<ul>
<li> Purpose 1 ?
<li> Purpose 2 ?
</ul>
@author John Smith
@date 1/1/00
*/
# This file is part of PrologDoc (http://prologdoc.sourceforge.net/).
#
# Copyright (C) 1999 by Elisheva Bonchek (le7bonch AT cs.huji.ac.il)
# and Sara Cohen (sarac AT ie.technion.ac.il, http://iew3.technion.ac.il/~sarac)
# Copyright (C) 2004 by Bram Adams (bram.adams AT ugent.be)
# Copyright (C) 2004 by Salvador Fandino (sfandino@yahoo.com)
#
#
# PrologDoc is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# PrologDoc 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 General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with PrologDoc; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA