Best way to read the reference manual locally?

Help!
1

If I remember correctly, there was at one point a fairly convenient way to launch a local web server serving a local copy of the reference manual. (And did typing help(foo) automatically launch the web browser? Maybe.)

Is that still available (assuming I am remembering correctly that it was once available)?

I am currently not finding any description in the reference manual of how to run the reference manual locally. (I see what looks like a full set of HTML documents inside /Applications/SWI-Prolog.app, but Safariā€™s ā€˜Open Fileā€™ dialog refuses to let me navigate into the app directory to select an HTML page to open. And I also see what looks like a way to browse auto-generated documentation for the Prolog source. I donā€™t see anything that is nearly as simple as I remember it being.)

Iā€™m using SWI-Prolog version 8.0.3, or was, until I installed 8.1.19 just now, trying to figure where the XPCE interface to the reference manual had gone (sigh ā€“ I did like it, and Iā€™m sorry itā€™s gone away).

Two reasons that I think I want to read the reference manual locally instead of only at https://eu.swi-prolog.org/pldoc/refman ā€“

(1) I do spend time in places where I donā€™t have good network connectivity (and yes, sometimes I pass the time in those places by writing programs for which I need the manual).

(2) I donā€™t always pick up new versions of swipl (or any other program) quickly, and it can be very confusing when something has changed and the description on the swi-prolog.org web site does not match the behavior of my running system. Much of this evening went to trying to puzzle out why the reference manual says the user initialization file is called init.pl, and the FAQ says itā€™s called .plrc, and what version 8.0.3 wants to see is .swiplrc; I suspect that that would have been easier to resolve had I been looking at a reference manual that matched my installed version. (It would still be helpful if the reference manual mentioned both old and new behavior, for changes like that one.)

Many thanks for any advice or help.

ā€“C. M. Sperberg-McQueen

P.S. A little further experimentation shows that something like

:- doc_server(Port).
:- use_module(library(pldoc/doc_library)).
:- doc_load_library.
:- doc_browser.

does something like what I remember and was hoping for. (Itā€™s not quite perfect, because the call to doc_load_library produces a screen or two of error messages over a not-found dynamic library, and the web server is sending log messages to the console, which would be distracting in the long run. But itā€™s progress. Iā€™m leaving the post up, though, in the hopes that someone will show me a better way that I would have found if I had managed to RTFM.)

1 Like
2

This is what I have been using in a external Swi-Prolog process.
The http_get/3 makes document system to setup itself, it takes annoingly long (seconds with my cheap Windows laptop) when setting up is done at a first call from Http browser. sleep/1 allows doc_server some time to setup itself. Inputting ā€œexit.ā€ exits the process.

Bug: doesnā€™t show help texts from the program under development.

:- module(docserverexe,[init/0]).
:- use_module(library(http/http_client)).

init:-
    window_title(_,'Document server'),
    writeln('Document server starting...'),
    doc_server(7000),
    sleep(1),
    http_get('http://localhost:7000/pldoc/doc_for?object=manual',_,[]),
    writeln(' \'exit.\' to exit'),
    read(exit).
3

All I do is call doc_browser as a directive inside a project load file. On windows I double-click the project load file and the documentation server starts and displays the README.md file in my projectā€™s root in my browser. My projectā€™s files are all accessible from a drop-down list above the README and lnks under it and those files that have a module header and documentation blocks for predicates also show them when I navigate to them.

The full Swi documentation is there too, under the drop-down list. The port for the documentation browser is chosen automatically I guess so if I close the project and reload it I get a new tab in my browser with the documentation, but if I refresh the old tab it gives me a 404ā€¦ I think?

Maybe you donā€™t need all the other directives you list in your post?

1 Like