Subject: Re: 3 issues

From: Jan Wielemaker <[email-masked]>
Date: Fri, 25 Jun 1999 10:30:03 +0200

Dear Lukas

On Fri, 25 Jun 1999, you wrote:

>1) the link <http://swi.psy.uva.nl/usr/jan/mailinglist/archive> on page
><http://swi.psy.uva.nl/usr/jan/SWI-Prolog.html> to the archive of the
>swi-prolog mailing list seems to be broken.

Works fine from the real home page at:

	http://www.swi.psy.uva.nl/projects/SWI-Prolog.html

The page you mentioned (the old home) has been changed in a page that
directs you to the proper location.  Thanks for warning me.

>2) concerning garbage collection of atoms: are there plans to implement
>   it someday? What are the obstacles to it? Do I understand you right
>   that strings are garbage collected?

Strings are handled as terms and numbers: they live on the stack and are
removed on backtracking or garbage collection.

There aren't real problems in supporting atom garbage collection, except
that it is a lot of work.  Atoms are used all over the place and a
conbination of searching the stacks (as in normal GC) and reference
counting has to implemented to locate the garbage atoms.  Especially
realising reference counting implies numerous changes throughout all
foreign code.

>3) I'd like to extend the existing online help (help/1, apropos/1) with
>   the documentation of my own modules. How can I achieve that?  Most helpful
>   would be if one could embed the documentation within the prolog
>   source code and extract and format it both in nroff format for online
>   help as well as in HTML format, similar to the documentation builder
>   of java. 

We have no ready-made solution to that (though I appreciate it would be
useful).  It shouldn't be too hard to think of reasonable hooks into
help/1 and friends to allow for user extendable help format: just make
help/1 call some user defined hook predicate to provide additional
answers.  I guess you can manage that and if it looks sensible I will
integrate it into the base system.

Harder is the code itself.  There are zillions of options there,
depending largely on your background.  Basically I guess some special
Prolog comment delimiters should start/end documentation, so code is
immediately readable by Prolog.

But for the format, there is nroff, LaTeX, texinfo, html, xml or even
plain text with very strict layout conversions.  Prolog documentation
itself is in LaTeX with a macro layer to deal with Prolog primitives
and preprocessor to deal with some layout conventions (i.e.
member/2 is a reference to the predicate member with two arguments).

I would rule out nroff as unreadable.

Problem with LaTeX is that it is too easy to write layout that cannot
easily be converted to plain text or HTML.

texinfo is a better choice, but it is not very suited for Prolog and
not extensible.

html is too layout oriented.

So, I think I would go for XML (or maybe better SGML to be a bit more
relaxed on the tagging conventions).  For all practical purposes I would
also introduce some layout conventions to be translated automatically
(you a preprocessor anyhow to strip the documentation from the Prolog
source).
	
We are working on providing SGML/XML support libraries for SWI-Prolog
based on James Clarks SP library for SGML/XML.  That can be used to
provide query and conversion tools.

	Regards --- Jan