[Sisc-users] Possible docs patches

[Norman G. <no...@as...>]

Greetings.

I've attached a small patch with documentation suggestions.  These  
are against the current SISC HEAD.

This contains a few additions to the recently expanded (thanks!)  
description of how to call Scheme from Java.  In particular, it  
mentions the execute(sisc.interpreter.SchemeCaller) method as well as  
the execute 
(sisc.interpreter.AppContext,sisc.interpreter.SchemeCaller) method,  
and suggests that the former is the preferred one if the programmer  
has no particular need for a non-default AppContext or Heap.  This  
was the impression I'd gleaned from the recent discussion of this new  
interface here -- perhaps I'm wrong.  My aim was to emphasise the  
simplicity of the new interface.  I made a few other wording changes  
nearby that seemed worth while.

The patch also adds javadoc comments to a (very) few routines.  This  
addition isn't systematic, but consists, more-or-less, of the notes I  
made when I was recently trawling through the API.  These javadocs  
now compile without warnings.

As an addition, I added a line to build.xml which makes it read a  
file build.properties if it exists in the current directory.  This is  
very convenient if you have required files in non-standard locations,  
or if you want to install in a non-standard location (myself, I  
override doc.style and prefix in this file).  It has no effect if the  
file is missing.

As a final point, can I suggest that the javadocs be installed  
alongside the manual?  Since the manual does refer to the API, it  
takes one a little by surprise to find that the javadocs aren't  
installed.

I hope these suggestions are useful.  Use, discard or hack them at  
your pleasure!

Best wishes,

Norman


-- 
------------------------------------------------------------------------ 
----
Norman Gray  /  http://nxg.me.uk
eurovotech.org  /  University of Leicester, UK