This is the source directory for KPML (Version 3.2)
====================================================

John Bateman, May 2000.
University of Bremen, Germany.
e-mail: bateman@uni-bremen.de

CONTENTS
========

0. Welcome
1. Installation
2. Directory structure
3. Development history

NOTE: KPML 3.2 may be used with Allegro 5.0 for PCs, it will compile
====  and generate without problem: however, there are still gaps in
      in the  GUI with ACL5  for PCs. Contact me if you  require more
      stability in your ACL5.0 for PC version and I will give this task 
      higher priority..

WELCOME
=======
...   to the KPML  3.2 release  for grammar  development, grammar
exploration, and large-scale resource maintanence.

This directory contains the full  source code for KPML 3.2. To be
used, this source  code needs to be compiled  and loaded within a
running  version of Common  Lisp with  the Common  Lisp Interface
Manager (CLIM).  If you do not have a Common Lisp available, then
you can use the released  standalone images given on the KPML web
site  (Windows only). KPML  3.2 has  been tested  most thoroughly
under  Allegro Common  Lisp 5.0  (Unix) and  under  Lispworks 4.1
(PC).

Under Unix  (Sparc, Solaris 2.5+),  the recommended configuration
is  with Allegro  Common Lisp  (4.3 or  newer) and  CLIM  (2.1 or
newer),    with   GNU    Emacs   also    being    present.    The
emacs-initialization files  that should be loaded  from .emacs or
its   equivalent    are   to   be   found    in   the   directory
*root-of-kpml*/Emacs.

Under  Windows, the recommended  configuration is  with Harlequin
LispWorks 4.1  (or newer). Under Lispworks,  editing proceeds via
Lispworks  own  internal Emacs-like  editor  and  so no  external
editor is required.  Also  possible are Allegro Common Lisp 3.0.2
with  CLIM  (2.1  or  newer)  and  WinEmacs--interaction  between
ACL3.0.2 and WinEmacs is provided by the Franz Editi Open Editing
Package--Lispworks  4.0 with  CLIM, and  Allegro Common  Lisp 5.0
with CLIM  2.2 for PCs (but  see opening note  above). At present
the  Harlequin  Lispworks  4.1  version  has  received  the  most
testing.

If  you do  not have  a version  of Common  Lisp then  you cannot
compile  this  source  code.   For  PCs you  can  still  download
standalone versions of the KPML  system that can be run without a
Lisp  system  however:  these  introduce some  restrictions,  but
should  not become  an issue  until very  serious  development is
required.

INSTALLATION.
=============

Installing  KPML-3.2 is  conditionalized so  that the  same steps
apply  regardless of  one is  running under  Unix or  Windows and
whether under  Franz or Harlequin products. KPML  will by default
always assume  the existence  of /tmp under  Unix (unproblematic)
and  C:\tmp  under Windows  (sometimes  problematic);  if such  a
directory does not exist on your machine, first create it.

There are then  two ways of installing the  system, but the first
step in each case is the  same: KPML must first be informed about
where the  linguistic resources  to be used  live and  about what
knowledge representation  system it is  to use.  These  (and some
other) options and paths that  give KPML this information are all
in   the   file:   configuration.lisp.    Read   the   individual
instructions for  paths and  flags in this  file.  No  other file
needs to be altered  or inspected for the regular straightforward
use of KPML.

The simplest option  for getting started is by  loading the file:
install-kpml.lisp.   This will  compile KPML  according  with the
neutral configurations and settings. Slightly more flexibility is
provided  by loading the  file KPML-INSTALLATION.lisp  The latter
option  allows more  sophisticated  options to  be  set, but  the
former is quite sufficient for normal use. 

Following compilation KPML must be 'loaded'. If you load the file
start-kpml.lisp, then all the  necessary files will be loaded and
the KPML  development interface  will be brought  up. If  you are
following the  more KPML-INSTALLATION.lisp option  and answer 'y'
to  the Load  KPML  question,  then you  will  be left  following
loading  in  a  Lisp  listener  and  must  start  KPML  yourself,
typically by  means of  the function call  (kpml-i::startup). You
may also use KPML-INSTALLATION.lisp  to compile and load versions
of  KPML that  do  not  use the  window  interface, for  blackbox
generation, etc.

Due to peculiarities of Lispworks,  it is not possible to use the
standard  KPML  image  making  files  for  saving  out  installed
versions  of  the  system  for  quick  reloading:  the  directory
KPML-IMAGE-SCRIPTS  accordingly  contains  example  image  making
scripts for use with Lispworks 4.0 and 4.1. It is possible to use
these  scripts  for  'one  step' installation,  since  they  also
contain all of the localization paths that are required.

