








                        The Andrew Distribution 

                              Version 6.3.1

                             (August, 1994)





                                   For more information, please contact: 

                                                        Andrew Consortium
                                               School of Computer Science
                                               Carnegie Mellon University
                                                       5000 Forbes Avenue
                                                Pittsburgh, PA 15213-3890
                                                                   U.S.A.
                                                           (412) 268-6710

                                 Mailing list: info-andrew@andrew.cmu.edu
                   (info-andrew-request@andrew.cmu.edu for subscriptions)
                                          Newsgroup: comp.soft-sys.andrew


Copyright Carnegie Mellon University 1991, 1994  - All Rights Reserved
Copyright IBM Corporation 1988, 1991 - All Rights Reserved
Additional copyright information can be found in config/COPYRITE.bls
config/COPYRITE.att, and config/COPYRITE.img in both the source and
destination areas.
This product includes software developed by the
University of California, Berkeley and its contributors.

$Disclaimer: 
Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose is hereby granted without fee, 
provided that the above copyright notice appear in all copies and that 
both that copyright notice, this permission notice, and the following 
disclaimer appear in supporting documentation, and that the names of 
IBM, Carnegie Mellon University, and other copyright holders, not be 
used in advertising or publicity pertaining to distribution of the software 
without specific, written prior permission.


IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 
DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 
SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
OF THIS SOFTWARE.
 $

The following copyright and permission notice apply to versions of the
Andrew User Interface System distributed previously.  The above notice
applies to this release.

Copyright Carnegie Mellon University 1991, 1994  - All Rights Reserved
Copyright IBM Corporation 1988, 1991 - All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee, provided
that the above copyright notice appear in all copies and that both that
copyright notice, this permission notice, and the following disclaimer
appear in supporting documentation, and that the names of IBM, Carnegie
Mellon University, and other copyright holders, not be used in
advertising or publicity pertaining to distribution of the software
without specific, written prior permission.

IBM, CARNEGIE MELLON UNIVERSITY, AND OTHER CONTRIBUTORS OF THIS SOFTWARE
DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR
PURPOSE.  IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY , OR ANY
OTHER CONTRIBUTOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
OF THIS SOFTWARE.    



1	Installation Instructions for the Andrew Distribution

This document contains instructions for the installation of the Andrew
User Interface System software, namely the Andrew Toolkit (ATK), and its
applications, including the Andrew Message System (AMS).  File name
references found in this document that start with ./ are relative to the
top-level of the source tree.  

This release includes innumerable bug fixes and evolutionary
improvements to many of Andrew's components. Several new system types
are supported,  including Sun's Solaris, SVR4, SGI, NetBSD (for i386
machines) and Linux.  

         ***** Quick-Start Instructions for the Impatient  *****

Copy the template files./config/site.h.tpl to ./config/site.h and
./config/site.mcr.tpl to ./config/site.mcr.  You should then edit the
non-tpl files as follows:   ./config/site.h includes your site's
adjustments to ./config/allsys.h and ./config/system.h.  You should
specify the location of the DEFAULT_ANDREWDIR_ENV.  ./config/site.mcr
contains your site's adjustments to macros in ./config/allsys.mcr and
./config/system.mcr.  You may want to change XINCDIR, XLIBDIR and
XINCDIR which define the location of your X libraries and utilities. 
You should  check the other options available below under section 1.2.1
for the ./config/site.mcr file and section 1.2.4 for the site.h file. 

If you did not pick up auis3.tar.Z (ams and atkams) then you should add
the following to the ./config/site.h file:

#undef AMS_ENV

If you picked up contrib.tar.Z and you wish to build and install it,
then you should add the following:

#define CONTRIB_ENV 1

Then check the "Notes on ..." sections later in this document for
information possibly relevant to your particular system type, or X
server.  (There are notes for: Decstation Ultrix 4.2 and 4.3,
MIPS,SPARC,Open Windows server, IBM RS/6000, Sun Solaris, PS/2 AIXv1.2,
SCO Unix , HPUX,  NeXT, SGI Iris,  and BSD derivatives for 386 class
machines.)

If you are going to use gcc you will need to specify this in your site
files, e.g.:

In site.mcr:
GCCLIB="the full path to your copy of libgcc.a, typically something like
 /usr/local/lib/gcc-lib/rs6000-ibm-aix/2.3.3/libgcc.a, it should be in
quotes to prevent macro substitution by imake."
CC=gcc -traditional
(If you encounter problems using gcc -traditional, try gcc -fwritable-strings.)

In site.h:
#define GNU_ENV 1

In the top level (directories ./overhead, ./atk, ./ams, ... exist), run
the following command: 

    imake -I. -I./config -Timake.tmpl -s Makefile -DTOPDIR=.

This will generate the top level Makefile.  Then run:

    make World

While you're waiting, please read the known problems list.  (PROBLEMS in
the top level of the source tree.)  And read or at least scan the rest
of this document.

If you installed the console application you will need to make
$ANDREWDIR/bin/getstats and possibly $ANDREWDIR/bin/getconsole setuid
root, or setgid to an appropriate group. (often mem or kmem) Typically
these programs need access to /dev/mem and /dev/console.

Error reports and request for assistance should be sent to
info-andrew-bugs@andrew.cmu.edu.  


1.1	Assumptions and Requirements 

The Andrew Distribution is portable to a number of system types. Andrew
is able to run on RS/6000 AIX3{1,2}, PS/2 AIX1.2, Sun3{ 3.5, 4.0, 4.1}, 
Sun4 {4.0, 4.1}, Vax Ultrix 3.1, Vax Ultrix 4.2, Vax BSD, DEC MIPS, SCO
I386, SGI IRIX 4.0, Apollo, HP, NeXT (under X11), Linux,  NetBSD (for
i386 machines), BSDI/386 (for i386 machines), and Macintosh II MacMach.
We run it on RS/6000 AIX3.1 and AIX3.2, Sun 4 Mach, Pmax Mach, Pmax
Ultrix 4.2, Linux, and HP UX.  

As shipped, the Andrew distribution is about 50 megabytes of source that
generates many megabytes of object files, libraries, fonts and
applications (where the exact amount of object space varies with each
machine). The default configuration generates about 70 megabytes;
changing that configuration to include building everything generates
about 120 megabytes. If you do not have sufficient disk space, the
procedures for building a partial system are described later in this
document.

In addition to space requirements, the distribution assumes that you
have the X Window System Distribution from MIT, which contains the
following files and programs:

    imake -- part of program construction (makefile) facility
    bdftosnf or bdftopcf -- font compiler
    makedepend --part of program construction (makefile) facility
    Xlib -- X.V11 include files and libraries

1.2	Modifying the Configuration Files 

The construction and installation of Andrew requires a local site to
provide a variety of information to the construction process:

    a. What kind of machine and operating system are being used
    b. Location of various pieces of system software (including the X
    distribution)
    c. Location and configuration of services for the installed Andrew system

This information is conveyed to the build process through various
configuration files. This section describes each of the major
configuration files and how an installer should edit them for a local
site.

Through the use of various switches ("DEFINE"s), one can control how
much of the system is built and select the appropriate operating system
and machine dependent pieces. Because of the large size of the system,
many options are provided. Definitions that you must provide are
described in this section. Optional definitions are described later.

