Andrew Toolkit 
Frequently Asked Questions
Release 5.1

This file contains questions from everywhere and answers from many
places.  The sections on General Information and Common Problems
Building Andrew were compiled by Susan Straub (susan+@andrew.cmu.edu). 
The section on User Questions has been extracted from a larger FAQ for
CMU maintained by Andrew Plotkin (ap1i+@andrew.cmu.edu).  You can send
suggestions and comments to these people or directly to the consortium's
mailing list/bulletin board:  

	info-andrew@andrew.cmu.edu.

Send bug reports to:

	info-andrew-bugs@andrew.cmu.edu

For information about the consortium you can contact:

    Wilfred J. Hansen
    Director, Andrew Toolkit Consortium
    238 UCCB   4910 Forbes Ave.
    Pittsburgh, PA 15213
    wjh+@andrew.cmu.edu
    412 268 6710


General Information

G1.  What is Andrew?
G2.  How do I obtain the latest release?
G3.  Which platforms has Andrew been ported to?
G4.  What books have been written for Andrew and where can I obtain them?
G5.  What is the Remote Andrew Demo Service?

Common Problems/Questions Building Andrew

Q1.  Why doesn't my macro expand in site.mcr?
Q2.  How can I instruct "messages" to use /usr/spool/mail for mail drop?
Q3.  Why do I get errors when building Ultrix 4.2 against AFS 3.1 libraries?
Q4.  Why does the distribution as made available on MIT's X.V11R5 tape
    install files as links instead of actual files? 
Q5.  Which configuration variables are used most often? 
Q6.  Do I need to have AFS to run the Andrew Message System (AMS)?
Q7.  How can I get other useful software?
Q8.  How can I use PostScript fonts other than those defined in
    /usr/andrew/X11fonts both in displayed and printed documents? 
Q9.  How can I print Andrew documents?
Q10.  Ezprint outputs rasters in PostScript.  Can I print those rasters?
Q11.  When using UCB sendmail, are aliases in /usr/lib/aliases
case-sensitive?  
Q12.  How can I fix the error message in my console about <getstats/gvm>
    Cannot open /dev/kmem? 
Q13.  I get the following error in my console:  <appname>X error
    BadValue, integer parameter out of range ...  How can I fix this?  
Q14.  Why can't the help program find any help files?
Q15.  Should I modify the Imakefile or the Makefile?
Q16.  How do I use the spell checker function in ez?  
Q17.  How do I debug Andrew applications?  


User Questions  (Extracted from CMU FAQ)

U0. Introduction
U1. Customizing your account
U2. Playing with ATK things, including ez, typescript, console, and help
U3. Mail and bboards, including messages
U4. Strange file formats
U5. Working with graphics and images
U6. Fancy key bindings
U7. Programming in Ness and C

___________________________________________________
General Questions

G1.  What is Andrew?
    The Andrew Toolkit (ATK) is a portable user-interface toolkit
    that runs under X11. It provides a dynamically-loadable
    object-oriented environment wherein objects can be embedded in
    one-another. Thus, one could use our 'generic-object' editor
    (ez) to edit text that, in addition to containing multiple
    fonts, contains embedded raster images, spreadsheets, drawing
    editors, equations, simple animations, etc.. These embedded
    objects could themselves contain other objects, including text.
    With the toolkit, programmers can create new objects that can be
    embedded as easily as those that come with the system. Many
    objects, including those mentioned above, along with a help
    system, a system monitoring tool (console), an editor based
    shell interface (typescript), and support for printing
    multi-media documents, are included in the release, making it
    useful to programmers and non-programmers alike. 

    The Andrew Message System(AMS) provides a multi-media interface
    to mail and bulletin-boards.  AMS contains many advanced 
    features including authentication, return receipts, automatic
    sorting of mail, vote collection and tabulation, enclosures,
    audit trails of related messages, and subscription management.
    It also provides a variety of interfaces that support ttys and
    low-function personal computers in addition to the high-function
    workstations. 

G2.  How do I obtain the latest release?

    This release, 5.1, can be obtained in several ways.  The entire
    X distribution is available via anonymous ftp from the Internet
    host export.lcs.mit.edu (Internet address:  18.30.0.238).  The
    sources of ATK and AMS are located in the contrib/andrew tree,
    one of the contributed toolkits.  Andrew, as well as a variety
    of CMU software and the latest patches, is also available via
    anonymous ftp from the Internet host, emsworth.andrew.cmu.edu
    (Internet: 128.2.30.62).   Due to its size, the compressed tar'd
    tree is split into 11 files, andrew.aa through andrew.ak (about
    1MB each) in the split/ directory.    You should cat andrew.*
    together into andrew.tar.Z, uncompress the tree then tar -xvpf.  

    NOTE:  If you obtain Andrew from the X tape, you will receive
    Release 5.0.  You should review the file ANNOUNCE.5 in the
    contrib/andrew directory for instructions on fixing build
    problems you will encounter.

