README


Contents
--------

1. Contents of disc/ftp archive.
2. Bug fixes.
3. New features and changes.
4. Note.


1. Contents of disc/ftp archive
===============================


1.0 Top-level documentation, and disc/archive layout
----------------------------------------------------

This file is README. There is also a file called MODULES, which gives
information about programming style, module structure, and auxiliary
programs such as the Lint checker, autotester, and cross-referencer.


Skip the next few paragraphs if using FTP.


The disc distributed with this book ("The Logic Programming Tutor",
Jocelyn Paine, Intellect, 1992) is in MS-DOS format, high-density,
single-sided, 3.5 inch. It contains the following files:
    README.         This file.
    MODULES.        Programming style, etc.
    AUTOTEST.ARC    Autotester.
    KBS.ARC         Knowledge bases.
    LESSONS.ARC     Lessons and supplements.
    LINT.ARC        Lint checker.
    SOURCE.ARC      Source of Tutor.
    TRAVELLE.ARC    Traveller.
    XREF.ARC        Cross-referencer.
    ARC.EXE         Archiver/dearchiver.

Each .ARC file corresponds to a separate directory, and has been created
by running ARC.EXE from MS-DOS with the command line:
    arc a <archive name> *.*

To extract the files, create an MS-DOS directory of the appropriate
name, make it your current directory, and then run ARC with the
command line
    arc x <archive name>

All the resulting files will be text, so you can safely transfer them to
any other computer system via Kermit, Ethernet, Email, or whatever.


MS-DOS shortens all file and directory names to eight characters. You
will therefore have to rename some of the files once extracted,
particularly the source files such as ANALYSE_SDO.SDO. It also shortens
file extensions to three characters. This means that all my .LOGIC
knowledge bases become .LOG files. Nothing I can do about this: write to
Microsoft and tell them what a modern computer system looks like.


Just in case your version of MS-DOS rejects the ARC included here, it
will help to know what it is so you can find a copy that works. The
details displayed when it starts are
    ARC - Archive utility, Version 5.21, created on 04/22/87 at
      15:05:21
    (C) COPYRIGHT 1985,86,87 by System Enhancement Associates:
      ALL RIGHTS RESERVED

    Please refer all enquiries to:

        System Enhancement Associates
        21 New Street, Wayne NJ 07470


If you are using FTP, you should find this software stored as a TAR or
compressed TAR file. The original directory structure will be intact,
one directory for each batch of stuff, plus the top level files.


You will not be able to run the Tutor straight away, because a lot of it
is non-portable. Even if you are lucky enough to have Poplog Prolog, you
will still need to change the filenames in modules such as KBFILES. I
therefore suggest that you start by listing the modules, and reading
their implementation sections, in the order in which I describe them in
Chapter 4. I hope the portability hints will suffice for all but the
strangest Prolog implementation.


In the rest of this file, I assume you have set up the necessary
directories, and I refer to files and directories by their full names.


1.1 Lessons and supplements.
----------------------------

These are in directory \LESSONS. It contains the eight lessons, as
straight ASCII text, and the eight supplements, as LaTeX files.

To make the lessons readable by the Tutor, use program FILE_TO_TERMS, as
described in Chapter 4. I have done this for you, the resulting files
being given the extension .SCR, but you will have to redo it (after
modifying FILE_TO_TERMS) if your string-escape conventions are different
from mine.

For LaTeX users: The supplements contain my index commands, but with
"\index" replaced by "\idx", which is defined to be a null command. You
might want these if you want to build up your own index: in that case,
globally replace "\idx" by "\index".

The supplements use the style file ALLTT.STY, which is also included.
All this is used for is allowing index commands to appear in verbatim
text; if you don't need that, you can replace "alltt" by "verbatim"
throughout (but remove the index commands first!).

I have also left the teacher's annotations in the supplements, but
commented out.


1.2 Traveller.
--------------

This is in directory \TRAVELLER. It includes the board-definition file,
board-to-Prolog cconverter BOARDGEN.PL, source of Traveller, the
route-finder ROUTE.PL, the board-to-LaTeX concerter, and sample LaTeX
and PostScript output.


1.3 Knowledge bases.
--------------------

These are in directory \KBS. Files with extension .LOGIC are to be
restored; those with extension .PL are to be loaded.


1.4 Cross-referencer.
---------------------

This is in directory \XREF. It comes with a help file XREF.HLP.


1.5 Source.
-----------

This is in directory \SOURCE.


1.6 Lint program.
-----------------

This is in directory \LINT. Load LINTMASTER.PL, and call lint/2 from
LINT.PL to run it.


1.7 Autotester.
---------------

This is in directory \AUTOTEST. Read AUTOTEST.PRE to find out how
to use it.


2. Bug fixes.
=============


2.1 Lessons and supplements.
----------------------------

I have corrected several errors I'd missed in the lessons and
supplements. The corrected versions are on the disc. Amongst the
errors:

1) X \= marathon should give the answer "no", not "yes". (Lesson 5).

2) You don't need a dot after the replies when running DEPRESSION.LOGIC.
(Supplement 4).

3) The answer to (8^3)/3 in Lesson 6 was wrong.

4) 'next' as a predicate in Traveller won't work, because it clashes
with the 'next' command. I've renamed it to 'adjacent' in the source
files and supplements.

5) Section 30 of Lesson 8 should make it clear that the file to restore
is SIZE.LOGIC.


2.2 Book.
---------

2.2.1 Negative fact numbers.
----------------------------

There is an inconsistency in Chapter 3: the syntax says that negative
fact numbers are not allowed, but the Tutor actually permits them, so
that facts added with 'adda' can be manipulated. This is needed for
Traveller. Rewrite the syntax so that all fact numbers can be negative
or unsigned integers.

2.2.2 Editor.
-------------

In the listings of the editor, the calls to sync_database inside
append_fact and prepend_fact should use T0, not T. I have corrected this
in the source code.


3. New features and changes.
============================


3.1 The "ask" command.
----------------------

Syntax: ask --> [ask].

This re-asks the previous question, and reports an error if it doesn't
exist. The question-editing commands re-ask the result of their edit
anyway, but sometimes students want to take an existing question and try
it again without changes - perhaps because they have added some new
facts. This is what "ask" is for.


3.2 The "explain" command.
--------------------------

Syntax: explain --> [explain].

This marks a change to the error-handling. When an error is reported,
the reporting predicates report_and_saynotdone and report_diagnosis
save the explanatory text instead of outputting it. The student can then
ask to see this with the "explain" command. See Chapter 2 of the book
for comments on explanations.

NB. I may not have made all the message texts into proper explanations
by the time this disc goes out. For an example of one that is, try
typing
    john loves mary fred.
in Logic mode, and then do an
    explain.


3.3 RANDOM.PL
-------------

This module wasn't mentioned in the book. It defines a portable
random-number generator, which is used to select list elements in
SPIN.LOGIC and NOTES.LOGIC.


3.4 READ_SENTENCE.PL
--------------------

This module was also not mentioned. It defines sentence-reading
predicate, useful in extending the Richard Head exercise of Supplement
8.


3.5 TEXT.LOGIC
--------------

A text-ATN interpreter, with nice example data, which makes writing
knowledge bases like DEPRESSION easier.    


3.6 PARIS.PL
------------

A little computer game written by Paris Arnold, which illustrates the
style of Prolog (commands vs. logical predicates) that I teach.


3.7 MAIN_LOOP.PL
----------------

Now catches tokeniser errors. It is therefore different from the listing
in the book: there's an extra clause for process_sentence and for
extract_sentence, and some stuff for error-trapping.


3.8 COMMANDS.PL
---------------

As mentioned earlier, now handles the "ask" and "explain" commands, and
treats explanations differently. There is therefore a slight change from
what's printed in the book.


3.9 EDITOR.PL
-------------

As mentioned earlier, I have corrected a bug in the source code, so
there are about two characters different from the printed listing!


3.10 SHOW_SDO.SDO
-----------------

logic_argument_out now calls [writeq_(A)] to ensure that those atoms
which need quoting get it.


3.11 BLOCKS.PL and DRAW.PL
--------------------------

These modules weren't mentioned in the book, and aren't part of the
Tutor as it stands. They stem from some experiments I did, where the
student is given a picture of bricks on a table, and has to express it
in Logic. The Tutor will then call the predicate draw_bricks from      
DRAW.PL, and draw a picture from these facts. Mistakes in the
translation will thus be easy to spot. BLOCKS.PL defines the graphics
predicates on which DRAW.PL depends.


3.12 ASSERT_N.PL
----------------

Some predicates for random access to the database that I wrote when
experimenting with the editor. Not used in the current version.


3.13 FLAGS.PL
-------------

Predicates for setting and testing global flags. Not used in the current
version.


3.14 CPU_TIME.PL and MEAN_TIME.PL
---------------------------------

Predicates for timing other predicates.


3.15 MONOPOLY.PL
----------------

Before writing Traveller, I thought about making an automatic Monopoly
player. This is what would have been in MONOPOLY.PL. The file is not
complete, but you may find the bits of board data that I've typed
useful.                     


4. Note.
========

My address is:
    Jocelyn Paine,
    Department of Experimental Psychology,
    South Parks Road,
    Oxford OX1 3UD.

    Electronic mail (JANET): POPX @ UK.AC.OX.VAX

    Phone: (0865) 271444
    Fax: (0865) 310447

If you want to contact me, please use Email, fax, or paper mail if
possible.


The software that comes with this disc is distributed under the
understanding that it be made freely available for teaching. It is not
my intention that you convert it into a commercial product and sell it,
thus gaining at the expense of my work. I shall take action against
anyone I find doing so.


Please let me know of any bugs and improvements. If possible, I'll
include improvements on future releases of the disc, and in my library.
