Did you know ... | Search Documentation: |
Pack spuds -- prolog/spuds.pl |
This library is largely obsolete, however examples/spudlike.pl
is actively maintained.
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
doc_server_default( port, 4001 )
port for the spuds serverdoc_server_default( start_opens_browser, false )
should spuds_start, start a browser ?file_is_blocked_prolog_source( +AbsFile )
.pl file that shouldn't be servedfile_is_prolog_source( +AbsFile )
non .pl file that should be servedprolog_source_directory( -Dir )
all Prolog files in Dir will be servedprolog_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 filedebug(spuds)
be verbose (reporting in /tmp/spuds_debug.txt
)
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
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
date(Y,M,D)
term).server(s)
. Non-deterministic.
There should ever only be one process maximum, if all is working properly.ps
linux command to verify that the process
id matches to a spuds server.