G3.  Which platforms has Andrew been ported to?

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                 rs_aix31
    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
    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_42
    SGI                         IRIX 4.0                        sgi_4d
    SCO                         SCO                             sco_i386

G4.  What books have been written for Andrew and where can I obtain them?

    Nathaniel S. Borenstein's book: Multimedia Applications
    Development with the Andrew Toolkit (Prentice-Hall).

    ODA Project Book: Multi-media Document Interchange: ODA and the
    EXPRES Project (Springer Verlag).


____________________________
Common Problems/Questions Building Andrew


Q1.  Why doesn't my macro expand in site.mcr?

    Tabs are not allowed before macro declarations in the site.mcr. 
    Although the error is not reported as such, the macro is not
    expanded properly and thus not noticed by imake.  Use spaces.  

Q2.  How can I instruct "messages" to use /usr/spool/mail for mail drop?

    Although the following lines are in /usr/andrew/etc/AndrewSetup:

        AMS_NonAMSDelivery: yes
        AMS_MailBoxPrefix: /usr/spool/mail

    Messages says, "/usr/user/Mailbox" could not be properly read and
>     delivered (0 success, 0 failure)". 

    You should create a file $HOME/.mailrc and put in this line:

        unset hold

    WARNING:  Once you start reading mail with messages, you incoming
    mail will be stored within directories maintained by messages.  It
    is possible to return to other mail handling systems, but it may not
    be easy.

Q3.  Why do I get errors when building Ultrix 4.2 against AFS 3.1 libraries? 

    You need to define AFS_ULTRIX in your site.h file.  

Q4. Why does the distribution as made available on MIT's X.V11R5 tape
install files as links instead of actual files?  This fails in two
directories:  overhead/class/lib and xmkfontd.  

    The distribution defaults to install links instead of files.  To
    change this, #undef LINKINSTALL_ENV in your site.h file.   If you
    want to build using LINKINSTALL_ENV, you will have to change the
    following two files: 

    overhead/class/lib/Imakefile:

        29,32d28
        < #ifdef LIBDL_ENV
        < install.time:: libclass.a
        <       $(INSTALL) $(INSTLIBFLAGS) libclass.a $(DESTDIR)/lib
        < #else /* LIBDL_ENV */
        34d29
        < #endif /* LIBDL_ENV */

    xmkfontd/Imakefile:

        18c18
        <       $(INSTALL)  ${INSTLIBFLAGS} non-andrew.fonts.alias 
        ${DESTDIR}/X11fonts/fonts.alias 
        ---
        > InstallFileToFile(non-andrew.fonts.alias, ${INSTLIBFLAGS},
        ${DESTDIR}/X11fonts/fonts.alias)


Q5.  Which configuration variables are used most often? 

    AFS30_ENV
    AFS31_ENV 
    AMS_DELIVERY_ENV 
    WHITEPAGES_ENV 
    SNAP_ENV 
    ANDREW_MALLOC_ENV
    DEBUG_MALLOC_ENV
    MK_BASIC_UTILS
    MK_AUTHORING 
    MK_AUX_UTILS 
    MK_AUX_INSETS
    MK_EXAMPLES 
    RUN_AMDS_ENV
    ANDREW_PRINTING_ENV
    LINKINSTALL_ENV
    CONTRIB_ENV 
    PRE_X11R4_ENV 
    DPS_ENV 
    DEFAULT_ANDREWDIR_ENV 
    BUILDANDREWINSTALL_ENV 
    ISO80_FONTS_ENV     
    FONTS_TO_PCF_ENV

    CDEBUGFLAGS = -g
    MAKEDODEBUG = -g
    AFSBASEDIR = /usr/local
    XMKFONTDIR = /usr/local/bin/mkfontdir
    XFC = /usr/local/bin/bdftosnf
    XLIBDIR = /usr/local/lib
    XINCDIR = /usr/local/include
    RESOLVLIB = ${AFSBASEDIR}/lib/res/libresolv.a
    RESINC = -I$(AFSBASEDIR)/include/res
    INCLUDES =  -I${BASEDIR}/include -I$(BASEDIR)/include/atk $(RESINC)
    -I$(AFSBASEDIR)/include -I${XINCDIR}


Q6.  Do I need to have AFS to run the Andrew Message System (AMS)?

    No, but having AFS gives you better functionality. 

Q7.  How can I get other useful software?

    Enormous quantities of software are available for free from the
    internet.  Many of the pieces are also available via electronic
    mail.  Subsequent paragraphs list some software that may be of value
    as an adjunct to ATK/AMS.

archie - archive locator
    A major source of information about the location of software on the
    network is 'archie'.  Send mail to 
        archie@archie.rutgers.edu
    In the body of the message include line(s) of the form
        prog   name
    where name is the name of the software you would like to find out
    about.  For more information, the body can contain the line
        help
    The listing returned from a 'prog' request will list ftp sites
    containing information with the name you gave.  A site with a name
    ending in .com, .edu, or .gov will be in the United States and will
    be the best place to try.

