This file provides installation instructions and related information
useful for setting up a `local' version of:
* Lovelace, an Ada 95 tutor
* mklesson, a tutor generator
* Small, a sample Ada 95 Object-Oriented program.

This file is divided into the following sections:
  1. LEGAL NOTES
  2. WHERE TO FIND CURRENT VERSIONS
  3. INSTALLATION INSTRUCTIONS
  4. IF YOU'RE CRAMPED FOR DISK SPACE

=============================================================

1. LEGAL NOTES

The Lovelace Ada tutorial & mklesson (tutorial generator)
are covered by the GNU General Public License and/or
Library General Public License; see the file legal.htm
for more information. Unless otherwise noted, this material is
Copyright (C) 1994-1995 David A. Wheeler.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    GNU General Public License for more details.

Small is, in essence, public domain; see the legal notes in file
"legal.htm" for a more exact description of Small's legal status.

This tutorial is not an endorsement.
This tutorial was developed on my own time (off-hours).
I do work at the Institute for Defense Analyses (IDA), but
this tutorial does not represent any kind of endorsement by IDA,
the Ada Joint Program Office (AJPO),
the U.S. Department of Defense (DoD), or the U.S. Government.


=============================================================

2. WHERE TO FIND CURRENT VERSIONS

If you've already downloaded current versions of the files you need
(the Lovelace files, an uncompressing program like pkunzip, and 
a Web browser), you can skip to section 3 below.

Lovelace is distributed on the World Wide Web,
with the current home page URL of:
 http://www.adahome.com/Tutorials/Lovelace/lovelace.htm
Use a World Wide Web browser and go to that URL to see
the latest version of Lovelace.

If you can use "ftp" but aren't set up to use the Web, you can use
ftp to download Lovelace.  Here are the commands you'd use for a
typical text interface:
   ftp
   open lglftp.epfl.ch
   user anonymous YOUR_EMAIL_ADDRESS
{use username "anonymous", and your email address as your password}
   cd /pub/Ada/HTML
   binary
Then you get the file by running (for the zip format):
   get lovelace.zip
or (for the tar/gunzip format):
   get lovelace.tar.gz


If you don't have a program to uncompress the zip file format, you
can obtain an index of programs to do this for you from URL:
   ftp://ftp.uu.net/pub/archiving/zip/Index
To retrieve this file using ftp, type:
   ftp
   open ftp.uu.net
   user anonymous YOUR_EMAIL_ADDRESS
{use username "anonymous", and your email address as your password}
   cd /pub/archiving/zip
   ascii
   get Index
Then read the index file you receive.  When you've decided which
file you need, do the same as above, but instead of typing ascii, type:
   binary
   get NAME_OF_FILE_YOU_WANT


If you don't even have an ftp connection, but you have a working
email connection, you can still get the files, though it's not nearly
as easy or quick.  What you need to do is send an email message to a
service that will execute ftp requests for you and send you the results
by email.  Here are some such services, as noted by IEEE Institute,
November 1995:

  bitftp@pucc.princeton.edu
  ftpmail@decwrl.dec.com
  archive-server@Germany.eu.net
  ftpmail@ftp.uni-stuttgart.de
  mail-server@cs.tu-berlin.de
  archive-server@ibr.cs.tu-bs.de
  mailserver@Leo.org

Send an email message to one of the above sites (or another one you
identify) with no subject line and a single message line saying "help".
You will get a reply stating how to use the service.

In general, you'll need to mimic an ftp session in the message body
sent to these services. The text commands
listed above for ftp commands will be very useful to you.

Binary files can't be reliably sent over normal email without packing
it up as some sort of text format; one of the most common such formats
is "uuencoding".  You'll need to specify this packing format when you
talk to such services, and once you get the data via email to your
machine, you can then unpack it (say using uudecode) to turn it back
into a normal file.  Unfortunately, many email systems don't do this
binary unpacking automatically.

If you're doing this by email, good luck to you.  If you get stuck,
consult a local "guru" on the intricacies of obtaining binary files
with ftp and email.


=============================================================

3. INSTALLATION INSTRUCTIONS

You should have received a compressed file containing the Lovelace files.

The file may be in one of several different compressed formats.

If this file is stored in `tar plus gzip' format (a common Unix format),
it will probably have a filename like lovelace.tar.gz
(or a related filename; MS-DOS systems will have shorter
filenames like lovelace.gz).
`tar' is a format that allows multiple files to be stored in a single file.
`gzip' is a compression format supported by the FSF GNU `gzip' and `gunzip'
programs; it is NOT the same format as the MS-DOS `zip' format.

If the file is stored in `zip' format (a common PC format), it
will have a filename like `lovelace.zip'.

A. Create a new subdirectory called "lovelace", and move into that subdirectory.
   In Unix and MS-DOS systems, this can be done at the command
   line by executing:

   mkdir lovelace
   cd lovelace

