From: susan+@ANDREW.CMU.EDU (Susan Straub)
Newsgroups: comp.soft-sys.andrew
Subject: FAQ
Date: 14 Apr 92 16:47:25 GMT
Distribution: world
Organization: The Internet

<bigger><bold>Andrew Toolkit <nl>
Frequently Asked Questions<nl>
Release 5.1</bold></bigger><nl>
<nl>
This file contains questions from everywhere and answers from many places.  Th=
e sections on General Information and Common Problems Building Andrew were com=
piled 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 (ap1=
i+@andrew.cmu.edu).  You can send suggestions and comments to these people or =
directly to the consortium's mailing list/bulletin board:  <nl>
<nl>
	info-andrew@andrew.cmu.edu.<nl>
<nl>
Send bug reports to:<nl>
<nl>
	info-andrew-bugs@andrew.cmu.edu<nl>
<nl>
For information about the consortium you can contact:<nl>
<nl>
<leftindent>Wilfred J. Hansen<nl>
Director, Andrew Toolkit Consortium<nl>
238 UCCB   4910 Forbes Ave.<nl>
Pittsburgh, PA 15213<nl>
wjh+@andrew.cmu.edu<nl>
412 268 6710</leftindent><nl>
<nl>
<nl>
<bold>General Information</bold><nl>
<nl>
<bold>G1.</bold>  What is Andrew?<nl>
<bold>G2.</bold>  <leftindent>How do I obtain the latest release?</leftindent>=
<nl>
<bold>G3.</bold>  <leftindent>Which platforms has Andrew been ported to?<=
/leftindent><nl>
<bold>G4.</bold>  <leftindent>What books have been written fo=
r Andrew and where can I obtain them?</leftindent><nl>
<bold>G5.</bold>  <leftindent>What is the Remote Andrew Demo Service?</leftind=
ent><nl>
<nl>
<bold>Common Problems/Questions Building Andrew</bold><nl>
<nl>
<bold>Q1. </bold> <leftindent>Why doesn't my macro expand in site.mcr?</leftin=
dent><nl>
<bold>Q2. </bold> <leftindent>How can I instruct "messages" to use /=
usr/spool/mail for mail drop?</leftindent><nl>
<bold>Q3. </bold> <leftindent>Why do I get errors when building Ultrix 4.2 aga=
inst AFS 3.1 libraries?</leftindent><nl>
<bold>Q4.</bold> <leftindent> Why does the distribution as made available on M=
IT's X.V11R5 tape install files as links instead of actual files? </leftindent=
><nl>
<bold>Q5.</bold>  <leftindent>Which configuration variables are used mos=
t often? </leftindent><nl>
<bold>Q6.</bold>  <leftindent>Do I need to have AFS to run the Andrew Message =
System (AMS)?</leftindent><nl>
<bold>Q7. </bold> <leftindent>How can I get other useful software?</leftindent=
><nl>
<bold>Q8.</bold>  <leftindent>How can I use PostScript fonts other than =
those defined in /usr/andrew/X11fonts both in displayed and printed documents?=
 </leftindent><nl>
<bold>Q9.</bold>  <leftindent>How can I print Andrew documents?</leftindent><n=
l>
<bold>Q10.</bold>  <leftindent>Ezprint outputs rasters in PostScript.  Can =
I print those rasters?</leftindent><nl>
<nl>
<bold>User Questions</bold>  (Extracted from CMU FAQ)<nl>
<nl>
<bold>U0.</bold> <leftindent>Introduction</leftindent><nl>
<bold>U1. </bold><leftindent>Customizing your account</leftindent><nl>
<bold>U2.</bold> <leftindent>Playing with ATK things, including ez, typescript=
, console, and help</leftindent><nl>
<bold>U3.</bold> <leftindent>Mail and bboards, including messages</leftindent>=
<nl>
<bold>U4. </bold><leftindent>Strange file formats</leftindent><nl>
<bold>U5.</bold> <leftindent>Working with graphics and images</leftindent><nl>=

<bold>U6. </bold><leftindent>Fancy key bindings</leftindent><nl>
<bold>U7.</bold> <leftindent>Programming in Ness and C</leftindent><nl>
<nl>
___________________________________________________<nl>
<section>General Questions</section><nl>
<nl>
<bold>G1.  What is Andrew?</bold><nl>
<indent>The Andrew Toolkit (ATK) is a portable user-interface toolkit that run=
s under X11. It provides a dynamically-loadable object-oriented environment wh=
erein 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 fon=
ts, contains embedded raster images, spreadsheets, drawing editors, equations,=
 simple animations, etc.. These embedded objects could themselves contain othe=
r objects, including text. With the toolkit, programmers can create new object=
s that can be embedded as easily as those that come with the system. Many obje=
cts, including those mentioned above, along with a help system, a system monit=
oring tool (console), an editor based shell interface (typescript), and suppor=
t for printing multi-media documents, are included in the release, making it u=
seful to programmers and non-programmers alike. <nl>
<nl>
The Andrew Message System(AMS) provides a multi-media interface to mail and bu=
lletin-boards.  AMS contains many advanced  features including authentication,=
 return receipts, automatic sorting of mail, vote collection and tabulation, e=
