SourceForge.net Logo

PrologDoc

What is it?

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.

Installation

  1. install SWI-Prolog (freely available on http://www.swi-prolog.org/)
  2. unpack the .tar.gz-file to a directory D
  3. cd D
  4. ./configure [options]

    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.

  5. make
  6. su
  7. make install (alternatively on Slackware: checkinstall)
  8. We supply a default style.css, which you can change or replace if needed. It's located in the specified css-directory.

Use

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'.

Tags

Automatically generated information

When documenting a Prolog program "filename", the following information is automatically inserted in PrologDoc documentation, without user intervention:

Predicate-specific comments

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:

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
*/

General file comments

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:

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
*/

FAQ

  1. Is embedded HTML-code possible?
  2. Why do embedded lists in file comments look so weird?
  3. Why do embedded lists in predicate comments look so weird?

  1. Yes, but be cautious with <ul>'s and <ol>'s (see b) and c)). Use \" instead of " in the tags (e.g. <font color=\"Red\">).
  2. End possible text before the list with </p> and start text after it with <p>.
  3. Known bug ;-).

Future work

# 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