10.1 During development

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_collect(+Bool)

Enable/disable collecting structured comments into the Prolog database. See doc_server/1 or doc_browser/0 for the normal way to deploy the server in your application. All these predicates must be called before loading your program.

doc_server(?Port)

Start documentation server at Port. Same as 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.

doc_server(?Port, +Options)

Start documentation server at Port using Options. Provided options are:

root(+Path)

Defines the root of all locations served by the HTTP server. Default is /. Path must be an absolute URL location, starting with / and ending in /. Intented for public services behind a reverse proxy. See documentation of the HTTP package for details on using reverse proxies.

edit(+Bool)

If 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(+HostOrIP)

Allow connections from HostOrIP. If Host is an atom starting with a’.’, suffix matching is preformed. I.e. 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,_)).

deny(+HostOrIP)

Deny access from the given location. Matching is equal to the allow option.

Access is granted iff

• Both deny and allow match
• allow exists and matches
• allow does not exist and deny does not match.

doc_browser

Open the user's default browser on the running documentation server. Fails if no server is running.

doc_browser(+Spec)

Open the user's default browser on the specified page. Spec is handled similar to edit/1, resolving anything that relates somehow to the given specification and ask the user to select.^{bugThis flexibility is not yet implemented}.