------------------------------------------------------------------

DIRECTORY STRUCTURE.
====================

The  particular files/directories  to be  found in  the top-level
KPML directory and their purposes  are as follows (some of these,
as  marked by  *, can  be useful  for various  aspects  of KPML's
behaviour):

Files:
------

*  configuration.lisp       the file where pathnames should
                            be changed for installing the
                            system. 
*  KPML-INSTALLATION.lisp   dialogue-driven installation/startup
*  install-kpml.lisp        install KPML by compiling the source code
*  start-kpml.lisp          load a compiled KPML and start the interface

clisp-defsys.lisp           definition of the CLISP Lisp package
compile-kpml.lisp	    compiles KPML, normally not required by
                            a user as it is called properly by
                            KPML-INSTALLATION.lisp and install-kpml.lisp
cond-defsystem.lisp         a KPML-adapted version of Mark Kantrowitz's 
(2.1 addition)              portable system definition facility
                            (defsystem.lisp, see below) that is
                            always loaded for KPML installations, regardless
                            of whether someone else loaded another version
                            previously.
system-flag-defs.lisp       a preinstallation configuration
                            file called by KPML-INSTALLATION, install-kpml,
                            and start-kpml to run the user dialog or 
                            configure are required.
kpml-defsys.lisp            definition of the KPML system.
kpml-package-def.lisp       definition of the KPML Lisp package
*  kpml-xdefaults           a better appearance for the interface
                            can be gained by assigning Lisp
                            managed typefaces to particular
                            operating system typefaces. This
                            file contains an example that is
                            useful for getting the menubars to
                            look better under X-windows.
*  kpmlconf                 a simple KPML configuration file.
*  kpmlconf.template        a template of the kinds of values 
                            that can be set up in a KPML
                            configuration file.
load-kpml.lisp              loads KPML, normally not required by
                            a user as it is called properly by
                            KPML-INSTALLATION.lisp and start-kpml.lisp
readme.txt                  this file.
*  selected-kpml-kr.lisp    this file contains specific information
                            for loading in a knowledge representation
                            system to be used with KPML. The 
                            standard release contains that required
                            for Loom (2.0, 2.1 and 3.0) as an example.
version-utilities.lisp      contains the utilities for easing moving
(2.1 addition)              between minor Lisp system updates 
                            (e.g., from ACL4.3 to 4.3.1 or
                            from LWW4.0 to 4.1) without having 
                            to go and change conditionalization
                            for things that have not changed in the
                            Lisp versions.

Directories:
------------

*  KPML-BIN-TEMPLATE        a skeleton of the KPML directory
                            structure that can be copied for
                            use when the compiled binaries are
                            to be kept in a different directory
                            structure to the sources.
* KPML-IMAGE-SCRIPTS        a collection of scripts for making
                            KPML images; generally for use where
                            a Lisp does not support ready image
                            making or for creation of standalone
                            KPML versions for those who have bought
                            the appropriate Lisp.
Processes                   where all the sources live.
clisp                       some of the very old code inherited
                            from Penman still uses a pre-Common
                            Lisp loop package, this is it.