ftp - file transfer package
    To retrieve information via ftp over the internet:  Give the command 
        ftp <site name>
    The response will ask for your login;  reply
        anonymous
    the response will ask for your email address;  type it in.  Now you
    can give the help command to see the commands.  I generally use ls,
    dir, cd, lcd, pwd, and get.

on the ATK cd-rom
    Some useful non-ATK software is included in the ATK cd-rom.  For
    details see subsequent paragraphs.
        binaries only:  X11 for RS6000, Sun 4, Dec Pmax, and HP700
        binaries and source:  metamail imake makedepend patch
        source only: ispell, psroff, pbmplus

X Windows System:  X11, imake, makedepend, patch
    Screen management and graphics software
    Binaries on cdrom in <system>/X11/...
    Bdf fonts  on cdrom in  src/util/bdffonts
    imake, makedepend, and patch
        source on cdrom in src/util/...
        objects on cdrom in <system>/util/...
    ftp: export.mit.edu and numerous other sites (see archie)
    newsgroup: comp.windows.x 
    mail address:
        MIT Software Distribution Center
        Technology Licensing Office
        room E32-300
        77 Massachusetts Avenue
        Cambridge, MA  02139
    phone: (617) 258-8330

metamail
	Converter for implementing MIME multi-media internet standard.
	newer version due early April, 1992
	contact:  Nathaniel Borenstein
		Bellcore Room 2A-274
		Morristown, NJ 07962-1910
	phone: (201) 829-4270
	email: nsb@thumper.bellcore.com
	ftp:  thumper.bellcore.com,  see  pub/nsb/README
	source: $ATKSRC/overhead/mail/metamail

pbmplus
	Portable bit map conversion and transformation software
	version in cdrom:/src/util/pbmplus is from   10 December 1991
	contact: Jef Poskanzer
	email: jef@well.sf.ca.us

psroff
	Software augmenting troff and providing printer drivers.
	on cdrom: src/util/psroff  is version 3.0 patch level 07
	contact:  Chris Lewis
	psroff-request@ferret.ocunix.on.ca

ispell  
	version on cdrom in src/util/ispell is 2.0.02
		updated with a bigger dictionary
	new version 3.0 is coming soon
	contact: Geoff Kuenning
	email:  geoff@ITcorp.com

GNU software: groff, g++, gcc, gdb, gnuemacs, ... 
    Free software, eventually replacing Un*x
    ftp: prep.ai.mit.edu
        see pub/gnu/GNUinfo/FTP
        and pub/gnu/etc/DISTRIB
    email: gnu@prep.ai.mit.edu
    mailing address:
        Free Software Foundation, Inc.
        675 Massachusetts Avenue
        Cambridge, MA  02139
        USA
    phone:  +1 617-876-3296

transcript (psdit)
	Contact: 
		Adobe
		1585 Charleston Road
		P.O. Box 7900
		Mountain View, CA 94039-7900
	phone: 1-800-833-6687

Documenter's WorkBench
	AT&T / NCR Computer Division
		800 225 5627
	Gary Wagner  513 445 1475


Q8.  How can I use PostScript fonts other than those defined in
/usr/andrew/X11fonts both in displayed and printed documents?
There are two aspects of this problem: screen display and print display.
Screen Display
    To have your own fonts used by ATK applications for displaying text
    you must first create those fonts and place them in a directory,
    possibly set up a fonts.alias file, run mkfontdir to get a fonts.dir
    file, and finally add that directory to your X fontpath.  Also,
    you'll have to specify in your preferences file the fontname:

    ez.bodyfont: myfont12

Print Display
    To get these fonts to print you have to create the appropriate troff
    device-specific font description files (see /usr/lib/font/devpsc for
    the Postscript fonts).  Question: Are there tools around that let
    you create a troff font? Furthermore, you'd have to alter the
    ATK-to-troff text translator (../andrew/atk/text/txtroff.c) to
    recognize your new font family and to make the appropriate mapping
    from your fontname to the troff fontname.  Currently, the only fonts
    used for printing are Times, Helvetica, and Courier.