nclosures, audit trails of related messages, and subscription management. It a=
lso provides a variety of interfaces that support ttys and low-function person=
al computers in addition to the high-function workstations. <nl>
</indent><nl>
<bold>G2.  How do I obtain the latest release?</bold><nl>
<indent>This release, 5.1, can be obtained in several ways.  The entire X dist=
ribution 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.  Just the andrew =
tree from the X distribution, as well as the latest patches, is 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 s=
hould cat andrew.* together into andrew.tar.Z, uncompress the tree then tar -x=
vpf.  <nl>
<nl>
</indent><bold>G3.  Which platforms has Andrew been ported to?</bold><nl>
<nl>
The (intended) available machine types are:<nl>
<nl>
<formatnote><leftindent>Machine Type		Operating System		<lt>machine><nl>
<nl>
IBM RT			AOS December 1988		rt_aos4<nl>
IBM RT			AIX 2.2.1			rt_aix221<nl>
IBM RS/6000			AIX 3.1			rs_aix31<nl>
IBM PS/2 M70/80		AIX 1.2			ps_aix12 <nl>
Sun 3				SunOS 3.5			sun3_35<nl>
Sun 3				SunOS 4.0			sun3_4<nl>
Sun 3				SunOS 4.1			sun3_41<nl>
Sun 4				SunOS 4.0			sun4_40<nl>
Sun 4				SunOS 4.1			sun4_41<nl>
DEC Vax			Ultrix 3.0			vax_3<nl>
DEC Vax			BSD (4.3)			vax_43<nl>
HP 300			HP UX				hp300<nl>
HP 900			HP UX				hp800<nl>
Macintosh II			MacMach			mac2_51<nl>
Apollo				DomainOS			apollo68k<nl>
DEC MIPS			Ultrix 3.0			pmax_3<nl>
DEC MIPS			Ultrix 4.1			pmax_41<nl>
DEC MIPS			Ultrix 4.2			pmax_42<nl>
SGI				IRIX 4.0			sgi_4d<nl>
SCO				SCO				sco_i386<nl>
</leftindent></formatnote><nl>
<bold>G4.  What books have been written for Andrew and where can I obtain them=
?</bold><nl>
<indent><nl>
Nathaniel S. Borenstein's book: <italic>Multimedia Applications Development wi=
th the Andrew Toolkit </italic>(Prentice-Hall).<nl>
<nl>
ODA Project Book: <italic>Multi-media Document Interchange: ODA and the EXPRES=
 Project </italic>(Springer Verlag).</indent><nl>
<nl>
<nl>
____________________________<nl>
<section>Common Problems/Questions Building Andrew<nl>
</section><nl>
<nl>
<bold>Q1.  Why doesn't my macro expand in site.mcr?</bold><nl>
<nl>
<leftindent>Tabs are not allowed before macro declarations in the site.mcr.  A=
lthough the error is not reported as such, the macro is not expanded properly =
and thus not noticed by imake.  Use spaces.  </leftindent><nl>
<nl>
<bold>Q2.  How can I instruct "messages" to use /usr/spool/mail for mail drop?=
</bold><nl>
<nl>
<leftindent>Although the following lines are in /usr/andrew/etc/AndrewSetup:<n=
l>
<nl>
<leftindent>AMS_NonAMSDelivery: yes<nl>
AMS_MailBoxPrefix: /usr/spool/mail<nl>
</leftindent><nl>
Messages says, "/usr/user/Mailbox" could not be properly read and delivered (0=
 success, 0 failure)". <excerpt><nl>
</excerpt><nl>
You should create a file $HOME/.mailrc and put in this line:<nl>
<nl>
<leftindent>unset hold</leftindent><nl>
<nl>
WARNING:  Once you start reading mail with <italic>messages</italic>, you inco=
ming mail will be stored within directories maintained by <italic>messages</it=
alic>.  It is possible to return to other mail handling systems, but it may no=
t be easy.<nl>
</leftindent><nl>
<bold>Q3.  Why do I get errors when building Ultrix 4.2 against AFS 3.1 librar=
ies? </bold><nl>
<nl>
<leftindent>You need to define AFS_ULTRIX in your site.h file.  <nl>
</leftindent><nl>
<bold>Q4. Why does the distribution as made available on MIT's X.V11R5 tape in=
stall files as links instead of actual files?  This fails in two directories: =
 overhead/class/lib and xmkfontd.  </bold><nl>
