doc_http.pl -- Documentation server

The module library(pldoc/http) provides an embedded HTTP documentation server that allows for browsing the documentation of all files loaded after library(pldoc) has been loaded.

doc_enable(+Boolean)

Actually activate the PlDoc server. Merely loading the server does not do so to avoid incidental loading in a user HTTP server making the documentation available.

doc_server(?Port) is det

doc_server(?Port, +Options) is det

Start a documentation server in the current Prolog process. The server is started in a separate thread. Options are handed to http_server/2. In addition, the following options are recognised:

allow(HostOrIP): Allow connections from HostOrIP. If HostOrIP is an atom it is matched to the hostname. It if starts with a ., suffix match is done, matching the domain. Finally it can be a term ip(A,B,C,D). See tcp_host_to_address/2 for details.
deny(HostOrIP): See allow(HostOrIP).
edit(Bool): Allow editing from localhost connections? Default: true.

The predicate doc_server/1 is defined as below, which provides a good default for development.

doc_server(Port) :-
        doc_server(Port,
                   [ allow(localhost)
                   ]).

See also: - doc_browser/1

doc_current_server(-Port) is det[private]

TCP/IP port of the documentation server. Fails if no server is running. Note that in the current infrastructure we can easily be embedded into another Prolog HTTP server. If we are not started from doc_server/2, we return the port of a running HTTP server.

Errors: - existence_error(http_server, pldoc)
To be done: - Trap destruction of the server.

doc_browser is det

doc_browser(+What) is semidet

Open user's default browser on the documentation server.

prepare_editor[private]

Start XPCE as edit requests comming from the document server can only be handled if XPCE is running.

pldoc_root(+Request)[private]

Reply using the index-page of the Prolog working directory. There are various options for the start directory. For example we could also use the file or directory of the file that would be edited using edit/0.

pldoc_index(+Request)[private]

HTTP handle for /index.html, providing an overall overview of the available documentation.

pldoc_file(+Request)[private]

Hander for /file?file=File, providing documentation for File.

pldoc_edit(+Request)[private]

HTTP handler that starts the user's default editor on the host running the server. This handler can only accessed if the browser connection originates from localhost. The call can edit files using the file attribute or a predicate if both name and arity is given and optionally module.

go_place(+Request)[private]

HTTP handler to handle the places menu.

allowed_directory(+Dir) is semidet[private]

True if we are allowed to produce and index for Dir.

allowed_file(+File) is semidet[private]

True if we are allowed to serve File. Currently means we have predicates loaded from File or the directory must be allowed.

pldoc_resource(+Request)[private]

Handler for /res/File, serving CSS, JS and image files.

pldoc_doc(+Request)[private]

Handler for /doc/Path

Reply documentation of a file. Path is the absolute path of the file for which to return the documentation. Extension is either none, the Prolog extension or the HTML extension.

Note that we reply with pldoc.css if the file basename is pldoc.css to allow for a relative link from any directory.

edit_options(+Request, -Options) is det[private]

Return edit(true) in Options if the connection is from the localhost.

pl_file(+File, -PlFile) is semidet[private]

wiki_file(+File, -TxtFile) is semidet[private]

True if TxtFile is an existing file that must be served as wiki file.

clean_path(+AfterDoc, -AbsPath)[private]

Restore the path, Notably deals Windows issues

pldoc_man(+Request)[private]

Handler for /man, offering one of the parameters:

predicate=PI: providing documentation from the manual on the predicate PI.
function=PI: providing documentation from the manual on the function PI.
CAPI=F: providing documentation from the manual on the C-function F.

pldoc_object(+Request)[private]

Handler for /doc_for?object=Term, Provide documentation for the given term.

pldoc_search(+Request)[private]

Search the collected PlDoc comments and Prolog manual.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.