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

John Bateman, March/April 2002 - December 2004
University of Bremen, Germany.
e-mail: bateman@uni-bremen.de

CONTENTS
========

   0. Welcome
   1. Recommended configurations
   2. Installation
   3. Directory structure
   4. Development history

WELCOME
=======

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

   This directory contains the full source code for KPML 4. 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 4 has been tested most thoroughly under
   Allegro Common Lisp 5.0 (Unix) and under Lispworks 4.1 (PC).

RECOMMENDED CONFIGURATIONS
==========================

 ***********************************************************************
 * 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: these introduce some
   restrictions, but should not become an issue until very serious
   development is required.

   If you are not using the graphical user interface of KPML--for
   example, if you are doing blackbox generation work or are happy
   just to use KPML directly from Lisp--then any Common Lisp
   implementation should work.

   Otherwise, CLIM is required and implementations of CLIM are not all
   equally stable or completely compatible across all platforms.

   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 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. Emacs is then available for
   editing the linguistic resources in addition to the KPML-supported
   graphical editing modes.

   Under Windows, the recommended configuration is with Harlequin
   LispWorks 4.1 (or newer). Under Lispworks, editing resource
   definitions proceeds via Lispworks own internal Emacs-like editor
   and so no external editor is required.

   ACL 5+ on non-NT/XP Windows has a lot to do to cope with the lack of
   true multiprocessing, and appears less than stable with the current
   KPML code, which was written without the rather strict limitations
   that ACL 5+ imposes on inter-process communication. For this reason
   ACL 5+ is not recommended for non-NT/XP/2000 Windows versions.

   Other possible configurations 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 note above). At present the Harlequin
   Lispworks 4.1 version has received the most testing of all and is
   so the guranteedly most stable.


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

   Installing KPML-4 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.

(1) There are then two ways of installing the system, but the first
    step in each case is the same:

  (a) KPML must first be informed about where the linguistic resources
      to be used live and 
  (b) 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 REGULAR
STRAIGHTFORWARD USE OF KPML.

(2)
    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.  If you are not sure what you are doing, stay with the first
   option until you are comfortable with KPML installation.

(3)
   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.

   NOTE (making images under Lispworks):

   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


*  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:
------------

*  README-files             where all the various readme files for
                            various parts of the system are now
                            gathered. These include:

               README-kpml-installation.txt -- this file.

               README-loom-installation.txt --
                            very brief minimal instructions for installing
                            Loom when Loom is being used as the knowledge
                            representation language for the upper model
                            and domain models. Note that *some* knowledge
                            representation system is required, and Loom
                            is assumed by default. 

*  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
===================

April/May 2002 - December 2004: KPML 4: this version.

-----------------------------------------------------------------
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 published by the GMD at Sankt Augustin
in 1996. (Previously at http://www.gmd.darmstadt.de/publish/komet
but this WWW domain no longer exists.)