B. Place the compressed Lovelace file (which may be called LOVELACE.gz.tar,
   lovelace.zip, lovecell.zip, or something similar) into this new directory.
   In Unix, this is done with the "mv" command. In MS-DOS, this
   can be done using the "copy" command.

C. Uncompress the file.

   For the tar+gzip file, on Unix and MS-DOS systems, do:
     gunzip lovelace.tar.gz
     tar xvf lovelace.tar
   Some MS-DOS machines don't have these programs already; consult
   your "local expert" on how to get programs to uncompress and untar
   these files.

   For the zip file, on MS-DOS systems, do:
      unzip lovelace.zip
   (or whatever your unzipping program name is, such as
    pkunzip or dezip).

   On Macintoshes, use programs such as stuffit or suntar.
   Again, if you don't have programs to uncompress and untar, consult
   your "local expert".

   If you want to support the Java applets, you need to expand those
   as well. Unzip the "adaclass.zip" or "tar xvf" the "adaclass.tar"
   file; this will expand into a set of directories and subdirectories
   needed to support the Java applets.  If only a few users will use
   this system, you could alternatively have the users set their
   "CLASSPATH" variable to include the "adaclass.zip" file in this
   directory.
    

D. On multiuser systems you _may_ need to reset file access permissions.
   For Unix systems, do:
   chmod a=r *

E. Read the file "readme", which points out the key files here.
   On Unix and MS-DOS machines, this can be done using:
   more < readme

F. If you don't already have a "web browser" such as Mosaic, Netscape, Lynx,
   Cello, etc., install one.  You do NOT need Internet access to use
   Lovelace this way, though Internet access will increase your
   capabilities.

   Some versions of Lovelace are available that have the Cello browser
   already integrated into them.  If you have such a version, you can simply
   run Cello by running the program "cello.exe" in the lovelace directory
   (Cello will automatically start at the Lovelace local home page).

   If you don't have Internet access, make sure your web browser is
   configured so it will NOT attempt Internet access and make sure that
   the Web browser "home page" is a local file (say, the initial Lovelace file).

   For example, to set up Cello so you don't need an Internet connection,
   edit the "CELLO.INI" file (in Cello's directory) to contain the following
   settings:

        LocalOnly=Yes
        HomePage=c:\lovelace\local.htm

   The "LocalOnly" line indicates that the web browser (Cello in this case)
   should not attempt network connections, and the "Homepage" line
   gives the filename that will be the first filename viewed (change
   the C:\LOVELACE to wherever you've installed Lovelace).

   Other web browsers work similarly.

G. Start up your web browser (Mosaic, Netscape, etc).

   If you're using the version of Lovelace integrated with Cello, start up
   Microsoft Windows and then run the program "cello.exe" in the
   directory you put lovelace in.  For example, if you use Windows 3.1
   and you installed Lovelace in c:\lovelace, from the program manager
   select File/Run and enter "c:\lovelace\cello.exe" (don't enter the quotes).
   
   If your web browser doesn't automatically open Lovelace on start-up,
   open the file "local.htm" in whatever directory you installed Lovelace.
   In most browsers this is simply a "File/Open File" command with the
   filename "C:\lovelace\local.htm" for MS-DOS machines and
   "local.htm" for other machines.  At this point it should all work!

   The "local.htm" file contains a warning saying that this version of
   Lovelace is a local version.  If you don't want that warning,
   you can open the normal home page "lovelace.htm" instead of "local.htm".

   Most browsers permit you to provide a starting URL when you start them
   up. You can use that capability to move directly to Lovelace on startup.

H. When everything seems to work correctly, remove the tar or zip file.
   In Unix systems, this is done with:
     rm lovelace.tar
   In MS-DOS systems, this is done with:
     delete lovelace.tar
     -or-
     delete lovelace.zip

I. From now on, you can simply start up the browser (step G) to use Lovelace!

=============================================================

4. IF YOU'RE CRAMPED FOR DISK SPACE

If all you want to do is run the Lovelace tutorial and you're
cramped for disk space, delete the following files:

  *.les        (lesson source)
  *.tim        (timestamps)
  makefile
  mklesson
  template
  default
  userg.htm

If you're not using the Ada source code, you can also delete them:
  *.adb     (Ada bodies)
  *.ads     (Ada specifications)

If you have a version integrated with Cello and you're not using Cello,
remove the following files:
  1024-768.sty
  640-480.sty
  800-600.sty
  cello.bmk
  cello.exe
  cello.ini
  cello.ino
  cello.sig
  cello.sto
  cello.sty
  clohelp.hlp
  default.htm
  readme.1st


MS-DOS-derived systems should note that Lovelace is implemented as a
large number of small text files. In some sense this is a "worst case"
for MS-DOS and similar systems; when not using a compressed drive such
files use a lot of extra space.  If you're really hurting for disk
space, using a compressed drive will provide significantly more space.



Enjoy!

--- David A. Wheeler
    wheeler@ida.org