<nl>
<leftindent>The distribution defaults to install links instead of files.  To c=
hange 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: <nl>
<nl>
overhead/class/lib/Imakefile:<indent><nl>
<nl>
29,32d28<nl>
<lt> #ifdef LIBDL_ENV<nl>
<lt> install.time:: libclass.a<nl>
<lt> 	$(INSTALL) $(INSTLIBFLAGS) libclass.a $(DESTDIR)/lib<nl>
<lt> #else /* LIBDL_ENV */<nl>
34d29<nl>
<lt> #endif /* LIBDL_ENV */<nl>
<nl>
</indent>xmkfontd/Imakefile:<nl>
<indent><nl>
18c18<nl>
<lt> 	$(INSTALL)  ${INSTLIBFLAGS} non-andrew.fonts.alias  ${DESTDIR}/X11fonts/=
fonts.alias	<nl>
---<nl>
> InstallFileToFile(non-andrew.fonts.alias, ${INSTLIBFLAGS}, ${DESTDIR}/X11fon=
ts/fonts.alias)<nl>
</indent></leftindent><indent><nl>
</indent><nl>
<bold>Q5.  Which configuration variables are used most often? </bold><nl>
<nl>
<leftindent>AFS30_ENV<nl>
AFS31_ENV <nl>
AMS_DELIVERY_ENV <nl>
WHITEPAGES_ENV <nl>
SNAP_ENV <nl>
ANDREW_MALLOC_ENV<nl>
DEBUG_MALLOC_ENV<nl>
MK_BASIC_UTILS<nl>
MK_AUTHORING <nl>
MK_AUX_UTILS <nl>
MK_AUX_INSETS<nl>
MK_EXAMPLES <nl>
RUN_AMDS_ENV<nl>
ANDREW_PRINTING_ENV<nl>
LINKINSTALL_ENV<nl>
CONTRIB_ENV <nl>
PRE_X11R4_ENV <nl>
DPS_ENV <nl>
DEFAULT_ANDREWDIR_ENV <nl>
BUILDANDREWINSTALL_ENV <nl>
ISO80_FONTS_ENV	<nl>
FONTS_TO_PCF_ENV<nl>
<nl>
CDEBUGFLAGS =3D -g<nl>
MAKEDODEBUG =3D -g<nl>
AFSBASEDIR =3D /usr/local<nl>
XMKFONTDIR =3D /usr/local/bin/mkfontdir<nl>
XFC =3D /usr/local/bin/bdftosnf<nl>
XLIBDIR =3D /usr/local/lib<nl>
XINCDIR =3D /usr/local/include<nl>
RESOLVLIB =3D ${AFSBASEDIR}/lib/res/libresolv.a<nl>
RESINC =3D -I$(AFSBASEDIR)/include/res<nl>
INCLUDES =3D  -I${BASEDIR}/include -I$(BASEDIR)/include/atk $(RESINC) -I$(AFSB=
ASEDIR)/include -I${XINCDIR}<nl>
<nl>
</leftindent><nl>
<bold>Q6.  Do I need to have AFS to run the Andrew Message System (AMS)?</bold=
><nl>
<nl>
<leftindent>No, but having AFS gives you better functionality. <nl>
</leftindent><nl>
<bold>Q7.  How can I get other useful software?</bold><nl>
<nl>
<leftindent>Enormous quantities of software are available for free from the in=
ternet.  Many of the pieces are also available via electronic mail.  Subsequen=
t paragraphs list some software that may be of value as an adjunct to ATK/AMS.=
<nl>
</leftindent><nl>
<bold>archie - archive locator</bold><nl>
<leftindent>A major source of information about the location of software on th=
e network is 'archie'.  Send mail to <nl>
	archie@archie.rutgers.edu<nl>
In the body of the message include line(s) of the form<nl>
	prog   name<nl>
where name is the name of the software you would like to find out about.  For =
more information, the body can contain the line<nl>
	help<nl>
The listing returned from a 'prog' request will list ftp sites containing info=
rmation 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.<nl>
</leftindent><nl>
<bold>ftp - file transfer package</bold><nl>
<leftindent>To retrieve information via ftp over the internet:  Give the comma=
nd <nl>
	ftp <lt>site name><nl>
The response will ask for your login;  reply<nl>
	anonymous<nl>
the response will ask for your email address;  type it in.  Now you can give t=
he help command to see the commands.  I generally use ls, dir, cd, lcd, pwd, a=
nd get.<nl>
</leftindent><nl>
<bold>on the ATK cd-rom</bold><nl>
<leftindent>Some useful non-ATK software is included in the ATK cd-rom.  For d=
etails see subsequent paragraphs.<nl>
	binaries only:  X11 for RS6000, Sun 4, Dec Pmax, and HP700<nl>
	binaries and source:  metamail imake makedepend patch<nl>
	source only: ispell, psroff, pbmplus<nl>
</leftindent><nl>
<bold>X Windows System:  X11, imake, makedepend, patch</bold><nl>
<leftindent>Screen management and graphics software<nl>
Binaries on cdrom in <lt>system>/X11/...<nl>
Bdf fonts  on cdrom in  src/util/bdffonts<nl>
imake, makedepend, and patch<nl>
	source on cdrom in src/util/...<nl>
	objects on cdrom in <lt>system>/util/...<nl>
ftp: export.mit.edu and numerous other sites (see archie)<nl>
newsgroup: comp.windows.x <nl>
mail address:<nl>
	MIT Software Distribution Center<nl>
	Technology Licensing Office<nl>
	room E32-300<nl>
	77 Massachusetts Avenue<nl>
	Cambridge, MA  02139<nl>
phone: (617) 258-8330<nl>
</leftindent><nl>
<bold>metamail</bold><nl>
	Converter for implementing MIME multi-media internet standard.<nl>
	newer version due early April, 1992<nl>
	contact:  Nathaniel Borenstein<nl>
		Bellcore Room 2A-274<nl>
		Morristown, NJ 07962-1910<nl>
	phone: (201) 829-4270<nl>
	email: nsb@thumper.bellcore.com<nl>
	ftp:  thumper.bellcore.com,  see  pub/nsb/README<nl>
	source: $ATKSRC/overhead/mail/metamail<nl>
<nl>
<bold>pbmplus</bold><nl>
	Portable bit map conversion and transformation software<nl>
	version in cdrom:/src/util/pbmplus is from   10 December 1991<nl>
	contact: Jef Poskanzer<nl>
	email: jef@well.sf.ca.us<nl>
