This library creates, uses and manages a persistent documentation server on a single port. In addition to serving all Prolog library code as per doc_server/1, spuds/1 also serves installed packs and all user code declared as such, on the same server.
spuds is available as a SWI-Prolog pack, and can be installed the usual way.
pack_install( spuds ).
Since 0:1:0 spuds supports http_daemon/0. It also provides a swipl-spuds bash shell file (pack(spuds/server/'swipl-spuds')), to be placed in the /etc/init.d/ directory. This is a direct copy from the SWI file. It follows well after standard scripts for servers starting/stopping. And can be used when you want all documents to be available as an independent server.
Pack files from
swi(pack/.../prolog/...) are loaded via
use_module(File,]).User documentation files are also
loaded via use_module if their first term is a module declaration, otherwise
their comments are loaded by
use_module/2 has the side-effect of loading the code on to the server.
If we were to load module files by xref/2, the downside would be that
as far as we understand SWI will not serve the module page correctly
(particularly missing the top comments that describe module files).
Currently to ask for help users need to call
spuds(Topic) although ideally one
can use help_hook/1 in which case normal route via help/1 should be possible.
When looking for help pages, the library tries to locate a running spuds server. If one is not found, it starts one. The behaviour of this server can be controlled via a set of predefined terms/clauses in a user profile file. spuds/1 also starts a new web browser window pointing to the spuds server on the requested topic.
The default profile location is
An alternative location can be provided via (user:)spuds_profile/1.
In you profile you can add:
blocked_sys_library( 'jpl.pl' )if any of those are defined matcing system libraries, (whole dirs or
doc_server_default( port, 4001 )port for the spuds server
doc_server_default( start_opens_browser, false )should spuds_start, start a browser ?
file_is_blocked_prolog_source( +AbsFile ).pl file that shouldn't be served
file_is_prolog_source( +AbsFile )non .pl file that should be served
prolog_source_directory( -Dir )all Prolog files in Dir will be served
prolog_source_directory( -Dir, -Opts )all Prolog files in Dir will be served if returned by
prolog_source_file( -File )serve this file
debug(spuds)be verbose (reporting in /
Docs for each
prolog_source_file are loaded to the spuds server by means of:
use_module( File,  ) if the File in question is a module file or
Documentation for each prolog file within each
prolog_source_directory is also
loaded similarly. Note you need library(os_sub) for this to work.
This is available as a pack install as per usual via
pack_install( os_sub ).
Within each source directory (Dir above) files are considered to be Prolog source if there is no barring success of the call file_is_blocked_prolog_source/1 and either file has extension 'pl' or the call file_is_prolog_source/1 succeeds. These calls are performed with the absolute location of the file as argument.
The server only works under linux. Compatibility patches to other platforms are very welcome. For MacOs there should be a trivial change on the ps flags, if that, that should be sufficient. For other systems we need
To pick changes to the user code base up and even those on Swi (say after you installed a new version) the server needs to be restarted. This can be done via spuds_restart/0.
One scenario for starting the server as a debian server, including at start time,
copy spuds/server/swipl-spuds into /etc/init.d/ then follow the instrunctions in the file.
Usually you want to make a clean place where from the server runs.
So for instance create /srv/www/html/spuds/ and copy into it
spuds/server/spuds_daemon.pl (along with
spuds_docs.pl from same place).
On you window manager you can then have a launcher that points to:
$PREFIX/swipl -f none -g "use_module(library(www_browser)), www_open_url('http://localhost:4004/index.html'), sleep(1), halt(0)"
spuds stands for, Spuds Persistent User-code-inclusive Documentation Server
server(s). Non-deterministic. There should ever only be one process maximum, if all is working properly.
pslinux command to verify that the process id matches to a spuds server.