spuds: persistent, user code inclusive, doc server for linux

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 xref_source(Abs,[comments(store),silent(Silent)]) 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 $HOME/.pl/spuds_profile_<Hostname>.pl or $HOME/.pl/spuds_profile.pl . 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 source files) the corresponding parts will be ignored. In this case so_sub/3 is used instead of doc_load_library/1.
• 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 os_sub(Dir,Opts).
• prolog_source_file( -File ) serve this file
• spuds_debug( Debug ) be verbose and silent(false) for all loads of spuds server

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 xref_source(File,[comments(store),silent(true)]) otherwise.

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

• ability to start background prolog script from within Prolog
• ability to get pid from script name (can work around this one with pid files)
• ability to kill a process by script name or pid.

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

spuds stands for, Spuds Persistent User-code-inclusive Documentation Server

author

- Nicos Angelopoulos

version

- 0:1:4

See also

- http://stoics.org.uk/~nicos/sware/spuds

- pack(spuds)

- pack(spuds/profiles)

license

- Perl Artistic

To be done

- support for other oses (MacOs should be a matter of using the correct ps flags).

- add seconds delay option

spuds_version (-Version, -Date)

Version and release Date (date(Y,M,D) term).

spuds_pid (-Pid)

Process id of any running spud server(s). Non-deterministic. There should ever only be one process maximum, if all is working properly.

spuds_stop

Kill the spuds server. True iff a single server can be found. If there are mulitple servers funning use spuds_stop_pid/1 to force a quit.

spuds_stop_pid (Pid)

Kill the spuds server with process id, Pid. The predicate checks in the output of ps linux command to verify that the process id matches to a spuds server.

spuds_restart

Restart the spuds server. It does not complain if one cannot be found. No browser tabs/windows are open.

spuds_start

Start the spuds server. It prints an error and aborts if one is already running.

spuds (Topic)

Open a new web browser tab (www_open_url/1) on spuds server for query Topic. If there is no spuds server running, start one. This is run in the background and will persist beyond the limits of the current session. The spuds server can be managed with spuds_stop/0, spuds_pid/1 and spuds_restart/0 from any Prolog session.

spuds_profile_file (-ProFile)

Locates user's Profile file.