<nl>
<bold>psroff</bold><nl>
	Software augmenting troff and providing printer drivers.<nl>
	on cdrom: src/util/psroff  is version 3.0 patch level 07<nl>
	contact:  Chris Lewis<nl>
	psroff-request@ferret.ocunix.on.ca<nl>
<nl>
<bold>ispell</bold>  <nl>
	version ion cdrom in src/util/ispell is 2.0.02<nl>
		updated with a bigger dictionary<nl>
	new version 3.0 is coming soon<nl>
	contact: Geoff Kuenning<nl>
	email:  geoff@ITcorp.com<nl>
<nl>
<bold>GNU software: groff, g++, gcc, gdb, gnuemacs, ... </bold><leftindent><nl=
>
Free software, eventually replacing Un*x<nl>
ftp: prep.ai.mit.edu<nl>
	see pub/gnu/GNUinfo/FTP<nl>
	and pub/gnu/etc/DISTRIB<nl>
email: gnu@prep.ai.mit.edu<nl>
mailing address:<nl>
	Free Software Foundation, Inc.<nl>
	675 Massachusetts Avenue<nl>
	Cambridge, MA  02139<nl>
	USA<nl>
phone:  +1 617-876-3296<nl>
</leftindent><nl>
<bold>transcript (psdit)</bold><nl>
	Contact: <nl>
		Adobe<nl>
		1585 Charleston Road<nl>
		P.O. Box 7900<nl>
		Mountain View, CA 94039-7900<nl>
	phone: 1-800-833-6687<nl>
<nl>
<bold>Documenter's WorkBench</bold><nl>
	AT&T / NCR Computer Division<nl>
		800 225 5627<nl>
	Gary Wagner  513 445 1475<nl>