emacs                       where the Emacs-specific code lives.
*  patches                  where standardly released patches go:
                            patches are made available at the
                            KPML ftp-site (e.g., 
                            ftp://ftp.uni-bremen.de/langpro/kpml or
                            similar: see the website for a direct
                            link) and consists of files with a name such as 
                            `19990328-patches.tar.gz'. Gunzipping
                            and untaring this gives directories
                            with names such as `19990328-patches'.
                            This should be renamed to `patches'
                            always *replacing* the previous directory
                            of that name. Under Unix Allegro this
                            happens automatically whenever a gzipped
                            tarred patchfile is places in the home
                            KPML directory and a standard KPML image
                            is started. With other Lisps you may have
                            to give a helping hand.

------------------------------------------------------------------

DEVELOPMENT HISTORY
===================

March 2000 (University of Bremen)

KPML 3.1 modifies the handling of windows internally and provides
an additional window  managing tool for closing some  of the many
windows  that   KPML  sometimes   produces  in  response   to  an
information request.  Also added are user interface access to the
grammar consistency tests. KPML 3.1 is almost but not quite fully
compatible with  Allegro 5.0 for PCs: full  compatibility will be
pursued for the next release, especially if anyone says that they
are waiting for  it; if I am the  only one using ACL 5.0  on a PC
then it will not receive such a high priority.

------------------------------------------------------------------
October 1999 (University of Bremen)

KPML 3.0 is a full new  release including several new tools and a
rearrangement of  the windows and menu  options. Installation for
newcomers is also simplified.

------------------------------------------------------------------
June-September 1999 (University of Bremen)

KPML 2.1 is a maintanance release that takes the functionality of
KPML  2.0.62  as  baseline.   It includes  improved  support  for
recompilation under newer versions  of the underlying Lisp system
as well as some minor  additions to the user interface.  KPML 2.1
is compatible with at  least ACL4.3, ACL4.3.1, ACL5.0, LWW4.0 and
LWW4.1.  A  list of the  patches 2.0.1-2.0.62 is appended  at the
end of  this file;  these are all  included in the  basecode from
KPML 2.1 onwards. A  note on the new conditionalization behaviour
is also included below: this is  relevant if you are going to add
information or change definitions.

------------------------------------------------------------------
February-April  1998 (University of Stirling)

KPML 2.0 contains considerably  more user functionality than that
documented in full  (1.0.49) in the bound GMD  Report (GMD Studie
304, available from Sankt Augustin)  and the Web pages.  There is
a much  increased range  of graphical operations  for interacting
with grammars  during generation as  well as support  for various
language engineering and teaching enhancements.

------------------------------------------------------------------

The  principal enhancments  over releases  prior to  2.0  are the
following:

* Support for running on PCs (Windows 95
  and WindowsNT) is provided, with both Franz Allegro
  Common Lisp (3.0) and Harlequin LispWorks (4.0).
  In both cases CLIM 2 is required as usual. Unix
  support continues as before (with Allegro CL).

* Graphical editing of systems, choosers, and inquiries
  is provided internally within KPML without accessing
  an external editor unless desired.

* There are several additional `tools' that can be
  used with KPML-2.0 in an integrated fashion (e.g.,
  the graphical grammar editor, subgrammar extractor, 
  grammar explorer, coder, and the documentor). These
  are available separately and are documented on the
  Web.

* Standalone free versions of KPML-2.0 for PCs are
  available without any license requirements.

* Switching between knowledge representation systems
  is supported more positively.

* All access to a lexicon is now made available as a
  small set of Common Lisp methods that users may
  freely specialize for individual languages, thus providing
  smooth access to external lexicons and/or morphology
  components.

* A  configuration file is  consulted   prior  to
  starting   any  image  (including  standalone   PC
  versions) so that it is easier to customize the operation of
  KPML to particular environments without needing
  to intervene from Lisp.

* Interaction with WinEmacs for editing/creating
  resources with the ACL PC version is provided if
  required.

* The  Lisp-conditionalization     behaviour  is   now    as
  follows. Types  of Lisp  are   fine  and may be   used  to
  conditionalize behaviour (e.g., lispworks, allegro).  Some
  one-offs are also  ok (e.g., ACL3.0).  Mostly, though, any
  versioned conditionalized is  replaced  by  a  range  that
  begins  with  the mentioned  version,  e.g., if previously
  conditioned  for Allegro-V4.2, this  is now interpreted as
  any Allegro-V version that is 4.2 or greater, up until the
  next explicit conditionalization that is given (if any).

  DRAWBACKS OF CONDITIONALIZATION: as currently implemented
  all of the conditions are examined, that is, it is not the
  case as in reader conditionalization that Lisp does not 
  even see the expression: this means that undefined packages
  or non-exported symbols will cause problems if they do not
  exist in the Lisp that is actually being used. To work
  around this, the entire condition range will usually be
  reader-conditionalized to make it more likely that the
  symbols referred to exist, external symbols will not 
  be referred to as such (i.e., we write foo::bar instead of
  foo:bar even when foo:bar is possible), and some additional
  empty packages are defined when necessary so that nothing
  trips up compilation.