Before building Andrew, you should look through the several files that
configure the system, and change them as necessary so that the Andrew
software will be built and installed correctly for your environment.
Each file, and the modifications you might want to make to it, are
explained below. Looking from the top of the extracted source tree, the
files are:

	./config/allsys.mcr
	./config/<machine>/system.mcr
	./config/site.mcr	 (your site's adjustments to allsys.mcr and system.mcr)

	./config/allsys.h
	./config/<machine>/system.h
	./config/site.h	(your site's adjustments to allsys.h and system.h)

	./atk/console/lib/sitevars.h
	./overhead/util/lib/svcconf.c
	./overhead/mail/lib/mailconf.c
	./helpindex/index.tpl

where "<machine>" is the machine type on which you plan to install and
build Andrew. The (intended) available machine types are:

Machine Type		Operating System		<machine>

IBM RT			AOS December 1988	rt_aos4
IBM RT			AIX 2.2.1			rt_aix221
IBM RS/6000		AIX 3.1, 3.2		rs_aix3
IBM PS/2 M70/80	AIX 1.2			ps_aix12 
Sun 3			SunOS 3.5			sun3_35
Sun 3			SunOS 4.0			sun3_4
Sun 3			SunOS 4.1			sun3_41
Sun 4			SunOS 4.0			sun4_40
Sun 4			SunOS 4.1			sun4_41
DEC Vax			Ultrix 3.0		vax_3
DEC Vax			BSD (4.3)			vax_43
HP 300			HP UX			hp300
HP 900			HP UX			hp800
386/486			Linux			i386_Linux
386/486			NetBSD			i386_bsd
386/486			BSDI/386		i386_bsdi (new, untested)
Macintosh II		MacMach			mac2_51
Apollo			DomainOS			apollo68k
DEC MIPS			Ultrix 3.0		pmax_3
DEC MIPS			Ultrix 4.1		pmax_41
DEC MIPS			Ultrix 4.2		pmax_ul4
DEC MIPS			Ultrix 4.3		pmax_ul4 (using cc, not gcc)
SGI				IRIX 4.0			sgi_4d
SCO				SCO				sco_i386
NeXT				NeXt Mach 2.0		next_mach20


A new document is included in the ./config directory, Porting.doc.  This
document provides general rules for porting AUIS to a new platform.  

1.2.1	The allsys.mcr, system.mcr, and site.mcr{.tpl} Files

./config/allsys.mcr, ./config/<machine>/system.mcr, ./config/site.mcr --
The definitions in these files specify where to find various programs,
include files, and libraries for building Andrew. The definitions that
are likely to change are clustered near the top of the allsys.mcr file.  

Definitions in these files are structured so that definitions in
allsys.mcr come first, then system-dependent overrides in system.mcr,
then site-specific overrides in site.mcr. 

You should NOT edit either allsys.mcr or your system.mcr. Instead, an
empty ./config/site.mcr.tpl template file is distributed.  Copy
./config/site.mcr.tpl to ./config/site.mcr then you can make your edits.
 This overrides the values specified in ./config/allsys.mcr and
./config/<machines>/system.mcr.  You can override #define'd macros in
your site.h file by using both #undef and #define, possibly within
#fidef/#endif pairs.  You can override make variables in your site.mcr
file by using lines such as ``FOO=bar''.  You may also use #ifdef/#endif
pairs to select which make variable settings should be used. (Make does
lazy evaluation of its $(FOO) variables, so it's reasonable to override
variables such as XUTILDIR in site.mcr.  

In the simplest case, you would copy ./config/site.mcr.tpl to
./config/site.mcr,  which results in the following default values:  

GCCLIB			[Default: none]

    GCCLIB specifies where the libgcc.a library is located.  This
    library is needed when compiling with gcc.

BASEDIR		[Default: DEFAULT_ANDREWDIR_ENV, from ./config/allsys.h - can
be overridden in ./config/site.h] 

    BASEDIR specifies where you want the root of the installed
    Andrew tree of system software. It is not possible to build
    Andrew without installing it. This directory will have several
    subdirectories created under it during the build process,
    including: include, bin, lib, dlib, etc, doc, and help. The
    value for BASEDIR is the path in which the installation process
    should put the Andrew system software, while the value for
    DEFAULT_ANDREWDIR_ENV (cf. section 1.2.5) is the path via which
    users, by default, will execute that software. To override this
    value, edit your site.mcr file, or override
    DEFAULT_ANDREWDIR_ENV in your site.h file.

    BASEDIR must be different from the root of your copy of the
    source tree. That is, in general, when you start, BASEDIR will
    point to an empty directory.

DESTDIR		[Default: $(BASEDIR)] 

    DESTDIR should always be identical to BASEDIR for system builds. 

    DESTDIR may be set to other values only in the course of local
    Andrew-based development.  

    For the Andrew build, this value will always be BASEDIR.  But
    for developers of Andrew-based software who want to install
    their binaries, this value may be set to a location specifying a
    local binary tree.  

AFSBASEDIR	[Default: /usr/local] 

    AFSBASEDIR denotes the full path to files exported by an AFS (Andrew
    File System) installation. (AFS is a distributed file system
    available from Transarc Corporation. For more information, please
    send mail to afs-sales+@transarc.com.)  It is used only if AFS_ENV
    is defined; otherwise, it is ignored entirely. If it is used, it is
    presumed that AFSBASEDIR/include/afs, AFSBASEDIR/lib/afs, and
    AFSBASEDIR/bin exist. Other specific requirements are listed in the
    discussion of AFS_ENV and AFS30_ENV in the section describing the
    *.h files.

    The default value is /usr/andrew . Override it in your site.mcr file
    if you need to.

WMBASEDIR	[Default: ]

    WMBASEDIR can be used to specify the root location of the old
    ITC window manager (WM) include files and libraries. WM is no
    longer supported by the ITC. If you specify this macro then you
    should also define WM_ENV in your site.h file (see sect. 1.2.4).
    If WM_ENV is defined and WMBASEDIR is specified, it is presumed
    that $(WMBASEDIR)/lib/libwm.a and
    $(WMBASEDIR)/include/{font.h,wmclient.h} exist.

    There is no default value for WMBASEDIR. Set WMBASEDIR in your
    site.mcr file if you want to run ATK applications with WM.

CDEBUGFLAGS	[Default: -O] 

    CDEBUGFLAGS are passed to the C compiler when compiling programs.

XBASEDIR		[Default: /] 

    XBASEDIR should point to the root of your installed X tree. X
    include files are assumed to be in $(XBASEDIR)/usr/include/X11. Xlib
    and bdftosnf are also found in this tree. If your compiler cannot
    handle paths like ``//usr/include/X11'' (with the double slash), you
    may wish to redefine this as the null string.


XINCDIR     [Default: $(XBASEDIR)/usr/include] 

XLIBDIR             [Default: $(XBASEDIR)/usr/lib] 

XBINDIR             [Default: /usr/bin/X11]

    XBINDIR should point to the location of the X bin directory under
    the XBASEDIR.  Do not include XBASEDIR in your definition of XBINDIR

XUTILDIR    [Default: /usr/bin/X11]

    As is the case with XBINDIR, XUTILDIR should also point to the
    location of the X bin directory under the XBASEDIR.  Do not include
    XBASEDIR in your definition of XUTILDIR

IMAKE               [Default: $(XUTILDIR)/imake] 

XMAKEDEPEND [Default: $(XUTILDIR)/makedepend] 

    IMAKE and XMAKEDEPEND need to be full paths to the X11 imake and
    makedepend programs. These are not normally installed as a part
    of X11, but are found in the X11 source tree in util/imake/imake
    and util/makedepend/makedepend. You can set either IMAKE and
    XMAKEDEPEND, or XUTILDIR, to point to the appropriate place.

XMKFONTDIR  [Default: $(XBASEDIR)/$(XBINDIR)/mkfontdir] 

XFC                 [Default:
    RELEASE2_ENV implies $(XSRCDIR)/fonts/compiler/fc,
    FONTS_TO_PCF_ENV implies $(XBASEDIR)/$(XBINDIR)/bdftopcf,
    otherwise $(XBASEDIR)/$(XBINDIR)/bdftosnf] 
    
XSRCDIR             [Default: empty string] 

    These are miscellaneous X-related absolute paths. XINCDIR needs
    to point to where your X include files are installed; it is used
    in the Andrew build process. XMKFONTDIR needs to point to the
    ``mkfontdir'' program from the X installation. XLIBDIR needs to
    point to where libX11.a is installed.  XFC should point to the
    ``bdftosnf'' font processor. Under RELEASE2_ENV, XSRCDIR should
    point to the top of an X11 source tree for the definition of
    XFC, but is otherwise not used.

RESOLVLIB	[Default: empty string] 

    RESOLVLIB denotes the full path of the domain name resolver
    library.  If RESOLVER_ENV is defined and the resolver functions
    are not in libc.a then RESOLVLIB should be set to the library
    which contains these functions, otherwise RESOLVLIB should be
    empty.  The default value (the empty string) is useful if the
    resolver code is in your libc.a. If the resolver code is in a
    separate library, such as /usr/lib/libresolv.a, that name should
    be the definition for RESOLVLIB; define it in your site.mcr file.

    The programmer's interface to the resolver library has changed
    over time. The file ./overhead/mail/lib/valhost.c (which is
    built into DESTDIR/lib/libmail.a) makes calls to different
    versions of that programmer's interface, using the fact that
    definitions in the resolver's exported ``include'' files changed
    slightly with successive releases. In particular, it checks for
    the definition of NO_DATA in the 4.8 version of
    /usr/include/netdb.h and for the definition of CQUERYM in the
    pre-4.7.3 version of /usr/include/arpa/nameser.h. If your
    versions of these include files correspond to the version of the
    resolver named by RESOLVLIB (or libc.a otherwise), you will have
    no trouble with its interface to Andrew. The
    ./overhead/mail/lib/valhost.c file contains suggestions for what
    to do if this is not the case.

INSTALL		[Default: $(BASEDIR}/etc/install] 

    INSTALL denotes the name of the install program on your system.
    If you do not have an install program, or if your install
    program does not work, edit the site.h file and:

    #define BUILDANDREWINSTALL_ENV  1

    and then re-make your Makefiles (if already made) and continue
    from there. (The setting of INSTALL is based upon the setting of
    BUILDANDREWINSTALL_ENV and will be picked up correctly if set in
    the ./config/site.h file.)

Additional definitions are unlikely to change. However, you may want to
check these values:

SHELL		[Default: /bin/sh] 

    SHELL specifies the path to the Bourne shell.

CSHELL		[Default: /bin/csh] 

    CSHELL specifies the path to the C shell.

CC			[Default: cc] 

    C compiler to use. On the IBM RT/PC, it is the hc Metaware
    compiler. On other systems, it is the pcc compiler.

ConstructMFLAGS	[Default: not defined]

    Define ``ConstructMFLAGS'' in your site.mcr if your make program
    accepts MAKEFLAGS but not MFLAGS.

1.2.2	The sitevars.h File

./atk/console/lib/sitevars.h -- contains defines indicating default
values for the console program. You probably need to be concerned with
only the following entries:

_SITE_NON_ANDREW_MAIL               [Default: /usr/spool/mail]

        Directory where console should look to see if incoming mail
        has arrived.

_SITE_NON_ANDREW_PRINTDIR   [Default: /usr/spool/lpd]

        Directory where console should look to see if any
        outstanding printing requests are waiting.

_SITE_LOGFILE               [Default: /tmp/ConsoleLog]

        Default file where console logs should be written when
        requested by the user of console.

_SITE_MTAB          [Default: /etc/mtab]

        File that console should use for obtaining information about
        the mounted file systems.

_SITE_BIN_SH                [Default: /bin/sh]

        Default shell to use for exec'ing sub-programs.

_SITE_DEV_TTY               [Default: /dev/tty]


_SITE_DEV_PTYP              [Default: /dev/ptyp]


_SITE_DEV_CONSOLE   [Default: /dev/console]

        Stream that console intercepts for its log (actually, its 0th log).

_SITE_DEV_KMEM      [Default: /dev/kmem]

        Device that console should use to obtain memory statistics.

_SITE_VMUNIX                [Default: /vmunix]

    File where console should get information about the kernel's
        symbol table.


1.2.3	The mailconf.c and svcconf.c Files

./overhead/util/lib/svcconf.c and ./overhead/mail/lib/mailconf.c --
These files contain configuration information for the mail system. You
will not likely have to change anything in this file; instead, once the
system is built, you will be able to change these options via the
AndrewSetup mechanism. The details concerning the information in this
file can be found in the AndrewSetup documentation
(./overhead/util/lib/setup.help), the Andrew Message System Installation
manuals (in ./ams/doc), the Andrew Message Delivery System Installation
manual (./ams/doc/AMDS.ins), and in the White Pages installation manual
(./overhead/util/lib/WP.ins).

After making your initial system build, but before expecting the
mail-related software to work, you should review the AndrewSetup help
file to check whether the settings for the available options are correct
for your system.

If you have problems bringing up the mail system and you believe that it
is a result of information contained in the svcconf.c or mailconf.c
files, you should send mail to: 

    info-andrew-bugs@andrew.cmu.edu


1.2.4	The allsys.h, system.h, and site.h{.tpl} Files: Defining What
Parts of Andrew to Build

./config/allsys.h, ./config/<machine>/system.h, ./config/site.h -- These
files specify several things: what parts of Andrew will be built, where
the resulting systems should be placed, and what flags and facilities
are available for that build. This section, 1.2.4, describes the options
in ./config/<machine>/system.h that select what parts of Andrew will be
built. The next section, 1.2.5, describes the options in
./config/<machine>/system.h that specify where the Andrew system is to
be installed and what facilities are available for its use.

Definitions in these files are structured so that definitions in
allsys.h come first, then system-dependent overrides in system.h, then
site-specific overrides in site.h.

You should NOT edit either ./config/allsys.h or ./config/system.h.
Instead, an empty ./config/site.h.tpl file is distributed.  Copy the
template file ./config/site.h.tpl to ./config/site.h   You should then
edit the non-tpl files to override what has come before. (You can do
this using both #undef and #define.)

In the simplest case, you would copy ./config/site.h.tpl to
./config/site.h,  which results in all facilities being built into
/usr/andrew. The success of this simplest case, however, depends on the
assumptions made in ./config/allsys.h and ./config/<machine>/system.h
being correct for your environment, so you may need to review the
options described in section 1.2.5. 

The default settings for this first group of options will build only a
portion of the Andrew system. This includes the basic editor and
typescript, the help system, a number of objects (including text,
c-text, raster, spreadsheet/table, drawing, animation and equations),
and the messages interface programs (messages, cui, vui). The set has
been chosen to allow you to view most of the messages demonstration
folder. You may add other parts of the system by defining the
appropriate flags in your ./config/site.h file. You can also choose to
build a smaller portion of the system by undefining the appropriate
flags. A description of the space requirements for setting certain
switches is presented later in this document.

AMS_ENV				[Default: defined]

    AMS_ENV is defined if the Andrew Message System should be built.
    This is the messages program and related libraries and programs.
     This distribution also contains Metamail.  See METAMAIL_ENV. 
    If you did not pick up auis3.tar.Z (ams and atkams) then you
    must undefine AMS_ENV by adding the following line to your
    ./config/site.h file: 

        #undef AMS_ENV

AMS_SUBSCRIPTIONMAPFILE		[Default: ".SubscriptionMap" or ".SubsMap"]

    This is the name of one of the files AMS uses to store information
    about the bboards which exist.  For historical reasons it defaults
    to .SubscriptionMap unless compiling on an HP or a SysV system
    (where M_UNIX is defined).  The reason for the distinction is the
    limitation of these systems to 14 character filenames.   If bboards
    will be stored on filesystems with this limitation all clients which
    access them must be compiled with:

        #define  AMS_SUBSCRIPTIONMAPFILE ".SubsMap" 

    in the site.h file.

    If HP or SysV systems without the 14 character limit on filenames
    are used all clients should be compiled with:

        #define  AMS_SUBSCRIPTIONMAPFILE ".SubscriptionMap"
         
    If you're not sure and don't have any existing AMS bboard trees the
    ".SubsMap" setting is safe for all systems.  If you have an existing
    AMS bboard tree you can check which setting to use with ls -a
    ..../.MESSAGES/.Subs*  (Where .... is replaced with the path to the
    top of the bboard tree.) 

METAMAIL_ENV			[Default: not defined]

    Metamail is an implementation of MIME, the Multipurpose Internet
    Mail Extensions, a proposed standard for multimedia mail on the
    Internet.

    Set MK_METAMAIL to build the version of Metamail that comes with
    this distribution and define METAMAIL_ENV if you are going to
    use it.  Some AMS code takes advantage of Metamail and
    METAMAIL_ENV is used to communicate that metamail is installed
    on the system.  Metamail is also distributed through other
    channels so, if you've already picked it up from elsewhere you
    would want to #define METAMAIL_ENV while not defining
    MK_METAMAIL.

AMS_DELIVERY_ENV		[Default: not defined]

    AMS_DELIVERY_ENV is defined if the Andrew Message Delivery
    System is to be built, regardless of whether it is expected to
    be used locally. Also see RUN_AMDS_ENV in a following section. 

    Note: The mail and sendmail programs will not automatically be
    replaced with the versions that call AMS. You must install these
    programs by hand after the system has been built successfully.
    These programs will be built and will be located in
    ./ams/delivery/{mail,sendmail}.

WHITEPAGES_ENV			[Default: not defined]

    WHITEPAGES_ENV is defined if the white pages facility (including
    phonetic name lookup) is to be built and used by the Andrew
    Message System.

SNAP_ENV				[Default: not defined]

    SNAP_ENV is defined if the Message Server is to be built.

WM_ENV				[Default: not defined]

    WM_ENV should be defined if you want to build the Andrew Toolkit
    to run on the unsupported ITC Window Manager (WM) which is not
    provided in this distribution. You can specify the root location
    of your WM include files and libraries by defining WMBASEDIR in
    your site.mcr file. 

X11_ENV				[Default: defined]

    X11_ENV is defined if the Andrew Toolkit is to be built for the
    X.11 Window System.

PRE_X11R4_ENV			[Default: not defined]

    PRE_X11R4_ENV should be defined if you will be linking against
    X11 header files and libraries that come from versions of X11
    prior to the fourth release (X11R4). This information is needed
    because release 4 defines some new variable types and makes use
    of ANSI C function prototypes.

DPS_ENV				[Default: not defined]

    DPS_ENV should be defined if your systems support the Display
    PostScript extension to X Windows. IBM's X.V11R3 server product,
    DEC's DecWindows product, and Sun's Solaris 2.3 all have this
    extension, while the MIT servers typically do not. Defining this
    variable will cause some code to attempt to link against the DPS
    libraries. It will also cause some code to attempt to contact
    the DPS extension of an X server at runtime.

ANDREW_MALLOC_ENV	[Default: defined]

    ANDREW_MALLOC_ENV, if defined, causes the Andrew Toolkit memory
    management package to be used. This memory allocator package not
    only saves VM space but also provides more error detection, when
    compared to many of the memory allocators distributed with Unix
    systems. On some system platforms, use of this allocator has led
    to multiply defined symbols. If this occurs, you can undefine
    this symbol and rebuild atk/basics and atk/apps.

DEBUG_MALLOC_ENV		[Default: not defined]

    DEBUG_MALLOC_ENV is defined if the debugging version of the
    Andrew Toolkit memory management package should be used. Its
    definition implies the definition of ANDREW_MALLOC_ENV.

SITE_ENV				[Default: not defined]

    SITE_ENV controls the construction of site specific Andrew
    applications. The source for such applications are meant to be
    placed in the directory ./site. See further documentation in
    ./site/README.site.

NO_FONTS_ENV			[Default: not defined]

    NO_FONTS_ENV controls whether or not the Andrew fonts will get
    built. Some sites, that make heavy use of Xterminals or support
    many different display types, may find it convenient to not
    convert the fonts to any specific server format. By default this
    symbol is not defined and, thus, the fonts are created and
    installed during the build process. Define this symbol in your
    ./config/site.h file if you do not want the Andrew fonts to be
    built.

FONTS_TO_BDF_ENV 		[Default: not defined]

    FONTS_TO_BDF_ENV controls whether or not the Andrew fonts will
    be converted into their Server Normal Format (.snf) during the
    build process. It may be convenient to leave the fonts in Bitmap
    Distribution Format (.bdf) when it is necessary to convert these
    to various different Server Normal Formats corresponding to the
    various X servers that may exist at your site. If you define
    this symbol the result will be that all of the Andrew fonts will
    be installed into ${DESTDIR}/X11fonts in BDF. You can then run
    self-created font conversion scripts to go to the various final
    formats.

FONTS_TO_PCF_ENV		[Default: defined]

    FONTS_TO_PCF_ENV controls whether the Andrew fonts will be
    converted into the .pcf format during the build process. If this
    is defined, you should ensure that XFC is a valid path to your
    bdftopcf compiler.

OPENWINDOWS_ENV		[Default: not defined]

    If you want to run Andrew applications under Open Windows,
    define this symbol in your site.h file. If you define this
    symbol, you should set your path to include the Open Windows
    binaries (usually /usr/openwin/bin). Open Windows is available
    only on Sun platforms. As such, all Sun site files define a
    CONVERTFONT macro to be /usr/openwin/bin/convertfont. You can
    override this default value in your ./config/site.mcr file. 

OLD_ULTRIX_ENV		[Default: not defined]

    Some older version of the Ultrix operating system had a bug that
    caused passwords to be echoed in the typescript program. Define
    this symbol in your ./config/site.h file if you are using a
    version of Ultrix that has this bug.

CONTRIB_ENV			[Default: not defined]

    CONTRIB_ENV controls the construction of the contributed
    software found under source directory ./contrib. At present,
    this includes a growing collection of interesting and valuable
    utilities and objects, including various classes for viewing
    programming language text files, a slew of utilities and classes
    submitted by MIT (such as header/footer, note, ps), an audio
    inset from Bell Labs, a subclass of textview that recognizes
    gestures (gtextv), and the termulator shell interface (tm).

    In order to build the ./contrib section, you need to pick up the
    contrib.tar.Z file from the ftp server.  

DOC_ENV				[Default:  not defined]

    DOC_ENV controls the installation of the documents in the ./doc
    directory.  You should define DOC_ENV in your ./config/site.h
    file if you would like to have the documents installed.   


ISO80_FONTS_ENV		[Default: defined]

    ISO80_FONTS_ENV controls which text fonts are used by Andrew
    applications. If ISO80_FONTS_ENV is defined, then a font.alias
    file is installed $ANDREWDIR/X11fonts to supply pointers to the
    X11 fonts that comply with the ISO 8859 defined international
    character set. For sites that have these fonts, this is the
    preferred option, since it will make accented characters
    available to users and programmers in most applications,
    including messages. See the cpchar help file for details on how
    to use them. This option also provides better behavior when used
    with R5's scalable fonts, and with 100dpi fonts, and it also
    eliminates the need for additional fonts to be installed in the
    destination directory. The only known drawback is that these
    fonts are not as carefully tuned as the their Andrew
    counterparts.

MK_BASIC_UTILS			[Default: not defined]
MK_BASIC_INSETS			[Default: defined]
MK_BLD_BLKS				[Default: defined]
MK_HELP					[Default: defined]
MK_TEXT_EXT				[Default: defined]
MK_AUTHORING			[Default: not defined]
MK_AUX_UTILS			[Default: not defined]
MK_AUX_INSETS			[Default: not defined]
MK_EXAMPLES			[Default: not defined]
MK_METAMAIL			[Default: defined]
MK_CALC				[Default: not defined] (in contrib)
MK_CHAMP				[Default: not defined] (in contrib)
MK_ZIP					[Default: not defined] (in contrib)

    These flags control the building of groups of software; the core
    of the ATK is not dependent upon these flags, but will be built
    if any part of the ATK is built. Normally, these flags are all
    defined.

        MK_BASIC_UTILS  (= console + ezprint + preview + launchapp)
        MK_BASIC_INSETS         (= eq + fad + table + layout)
        MK_BLD_BLKS     (= apt + org + bush + chart + figure)
        MK_HELP                 (= rofftext + help)
        MK_TEXT_EXT     (= srctext + lookz)
        MK_AUTHORING    (= controllers + music + ness + createinset
        + layout)
        MK_AUX_UTILS    (= datacat + toez + prefed )
        MK_AUX_INSETS   (obsolete)
        MK_EXAMPLES     (= examples)

    If you only want to build part of one (or more) of these groups,
    a flag MK_<SUBDIRECTORY> can be used to specify the ones you
    want to build; i.e.:

        MK_APT
        MK_BUSH
        MK_CALC         (CONTRIB_ENV must also be set)
        MK_CHAMP        (CONTRIB_ENV must also be set)
        MK_CHART
        MK_CONSOLE
        MK_CONTROLLERS
        MK_CREATEINSET
        MK_SRCTEXT   (includes ctext)
        MK_DATACAT
        MK_EQ
        MK_EXAMPLES
        MK_EZPRINT
        MK_FAD
        MK_FIGURE
        MK_HELP
        MK_LOOKZ
        MK_MUSIC
        MK_NESS
        MK_ORG
        MK_PREFS                (otherwise known as prefed)
        MK_PREVIEW
        MK_ROFFTEXT
        MK_TABLE
        MK_TOEZ
        MK_ZIP          (CONTRIB_ENVmust also be set)

    The ATK Imakefile (./atk/Imakefile), that uses these flags, has
    been fairly carefully set up so that it will build parts of the
    toolkit to support the parts that you ask to be built; in other
    words, it knows about the various inter-dependencies. Thus even
    if you don't have MK_AUTHORING set, it will build 'value' if you
    have AMS_ENV set, because it knows that the program 'Messages'
    uses the 'value' inset.

The ./contrib/Imakefile uses MK_CALC, MK_CHAMP, MK_ZIP to decide whether
to build those programs.  It builds tm except on the SGI Iris.  alink is
built only on Sun Sparcs.  If AMS_DELIVERY_ENV is defined the pobbconf
directory will be built. (it consists of utilities for running the post
office machines needded by AMDS.)  If AMS_ENV is defined the eatmail
program will be built.  (This program incorporates mail from a normal
Unix spool mail file into the AMS mailbox.)

The programs rtf2, 2rtf, and scribetext are located in ./contrib/mit. 
These programs are only built if CONTRIB_ENV is defined as well as
RTF_ENV (for 2rtf & rtf2) or SCRIBETEXT_ENV (for scribetext).  These
programs are not built by default.

RTF_ENV	[Default:  not defined]
    2rtf takes an ATK datastream file and produces an RTF file capable
    of being used by Microsoft Word.  Alternately, rtf2 takes an rtf
    compatible file and produces an ATK datastream file capable of being
    used by ATK client programs. 

SCRIBETEXT_ENV 	[Default:  not defined]
    Scribetext takes a Scribe compatible manuscript file and produces an
    ATK datastream file capable of being used by ATK client programs. 

NEOS_ENV 	[Default:  not defined]
    Neos is a system for the electronic submission and grading of
    papers.  It requires Kerberos.

1.2.5	The ./config/allsys.h, ./config/<machine>/system.h, and
./config/site.h Files: Describing Your Environment

The ./config/allsys.h, ./config/<machine>/system.h, and ./config/site.h
files also contain a number of flags that need to be set appropriately
for your environment, describing whether or not various facilities are
available, where and how the software is to be installed, etc.

LINKINSTALL_ENV		[Default: not defined]

    WARNING:  As of Release 6.0, this installation option has not
    been thoroughly tested and may not compile cleanly.  It should
    NOT be used, we cannot support it.
    LINKINSTALL_ENV controls the method by which constructed files
    are installed. The choice is to copy or link the files. If
    LINKINSTALL_ENV is defined, the destination tree is constructed
    as a symbolic link tree, rather than actually installing
    (copying) the binaries, libraries, etc. into $(DESTDIR). 

POSIX_ENV				[Default: system dependent] 

    You will normally not need to modify this symbol.  When defined this
    symbol causes code mostly conformant to POSIX to be used where
    available.  (The code is by no means completely conformant, and some
    old BSD-style code probably still persists.)

CLASS_CTRAMPOLINE_ENV  	[Default: system dependent]

    When this preprocessor macro is defined the usual method of
    dispatching class procedures is modified to avoid the need for an
    assembly language "trampoline" routine.  This symbol is defined to 1
    in the system.h files for hp700_80, hp800_80, and telmat_svr4. 
    Generally this symbol should only be set in the system.h file for an
    architecture where it is not feasible to write the assembly language
    trampoline code.

ANSI_COMPILER			[Default: system/compiler dependent]

    You will normally not need to modify this symbol.  When not
    defined this symbol causes special measures to be taken to
    compile some code.  (Particularly in ./overhead/image.)

AFS_ENV				[Default: not defined]
    (note: if AFS_ENV is defined, then WHITEPAGES_ENV should also be
    defined. Even if you don't intend to actually use the white
    pages.)
    AFS_ENV is defined if the Andrew File System is being used. This
    is a distributed file system available from Transarc
    Corporation. For more information, please send mail to
    afs-sales+@transarc.com.   If AFS_ENV is defined, it is assumed
    that the following files will be available under AFSBASEDIR :
        include/afs/afsint.h include/afs/auth.h
        include/afs/cellconfig.h include/afs/print.h
        include/afs/prserver.h include/afs/comauth.h
        include/afs/auth.h include/afs/errors.h
        include/afs/prs_fs.h include/afs/venus.h
        include/afs/vice.h include/rx/xdr.h lib/afs/libauth.a
        lib/afs/libsys.a lib/librx.a lib/liblwp.a
    If SNAP_ENV is also defined, other files needed under AFSBASEDIR are:
        lib/afs/librauth.a lib/afs/libacl.a lib/libr.a lib/libscrypt.a
    If RUN_AMDS_ENV is also defined, so that ./contrib/pobbconf will
    be built, AFSBASEDIR/bin/fs will also be needed.

AFS30_ENV				[Default: not defined]

    AFS30_ENV is defined if version 3.0 or later of the Andrew File
    System (including the protection server) is being used. If
    AFS30_ENV is defined, so should AFS_ENV be. If this is defined,
    it is assumed that the following files will be available under
    AFSBASEDIR, in addition to those listed in the basic AFS_ENV
    discussion:
        include/afs/acl.h include/afs/prclient.h
        include/afs/prerror.h lib/afs/libprot.a lib/libubik.a
        lib/librxkad.a lib/libscrypt.a lib/afs/libcom_err.a

AFS31_ENV				[Default: not defined]

    AFS31_ENV is defined if version 3.1 or later of the Andrew File
    System (including the protection server) is being used. If
    AFS31_ENV is defined, so should AFS30_ENV be. If this is
    defined, it is assumed that the following files will be
    available under AFSBASEDIR, in addition to those listed in the
    basic AFS_ENV discussion:

        lib/afs/libdes.a

RUN_AMDS_ENV			[Default: not defined]

    RUN_AMDS_ENV is defined is the Andrew Message Delivery System is
    to be run at the site. This option affects only the default
    option values in mail system configuration, specified in the
    files ./overhead/util/lib/svcconf.c and
    ./overhead/mail/lib/mailconf.c, and whether /bin/mail and
    /usr/lib/sendmail are replaced with stubs that call AMDS. See
    AMS_DELIVERY_ENV in the previous section for actually building
    the delivery system.

RESOLVER_ENV			[Default: defined]

    RESOLVER_ENV is defined if the Internet Domain Name Resolver is
    to be used. See also the discussion for the symbol RESOLVLIB in
    the section describing the *.mcr files, because if RESOLVER_ENV
    is defined, RESOLVLIB will be used as the path to the resolver
    library routines.  If you undefine RESOLVER_ENV in your site.h
    file you should set RESOLVLIB to be empty in your site.mcr file.

DITROFF_ENV			[Default: defined]

    DITROFF_ENV is defined if ditroff is available for printing
    Andrew Toolkit documents. (See Section 4 Printing.)

DEFAULT_ANDREWDIR_ENV	[Default: /usr/andrew]

    DEFAULT_ANDREWDIR_ENV should be the pathname of the top of the
    installed tree containing Andrew software. This value is the
    pathname by which users will, by default, execute the Andrew
    software; for example, it is used by some Andrew software to
    know, at execution time, where other pieces of installed Andrew
    facilities may be found. This value may differ from the value
    for BASEDIR in ./config/{allsys.mcr, system.mcr, site.mcr} if,
    for instance, all the Andrew software is to be built using one
    path, and executed using another path.

    Because Andrew software uses dynamic binding of information, it
    needs to know where to find various installed objects, libraries
    and files. The software assumes that everything will be found
    relative to the installed Andrew tree. The pathname of the top
    of the tree is, by default, $(DEFAULT_ANDREWDIR_ENV). If,
    however, you have not installed the Andrew software in
    $(DEFAULT_ANDREWDIR_ENV), you may override the software's idea
    of where the Andrew installation is to be found. This value may
    be overridden by each user's setting the environment variable
    $ANDREWDIR to another pathname, or by the administrator using
    the AndrewSetup mechanism (see ./overhead/util/lib/setup.help)
    and specifying a value for the ``AndrewDir:'' attribute.

    See the discussion under LOCAL_ANDREW_SETUP_ENV.

LOCAL_ANDREW_SETUP_ENV	[Default: not defined]

    The AndrewSetup mechanism, described in
    ./overhead/util/lib/setup.help, is used for specifying system
    options to Andrew software at execution time.
    LOCAL_ANDREW_SETUP_ENV is defined if an additional path (or
    paths) for the AndrewSetup file should be compiled into Andrew
    software.

    Andrew software has many options that may be re-bound
    dynamically with the AndrewSetup mechanism, where a
    configuration file is read in at execution time. (One of the
    options that may be re-bound, for example, is the location of
    the installed Andrew software.) One option that cannot be
    configured by the AndrewSetup mechanism is the location of the
    AndrewSetup configuration file itself. Instead, Andrew software
    searches a path to find the AndrewSetup file to use. The
    LOCAL_ANDREW_SETUP_ENV option is the way that the Andrew
    installer may specify that Andrew software look in additional
    locations for the AndrewSetup file.

    Andrew software looks in the following five (or more) locations
    for an AndrewSetup file:
        /AndrewSetup
        /etc/AndrewSetup
        $(LOCAL_ANDREW_SETUP_ENV)
        /usr/vice/etc/AndrewSetup
        $(DEFAULT_ANDREWDIR_ENV)/etc/AndrewSetup
        /usr/andrew/etc/AndrewSetup
    (These alternatives have arisen from feedback about how typical
    sites protect their system directories.) If any file is found in
    this path, its values are used and no further files are
    examined; otherwise, compilation-time default values are used.
    The default condition for the LOCAL_ANDREW_SETUP_ENV option,
    that it not be defined, specifies that only those five locations
    are read. If LOCAL_ANDREW_SETUP_ENV is defined, it should be a
    path name of an AndrewSetup file, in double-quotes. It may also
    be a comma-separated list of double-quoted path names if many
    paths should be checked.

    An AndrewSetup file could, for example, contain the line

        AndrewDir: "full path of andrew tree base not in quotations"
        RequiredSubsFile: /usr/lib/RequiredSubscriptions

DEFAULT_LOCALDIR_ENV	[Default: "/usr/local"]

    DEFAULT_LOCALDIR_ENV controls where to find locally-installed
    information. Only a few options are specified via this ``local''
    directory; two examples are the name of a library of console
    files and the name of the file that names the folders to which
    all users must subscribe (via AMS). Andrew software's idea of
    the ``local'' directory may be overridden by either the value of
    the LOCALDIR environment variable or the value of the
    AndrewSetup option ``LocalDir''.

NDBM_ENV			[Default: defined for only some platforms]

    NDBM_ENV controls whether some parts of AMDS, the Andrew Message
    Delivery System, can use the ``ndbm'' package to manage small
    local databases.

GETDOMAIN_ENV		[Default: defined for only some platforms]

    GETDOMAIN_ENV, if defined, says that the getdomainname(2) call
    is available on this system and may be concatenated with the
    result of gethostname(2) to obtain a fully-qualified domain name
    for the local machine, for use by AMS. While this option is not
    defined in the distributed ./config/allsys.h file, it is defined
    in the platform-dependent ./config/@sys/system.h file for all
    Suns, for Vax BSD, and for Vax Ultrix version 3.0 and later.

RELEASE2_ENV			[Default: not defined]

    RELEASE2_ENV controls the use of some X.V11R2 specific files. By
    default, this is undefined (which then assumes an X11 release 3,
    4, or 5 environment). This only affects which font compiler (fc
    versus bdftosnf) is used, how aliases for fonts are generated,
    and some workarounds for early bugs in the Xlib region code.


1.2.6	Other Machine Types

If you are building this software on another machine type (other than
one for which a .mcr and .h file have been provided for) you will need
to create ./config/<machine>/system.mcr and ./config/<machine>/system.h
files, and rework the ./config/platform.tmpl file to include your new
./config/<machine>/system.mcr file. Other directories that need
customization are:
	./overhead/class/machdep
	./atk/console/stats
	./atk/console/stats/<machine>
	./atk/console/stats/common

1.2.7	Notes on Installation on a MIPS system (Including Decstations)

The previous notes about dealing with -G 0 libraries no longer apply.
MIPS has contributed a new ATK port which eliminates the complexities of
the old setup.  However gcc should not be used, use the mips cc.

1.2.8	Notes on Installation on a Sun 4 (SPARC) system

There have been reports of various version of the Sun C compiler dumping
core when optimization is used. You may find it necessary to set the
CDEBUGFLAGS= in the Imakefile for the directory in which the build
fails. Then rebuild the Makefile for that directory and recompile it
from scratch. 

XLIB and RESOLVLIB must be full pathnames of the archive libraries.

The GNU binutils should NOT be in your path while building AUIS.

As of ATK 4.10.0, there is support for the SunOS4.1 native dynamic
loader. Unfortunately, Sun has not made dbx cognizant of any
dynamically-loaded symbols. There is a patch set located on
ftp.andrew.cmu.edu that, when applied to gdb 3.5, provides a new
command, "add-dlopened-files", which finds out what objects have been
loaded since the last time "gdb" checked what objects have been loaded,
and loads the symbols for any new ones. 

[These notes about GDB 4.x and SunOS 4.x are from
auspex!guy@uunet.uu.net (Guy Harris).]

GDB 4.x includes support for SunOS 4.x dynamically-loaded code, both
shared libraries and "dlopen()"ed stuff. GDB 4.1 handles shared
libraries better, in that it automatically finds them; you still have to
use the "sharedlibrary" command to load up the symbol tables for stuff
loaded up by "dlopen()" - "sharedlibrary", with no arguments, appears to
find every shareable object that's been "dlopen()"ed since
the last time it checked, and read its symbols in.

There is a bug in GDB 4.1 where it doesn't set the "end of text" address
in the "partial symbol table" entry for a shareable object correctly; it
relocates the *beginning of text* address to put it where the object was
actually loaded, but not the end of text address. One consequence of
this is that you can't always (can't ever?) step into a routine in a
"dlopen()"ed shareable object. The following patch appears to fix that
(and has been sent to "bug-gdb", and appears in GDB 4.2):

*** dbxread.c.dist	Fri Sep 20 23:47:25 1991
--- dbxread.c	Mon Sep 30 18:20:27 1991
***************
*** 1708,1714 ****
  #ifdef END_OF_TEXT_DEFAULT
    end_of_text_addr = END_OF_TEXT_DEFAULT;
  #else
!   end_of_text_addr = text_addr + text_size;
  #endif
  
    symtab_input_desc = desc;	/* This is needed for fill_symbuf below */
--- 1708,1714 ----
  #ifdef END_OF_TEXT_DEFAULT
    end_of_text_addr = END_OF_TEXT_DEFAULT;
  #else
!   end_of_text_addr = text_addr + addr + text_size;	/* Relocate */
  #endif
  
    symtab_input_desc = desc;	/* This is needed for fill_symbuf below */

1.2.9	Notes on displaying on an Open Windows server

Open Windows uses it's own font format.  To build the appropriate fonts,
 you will need to compile on a machine with Open Windows installed and
with OPENWINDOWS_ENV defined in your ./config/site.h file.  If you won't
need the normal X .bdf fonts you can then replace the contents of the
$ANDREWDIR/X11fonts directory with that of the $ANDREWDIR/Xnewsfonts. 
If you don't wish to replace the contents of the X11fonts directory you
will need to explicitly add the Open Windows versions of the Andrew
fonts to your fontpath with a command like: xset +fp
$ANDREWDIR/Xnewsfonts in your .xinitrc.

1.2.10	Notes on Installation on a IBM RS/6000

This distribution builds for both rs_aix31 and rs_aix32.  Since there
are no differences needed for the various sytem files, the term rs_aix3
is used for both system types.  

If you are using AIX 3.1 or earlier running X.V11R3, you must use the
version of imake in /usr/lpp/X11/Xamples/util/imake.  Otherwise, you can
use the X11R4 imake that comes with AIX 3.2.  

Do not build the Class pre-processor (./overhead/class/pp) with
optimization-- it tickles a bug that causes later classes to fail.

If you are installing Andrew into a directory other than the one it is
being built into (ie. your destination directory isn't $(BASEDIR)), you
MUST set the parameter SHARED_LIB_PATH in your site.mcr file to match
the destination directory.  Otherwise the RS/6000 dynamic library system
will not be able to find important modules at run time.  The file
./config/rs_aix31/system.mcr sets this by default:

SHARED_LIB_PATH = -L${BASEDIR}/lib

for example, to set your destination directory to /usr/andrew you would
add the line:

SHARED_LIB_PATH = -L/usr/andrew/lib

to your ./config/site.mcr file.

1.2.11	Notes on Installation on PS/2 AIXv1.2

The PS/2 C compiler will die with optimization in these directories:

./overhead/parsec
./atk/raster/cmd
./atk/eq

Compile these directories with "CDEBUGFLAGS=".

1.2.12 Notes on Installation on SCO Unix 

First, in order to compile AUIS on standard SCO UNIX, you must use GCC.
The C compiler has a limit on identifier lengths, and it will be
entirely too painful to get around it. 

Second, you will want the following in your ./config/site.h and
./config/site.mcr files:

./config/site.h:

#define MEMMOVE_IS_BROKEN 1
	-> this replaces memmove() with a correctly working bcopy()
#define POSIX_ENV 1

-> If you're using the Elan Eroff package, then try these:

#define print_FORMATCOMMAND "cat /tmp/%s.n |"
#define print_PRINTCOMMAND "/usr/sco/bin/netroff -Le -b %s"
#define print_PSCPRINTCOMMAND "lpr -dps"
#define EROFF_ENV 1

./config/site.mcr:

CC = gcc -fwritable-strings
GCCLIB = '/usr/local/lib/gcc-lib/architecture/version/libgcc.a'

GCCLIB should be the full path to libgcc.a.

AUIS has not be tested under SCO Unix for some time, there may be
incompatibilies of which we are not yet aware.  If you have any problems
please contact us at info-andrew-bugs@andrew.cmu.edu.  
1.2.13 Notes on HPUX

1.  This release supports only HPUX8.0 or greater.  If you have a need
to build Andrew for an earlier version of HPUX, please contact the
Andrew Consortium for details on how to do so.  

2.  Because it is not possible to determine what version of HPUX you
have on the machine, see the file andrew/config/hpx.series for hacks to
enable compilation on HP Series 9000 machines.  

3.  There are several problems with ld on HPUX8.0.  ATK dynamic objects
are shared libraries.  The HPUX 8.05 link editor has a problem linking
either 1) normal archive libraries, or 2) shared libraries, into other
shared libraries.  So, for instance, if you are working with a dynamic
object, foo.{c,ch}, and it makes use of some math functions, you would
normally use this imake rule to create it:

	DynamicObject( foo, foo.o,,-lm)

For HPUX8.0 do not include the math library in this rule.  The main
executable, runapp, will contain the math library.  There has been
defined a make macro, MATHLIB, that is set appropriately and should be
used thusly:

	DynamicObject( foo, foo.o,,${MATHLIB})

If any of your Andrew-related software is to be expected to compile on
HPUX8.0 platforms, please use MATHLIB until there is an update to the
system.  As of this writing, HPUX 8.07 apparently fixes this problems
but has not been confirmed.  

4.  There may be problems if you have LPATH set to favor pa1.1
libraries, unset LPATH before compiling AUIS.

5.  There is a problem building amsn.do (the messages interface to ams)
because no shared version of libl.a is available,  this problem hasn't
been encountered under HP-UX 9.03 though.  Upgrade if possible. 
Otherwise complain to HP that a shared or pic version of libl.a should
be available.
You may wish to get and use flex instead, but we haven't tested this.
To use flex:

First get flex and compile it with the +z option passed to cc. 
Presumably you can do this with:

make CC="cc +z" <whatever arguments building flex calls for>

In site.h add:
#define FLEX_ENV 1

In site.mcr add:
LEX = flex /* or the path to flex */
LEXLIB = -lfl /* or the path to libfl.a */

Edit overhead/eli/lib/elil.flex:

Replace the line:

int my_yy_input(char *buf, int max_size, FILE *yyin)

with:

#ifdef ANSI_COMPILER
int my_yy_input(char *buf, int max_size, FILE *yyin)
#else
int my_yy_input(buf,max_size,yyin) char *buf; int max_size; FILE *yyin;
#endif

1.2.14 Notes on NeXT

The cpp supplied with the 2.0 release of the NeXT OS is not suitable for
use in imake.   Recent versions include a version of cpp and this cpp is
known to work.

1.2.15 Notes on SGI Iris

Console has not been ported to this system.  To avoid attempting to
build it, modify the following files as indicated:

./config/site.h: (add the following lines)
#undef MK_BASIC_UTILS
#define MK_EZPRINT 1
#define MK_PREVIEW 1

./config/site.mcr: (add the following line)
LAUNCHAPP = launchapp

1.2.16  Notes on Sun Solaris

The GNU binutils should NOT be in your path while building AUIS.

The C preprocessor does not define SOLARIS.  As such, you must add the
-DSOLARIS flag to the initial imake that generates the top level
Makefile.   Your initial command will be: 

imake -I. -I./config -Timake.tmpl -s Makefile -DSOLARIS -DTOPDIR=.

If you are not using the standard user account set up you may need to
set LD_LIBRARY_PATH, or add the following to site.mcr:

 SHARED_LIB_PATH = -R${BASEDIR}/lib:${XLIBDIR}:/lib:/usr/lib:/usr/ccs/lib

This will ensure that all the shared libraries needed for AUIS can be
found.  This is necessary only when LD_LIBRARY_PATH does not include the
appropriate directories by default.

1.2.17 Notes on Decstation Ultrix 4.2 and Ultrix 4.3

Ultrix 4.2 and 4.3
If you will be using the Dec versions of the X11 libraries you will need
to add the following to site.mcr:

XLIB = /lib/libc.a $(XLIBDIR)/lib/libX11.a
RESOLVLIB=

If you need to set RESOLVLIB you may need to add it to XLIB (before
/lib/libc.a) as well to avoid multiply defined symbols when building
runapp.  The XLIB line would then be:

XLIB = $(RESOLVLIB) /lib/libc.a $(XLIBDIR)/lib/libX11.a

Ultrix 4.3a
This hackery avoids multiple definitions of malloc which occur because
libX11.a has a malloc function of it's own.

If you are using Ultrix 4.3a and the latest version of the C compiler
you may need to add the following to your site.mcr:

CC=cc -oldc

This fixes a problem with undefined symbols in atkams/messages/lib.

Ultrix 4.3 and AFS
Release 6 of the AUIS (and probably even previous releases) fails to build
on Ultrix 4.3 when it is built to run in an AFS 3.2 environment.  The
first time the problem is seen is when linking "runapp", and the symptom
is that a number of symbols for the XDR routines show up as multiply
defined.  These symbols are defined in both the AFS Rx library, and the
Ultrix C library, and differences in cross-module symbol references make
it impossible to link any program using XDR against both of these libraries
at the same time.

However, the XDR routines in AFS are taken directly from the Sun's
RPC source kit (which they distribute freely) - there is nothing special
about them.  It is therefore possible to simply use the XDR routines
provided in the C library instead of using AFS's versions.

To do this, it is necessary to delete the XDR modules from the
appropriate library (librx.a), as follows:

% cd $(AFSBASEDIR)/lib
% cp librx.a librx.a.orig      # Save a copy of the original!
% ar d librx.a xdr.o xdr_array.o xdr_float.o xdr_mem.o xdr_rec.o \
       xdr_refernce.o xdr_update.o
% ranlib librx.a

Note that the module "xdr_rx.o" must remain in librx.a; this is the only
XDR module in this library that contains AFS-specific code.

Once this is done, Andrew will compile and link correctly without any
"multiply defined" symbol errors.

1.2.18  Notes on Installation on a Linux System

AUIS has been successfully made on Linux version 0.99 patch level 14 and
later.  It probably can be made on earlier versions also.  AUIS was
tested using the Slackware 1.1.1 distribution.  The macro COMPILERFLAGS
= -m486 flag is set in the ./config/i386_Linux/system.mcr.  This flag
gets passed to the gcc compiler. 

The following problem reports were submitted by the user who built AUIS
on the Slackware 1.1.1 distribution. 

* In chart, select Rechart -> Dot.  The "points" are denoted with "C".  
This is possibly a font problem.  See Section D2 of the FAQ for
instructions on getting the correct fonts.  

* In chart, select Rechart -> Dot or Rechart -> Line and then select
Expose pallette.  Select Delete in the new pallette and then select any
point on a  Line or Dot. Chart dies.

* Figure does not prompt when you modify a figure and then select Quit. 
It just quits.

* The image do dies on certain documents.  It seems this happens when
trying to import an Xpixmap.

* A raster cannot be imported into an image.

A full AUIS build will require about 95 MB of disk space for the object
tree and 31 MB for the destination tree. Please note that the console
application does not correctly read /proc and is therefore not very
useful.  A binary distribution of AUIS 6.1 is available in
ftp:/pub/Linux/X11/andrew on sunsite.unc.edu.  See the ./FAQ for a list
of known problems.   A binary distribution of Release 6.2 will be made
available soon.  Look for an announcement from the info-andrew
distribution list. 

1.2.19  Notes on Installation on BSD derivatives for 386 class machines

This is the first public release to support NetBSD 0.9, BSDI/386, and
possibly FreeBSD.  

See <sources>/ossupport/i386_bsd/NetBSD.README for more information,
including fixes needed to csh and make for them to work for AUIS.

  2	Building the System

We assume you have a C preprocessor or static preprocessor similar to
the 4.3BSD cpp.c. (You should set symisiz at 7500 and sbfsize at
125*4096.)

To build AUIS,  'cd' to the top-level of the AUIS sources and type the
following :

    {$XBINDIR}/imake  -I.  -I./config  -Timake.tmpl  -s Makefile  -DTOPDIR=.

This will generate the top-level Makefile.  Continuing from the same
directory, use the following commands:

    make World

If you installed the console application you will need to make
$ANDREWDIR/bin/getstats and possibly $ANDREWDIR/bin/getconsole setuid
root, or setgid to an appropriate group.  Typically these programs need
access to /dev/mem and /dev/console.

If you want to build Andrew in stages, these are the steps:

    make Makefiles
    make dependInstall

You can clean out the directories using:

    make Clean

> ("Clean" recurses from that point on. "clean" only cleans out the
> current directory.)

NOTE: if you are using LINKINSTALL_ENV (default off, and against all our
advice) you will probably want to use 'make Tidy' instead of 'make
Clean'. Tidy will only remove the non-installed generated files--i.e. it
will leave libraries, programs, and .do files alone. "Tidy" recurses;
"tidy" does not.

If you do not want to regenerate the dependencies, you can just do a
"make Install" instead of a "make dependInstall". The dependencies
shipped with the tape should work for all machine types; we remove
general system include files from the dependency list.

NOTE: On vaxes we have found it necessary to increase the stack size.
You can do this by:

    limit stack 2048

2.1	Error Recovery

2.1.1	Errors in the Build Process Itself

If the build process should fail sometime before it has completely built
and installed, you can do one of several things, depending on what has
caused the build to fail. The simplest and most time consuming is to fix
the problem and then do a "make dependInstall" from the root of the
Andrew tree.

A faster approach is to continue the build process manually. For
example, assume the make died in ./atk/eq. After correcting the problem,
you could move into the ./atk directory and do a 

    make dependInstall SUBDIRS="fad table rofftext help ..."

where the actual contents of the SUBDIRS entry can be determined by
looking at ./atk/Imakefile. When the build for ./atk completes, examine
the Imakefile for the top level and observe that the remaining SUBDIRS
that need to be built are: ams atkams contrib helpindex xmkfontd and
doc. So change directory to the root of the object tree (./) and execute

    make dependInstall SUBDIRS="ams atkams contrib helpindex xmkfontd doc"

After building the entire system you can recompile and install a subtree
or directory, by moving to that directory and issuing

    make Install

See the file FAQ for a list of common problems and the accompanying fixes.  

  2.2	System Components

The major parts of the distribution consists of: underlying libraries
and programs (overhead), the Andrew Toolkit (atk), the Andrew Message
System (atkams), applications of both ATK and AMS (atkams), and the
Andrew Documentation. In addition, we also include a small collection of
contributed AUIS insets.

This document contains a brief description of the contents of the Andrew
Distribution. 

2.2.1	Overhead
    genmake - a script for generating Makefiles from Andrew
        style Imakefiles
    sys - a program used for distinguishing between different
        system (hardware/os) types
    util - lots of utility functions. Includes the White Pages readers
    addalias - adds aliases for help probes
    errors - a package for handling some low-level error reports
        in a uniform way
    index - utility to map class names to file names
    malloc - the Andrew version of malloc
    class - an object-oriented C language preprocessor used by ATK
    rxp - a regular-expression package used in ELI
    eli - the ``embedded lisp interpreter'' used by AMS
    image - various popular public domain image-compression libraries
    conv - several conversion programs for sites which have used
        earlier versions of the Andrew distribution.
    fonts - fonts used by ATK programs
    xicons - a small collection of icons for use under X window
        managers
    cmenu - the ATK stack-of-cards X11 menu package
    mail - library of AMS functions
    wputil - programs and data to initialize and build a White Pages
    wpi - allows mail-basd updates to White Pages entries


2.2.2	ATK
	Basics (or Core)
        basics - underlying ATK core
        support - underlying ATK core
        supportviews- underlying ATK core
        text - facilities for styled text and text formatting
        utils - support for dialog boxes 
        frame - support for file commands and buffers
        textaux - more support for text operations,  gnu-emacs
            compatibility and ISO Latin-1 input
        atkvers - version numbering scheme
        ez - a multi-media editor
        extensions - many user support packages, include
            gnu-search and meta-x
        typescript - a flexible csh window (not TERMCAP)
        apps - the core application executable
        textobjects - directory editor and a list view
        hyplink - a hypertext-like link inset
        value - a set of widgets for use with adew
        adew - a direct manipulation user interface builder
        raster - a raster (bitmap) editor

        Basic Utilities
            console - a system monitoring program
            ezprint - allows printing of ATK format documents
            image - a color raster viewer
            preview - a ditroff previewer
            rofftext - utility for viewing troff files

        Basic Insets
            eq - an equation editor
            fad - a simple frame animator
            table - a simple spreadsheet

        Building Blocks
            apt - basic components
            org - an organizational chart editor
            bush - a directory tree/file browser
            figure - a drawing editor
            chart - a chart/graph program (line graphs, pie 
            charts, histograms etc.)
            calc - a simple calculator
            prefed - a preferences editor

        Help (program)
            help - a user interface for help files and man pages

        Text Extensions
            srctext - a text formatting package, including support
            for Assembly, C, Modula3 and other languages
            (this package is not an active interpreter - only a formatter)
            spell - a spell checker. See note below.

        Authoring Systems
            ness - an embedded string manipulation authoring system
            syntax - a new set of tools has been introduced for
            token analysis and parsing.
            syntax/bison - a modified version of the Bison parser
            from the FSF
            syntax/parse - a parser object that uses tables 
            syntax/lexan - a superclass for lexical analyzers 
            syntax/tlex - a subclass of lexan which lexically
            analyzes input in the form of an ATK text object.
        syntax/sym - a symbol table package 

        Auxiliary Utilities
            datacat - a utility for concatenating two (or more) ATK
                format files together
            toez - a utility for converting files (scribe, troff)
                into ATK format
            layout - facility for designing screen layouts
            controllers - examples of adew-generated code 
            createinset - a program to create an example inset with
                the name customized
            lookz - a style editor

        Example Programs
            examples  - illustrates how to write an inset and application
        	launchapp - demo application using in the Remote Andrew Demo service

2.2.3	AMS

    delivery - the fundamental programs in AMDS that manage mail
        queues and deliver mail
    demo - builds a multi-media folder that you can use as an
        AMS/ATK demo
    doc - AMS documentation of all sorts
    flames - ELI application that handles new messages interpretively
    libs - libraries used in building AMS user agent programs
    ms - the RPC veneer over the lower-level parts of those AMS
        libraries, making the MessageServer process
    msclients - AMS user agent programs
    utils - useful programs in managing AMDS installations

2.2.4	ATKAMS

    messages - our flagship AMS program; multi-media mail and bboards

2.2.5	Contrib

Among other things, you will find:

    alink - an audio inset for Sparcstations
    atkbook - examples from N. Borenstein's book on the Andrew Toolkit
    bdffont - a BDF font viewing and editting inset
    calc - a calculator program
    champ - a calendar program
    demos - an AUIS demo
    eatmail - a program which transfers mail from
        /usr/spool/mail/{uid} into separate files in {uid}'s Mailbox
        directory
    gestures - a gesture-based text view
    mit/annot - a note and a postscript inset
    mit/neos - Networked Educational On-line System
    mit/scribetext - a scribe text formatter
    mit/thesis - a thesis-writing package
    mit/util - header/footer object for text, a printer option
        dialog box, ez2ps
    parsec - a C language parser plus a procedure to clean up
        YACC output
    snap2 - an RPC package used by the Andrew Message System
    srctext/ltext - a LISP text editing package
    srctext/ptext - a PASCAL text editing package
    srctext/html - an HTML text editing package
    time - analog and digital clocks, time-of-day and writestamp
        (useful in documents)
    tm - an alternative to typescript
        zip - an hierarchical drawing editor

Many of these objects have proven very useful, and are a part of our
default environment at CMU. We welcome your contributions.

2.2.6  Rdemo

This directory tree contains the sources for the Remote Andrew Demo
(rdemo for short).  Rdemo is an Internet network service provided by a
few nodes at the Andrew Consortium.  It allows users anywhere on the
Internet to interactively experiment with Andrew software.

We do not expect that people will want to build rdemo and provide the
network service themselves.  We've included the sources because we
expect that some people may wish to emulate this service and create
their own remote demos.  The sources are included primarily for the
edification of programmers who wish to do this (although there's nothing
stopping you from building the rdemo suite if you so desire).  See the
README in the ./rdemo directory for more information.  

2.3	Make Targets

The generated Makefiles contain the following targets:

        Makefile: Generates the Makefile from the Imakefile in the
        current directory (assuming there is already a Makefile present).

        Makefiles: Generates the Makefiles for subdirectories (does not
        generate the Makefile for the current directory).

        all:
                Builds the contents of the current directory.
                
        depend:
                Generates dependency information for the current directory.
                
        doc:
                Installs documentation from the current directory.
                
        Doc:
                Same as above but recurses thought subdirectories.
                (depends on "doc")

        aliases:
                Generates 'help alias' information for the current directory.
                
        Aliases:
                Same as above but recurses through subdirectories.
                (depends on "aliases")

        install:
                Installs the binaries, libraries, include files, etc.
        for the current directory.
                (depends on "all" and "doc")

        Install:
                Same as above but recurses through subdirectories.
                (depends on "install")

        dependInstall:
                Generates dependency information.
                Installs binaries, libraries, include files etc.
                Installs documentation.
                Recurses through subdirectories.

        world:
                (depends on "depend", "install", "aliases")
                (for current directory only)

        World:
                Same as above but recurses through subdirectories.

        tidy:
                Removes only non-installed generated files (*.o *.BAK
        core, etc) thus not removing files which have links pointing to
        them from DESTDIR.

        Tidy:
                Same as above but recurses through subdirectories.

        clean:
                Removes all generated files (*.o, *.a, etc.) in current
        directory only.
                (depends on "tidy")

        Clean:
                Same as above but recurses through subdirectories.

2.4	What Gets Built

During the build process, the makefile constructs applications,
dynamically loadable objects, libraries, fonts, templates, console
descriptions, help files and include files. Each of these collections
goes into its own directory. At runtime, ATK applications and objects
assume that there will be an environment variable called ANDREWDIR that
will be the root of all andrew related run-time files. (See the
discussion of DEFAULT_ANDREWDIR_ENV, above.) Within the makefiles, the
variable BASEDIR is used for the value you expect to use for ANDREWDIR
during run time. In particular, the system should install files so that
the following directories are used for each category:

        ${ANDREWDIR}/bin - Runnable applications
        ${ANDREWDIR}/dlib/atk - Dynamic objects
        ${ANDREWDIR}/X11fonts -ATK specific fonts for X
        ${ANDREWDIR}/Xnewsfonts - ATK fonts for running under Open
        Windows (if enabled)
        ${ANDREWDIR}/lib/tpls - Style templates for text-oriented objects
        ${ANDREWDIR}/lib/consoles - Console descriptions
        ${ANDREWDIR}/lib/atk - Compile time libraries
        ${ANDREWDIR}/include/atk - Compile time include files
        ${ANDREWDIR}/help - Help files
        ${ANDREWDIR}/doc - Doc files
        ${ANDREWDIR}/etc - Auxiliary files, usually not accessed
        directly by users

2.5	Size of the System

The following list provides information about building the Andrew
system. These are approximate values, derived from our test builds of
the complete system with full debugging (-g). If you have 
LINKINSTALL_ENV turned on then you should only be concerned with the
size of the objects (the installed tree will just contain links back to
the object tree). If you compile the system with optimization and no
symbols (-O) these sizes will be much smaller -- by roughly a factor of
two or three. 35-50M is sufficient for the objects on most systems with
LINKINSTALL_ENV turned on and debugging off.

The minimum setup (including help and the text extensions) occupies
about 25% of the total space.
The default (enough to run the messages demo) is about 75% of the total.
Not compiling with -g will reduce these numbers substantially.

Sources distributed:
    50M

Total Objects:

    Dec Mips: 125M
    Sun4: 170M
    RS/6000: 222M

Binaries:

    Dec Mips: 65M
    Sun4: 82M
    RS/6000: 60M

  3	Setting up the Environment to Run Applications


To run our software you must be running X11, and have your DISPLAY
environment variable set appropriately. Our applications support the
-fg, -bg, -display and -geometry switches.

In addition, most ATK applications also reference the file ~/preferences
or ~/.Xdefaults for lines of the form:

appname.foregroundcolor: colorspec
appname.backgroundcolor: colorspec
appname.geometry: geometryspec

where appname is the name of the application (i.e. console, ez, etc.).

If you want the Check Spelling menu in text to work, you will need the
ispell program. Ispell must be found along a user's path.

Before running AMS, you may want to review the options available with
the AndrewSetup mechanism, described in the setup.help file
(BASEDIR/help/setup.help).

Examples of preferences files and other init files are in the sources in
overhead/util/lib/samples, and are installed into $DESTDIR/lib/samples.

4	Printing

The ATK software uses the new version of troff (ditroff) and Adobe's
TransScript software to provide printing support for Postscript
printers. The defaults are set up to use lpr to spool print requests.
Our applications use two values found in the user's preferences file to
control printing:

    formatcommand: Command used to generate a file to be shipped to
        the printer.
    printcommand: Command used to ship the file to the printer.

The defaults for these commands are:

    formatcommand: eqn /tmp/%s.n | troff - |
    printcommand: lpr -n

This preference will make printing work on RS/6000's:

	?C=rs:*.printcommand: psdit|lpr

A temporary troff file is generated automatically in /tmp in the process
of printing a file. You should run 

    help preferences

once you have brought up the system to see how to change your preferences.

A document describing in some detail how printing works and giving some
guidelines for testing printing is in the source tree in
atk/ezprint/printing.ins.

5	Configuring a Help System 

5.1	The index

Help is configured by default to index (and thus make available) files
in the following directories:

    $(DESTDIR)/help
    /usr/man/man[1-8,n,o,l,p]

This collection of directories indexed by the Help system is specified
in an input file to an index-making program, mkindex. If you want to
index more than the Andrew help files and man pages in
/usr/man(/man[1-8,n,o,l,p]), you should edit the file
``./helpindex/index.tpl'' and add lines for each of the directories you
want to be included in the Help system, in the following format (the
following description is taken from ./atk/help/doc/Maint.d):

#	comment
dir	actual-directory-name	link-directory-name
include	filename
key	keyword	filename

The white space between the words on each line can be any number of tabs
or spaces. Here is an explanation of the commands:

#	comment
    Any line beginning with "#" is a comment and is ignored.

dir	actual-directory-name	link-directory-name
    This command tells mkindex to index the files in
    actual-directory-name, and record the path to those files as
    starting with link-directory-name. At Carnegie Mellon, /usr/man is a
    link to /afs/andrew/<machine>/usr/man, so mkindex's input file
    contains the line:

    dir /afs/andrew/machinetype/usr/man/man1 /usr/man/man1

    where machinetype is the name used to refer to a specific machine's
    system-specific directories.

include	filename
    This line tells mkindex to read in the file filename as more
    mkindex commands. At Carnegie Mellon, this facility is used to
    allow different indices on different machine types to all
    include a set of common system directories.

key	keyword		filename
    This line tells mkindex to explicitly use the given keyword as
    an alias for the file filename. This alias functions identically
    to aliases in the help.aliases file, as described in the section
    Aliases in Maint.doc.

When the whole system is built, helpindex is built last and will make an
index for Help using index.tpl as an input file. The build is
accomplished by changing directory to the root of the object tree and
saying

    make dependInstall SUBDIRS=helpindex

or for any subtree with the command:

    make Aliases

Further information on configuring the Help system and program can be
found in the Help Maintainer's Guide which, once the system is
installed, is in:

    $(DESTDIR)/doc/help/Maint.doc

5.2	The documents

The documents ("help files") that describe the system will probably need
to be edited at some point to reflect the system you have built
correctly, if you intend users not to be unpleasantly surprised by the
lack of a documented feature. Unfortunately, the help files describe a
full installation of Andrew; they are not configured during the building
process to reflect partial installations. In particular, the Message
System documentation may need to be reviewed because it describes a
system that includes the White Pages, the Andrew Message Delivery
System, and (at times) a bulletin board system. See the Help
Maintainer's guide for more information.

6	Hard Copy Documentation

Hard copy user and programmer documentation is available by U.S. mail.
The documents are provided at cost, plus shipping and handling. More
information, as it becomes available, will be posted to info-andrew (see
below), or you can write:

	Information Requests
    Andrew Consortium
        School of Computer Science
	Carnegie-Mellon University
    Pittsburgh, PA 15213
    U.S.A.
    (412) 268-6710
    FAX: (412) 681-5739


7	How to Get More Information about Andrew 

There are two(*) mailing lists read by the developers and others
interested in the Andrew User Interface System. The first is a bug
report list moderated by members of the Andrew Consortium. 

    info-andrew-bugs@andrew.cmu.edu

The second is an unmoderated list devoted (but not limited) to getting,
compiling, and installing Andrew, announcements, bug reports, fixes, and
request for features. This address is: 

    info-andrew@andrew.cmu.edu

Subscription requests should be sent to one of the following addresses:

    info-andrew-request@andrew.cmu.edu

When you send in a request, you will be put on both lists, unless you
specify otherwise. If you are running the Andrew Message System, you can
also request to be put on the multi-media list. This list receives
exactly the same messages as info-andrew and info-andrew-bugs, except
that the messages are sent out with their formatting intact, so you can
see the multi-media portions of messages that have them. If you don't
request multi-media, you will be put by default on the non-multi-media
list.

(*)Note: the second list, info-andrew@andrew.cmu.edu, is
bi-directionally gatewayed with the Netnews group comp.soft-sys.andrew.
You do not/can not subscribe to the netnews group through us, and the
netnews group contains ONLY non-multi-media posts.

