To support the developer with an up-to-date version of the
documentation of both the application under development and the system
libraries the developer can start an HTTP documentation server using the
command
doc_server(?Port). A good way to deploy PlDoc for program
development is to write a file called e.g., debug.pl that
sets up the preferred development environment and loads your program.
below is an example debug.pl that starts PlDoc and prints
strings as text before loading the remainder of your program.
:- doc_server(4000). % Start PlDoc at port 4000 :- portray_text(true). % Enable portray of strings :- [load]. % load your program
doc_server(Port, [allow(localhost), workers(1)]). This
predicate must be called before loading the program for which
you consult the documentation. It calls doc_collect/1
to start collecting documentation while (re-)loading your program.///false, do not allow editing, even if the connection
comes from localhost. Intended together with the root
option to make pldoc available from behind a reverse proxy. See the HTTP
package for configuring a Prolog server behind an
Apache
reverse proxy.allow('.uva.nl')
grants access to all machines in this domain. IP addresses are specified
using the library(socket) ip/4
term. I.e. to allow access from the 10.0.0.X domain, specify
allow(ip(10,0,0,_)).allow option.Access is granted iff
The library library(pldoc/doc_library) defines doc_load_library/0
to load the entire library.
:- doc_server(4000,
[ allow('.my.org')
]).
:- use_module(library(pldoc/doc_library)).
:- doc_load_library.
Example code can be found in $PLBASE/doc/packages/examples/pldoc.
The documentation system is normally accessed from a web-browser after starting the server using doc_server/1. This section briefly explains the user-interface provided from the browser.
The top-right of the screen provides a search-form. The search string
typed is searched as a substring and case-insensitive. Multiple strings
separated by spaces search for the intersection. Searching for objects
that do not contain a string is written as -"<string>".
Here are some examples:
load file | Searches for all objects with the
strings
load and file. |
load -file | Searches for objects with load,
but
without file. |
"load file" | Searches for the string load
file. |
The two radio-buttons below the search box can be used to limit the search. All searches both the application and manuals. Searching for Summary also implies Name.
The web-browser supports several views, which we briefly summarise here:
README and TODO files is
given.
/** <module ... */ comment and the public
predicates with their full documentation. Using the zoom button
the user can select to view both public and documentated private
predicates. Using the source button, the system shows the source
with syntax highlighting as in PceEmacs and formatted structured
comments.7This mode is still
incomplete. It would be nice to add line-numbers and links to
documentation and definitions in the sources.
If the browser is accessed from localhost, each object
that is related to a known source-location has an edit icon at the right
side. Clicking this calls edit/1
on the object, calling the user's default editor in the file. To use the
built-in PceEmacs editor, either set the Prolog flag editor
to pce_emacs or run ?- emacs. before clicking
an edit button.
Prolog source-files have a reload button attached. Clicking this reloads the source file if it was modified and refreshes the page. This supports a comfortable edit-view loop to maintain the source-code documentation.
Create stand-alone documentation from a bundle of source-files. Typical use of the PlDoc package is to run it as a web-server from the project in progress, providing search and guaranteed consistency with the loaded version. Creating stand-alone files as provided by this file can be useful for printing or distribution.
file(s). Options
include
html.doc.http://www.swi-prolog.org/pldoc/index.loaded (default) only
documents files loaded into the Prolog image. true
documents all files.true, recurse into subdirectories.copy, copy the CSS file to created directories. Using inline,
include the CSS file into the created files. Currently, only the default copy
is supported.
The typical use-case is to document the Prolog files that belong to a
project in the current directory. To do this load the Prolog files and
run the goal below. This creates a sub-directory doc with
an index file index.html. It replicates the directory
structure of the source directory, creating an HTML file for each Prolog
file and an index file for each sub-directory. A copy of the required
CSS and image resources is copied to the doc directory.
?- doc_save(., [recursive(true)]).
The LaTeX backend aims at producing quality paper documentation as
well as integration of predicate description and Wiki files in LaTeX
documents such as articles and technical reports. It is realised by the
library doc_latex.pl.
The best practice for using the LaTeX backend is yet to be
established. For now we anticipate processing a Wiki document saved in a
.txt file using doc_latex/3 to
produce either a simple complete LaTeX document or a partial document
that is included into the the main document using the LaTeX \input
command. Typically, this is best established by writing a Prolog
Script that generates the required LaTeX document and call this from
a Makefile. We give a simple example from PlDoc, creating this
section from the wiki-file latex.txt below.
:- use_module(library(doc_latex)). :- [my_program].
We generate latex.tex from latex.txt using this Makefile
fragment:
.SUFFIXES: .txt .tex
.txt.tex:
swipl -f script.pl \
-g "doc_latex('$*.txt','$*.tex',[stand_alone(false)]),halt" \
-t "halt(1)"
High-level access is provided by doc_latex/3,
while more low level access is provided by the remaining predicates.
Generated LaTeX depends on the style file pldoc.sty, which
is a plain copy of pl.sty from the SWI-Prolog manual
sources. The installation installs
pldoc.sty in the pldoc subdirectory of the
Prolog manual.
/ Arity// ArityTypically Spec is either a list of filenames or a list of predicate indicators. Defined options are:
true (default), create a document that can be run
through LaTeX. If false, produce a document to be included
in another LaTeX document.true (default), only emit documentation for exported
predicates.section.modules([Module]).stand_alone, public_only
and section_level. See doc_latex/3
for a description of the options.stand_alone, public_only
and
section_level. See doc_latex/3
for a description of the options.\begin{description}...\end{description}
environment, just a plain list of \predicate, etc.
statements. The current implementation ignores Options.