
 * The authors of this software are Rob Pike and Howard Trickey.
 *		Copyright (c) 1998 by Lucent Technologies.
 * Permission to use, copy, modify, and distribute this software for any
 * purpose without fee is hereby granted, provided that this entire notice
 * is included in all copies of any software which is or includes a copy
 * or modification of this software and in all copies of the supporting
 * documentation for such software.
 * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
 * WARRANTY.  IN PARTICULAR, NEITHER THE AUTHORS NOR LUCENT TECHNOLOGIES MAKE ANY
 * REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
 * OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

Introduction
------------

This is 9libs, a package of Plan 9 compatability libraries derived from
the X11 version of Rob Pike's editor, sam. The original sam package is
available from plan9.bell-labs.com in the directory plan9/unixsrc/sam.
This release differs from the Bell Labs release in the following ways:

* The set of Makefiles which provided portability to different platforms
  has been replaced with a build system implemented using GNU autoconf,
  automake and libtool.

* sam is not included. Instead it is available as an extra package
  which can be compiled and linked with these libraries.

This repackaged version was put together by Mark Wilkinson
<mhw@kremvax.demon.co.uk>, and all problems with the package should be
sent in the first instance to that address, not to Bell Labs.

The package consists of:

* libXg, an X11 implementation of Plan 9's libg graphics library.
  The library's declaration are in include/libg.h
* libframe, a library which implements rectangular text areas using
  libXg. Declarations are in include/frame.h
* libplan9c, a library which aims to provide implementations of some of
  the more general-purpose parts of the Plan 9 C library. This includes
  the libregexp library from recent sam distributions. Declarations
  are in include/u.h and include/libc.h, which are the first things
  included by Plan 9 C files. Declarations for the regular expression
  components of the library are in regexp.h.
* Documentation for the libraries, as manual pages in the doc directory.

Installation
------------

The main aim of this package is to factor out the libraries common to
the programs sam, 9term, wily and 9x. The libraries may be useful on
their own as a cleaner interface to X windows, but these instructions
assume you are building other programs which require the Plan 9
libraries. Generally, installation involves three steps: unpacking the
distribution files, configuring the package(s) using configure scripts
and running make to control the compilation.

Unpacking

The programs which use 9libs depend on being able to find the libraries
and include files it provides. For this reason, the way in which you
unpack 9libs and programs which use it will affect how simple the
package is to build.

The simplest way of building 9libs and programs which use it is to unpack
the program's distribution inside the top level 9libs directory; i.e.

	; gzcat 9libs.tar.gz | tar xf -
	; cd 9libs
	; gzcat ../<program>.tar.gz | tar xf -

This will allow 9libs' configure script to recurse into subdirectories
for each program in order to configure and build them.

If you want to keep 9libs in a completely separate directory hierarchy
from any programs which use it, you can unpack them separately too:

	; gzcat 9libs.tar.gz | tar xf -
	; gzcat <program>.tar.gz | tar xf -

In this case you will have to configure the programs separately and run
make in each one to compile things.

Configuring

Essentially you should be able to type `configure' or `./configure'
depending on your search path, and have things configured pretty much
automatically. If you opted to unpack a program which uses 9libs
somewhere other than the 9libs directory you will need to configure the
program in a similar way. You should configure 9libs before any programs
which use it.

The 9libs configure script will by default create only static libraries.
You can use the --enable-shared and --disable-static command line
arguments to override this default.

If you need to configure the programs which use 9libs separately from
9libs itself, you may need to use the `--with-9libs=DIR' flag to the
program's configure script to tell it where the 9libs directory is.  Try
running configure first though; it will look for a configured 9libs
distribution and tell you if it can't find the libraries nearby. If you
need to supply the directory, DIR should be an absolute or relative path
to the directory where you ran 9libs' `configure' script. If you are
compiling 9libs in a different directory from the sources the configure
script will figure out where the source directory is by examining the
build directory.

You should check the documentation accompanying each program you install
for information about other options to configure.

Compiling

Once 9libs is configured, type `make' to compile it. You may also need
to do the same for each program which uses 9libs, depending on how you
unpacked things. If the compilation fails, let me know so I can try and
fix things.

Installing

Once 9libs is built you can install the include files and libraries by
typing `make install'.  If you specified different values for the --prefix
and --exec-prefix options to `configure' then you may want to use
`make install-data' and `make install-exec' to install the architecture-
independent and architecture-specific files respectively.

Once you have installed 9libs you should be able to configure and install
any package which relies on it without using the 9libs distribution. Just
make sure you use the same --prefix and --exec-prefix options that you
used when configuring 9libs. This should allow the package to find out
where the include files and libraries are installed.

Summary

If you unpacked your programs inside 9libs' directory you should be able
to do this:

	; ./configure
	; make

If you unpacked into separate directories, this should do:

	; cd 9libs
	; ./configure
	; make
	; cd ../<program>
	; ./configure
	; make

If a program is further away from 9libs than that, or you're building
binaries in a separate directory from the 9libs source, you may need
extra options to the configure command for the program.

Cursor Keys
-----------

libXg supports two mappings for cursor keys: the original Bell Labs
mapping to the View and Preview scroll keys and an extended mapping
to key codes for the different cursor keys. At the moment only wily
handles the extended cursor key mapping. In order to get libXg to
provide the extended cursor key codes to wily you will need to set
the X resource "Wily.gwin.cursorControl" to true. You can do this
by adding the line

	Wily.gwin.cursorControl: true

to the appropriate X resource file. At some time in the future you
may be able to get gwin.cursorControl to true for other applications
too.

Authors
-------

Rob Pike designed and implemented the original Unix version of sam and
the current version ported from Plan 9. Howard Trickey provided the X
version of the graphics library, libXg. Matty Farrow and his colleagues
at the University of Sydney extended libXg to support Runes. Doug Gwyn
contributed many useful ideas to the X implementation of sam. James
Clark provided the simulations of the V10 Unix Man macros at the
beginning of each manual page.
