SWI-Prolog -- Running the documentation system

10 Running the documentation system

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

10.2 As a manual server

The library library(pldoc/doc_library) defines doc_load_library/0 to load the entire library.

doc_load_library

Load all library files. This is intended to set up a local documentation server. A typical scenario, making the server available at port 4000 of the hosting machine from all locations in a domain is given below.

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

10.3 Using the browser interface

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.

10.3.1 Searching

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>. A search for adjacent strings is specified 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.

10.3.2 Views

The web-browser supports several views, which we briefly summarise here:

Directory
In directory-view mode, the contents of a directory holding Prolog source-files is shown file-by-file in a summary-table. In addition, the contents of the README and TODO files is given.
Source File
When showing a Prolog source-file it displays the module documentation from the /** <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.}
Predicate
When selecting a predicate link the system presents a page with the documentation of the predicate. The navigation bar allows switching to the Source File if the documentation comes from source or the containing section if the documentation comes from a manual.
Section
Section from the manual. The navigation bars allows viewing the enclosing section (Up).

10.3.3 Editing

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.

10.4 library(doc_files): Create stand-alone documentation files

To be done: Generate a predicate index?

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.

doc_save(+FileOrDir, +Options)

Save documentation for FileOrDir to file(s). Options include

format(+Format): Currently only supports html.
doc_root(+Dir): Save output to the given directory. Default is to save the documentation for a file in the same directory as the file and for a directory in a subdirectory doc.
title(+Title): Title is an atom that provides the HTML title of the main (index) page. Only meaningful when generating documentation for a directory.
man_server(+RootURL): Root of a manual server used for references to built-in predicates. Default is http://www.swi-prolog.org/pldoc/
index_file(+Base): Filename for directory indices. Default is index.
if(Condition): What to do with files in a directory. loaded (default) only documents files loaded into the Prolog image. true documents all files.
recursive(+Bool): If true, recurse into subdirectories.
css(+Mode): If 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.
include_reexported(+Boolean): When true (default false), include predicates that are re-exported from this module into the documentation of the module.

10.5 Including PlDoc in a LaTeX document

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)"

10.5.1 Predicate reference for the LaTeX backend

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.

[det]doc_latex(+Spec, +OutFile, +Options)

Process one or more objects, writing the LaTeX output to OutFile. Spec is one of:

Name / Arity: Generate documentation for predicate
Name // Arity: Generate documentation for DCG rule
File: If File is a prolog file (as defined by user:prolog_file_type/2), process using latex_for_file/3, otherwise process using latex_for_wiki_file/3.

Typically Spec is either a list of filenames or a list of predicate indicators. Defined options are:

stand_alone(+Bool): If true (default), create a document that can be run through LaTeX. If false, produce a document to be included in another LaTeX document.
public_only(+Bool): If true (default), only emit documentation for exported predicates.
section_level(+Level): Outermost section level produced. Level is the name of a LaTeX section command. Default is section.
summary(+File): Write summary declarations to the named File.
modules(+List): If [[Name/Arity]] needs to be resolved, search for the predicates in the given modules.
module(+Module): Same as modules([Module]).

[det]latex_for_file(+File, +Out, +Options)

Generate a LaTeX description of all commented predicates in File, writing the LaTeX text to the stream Out. Supports the options stand_alone, public_only and section_level. See doc_latex/3 for a description of the options.

[det]latex_for_wiki_file(+File, +Out, +Options)

Write a LaTeX translation of a Wiki file to the steam Out. Supports the options stand_alone, public_only and section_level. See doc_latex/3 for a description of the options.

[det]latex_for_predicates(+PI:list, +Out, +Options)

Generate LaTeX for a list of predicate indicators. This does not produce the \begin{description}...\end{description} environment, just a plain list of \predicate, etc. statements. The current implementation ignores Options.