<nl>
<nl>
<bold>Q8.  How can I use PostScript fonts other than those defined in /usr/and=
rew/X11fonts both in displayed and printed documents?<nl>
There are two aspects of this problem: screen display and print display.<nl>
Screen Display</bold><nl>
<leftindent>To have your own fonts used by ATK applications for displaying tex=
t you must first create those fonts and place them in a directory, possibly se=
t up a fonts.alias file, run mkfontdir to get a fonts.dir file, and finally ad=
d that directory to your X fontpath.  Also, you'll have to specify in your pre=
ferences file the fontname:<nl>
<nl>
ez.bodyfont: myfont12<nl>
<nl>
</leftindent><bold>Print Display</bold><nl>
<leftindent>To get these fonts to print you have to create the appropriate tro=
ff device-specific font description files (see /usr/lib/font/devpsc for the Po=
stscript 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 (../a=
ndrew/atk/text/txtroff.c) to recognize your new font family and to make the ap=
propriate mapping from your fontname to the troff fontname.  Currently, the on=
ly fonts used for printing are Times, Helvetica, and Courier.</leftindent><nl>=

<nl>
<nl>
<bold>Q9. How can I print Andrew documents?</bold><nl>
<leftindent><nl>
Printing requires two steps, text formatting and then driving the printer.  AT=
K 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 p=
rinter be driven with PostScript.<nl>
<nl>
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 gene=
ral defaults are:<nl>
<leftindent>*.FormatCommand: eqn -Tpsc /tmp/%s.n  | troff -Tpsc - |<nl>
*.PrintCommand: lpr -n<nl>
</leftindent>The -Tpsc flags specify that the troff output is ultimately inten=
ded 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 st=
yled text can be printed via most versions of troff and most print drivers.<nl=
>
<nl>
To print ATK documents via PostScript printers, you have three options:<nl>
	troff - psroff<nl>
	ditroff - psdit<nl>
	groff<nl>
These differ in cost and the difficulty of installation.  See Q8 for hints on =
acquiring these packages.<nl>
<nl>
<italic>troff - psroff</italic><nl>
Standard Unix systems are often delivered with an old troff which generates ou=
tput 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 in=
ternet.  See the psroff documentation.<nl>
<nl>
<italic>ditroff - psdit</italic><nl>
This is the route we use at CMU.  <italic>ditroff</italic> is the device indep=
endent troff which comes with the Documenters Work Bench portion of Unix Syste=
m V.  <italic>psdit</italic> is part of the "Transcript" package available fro=
m Adobe software.  Both ditroff and Transcript cost money.  Adjust the FormatC=
ommand to utilize the ditroff version of troff (it is usually called <italic>t=
roff</italic>).  The PrintCommand should usually use the -n switch and the lpr=
 daemon will run psdit.<nl>
</leftindent><italic><nl>
</italic><leftindent><italic>groff </italic><nl>
This package is free from the Free Software Foundation, the gnu people.  The o=
nly hitch is that to build <italic>groff</italic> you must first build <italic>g++</italic> and to build <italic>g++</italic> you must first build <italic>gcc</italic>.  We have compiled groff without any problems with g++-1.=
39.1. g++ also compiled gpic, geqn, gtbl.   <nl>
<nl>
Groff includes gtroff to do text formatting and grops to generate PostScript. =
 To To use both, have this specification:<nl>
	*.formatcommand:      groff -pte -E /tmp/%s.n |<nl>
	*.PrintCommand: lpr -v<nl>
Note:  The -pte switches tell it to run gpic, gtbl, and geqn before running gt=
roff.  The output of gtroff is automatically piped into grops, which generates=
 the PostScript.  (This assumes that /usr/gnu/bin (or wherever groff is instal=
led) is on one's path.)<nl>
<nl>
The drawback of this simple approach is that the ATK preview option will no lo=
nger work.  To retain the preview command, I believe, one can use specificatio=
ns something like this:<nl>
	*.FormatCommand: cat /tmp/%s.n | gpic|gtbl|geqn|gtroff -Tpsc |<nl>
	*.PrintCommand: grops | lpr -v<nl>
</leftindent><nl>
<bold>Q10.  Ezprint outputs rasters in PostScript.  Can I print those rasters?=
</bold><nl>
<nl>
<leftindent>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<nl>
	20 20 translate<nl>
to get it out of the bottom corner.  You may also have to add an initial line =
containing only <nl>
	%!<nl>
<nl>
If you haven't got a postscript printer, the raster image can still be massage=
d with the pbm package.  pbm understands the Andrew format or you can use the =
output of <nl>
	ezprint -t <lt>file><nl>
which will include the raster encoded in PostScript / hex form.<nl>
</leftindent><nl>
<nl>
___________________________________________________<nl>
<section>User Questions</section><nl>
<nl>
<section>U0. Introduction</section><nl>
<nl>
This section has been extracted from a larger FAQ file maintained at CMU by An=
drew Plotkin  (ap1i+@andrew.cmu.edu).  Its permission information reads:<nl>
<nl>
<indent>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 stap=
le 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.<nl>
<nl>
Thanks to the multiple people who provided me with questions and answers.</ind=
ent><nl>
<smaller><nl>
</smaller><nl>
<section>U1. Customizing your account<nl>
</section><nl>
<bold>How can I customize my Andrew account?</bold><nl>
<leftindent>For info on your preferences file:<nl>
<fixed>	help preferences</fixed>   (or <fixed>help prefs</fixed>)<fixed><nl>
</fixed></leftindent><nl>
<bold>I edited my .cshrc, but now I get strange errors when I start <italic>ty=
pescript</italic></bold>, or<bold><nl>
I edited my .login, but now I get strange errors when I log in</bold>, or<bold><nl>
I edited my .plan, but now I get strange symbols when I <italic>finger</italic=
> myself</bold>, or<bold><nl>
I edited my .Xresources, but now I get strange errors when I start X</bold>, o=
r<bold><nl>
I edited this file, but now I get strange errors....</bold><nl>
<leftindent>If you use <italic>ez</italic> to edit your .plan, .login, .logout=
, preferences, .cshrc, .Xresources, .Xclients, .Xmodmap, .signature, or any fi=
le like that: you <italic>must</italic> get rid of any styles you put in. You =
can't have sections of bold, or typewriter, or italics, or different text size=
s, or indentation. (Not even in your .plan file or .signature, although that w=
ould be nice.) Use "Plainest" on the whole file if you have to.<nl>
</leftindent><nl>
<nl>
<section>U2. Playing with ATK things<nl>
</section><nl>
<bold>How do I customize an ATK program?<nl>
</bold><leftindent>See the help file on it. The ATK help files are more friend=
ly than average; lots of examples, no words over two syllables, etc.<nl>
</leftindent><nl>
<bold>How do I change the behavior, fonts, and so on in ATK windows and menus?=
<nl>
</bold><leftindent>Most of these are controlled by preferences:<nl>
<fixed>	help preferences<nl>
	help menubar<nl>
</fixed>The lines described in these help files go in your <italic>preferences=
</italic> file. For example, <nl>
<fixed>	*.Thumbscroll: yes<nl>
</fixed>will cause the text in any ATK window to swoop up and down when you wi=
ggle the scroll bar.<nl>
<fixed>	typescript.Thumbscroll: yes<nl>
</fixed>will cause that to happen only in <italic>typescript</italic> windows.=
<nl>
<nl>
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.)<nl>
<fixed>	help cmenu<nl>
</fixed>The resources described in this help file go in your <italic>.Xresourc=
es</italic> file. <nl>
<fixed>	*TitleFont: andysans22b<nl>
</fixed>will cause your menu card titles to be printed in a 22-point bold sans=
-serif font. <nl>
<fixed>	help*TitleFont: andysans22b<nl>
</fixed>will cause that to happen only in <italic>help</italic> windows.<nl>
(Notice the format of an <italic>.Xresources</italic> entry is different from =
a <italic>preferences</italic> entry.)<nl>
</leftindent><nl>
<bold>I have a color display.  Can I get windows in colors other than black an=
d white?</bold><nl>
<leftindent>Yes, set the colors in your preference file with lines like this:<=
nl>
<nl>
<leftindent># darker blue on lighter tan.  tan good.  (blue not really dark en=
ough)<nl>
ez.foregroundcolor: #003ea2<nl>
ez.backgroundcolor: wheat<nl>
</leftindent><nl>
For colors you can run <italic>xcolorpick</italic> or edit the file /usr/lib/X=
11/rgb.txt.   Color names are recognized by X only if they are in rgb.txt.<nl>=

If you want colors just for one execution of a program, you can set them on t=
he command line:<nl>
	typescript -fg black -bg burlywood<nl>