Q9. How can I print Andrew documents?

    Printing requires two steps, text formatting and then driving the
    printer.  ATK utilizes troff for text formatting.  That is adequate
    for printing documents with styled texts, but some insets such as
    rasters and zip require that the printer be driven with PostScript.

    Print processing is controlled via the FormatCommand and
    PrintCommand options, which can be specified in site.h during system
    build, the global preferences in $ANDREWDIR/lib/global.prf, or the
    user's ~/preferences file.  The most general defaults are:
        *.FormatCommand: eqn -Tpsc /tmp/%s.n  | troff -Tpsc - |
        *.PrintCommand: lpr -n
    The -Tpsc flags specify that the troff output is ultimately intended
    for a PostScript printer.  If you do not have one, this value must
    be set to whatever is appropriate for your printer.  ATK documents
    containing only styled text can be printed via most versions of
    troff and most print drivers.

    To print ATK documents via PostScript printers, you have three options:
        troff - psroff
        ditroff - psdit
        groff
    These differ in cost and the difficulty of installation.  See Q8 for
    hints on acquiring these packages.

    troff - psroff
    Standard Unix systems are often delivered with an old troff which
    generates output for the "CAT" typesetter.  This troff can be used
    to print ATK documents by sending the output through the psroff
    processor, available freely on the internet.  See the psroff
    documentation.

    ditroff - psdit
    This is the route we use at CMU.  ditroff is the device independent
    troff which comes with the Documenters Work Bench portion of Unix
    System V.  psdit is part of the "Transcript" package available from
    Adobe software.  Both ditroff and Transcript cost money.  Adjust the
    FormatCommand to utilize the ditroff version of troff (it is usually
    called troff).  The PrintCommand should usually use the -n switch
    and the lpr daemon will run psdit.

    groff 
    This package is free from the Free Software Foundation, the gnu
    people.  The only hitch is that to build groff you must first build
    g++ and to build g++ you must first build gcc.  We have compiled
    groff without any problems with g++-1.39.1. g++ also compiled gpic,
    geqn, gtbl.   

    Groff includes gtroff to do text formatting and grops to generate
    PostScript.  To To use both, have this specification:
        *.formatcommand:      groff -pte -E /tmp/%s.n |
        *.PrintCommand: lpr -v
    Note:  The -pte switches tell it to run gpic, gtbl, and geqn before
    running gtroff.  The output of gtroff is automatically piped into
    grops, which generates the PostScript.  (This assumes that
    /usr/gnu/bin (or wherever groff is installed) is on one's path.)

    The drawback of this simple approach is that the ATK preview option
    will no longer work.  To retain the preview command, I believe, one
    can use specifications something like this:
        *.FormatCommand: cat /tmp/%s.n | gpic|gtbl|geqn|gtroff -Tpsc |
        *.PrintCommand: grops | lpr -v

Q10.  Ezprint outputs rasters in PostScript.  Can I print those rasters?

    If you just want to print one raster from an Andrew document, you
    can extract the raster from the troff output with a raw text editor
    and print it directly.  You may have to add the line
        20 20 translate
    to get it out of the bottom corner.  You may also have to add an
    initial line containing only 
        %!

    If you haven't got a postscript printer, the raster image can still
    be massaged with the pbm package.  pbm understands the Andrew format
    or you can use the output of 
        ezprint -t <file>
    which will include the raster encoded in PostScript / hex form.

Q11.  When using UCB sendmail, are aliases in /usr/lib/aliases
case-sensitive?  

    If you build your UCB sendmail with the ``DBM'' option set, aliases
    in /usr/lib/aliases are case-sensitive; if you build it without that
    option, they're case-insensitive. For purposes of validating user
    names, AMS assumes that aliases in /usr/lib/aliases are
    case-insensitive. This might mean that a name that validates OK with
    AMS might be rejected by UCB sendmail, if that sendmail uses DBM to
    do its alias lookup.

Q12.  How can I fix the error message in my console about <getstats/gvm>
Cannot open /dev/kmem?

    You may see the following error message: 

        |>> console:<getstats/gvm> Cannot open /dev/kmem - will not
        monitor Disk and GVMStats <<| 
        console: ->> Try 'Restart Stats' Menu <<

    If you get this message, your ``getstats'' program, installed from
    atk/console/stats/common, wasn't installed with sufficient privilege
    to be able to open /dev/kmem. This happens because your /dev/kmem is
    protected against global reading, but you didn't do an Andrew
    installation from an account with enough privilege to install
    ``getstats'' set-uid or set-gid. One possibility for this is that
    you are running AFS although you didn't turn the AFS flag on for the
    compilation. In order for console to monitor information available
    only through /dev/kmem, you'll have to do the following: 

        cd ..../atk/console/stats/common
        su admin (or su root)
        chmod 4555 getstats

    We have not included any consoles specifically tailored to a
    non-AMDS, non-AFS environment. We hope to have some available in
    future patch distributions. 

Q13.  I get the following error in my console:  <appname>X error
    BadValue, integer parameter out of range ...  How can I fix this?  

    Some users do not remember to run mkfontdir in the
    ${DESTDIR}/X11fonts directory after the dependInstall operation is
    complete. If you do not do so, you will see an error message similar
    to the following: 

        <appname>X error BadValue, integer parameter out of range ...

    Running on HP-UX, you may see problems with the fonts. A possible
    workaround for the font problem is to change the bodyfont font
    preference in your preferences file to some font that is in the X
    default font path. 

    Some formulation of the bdf files causes either convertfont or the
    window system to miscount the position of the glyphs in the font.
    This means that the window system doesn't believe that you have
    glyphs for lower-case characters. 

    The distributed Andrew fonts are tailored for about 80 pixels to the
    inch. By default these are not used, since for workstations with
    other resolutions it is generally best to utilize the X fonts
    instead. See the discussion of ISO80_FONTS_ENV above.

Q14.  Why can't the help program find any help files?

    If help files cannot be found or the alias database is missing, the
    following make operations from the root of the object tree may help:

        make dependInstall SUBDIRS='helpindex helpaliases'

    These operations can be repeated as desired.

Q15.  Should I modify the Imakefile or the Makefile?  
    Changes should never be made to the Makefile. All changes should be
    made to Imakefile; "make Makefile" to regenerate that one file, or
    "make Makefiles" to regenerate the Makefiles in all subdirectories,
    recursively.

    "make clean" and "make Clean" do not delete the Makefile, so a
    subsequent "make Makefile" says it is up to date, i.e., comparing
    its own timestamp against itself. Beware: once you remove the
    Makefile from a directory, you can't say "make Makefile" there
    again, You can, however, rename Makefile to another name and say
    "make Makefile -f newname". 

Q16.  How do I use the spell checker function in ez?  

    If Ispell, the spelling checker used by ez, is not available at your
    site or is not along your path, ez will not be able to perform this
    function. Ispell is widely available (e.g. via anonymous FTP off of
    uunet.uu.net). All an installer has to do to get ez spell checking
    to work is to install ispell somewhere along the user's path. The
    following .atkinit line will then be useful:

        addmenu "spell-check-document" "Search/Spell~1,Check
        Spelling~30" textview

Q17.  How do I debug Andrew applications?  

    In order to debug ATK applications you will need to have gdb version
    3.5 or greater from the Free Software Foundation.    See Q7, How can
    I get other useful software? above for information on how to contact
    the FSF.  

    To compile the system such that symbol tables exist add these two
    lines to your site.mcr:

            CDEBUGFLAGS = -g
            MAKEDODEBUG = -g

    To debug the raster application you would first load the
    statically-linked portion of the ATK run-time system, called runapp,
    into gdb. It is important that the above make.1 macros are set to
    include the -g switch so that the symbol table is created. There is
    no use attempting to use gdb if the system has not been built with
    the -g switch.

    % gdb runapp
    GDB, Copyright (C) 1987 Free Software Foundation, Inc.
    There is ABSOLUTELY NO WARRANTY for GDB; type "info warranty" for details.
    GDB is free software and you are welcome to distribute copies of it
     under certain conditions; type "info copying" to see the conditions.
    Reading symbol data from runapp...
    done.
    Type "help" for a list of commands.
    (gdb) run -d ezapp foo.ras -d
    Starting program: runapp -d ezapp foo.ras -d
    Starting ez (Version 7.0, ATK 15.0); please wait...
     raster: text = 0x10046594  data = 0x10049280  entry = 0x100498a8
     rasterview: text = 0x1004f820  data = 0x1005cc60  entry = 0x1005f8d8
     rasterimage: text = 0x1006701c  data = 0x100675d0  entry = 0x10067810
     pixelimage: text = 0x1006e758  data = 0x100703bc  entry = 0x1007068c

    To load the symbol table for the raster dynamic object you would use
    this command on a Sun or a DECstation 3100[An Andrew ToolKit view (a
    footnote) was included here, but could not be displayed.]:
    (gdb) add-file raster.dog 0x10046594

    and on an RT:
    (gdb) set-rel 0x10046594
    (gdb) add-file raster.dog

    Note that the addresses passed to these gdb commands come from the
    text address that runapp outputs when the -d switch is used (the
    second -d switch prevents runapp from forking itself to become an
    orphaned process). To determine which module to load in the fashion
    described above compare the various text addresses with the address
    at which the program failed. For example, if the program died at
    address 0x1004a520 you would find that address between what was
    reported as the start of the text segments for raster and
    rasterview. Since the raster module was loaded first, we can
    conclude that the failure was somewhere in the raster module.
___________________________________________________
User Questions

U0. Introduction

This section has been extracted from a larger FAQ file maintained at CMU
by Andrew Plotkin  (ap1i+@andrew.cmu.edu).  Its permission information
reads:

    Everything in this file is public domain. You can copy it, mail
    it to people, put bits of it in other files, print it out in
    500-point type and staple it to the walls, whatever you want --
    I'm happy to give you the opportunity, and I couldn't do a thing
    about it if I wanted to.

    Thanks to the multiple people who provided me with questions and
    answers.


U1. Customizing your account

How can I customize my Andrew account?
    For info on your preferences file:
        help preferences   (or help prefs)

I edited my .cshrc, but now I get strange errors when I start typescript, or
I edited my .login, but now I get strange errors when I log in, or
I edited my .plan, but now I get strange symbols when I finger myself, or
I edited my .Xresources, but now I get strange errors when I start X, or
I edited this file, but now I get strange errors....
    If you use ez to edit your .plan, .login, .logout, preferences,
    .cshrc, .Xresources, .Xclients, .Xmodmap, .signature, or any file
    like that: you must get rid of any styles you put in. You can't have
    sections of bold, or typewriter, or italics, or different text
    sizes, or indentation. (Not even in your .plan file or .signature,
    although that would be nice.) Use "Plainest" on the whole file if
    you have to.


U2. Playing with ATK things

How do I customize an ATK program?
    See the help file on it. The ATK help files are more friendly than
    average; lots of examples, no words over two syllables, etc.

How do I change the behavior, fonts, and so on in ATK windows and menus?
    Most of these are controlled by preferences:
        help preferences
        help menubar
    The lines described in these help files go in your preferences file.
    For example, 
        *.Thumbscroll: yes
    will cause the text in any ATK window to swoop up and down when you
    wiggle the scroll bar.
        typescript.Thumbscroll: yes
    will cause that to happen only in typescript windows.

    A major exception is the appearance of the pop-up menus you get when
    you press and hold the middle button. These are controlled by X
    resources (when you are running X.)
        help cmenu
    The resources described in this help file go in your .Xresources file. 
        *TitleFont: andysans22b
    will cause your menu card titles to be printed in a 22-point bold
    sans-serif font. 
        help*TitleFont: andysans22b
    will cause that to happen only in help windows.
    (Notice the format of an .Xresources entry is different from a
    preferences entry.)

I have a color display.  Can I get windows in colors other than black
and white?
    Yes, set the colors in your preference file with lines like this:

        # darker blue on lighter tan.  tan good.  (blue not really dark enough)
        ez.foregroundcolor: #003ea2
        ez.backgroundcolor: wheat

    For colors you can run xcolorpick or edit the file
    /usr/lib/X11/rgb.txt.   Color names are recognized by X only if they
    are in rgb.txt.
    If you want colors just for one execution of a program, you can set
    them on the command line:
        typescript -fg black -bg burlywood

    Here's a technique for setting color preferences based on the value
    of the environment variable ISCOLOR, which you can set in your
    .login file as follows:  

        set TTY = `tty`
        if ($TTY == /dev/console || \
                $TTY == /dev/hft/0 || \
                $TTY == /dev/ttyaed || \
                $TTY == /dev/ttyapa16 || \
                $TTY == /dev/ttyap16 || \
                $TTY == /dev/tty8514 || \
                $TTY == /dev/pty/ttyse || \
                $TTY == /dev/ttymono) then
                set consolelogin = 1
                echo -n "Color display? [y/n]: "
                set answer = $<
                if ($answer" =~ [Yy]*) then
                        setenv ISCOLOR 1
                        echo "color console login"
                else
                        echo "console login"
                endif
                unset answer
        endif

    You can then reference this variable in your preferences file: 

        ?E=ISCOLOR=1:ez.backgroundcolor: antiquewhite1
        ?E=ISCOLOR=1:console.backgroundcolor: cornsilk
        ?E=ISCOLOR=1:typescript.backgroundcolor: cornsilk3
        ?E=ISCOLOR=1:help.backgroundcolor: cornsilk3
        ?E=ISCOLOR=1:messages.backgroundcolor: cornsilk2
        ?E=ISCOLOR=1:bush.backgroundcolor: #e5d7c6

How do I add styles to ATK documents?
    	help ez-styles

How do I add tables of contents and footnotes to ATK documents?
    	help ez-contents
        help ez-footnotes

How do I adjust line spacing and margins in ATK documents?
    	help ez
    and scroll down to "Formatting text: line spacing and margins".

What keystroke commands work in ATK programs?
    	help ez-keys
    Notice that most gnu-emacs keys work in ATK programs. 

How do I work with multiple ez windows or multiple buffers?
    	help ez-buffers

How do I remove ATK formatting from an ATK document, to turn it into
plain text?
    The easy way is to edit it with ez, select (highlight) the entire
    document, and select "Plainest". 
    This will not work if the document has pagebreaks, footnotes, or
    insets (such as embedded rasters.)
    If you don't want to start up ez, you can use ez2ascii:
        ez2ascii filename

    Another alternative is to type
        rtfm -f filename
    This produces output with terminal formatting. It will look ok in an
    xterm, and underlining and boldface will show up correctly. However,
    it will fail nastily in a typescript, or if you put the output in a
    file and edit it. 

    For more info, see
        help ez2ascii
        help rtfm

How can I write my own console layout?
    	help lacc
    The publically-available console layouts are in
    /usr/local/lib/consoles. If you want to write your own, it's best to
    start with one of these and modify it.

    Once you've written your console layout file, add this line to your
    preferences:
        console.default: consolefilename
    where consolefile is a full pathname (no ~'s), for example
    /afs/andrew/usr99/userid/layoutfile

What is a help search path?
    Look at
        help preferences
    and scroll down to "Help preferences." (Redundant, aren't I? And
    repetitive.)
    The default help search path includes the help directories for all
    the standard Andrew programs, and everything in /usr/contributed. To
    add, for example, the help directory for the Computer Club's
    programs, you would add this line to your preferences:
        help.searchpath: /afs/andrew.cmu.edu/usr0/cl0x/man
    If you have more than one directory in this line, they should be
    separated by colons, not spaces.

    The search path is read in when you start help. If help is already
    running, you can add a directory to the search path by choosing "Add
    Search Directory" from the menu. This change is only temporary and
    will go away when you quit help. To permanently add a directory, you
    have to put it in your preferences.


U3.  Mail and bboards

How do I set options for messages?
    Select "Set Options" on the "Other" menu card. This will bring up a
    long list of options where the message titles usually are, and
    explanations and switches where the message bodies usually are. You
    can scroll through either list, and click on the switches to change
    things. (Some of these changes take effect immediately; for others,
    you have to quit and restart messages.) 
    There are a few, more obscure, options that you can set in your
    preferences file. Type
        help preferences
    and scroll down to "Andrew Messages System preferences". 


U4. Strange file formats

How do I convert rasters, bitmaps, or images from one type to another?
    To convert old-style ATK rasters (.ras) to new-style ATK rasters
    (.raster) or vice-versa,
        help convertraster
    convertraster claims to be able to convert MacPaint files that you
    have ftp'd to Andrew. This may not be reliable.
    To convert other image types, including X bitmaps, MacPaint files,
    and GIFs, 
        help pbm
        help pnm
    and also see the help files on all the little programs they mention.

    Some notes:
        PBM, PPM, and PGM are special image file formats which are
    designed to be "intermediate" conversion formats. That is, you can
    convert anything to these formats, and then convert it to anything
    else. (The RLE format is another "intermediate" format available on
    Andrew. For information on it, see the help file on URT.)
        PBM ("portable bitmap") is for simple black-and-white images
    like those produced by MacPaint or bitmap. PGM ("portable greymap")
    is for images with shades of grey, and PPM ("portable pixmap") is
    for full-color images. PNM ("portable any-map") is not a file
    format; a program called "pnm-something" can handle PBM, PPM, or PGM
    files.
        PBM, PGM, and PPM can be interconverted with the appropriate
    programs (ppmtopgm, pgmtopbm.) Both of these lose information, of
    course: ppmtopgm reduces the color image to shades of grey, and
    pgmtopbm changes shades to grey to black-and-white (although it will
    simulate grey by mixing black and white dots.)
        Also, a PGM file can be used whenever a PPM file is expected
    (ie, as input to ppm-something), and a PBM file can be used whenever
    either of the other two formats is expected. This is reasonable,
    since a bitmap is just a greyscale image with only two shades of
    grey, and a greyscale image is just a color image with only grey
    colors.
        The PBM, PNM, PPM, and PGM programs (xbmtopbm, pbmtorast,
    pnmrotate, etc.) are not invoked directly; instead, you run pbm with
    the actual program name as the first argument. (Umm, that's still
    confusing. See the examples below.) 
        All the conversion programs (except convertraster) work as
    filters. See the examples below.
        There are two programs, atobm and bmtoa, which convert X bitmaps
    to and from ASCII files. There are no help files on them.
        The MacPaint to RLE program, painttorle, is not reliable for
    large (full-screen) MacPaint files.
        PostScript files are designed only to be printed, so they're
    hard to convert to any other format. If you want to do that, you
    should view the file with dxpsview and then take a window dump of
    the dxpsview window (which produces an XWD file), and then convert
    that.

    To convert an X bitmap to a PBM file, use
        cat file.bm | pbm xbmtopbm > file.pbm

    To convert a PBM file to an X bitmap file, use
        cat file.pbm | pbm pbmtoxbm > file.bm

    To convert a GIF to PostScript, use
        cat file.gif | pbm giftoppm | pbm ppmtops > file.ps

    To convert a MacPaint file that you've ftp'd to Andrew to PBM, use
        cat file.paint | painttorle | rletoppm | pbm ppmtopgm | pbm
    pgmtopbm > file.pbm


U5.  Working with graphics and images

What drawing and painting programs are available on Andrew?
    (Drawing programs are the ones like MacDraw, that let you put down
    geometric objects and then move them around, change their sizes, and
    so on. Painting programs, like MacPaint, let you splot paint down on
    a raster, possibly in geometric shapes, and edit it pixel by pixel.)
    There are the ATK versions, zip (drawing) and raster (painting). zip
    is slow and somewhat buggy, and nobody uses it. raster is very
    primitive, and nobody uses it. However, they have the advantage of
    letting you put zip-drawings or rasters into ATK documents along
    with text.
        help zip
        help raster

U6. Fancy key bindings

Some packages commonly used by developers are not normally bound to keys
in order to simplify the user interface.  If you want to bind them, add
the given line to your ~/.atkinit file or to apply the binding just to
application xxx, add the line to ~/.xxxinit.
	help initfiles

How can I execute an arbitrary expression?
	help ness
and read
	$ANDREWDIR/doc/atk/ness/nesshack.doc
The normal binding of this function is ESC-ESC, though some people find
this too easy to type by mistake (and Ness does take a couple of seconds
to load the first time it is called).  To get the ESC-ESC binding add to
your .atkinit the line:
	addkey ness-dostmt  \e\e  view  

What is the "proctable"?
	help procs
Menu entries and key sequences are not bound directly to functions in C
code.  Instead they are bound to routines made available by the C code
for the various insets.  For instance, the operation on text usually
bound to ESC-b, which moves the cursor backward by one word, is the
proctable function textview-backward-word.  When such a function is
called from Ness, however, the dashes are written as underscores:
textview_backward_word.  

How can I find out what is in the proctable?
	help deskey
The deskey package offers several proctable functions which can be bound
to keys or menu entries.  My own usage is given by these lines in my
~/.atkinit:
	addkey deskey-describe-bound-keys ^XK im
	addkey deskey-describe-proctable ^XP im
Then control-X-shift-K opens another window showing all the current key
bindings and control-X-shift-P opens a window showing all functions
currently in the proctable.  More functions are added as insets with new
user interfaces are added.

How can I execute an arbitrary proctable function?
	help metax
The metax package offers two operations to bind to keys.  They prompt
for a function to execute and provide name completion by examining the
proctable for function names.  To bind ESC-x the operation that calls a
function without passing an argument add to .atkinit the line:
	addkey metax "\ex" view metax

How can I get file name completion in typescript?
If you are typing a file name to ez, you can get file name completion
with space and question mark.  The same functionality is available in
the typescript window, but it is better to bind it to other keys.  The
following in you .atkinit:
	addkey fcomp-complete-filename "\t" typescript
	addkey fcomp-possible-completions "\e\t" typescript
will bind TAB so it completes the currently entered file name as far as
it can and will bind ESC-TAB so it offers a list of all possible
completions (as a list in the typescript).

Can I perform incremental search as in gnuemacs?
	help search
	help gsearch
Yes, three different alternative search packages are available.  Dynamic
search is described in the help file for search and a gnuemacs clone is
described in the gsearch helpfile.  (Unfortunately, when you ask for
help on 'search', you get the gsearch helpfile;  you have to select
twice the menu option Show More Documentation.)  

A simplified incremental search package with no documentation can be bound with
	addkey incsearch-forward ^S textview
	addkey incsearch-backward ^R textview
Note that incsearch-forward MUST be bound to ^S or it will do backward
searches.

How can I convert paragraphs that have hard newlines within them to ATK
paragraphs with newlines only at the ends?
	read $ANDREWDIR/lib/ness/format.n
To convert text in messages or DOS files to ATK format, you need to wrap
the lines.  This can be done with a query replace changing newlines to
spaces, but this is not always satisfactory because multiple spaces are
needed after sentence ending punctuation.  When you have a binding for
ness-dostmt you can use a Ness function.  Select the text to be wrapped,
type ESC-ESC or your binding for ness-dostmt, and then answer the prompt
with 
	format_wrap()
The selected text will be wrapped appropriately.


U7. Programming in Ness and C

Is there a way to bind a keystroke or menu to a simple combination of
other operations?
    You could write a "package" following the model of incremental
    search, but it's lots easier just to write a short Ness function.  
        help ness
    A simple approach is to create a directory ~/nesslib and put in it
    the files--say f.n and g.n--with the Ness functions.  Then in your
    .atkinit or other .XXXinit file, add the lines
        load ness
        call ness-load /usr/you/nesslib/f.n
        call ness-load /usr/you/nesslib/g.n
    Substitute the full path to your nesslib directory.  Do the "load
    ness" line only once.

    Example 1:  Provide a menu operation to start up a typescript. 
    (This was written for a user whose window manager and typescripts
    died often;  if any window was left the user could start a
    typescript.)  The Ness code is:

        extend "view:frame"
                on menu "File,Typescript~85"
                        system("typescript"     -- launch typescript
                                        -- and don't wait:
                                ~ " >/dev/null </dev/null  2>&1 &")
                end menu
        end extend

    Example 2: Add to messages a menu option "FollowUp-To" which sets up
    a reply to the sender of the current message, excerpts the body of
    the message into the reply, and warps the mouse to the sendmessage
    window.  This code was the subject of a "call ness-load" in
    ~/.messagesinit.

        extend "view:messwind"
                on menu "This Message,Followup-To"
                        messages_reply_to_sender(currentwindow)
                        messages_sendmessage_compound(currentwindow,
                                "sendmessage-excerpt-body;"
                                ~ "sendmessage-focus-on-body")
                        frame_next_window(currentwindow)
                        textview_end_of_text(currentinputfocus)
                end menu
        end extend

How can I create the C code for a new inset?
    	help createinset
    This program creates a directory and puts seven files in it which
    constitute a working, though not useful, inset.  You need only
    modify the appropriate portions to make an inset which does what you
    want.

_______________________