------------------------------------------------------------------
List of patches 2.0.2-2.0.62
 
 :KPML-2.0.2  inspection from structure graph extensions (interface)
 :KPML-2.0.3  lexicalization extensions and regularization
 :KPML-2.0.4  example set file name taken from set name when saving
 :KPML-2.0.5  system editing problem incompatibility Unix/PC fixed (interface)
 :KPML-2.0.6  editing examples from example manager added (interface)
 :KPML-2.0.7  punctuation rule applicability test was not strict enough
 :KPML-2.0.8  patch from .3 was not prepared for reified pseudohubs
 :KPML-2.0.9  minor improvements to options for editing and graphing
              networks (interface)
 :KPML-2.0.10 cumulated history maintanence made more robust 
              when generation is aborted
 :KPML-2.0.11 on the fly configurable inheritance of inflection
              behaviour for teaching
 :KPML-2.0.12 embedded literal numbers as SPL variables/instances fixed
 :KPML-2.0.13 example renaming/copying added to example manager (interface)
 :KPML-2.0.14 extended example target/generated mismatch 
              mangement provided (interface)
 :KPML-2.0.15 language variety menu sometimes tried to get at 
              non-existent frame (interface)
 :KPML-2.0.16 annoying check of saving user responses in 
              environment suppressed by default
 :KPML-2.0.17 font flexibility (support for Cyrillic, etc. under Windows) 
              improved (interface)
 :KPML-2.0.18 warnings during example running were not conditionalized 
              for Lispworks-PC
 :KPML-2.0.19 window name of system editor changes to reflect changed
              name (interface)
 :KPML-2.0.20 configuration file reload provided in main menu (interface)
 :KPML-2.0.21 description format was written in DOS-mode, which wrecks a format
 :KPML-2.0.22 example runner extended to report mismatches
 :KPML-2.0.23 quit made more forceful for Lispworks
 :KPML-2.0.24 slight extensions to the example mismatch tool and HTML report
 :KPML-2.0.25 examples ordered more sensibly and tidily in 
              displays, menus, etc.
 :KPML-2.0.26 some nonprototypical coder structures were escaping
              highlighting (interface)
 :KPML-2.0.27 language abbreviation property errors corrected.
 :KPML-2.0.28 system network updated automatically when a change exported.
 :KPML-2.0.29 previous patch made compatible and partially replace 2.0.5 
              and 2.0.9 for both Unix and PC
 :KPML-2.0.30 delete system action added to network graph possibilities
 :KPML-2.0.31 local and nonlocal resource set handling
 :KPML-2.0.32 selection expressions in examples corrected for single lists
 :KPML-2.0.33 pruning of system networks to show generation paths
 :KPML-2.0.34 realization statement boxes in graphs filled properly
 :KPML-2.0.35 setting region made more effective from system editing windows
 :KPML-2.0.36 system editing window (2.0.19) now reflects 
              current name for Unix too.
 :KPML-2.0.37 extra function for forcing recompilation of kpml patches defined.
 :KPML-2.0.38 patch of 2.0.32 extended to include selection expressions.
 :KPML-2.0.39 resetting with multilingual resources missing 
              preselection paths fixed.
 :KPML-2.0.40 extension to the agreement realization operator
 :KPML-2.0.41 language variety surveys and overviews extension
 :KPML-2.0.42 resource change protocol made more robust for oversensitive PCs
 :KPML-2.0.43 extensions to the region overview interface
 :KPML-2.0.44 hardcopy fix and more information in structure graphs
 :KPML-2.0.45 cancel/quit buttons in patches warning on quit 
              made more intuitive
 :KPML-2.0.46 patch 2.0.39 was still not quite right. Fixed.
 :KPML-2.0.47 case sensitivity and other options added to example
              mismatch reports
 :KPML-2.0.48 example clearing was leaving traces around. Fixed (interface).
 :KPML-2.0.49 some structure graphs and others made extra robust (interface)
 :KPML-2.0.50 local resource directory setting added to 
              environment dirs (interface)
 :KPML-2.0.51 chooser removal added to system editor
 :KPML-2.0.52 further extensions/corrections to the agreement 
              realization operator
 :KPML-2.0.53 language specialization was wrong in created string 
              cleanup declarations
 :KPML-2.0.54 traverse grammar command added (interface)
 :KPML-2.0.55 reload last loaded example, lexicon and indirectly 
              specified files
 :KPML-2.0.56 obscure term-type-p oversight patch
 :KPML-2.0.57 extra cautious (Lispworks only) realization statement
              dialog box option.
 :KPML-2.0.58 more informative options setting frame provided (interface)
 :KPML-2.0.59 writing out of examples/lexemes when versioning active 
              fixed (interface)
 :KPML-2.0.60 language range in multilingual resource sets and spl keyword fix
 :KPML-2.0.61 more robust progess noting during example running from interface
 :KPML-2.0.62 parameterization of no realization and lexical gap strings

----------------------

For development history prior to version 2.0, see the
documentation and webinfo at http://www.gmd.darmstadt.de/publish/komet