<nl>
Here's a technique for setting color preferences based on the value of the env=
ironment variable ISCOLOR, which you can set in your .login file as follows:  =
<nl>
<nl>
<leftindent>set TTY =3D `tty`<nl>
if ($TTY =3D=3D /dev/console || \<nl>
	$TTY =3D=3D /dev/hft/0 || \<nl>
	$TTY =3D=3D /dev/ttyaed || \<nl>
	$TTY =3D=3D /dev/ttyapa16 || \<nl>
	$TTY =3D=3D /dev/ttyap16 || \<nl>
	$TTY =3D=3D /dev/tty8514 || \<nl>
	$TTY =3D=3D /dev/pty/ttyse || \<nl>
	$TTY =3D=3D /dev/ttymono) then<nl>
	set consolelogin =3D 1<nl>
	echo -n "Color display? [y/n]: "<nl>
	set answer =3D $<lt><nl>
	if ($answer" =3D~ [Yy]*) then<nl>
		setenv ISCOLOR 1<nl>
		echo "color console login"<nl>
	else<nl>
		echo "console login"<nl>
	endif<nl>
	unset answer<nl>
endif</leftindent><nl>
<nl>
You can then reference this variable in your preferences file: <nl>
<nl>
<leftindent>?E=3DISCOLOR=3D1:ez.backgroundcolor: antiquewhite1<nl>
?E=3DISCOLOR=3D1:console.backgroundcolor: cornsilk<nl>
?E=3DISCOLOR=3D1:typescript.backgroundcolor: cornsilk3<nl>
?E=3DISCOLOR=3D1:help.backgroundcolor: cornsilk3<nl>
?E=3DISCOLOR=3D1:messages.backgroundcolor: cornsilk2<nl>
?E=3DISCOLOR=3D1:bush.backgroundcolor: #e5d7c6<nl>
</leftindent></leftindent><nl>
<bold>How do I add styles to ATK documents?<nl>
</bold><fixed><leftindent>	help ez-styles<nl>
</leftindent></fixed><nl>
<bold>How do I add tables of contents and footnotes to ATK documents?<nl>
</bold><fixed><leftindent>	help ez-contents<nl>
	help ez-footnotes<nl>
</leftindent></fixed><nl>
<bold>How do I adjust line spacing and margins in ATK documents?<nl>
</bold><leftindent><fixed>	help ez<nl>
</fixed>and scroll down to "Formatting text: line spacing and margins".<nl>
</leftindent><nl>
<bold>What keystroke commands work in ATK programs?<nl>
</bold><leftindent><fixed>	help ez-keys<nl>
</fixed>Notice that most gnu-emacs keys work in ATK programs. <nl>
</leftindent><nl>
<bold>How do I work with multiple ez windows or multiple buffers?<nl>
</bold><fixed><leftindent>	help ez-buffers<nl>
</leftindent></fixed><nl>
<bold>How do I remove ATK formatting from an ATK document, to turn it into pla=
in text?<nl>
</bold><leftindent>The easy way is to edit it with <italic>ez</italic>, select=
 (highlight) the entire document, and select "Plainest". <nl>
This will not work if the document has pagebreaks, footnotes, or insets (such =
as embedded rasters.)<nl>
If you don't want to start up <italic>ez</italic>, you can use <italic>ez2asci=
i</italic>:<nl>
<fixed>	ez2ascii filename<nl>
</fixed><nl>
Another alternative is to type<nl>
<fixed>	rtfm -f filename<nl>
</fixed>This produces output with terminal formatting. It will look ok in an x=
term, and underlining and boldface will show up correctly. However, it will fa=
il nastily in a typescript, or if you put the output in a file and edit it. <n=
l>
<nl>
For more info, see<nl>
<fixed>	help ez2ascii<nl>
	help rtfm<nl>
</fixed></leftindent><nl>
<bold>How can I write my own <italic>console</italic> layout?<nl>
</bold><leftindent><fixed>	help lacc<nl>
</fixed>The publically-available console layouts are in /usr/local/lib/console=
s. If you want to write your own, it's best to start with one of these and mod=
ify it.<nl>
<nl>
Once you've written your console layout file, add this line to your preference=
s:<nl>
<fixed>	console.default: consolefilename<nl>
</fixed>where consolefile is a full pathname (no ~'s), for example<nl>
/afs/andrew/usr99/userid/layoutfile<nl>
</leftindent><nl>
<bold>What is a help search path?<nl>
</bold><leftindent>Look at<nl>
<fixed>	help preferences<nl>
</fixed>and scroll down to "Help preferences." (Redundant, aren't I? And repet=
itive.)<nl>
The default help search path includes the help directories for all the standar=
d Andrew programs, and everything in /usr/contributed. To add, for example, th=
e help directory for the Computer Club's programs, you would add this line to =
your preferences:<nl>
<fixed>	help.searchpath: /afs/andrew.cmu.edu/usr0/cl0x/man<nl>
</fixed>If you have more than one directory in this line, they should be separ=
ated by colons, not spaces.<nl>
<nl>
The search path is read in when you start <italic>help</italic>. If help is al=
ready running, you can add a directory to the search path by choosing "Add Sea=
rch Directory" from the menu. This change is only temporary and will go away w=
hen you quit help. To permanently add a directory, you have to put it in your =
preferences.<nl>
</leftindent><nl>
<nl>
<section>U3.  Mail and bboards<nl>
</section><bold><nl>
How do I set options for <italic>messages</italic>?<nl>
</bold><leftindent>Select "Set Options" on the "Other" menu card. This will br=
ing up a long list of options where the message titles usually are, and explan=
ations and switches where the message bodies usually are. You can scroll throu=
gh either list, and click on the switches to change things. (Some of these cha=
nges take effect immediately; for others, you have to quit and restart <italic>messages</italic>.) <nl>
There are a few, more obscure, options that you can set in your preferences fi=
le. Type<nl>
<fixed>	help preferences<nl>
</fixed>and scroll down to "Andrew Messages System preferences". <nl>
</leftindent><nl>
<nl>
<section>U4. Strange file formats<nl>
</section><nl>
<bold>How do I convert rasters, bitmaps, or images from one type to another?<n=
l>
</bold><leftindent>To convert old-style ATK rasters (.ras) to new-style ATK=
 rasters (.raster) or vice-versa,<nl>
<fixed>	help convertraster<nl>
</fixed><italic>convertraster</italic> claims to be able to convert MacPaint f=
iles that you have ftp'd to Andrew. This may not be reliable.<nl>
To convert other image types, including X bitmaps, MacPaint files, and GIFs, <=
nl>
<fixed>	help pbm<nl>
	help pnm</fixed><nl>
and also see the help files on all the little programs they mention.<nl>
<nl>
Some notes:<nl>
	PBM, PPM, and PGM are special image file formats which are designed to be "in=
termediate" conversion formats. That is, you can convert anything to these for=
mats, and then convert it to anything else. (The RLE format is another "interm=
ediate" format available on Andrew. For information on it, see the help file o=
n URT.)<nl>
	PBM ("portable bitmap") is for simple black-and-white images like those produ=
ced by MacPaint or <italic>bitmap</italic>. PGM ("portable greymap") is for im=
ages 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-somethi=
ng" can handle PBM, PPM, or PGM files.<nl>
	PBM, PGM, and PPM can be interconverted with the appropriate programs (<italic>ppmtopgm, pgmtopbm</italic>.) Both of these lose information, of cours=
e: ppmtopgm reduces the color image to shades of grey, and pgmtopbm changes sh=
ades to grey to black-and-white (although it will simulate grey by mixing blac=
k and white dots.)<nl>
	Also, a PGM file can be used whenever a PPM file is expected (ie, as input to=
 <italic>ppm-something</italic>), and a PBM file can be used whenever either o=
f the other two formats is expected. This is reasonable, since a bitmap is jus=
t a greyscale image with only two shades of grey, and a greyscale image is jus=
t a color image with only grey colors.<nl>
	The PBM, PNM, PPM, and PGM programs (<italic>xbmtopbm</italic>, <italic>pbmto=
rast</italic>, <italic>pnmrotate</italic>, etc.) are not invoked directly; ins=
tead, you run <italic>pbm</italic> with the actual program name as the first a=
rgument. (Umm, that's still confusing. See the examples below.) <nl>
	All the conversion programs (except convertraster) work as filters. See the e=
xamples below.<nl>
	There are two programs, <italic>atobm</italic> and <italic>bmtoa</italic>, wh=
ich convert X bitmaps to and from ASCII files. There are no help files on them=
.<nl>
	The MacPaint to RLE program, <italic>painttorle</italic>, is not reliable for=
 large (full-screen) MacPaint files.<nl>
	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 <italic>dxpsview</italic> and then take a window dump of the <italic>dxpsview<=
/italic> window (which produces an XWD file), and then convert that.<nl>
<nl>
To convert an X bitmap to a PBM file, use<nl>
<fixed>	cat file.bm | pbm xbmtopbm > file.pbm<nl>
<nl>
</fixed>To convert a PBM file to an X bitmap file, use<nl>
<fixed>	cat file.pbm | pbm pbmtoxbm > file.bm<nl>
</fixed><nl>
To convert a GIF to PostScript, use<nl>
<fixed>	cat file.gif | pbm giftoppm | pbm ppmtops > file.ps</fixed><nl>
<nl>
To convert a MacPaint file that you've ftp'd to Andrew to PBM, use<nl>
<fixed>	cat file.paint | painttorle | rletoppm | pbm ppmtopgm | pbm pgmtopbm >=
 file.pbm<nl>
</fixed></leftindent><nl>
<section><nl>
U5.  Working with graphics and images<nl>
</section><nl>
<bold>What drawing and painting programs are available on Andrew?<nl>
</bold><leftindent>(Drawing programs are the ones like MacDraw, that let you p=
ut down geometric objects and then move them around, change their sizes, and s=
o on. Painting programs, like MacPaint, let you splot paint down on a raster, =
possibly in geometric shapes, and edit it pixel by pixel.)<nl>
There are the ATK versions, <italic>zip</italic> (drawing) and <italic>raster<=
/italic> (painting). <italic>zip</italic> is slow and somewhat buggy, and nobo=
dy uses it. <italic>raster</italic> is very primitive, and nobody uses it. How=
ever, they have the advantage of letting you put zip-drawings or rasters into =
ATK documents along with text.<nl>
<fixed>	help zip<nl>
	help raster<nl>
</fixed></leftindent><section><nl>
U6. Fancy key bindings</section><nl>
<nl>
Some packages commonly used by developers are not normally bound to keys in or=
der to simplify the user interface.  If you want to bind them, add the given l=
ine to your ~/.atkinit file or to apply the binding just to application <italic>xxx</italic>, add the line to ~/.<italic>xxx</italic>init.<nl>
	<fixed>help initfiles</fixed><nl>
<nl>
<bold>How can I execute an arbitrary expression?</bold><nl>
	<fixed>help ness</fixed><nl>
and read<nl>
	<fixed>$ANDREWDIR/doc/atk/ness/nesshack.doc</fixed><nl>
The normal binding of this function is ESC-ESC, though some people find this t=
oo 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 th=
e line:<nl>
	<fixed>addkey ness-dostmt  \e\e  view  </fixed><nl>
<nl>
<bold>What is the "proctable"?</bold><nl>
<fixed>	help procs</fixed><nl>
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 vario=
us insets.  For instance, the operation on text usually bound to ESC-b, which =
moves the cursor backward by one word, is the proctable function <italic>textv=
iew-backward-word</italic>.  When such a function is called from Ness, however=
, the dashes are written as underscores: <italic>textview_backward_word</itali=
c>.  <nl>
<nl>
How can I find out what is in the proctable?<nl>
	<fixed>help deskey</fixed><nl>
The deskey package offers several proctable functions which can be bound to ke=
ys or menu entries.  My own usage is given by these lines in my ~/.atkinit:<nl=
>
	<fixed>addkey deskey-describe-bound-keys ^XK im<nl>
	addkey deskey-describe-proctable ^XP im</fixed><nl>
Then control-X-shift-K opens another window showing all the current key bindin=
gs 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 a=
dded.<nl>
<nl>
<bold>How can I execute an arbitrary proctable function?</bold><nl>
	<fixed>help metax</fixed><nl>
The metax package offers two operations to bind to keys.  They prompt for a fu=
nction to execute and provide name completion by examining the proctable for f=
unction names.  To bind ESC-x the operation that calls a function without pass=
ing an argument add to .atkinit the line:<nl>
	<fixed>addkey metax "\ex" view metax</fixed><nl>
<nl>
<bold>How can I get file name completion in typescript?</bold><nl>
If you are typing a file name to ez, you can get file name completion with spa=
ce and question mark.  The same functionality is available in the typescript w=
indow, but it is better to bind it to other keys.  The following in you .atkin=
it:<nl>
	addkey fcomp-complete-filename "\t" typescript<nl>
	addkey fcomp-possible-completions "\e\t" typescript<nl>
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 l=
ist in the typescript).<nl>
<nl>
<bold>Can I perform incremental search as in gnuemacs?<nl>
	</bold><fixed>help search</fixed><bold><nl>
</bold><fixed>	help gsearch<nl>
</fixed>Yes, three different alternative search packages are available.  Dynam=
ic search is described in the help file for search and a gnuemacs clone is des=
cribed in the gsearch helpfile.  (Unfortunately, when you ask for help on 'sea=
rch', you get the gsearch helpfile;  you have to select <italic>twice</italic>=
 the menu option Show More Documentation.)  <nl>
<nl>
A simplified incremental search package with no documentation can be bound wit=
h<nl>
	addkey incsearch-forward ^S textview<nl>
	addkey incsearch-backward ^R textview<nl>
Note that incsearch-forward MUST be bound to ^S or it will do backward searche=
s.<nl>
<nl>
<bold>How can I convert paragraphs that have hard newlines within them to ATK =
paragraphs with newlines only at the ends?</bold><nl>
	read $ANDREWDIR/lib/ness/format.n<nl>
To convert text in messages or DOS files to ATK format, you need to wrap the l=
ines.  This can be done with a query replace changing newlines to spaces, but =
this is not always satisfactory because multiple spaces are needed after sente=
nce 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 f=
or ness-dostmt, and then answer the prompt with <nl>
	<fixed>format_wrap()</fixed><nl>
The selected text will be wrapped appropriately.<nl>
<nl>
<nl>
<section>U7. Programming in Ness and C</section><nl>
<nl>
<bold>Is there a way to bind a keystroke or menu to a simple combination of ot=
her operations?</bold><nl>
<leftindent>You could write a "package" following the model of incremental sea=
rch, but it's lots easier just to write a short Ness function.  <nl>
	<fixed>help ness</fixed><nl>
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 .XXX=
init file, add the lines<nl>
	load ness<nl>
	call ness-load /usr/you/nesslib/f.n<nl>
	call ness-load /usr/you/nesslib/g.n<nl>
Substitute the full path to your nesslib directory.  Do the "load ness" line o=
nly once.<nl>
<nl>
<bold>Example 1:</bold>  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:<=
nl>
<nl>
<leftindent>extend "view:frame"<nl>
	on menu "File,Typescript~85"<nl>
		system("typescript"	-- launch typescript<nl>
				-- and don't wait:<nl>
			~ " >/dev/null <lt>/dev/null  2>&1 &")<nl>
	end menu<nl>
end extend<nl>
</leftindent><nl>
<bold>Example 2:</bold> 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 mes=
sage into the reply, and warps the mouse to the sendmessage window.  This code=
 was the subject of a "call ness-load" in ~/.messagesinit.<nl>
<nl>
<indent>extend "view:messwind"<nl>
	on menu "This Message,Followup-To"<nl>
		messages_reply_to_sender(currentwindow)<nl>
		messages_sendmessage_compound(currentwindow,<nl>
			"sendmessage-excerpt-body;"<nl>
			~ "sendmessage-focus-on-body")<nl>
		frame_next_window(currentwindow)<nl>
		textview_end_of_text(currentinputfocus)<nl>
	end menu<nl>
end extend<nl>
</indent></leftindent><nl>
<bold>How can I create the C code for a new inset?</bold><nl>
<leftindent>	<fixed>help createinset</fixed><nl>
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 port=
ions to make an inset which does what you want.<nl>
</leftindent><nl>
_______________________