\begindata{text,538752284}
\textdsversion{12}
\template{help}
\define{global
}
\define{index
menu:[Title~3,Index~91]
attr:[FontFace Italic Int Set]}
\define{indexi
menu:[Title~3,InvisibleIndex~92]
attr:[Script PreviousScriptMovement Point -2]
attr:[FontFace Italic Int Set]}
\define{footnote

attr:[Flags OverBar Int Set]
attr:[FontSize PreviousFontSize Point -2]}
\bigger{\bold{Andrew Consortium

Frequently Asked Questions

Release 6.3.1}}


\bold{\flushright{\flushleft{Last Update:  8/94

}}}
\begindata{bp,538360232}
\enddata{bp,538360232}
\view{bpv,538360232,0,0,0}
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).  \



FIle and pathnames beginning with ./ are references to files in the AUIS 
sources;  names of installed files begin with $ANDREWDIR.

All patches assume you are in the top-level source directory, that is, the 
directory with subdirectories atk, ams, atkams, config, overhead, and so 
on.  You can send suggestions and comments to the consortium's mailing 
list/newsgroup:  \



	info-andrew@andrew.cmu.edu.


Send bug reports to:


	info-andrew-bugs@andrew.cmu.edu


We also offer an electronic answering system.  Send mail to 
 andrew-service@andrew.cmu.edu with the word ``help'' as the only word on a 
line in the body of the message.  You will receive instructions on 
obtaining other information.


For information about the consortium you can contact:


\leftindent{Wilfred J. Hansen, Director

Andrew Consortium

School of Computer Science

Carnegie Mellon University

5000 Forbes Avenue.

Pittsburgh, PA 15213

wjh+@andrew.cmu.edu

412 268 6710}


\bold{General Information}


\bold{   G1.}  What is Andrew?

\bold{   G2.}  \leftindent{How do I obtain the latest release?}

\bold{   G3.}  \leftindent{Which platforms has Andrew been ported to?}

\bold{   G4.}  \leftindent{What books have been written for Andrew and 
where can I obtain them?}

\bold{   G5.}  \leftindent{What is the Remote Andrew Demo Service?}

   \bold{G6.}  \indent{What is the Andrew Consortium and what benefits do 
the members receive?}

   \bold{G7.}  \indent{Will there be the restrictions on distributing 
non-source applications that are developed?}  \


   \bold{G8.}  \indent{What are the restrictions on non-members who develop 
using the X Consortium distribution?}


\bold{Common Problems/Questions Building and Running Andrew}


\italic{Building AUIS}


\bold{   B1. } \leftindent{Why doesn't my macro expand in site.mcr?}

\bold{   B2.} \leftindent{ Why does the distribution as made available on 
MIT's X.V11R5 tape install files as links instead of actual files? }\


\bold{   B3.}  \leftindent{Which configuration variables are most commonly 
used? }\


\bold{   B4.} \leftindent{ Should I modify the Imakefile or the Makefile?}

\bold{   }\bold{B5.}  Some parts of the ./contrib section will not build 
under Linux.  Are patches forthcoming? \



\italic{Binary Distributions}


    \bold{D1.}  What binary distributions are available?  \


    \bold{D2.}  What are the FAQs for these binary distributions?  \



\italic{Messages/Mail}


\bold{   M1. } \leftindent{How can I instruct "messages" to use 
/usr/spool/mail for mail drop?}

\bold{   M2.}  \leftindent{When using UCB sendmail, are aliases in 
/usr/lib/aliases case-sensitive?}  \


\bold{   M3.}  Why wasn't queuemail installed automatically?


\italic{AUIS on AFS }\



\bold{    A1. } \leftindent{Why do I get errors when building Ultrix 4.2 
against AFS 3.1 libraries?}

\bold{    A2.}  \leftindent{Do I need to have AFS to run the Andrew Message 
System (AMS)?}

\bold{    A3.}  \leftindent{What is AFS and how can I get more information? 
} \



\italic{Auxiliary Software}


\bold{   S1. } \leftindent{How can I get other useful software?}

\bold{   S2.}  \leftindent{How can I use PostScript fonts other than those 
defined in /usr/andrew/X11fonts both in displayed and printed documents? }\


\bold{   S3.}  \leftindent{How do I use the spell checker function in ez?  }\


\bold{   S4.}  \leftindent{How do I debug Andrew applications?  }\


\bold{   S5.}  Why can't ez find ispell when I know it's installed? \



\italic{Printing}

\bold{
   P1.}  \leftindent{How can I print Andrew documents?}

\bold{   P2.}  \leftindent{Ezprint outputs rasters in PostScript.  Can I 
print those rasters?}

\bold{N P3.}  \leftindent{How can I adjust for other printer page sizes?}


\italic{Applications}


\bold{   L1.} \leftindent{ How can I fix the error message in my console 
about <getstats/gvm> Cannot open /dev/kmem? }\


\bold{   L2.} \leftindent{ I get the following error in my console: 
 <appname>X error BadValue, integer parameter out of range ...  How can I 
fix this?  \


}\bold{   L3.} \leftindent{ Why can't the help program find any help files?}


\italic{Fonts}


\bold{    F1. } I'm not getting the right fonts.

\bold{    F2.} When using my NCD X terminal, I get the wrong fonts.  \


\bold{    F3.} \indent{When I run Andrew applications on a remote X server, 
I get the wrong fonts or cursors.}


\bold{User Questions}  (Extracted from CMU's FAQ)


\bold{   U0.} \leftindent{Introduction}

\bold{   U1. }\leftindent{Customizing your account}

\bold{   U2.} \leftindent{Playing with ATK things, including ez, 
typescript, console, and help}

\bold{   U3.} \leftindent{Mail and bboards, including messages}

\bold{   U4. }\leftindent{Strange file formats}

\bold{   U5.} \leftindent{Working with graphics and images}

\bold{   U6. }\leftindent{Fancy key bindings}

\bold{   U7.} \leftindent{Programming in Ness and C}


___________________________________________________

\section{General Questions}


\bold{G1.  What is Andrew?}

\indent{The Andrew User Interface System (AUIS) 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. \


}
\bold{G2.  How do I obtain the latest release?}


\indent{This release, 6.3.1, can be obtained in several ways.   Andrew, as 
well as a variety of CMU software and the latest patches, is available via 
anonymous ftp from the Internet host, ftp.andrew.cmu.edu (Internet: 
128.2.232.154) in pub/AUIS.   Due to its size, the compressed tar'd tree is 
split into 6 files, auis\{1,2,3,4\}, contrib and doc in the 
pub/AUIS/dist-6.3.1/ directory.    You should gzip and tar -xvf each file 
individually.   If you already have release 6.3 installed, you may wish to 
apply the patch found in pub/AUIS/patches/official to your current 
installation.  The README in that directory provides instructions for 
applying the patch. \



The distribution is also available via anonymous ftp from the Internet host 
ftp.x.org (Internet address:  198.112.44.100).  The sources are located in 
the contrib/libraries/andrew tree.   \



}\bold{G3.  Which platforms has Andrew been ported to?}


The (intended) available machine types are:


\formatnote{\leftindent{Machine Type		Operating System		<machine>


IBM RS/6000		AIX 3.2			rs_aix32

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

Sun 4				SunOS 4.1-Mach		sun4_mach

Sun				Solaris 2.0			sun4_51

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_42

DEC MIPS			Ultrix 4.2-Mach		pmax_mach

SGI				IRIX 4.0			sgi_4d

SCO				SCO				sco_i386

}}
\bold{G4.  \indent{What books have been written for Andrew and where can I 
obtain them?}}

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


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


\bold{G5.  What is the Andrew Remote Demo Service?  }\



\indent{This network service allows you to run Andrew Toolkit applications 
without the overhead of obtaining or compiling the Andrew software.  The 
Remote Andrew Demo service will have you running Andrew software within 5 
minutes.


You need a host machine on the Internet, and you need to be running the X11 
window system.  A simple "finger" command will allow you to experience ATK 
applications firsthand.  You'll be able to compose multimedia documents, 
navigate through the interactive Andrew Tour, and use the Andrew Message 
System to browse through CMU's three thousand bulletin boards and 
newsgroups.

}\indent{
HOW TO USE THE SERVICE


}\indent{To use the Remote Andrew Demo service, run the following command 
on your machine:


\leftindent{finger help@atk.itc.cmu.edu}


The service will give you any further instructions that may be necessary.}


\bold{G6.  What is the Andrew Consortium and what benefits do the members 
receive?}


\indent{The principal activity of the Andrew Consortium is to maintain the 
central sources for AUIS.   Improvements and enhancments from many 
organizations are gathered together for redistribution;  frequently to 
members and more-or-less annually to others via the X Consortium 
distribution channel.  Programming support and consultation are available 
to full members.  The Consortium also organizes an annual technical 
meeting, publishes a newsletter, and maintains the info-andrew mailing list 
on the internet. Organizations are invited to become members of the 
Consortium.  A variety of levels of membership are available ranging from 
nominal to fully supportive.}


\bold{G7.   Will there be the restrictions on distributing non-source 
applications that may be developed? } \



\indent{There are two flavors of release:  the "current" software 
distributed on a timely basis to members and the occasional release via the 
X consortium.  The latter is virtually unrestricted and anyone can 
distribute applications based on it to anyone.  The current software is 
subject to license restrictions;  contributing and full members can 
distribute applications based on the current software.  Associate members 
can build applications on the current software and release them internally 
and to other consortium members of any class.  To more generally release 
applications, an associate member would build them on top of the current 
software and then release them on top of the next X release.}


\bold{G8.  What are the restrictions on non-members who develop using the X 
Consortium distribution?}


\indent{The only restrictions are that they cannot use the names of IBM, 
CMU, and other contributors in their advertising, and they cannot sue any 
contributors.  Otherwise they can create and sell software based on the X 
release.


One advantage of associate membership is to get access to the current 
software so that when the application is ready it can be released on top of 
the latest ATK rather than an old one.}


____________________________

\section{Common Problems/Questions Building Andrew

}\section{Building AUIS}


\subsection{B1.  Why doesn't my macro expand in site.mcr?}


\leftindent{You probably used a tab in your site.mcr file instead of 
spaces.  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.  }\



\subsection{B2. 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.  \


}
\leftindent{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:\indent{


29,32d28

< #ifdef LIBDL_ENV

< install.time:: libclass.a

< 	$(INSTALL) $(INSTLIBFLAGS) libclass.a $(DESTDIR)/lib

< #else /* LIBDL_ENV */

34d29

< #endif /* LIBDL_ENV */


}xmkfontd/Imakefile:

\indent{
18c18

< 	$(INSTALL)  $\{INSTLIBFLAGS\} non-andrew.fonts.alias 
 $\{DESTDIR\}/X11fonts/fonts.alias	\


---

> InstallFileToFile(non-andrew.fonts.alias, $\{INSTLIBFLAGS\}, 
$\{DESTDIR\}/X11fonts/fonts.alias)

}}\indent{
}
\subsection{B3.  Which configuration variables are used most often? \


}
\leftindent{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\}


}\subsection{B4.  Should I modify the Imakefile or the Makefile?  }\


\leftindent{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". }\



\bold{B5.}\bold{  Some parts of the ./contrib section will not build under 
Linux.  Are patches forthcoming? }\



\leftindent{The ./contrib/gestures and ./contrib/tm directories do not 
build under Linux as of Release 6.2.  \



Also, there are problems building the ./contrib/mit/rtf2 and 
./contrib/mit/2rtf directories.  A patch was applied to hopefully remedy 
the problem but since the Consortium does not have a Linux system on which 
to test, we were not able to check if the fix really works.  \



A notice will be sent to the info-andrew distribution list once patches are 
available for these problems.  \


}
\bold{\bigger{Binary Distributions}}


\bold{\bold{D1.}  What binary distributions are available?  }\



\leftindent{A binary distribution of AUIS 6.1 for Linux is available in 
ftp:/pub/Linux/X11/andrew on sunsite.unc.edu.  A Linux binary distribution 
of Release 6.2 will be made available soon.  Look for an announcement from 
the info-andrew distribution list. \



Binary distributions are also available for Release 5.2.1, the CD-ROM 
Release for the following system types: \



hp700_80    pmax_ul4      sun4c_411     rs_aix31


These are available from the Consortium ftp server, ftp.andrew.cmu.edu, IP 
128.2.35.66.  Since these binaries are now outdated by the lastest release, 
we are planning to remove them soon.  At this time, we have no plans to 
provide future binary distributions other than those provided by other 
netters.  }\



\bold{\bold{D2.}  What are the FAQs for these binary distributions?  \


}
\leftindent{For help problems with the sunsite.unc.edu Linux distribution, 
see the L3.  "Why can't the help program find any help file"?. \



Another common problem with the sunsite distribution is that the cursor is 
only a little white dot on some boxes.  We think this might be an X server 
but or possibly a  limitation on the size of the cursor.  If it is a size 
limit you can try picking up afonts.tar.Z by anonymous ftp from 
atk.itc.cmu.edu.  Instructions for using them follow: \



    1.  Make a directory where you will place the fonts.  Cd to that 
directory.

    2.  Run "ftp atk.itc.cmu.edu".  When asked for your login name, respond 
with "anonymous".  When asked for your password, respond with your ordinary 
user-id.

    3.  Place ftp into binary file transfer mode with the command "binary".

    4.  Run the ftp command "get afonts.tar.Z".  Depending on the speed of 
the connection, this can take anywhere between a few seconds to a few 
minutes.

    5.  Quit ftp with "quit".

    6.  Extract the font files from afonts.tar.Z with the command 
"uncompress < afonts.tar.Z | tar xf -".

    6a. [If you are running a version of X11 earlier than release 4, you 
may need to compile the bdf-style font files with "bdftosnf", then run 
"mkfontdir".  Consult your local documentation.]

    7.  Place the current directory in your font path with the command 
"xset fp+ /directory/name/here/".  Be sure to include the trailing /.

}
\section{Messages/Mail}


\subsection{M1.  How can I instruct \italic{messages} to use 
/usr/spool/mail for mail drop?

}
\leftindent{Although the following lines are in 
/usr/andrew/etc/AndrewSetup:


\leftindent{AMS_NonAMSDelivery: yes

AMS_MailBoxPrefix: /usr/spool/mail

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


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


\leftindent{unset hold}


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



}\subsection{M2.  When using UCB sendmail, are aliases in /usr/lib/aliases 
case-sensitive?  }\leftindent{\


}
\leftindent{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.}


\subsection{M3.  Why isn't queuemail installed automatically? } \



\indent{Queuemail wants to be installed setuid-daemon, and the Andrew 
installation mechanism assumes that it can't do that.  The installation is 
omitted, albeit silently, and must be done by hand.  \


}
\section{AFS}


\subsection{A1.  \indent{Why do I get errors when building Ultrix 4.2 
against AFS 3.1 libraries? }\


}
\leftindent{You need to define AFS_ULTRIX in your site.h file.  \


}
\subsection{A2.  Do I need to have AFS to run the Andrew Message System 
(AMS)?

}
\leftindent{No, but having AFS gives you better functionality.   \



Public bboards and mail are no problem, but AMS is not smart enough about 
UNIX groups to do private bboards right.  \



}\bold{A3.}\bold{  \leftindent{What is AFS and how can I get more 
information?}  }\



\leftindent{AFS is a distributed file system available from Transarc 
Corporation. For more information, please send email to 
afs-sales+@transarc.com or snail mail to:  \


Transarc Corporation

The Gulf Tower

707 Grant Street

Pittsburgh, PA  15219

+1 412 338 4400 \



}\section{Adjunct Software}


\subsection{S1.  How can I get other useful software?}


\leftindent{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.

}
\bold{archie - archive locator}

\leftindent{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.

}
\bold{ftp - file transfer package}

\leftindent{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.

}
\bold{on the ATK cd-rom}

\leftindent{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

}
\bold{X Windows System:  X11, imake, makedepend, patch}

\leftindent{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: ftp.x.org and numerous other sites (see archie)

newsgroup: comp.windows.x \


mail address:

	X Consortium

	One Memorial Drive

	PO Box 546

	Cambridge, MA  02142-0004

	USA

	phone: (617) 374-1000

}
\bold{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


\bold{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


\bold{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


\bold{ispell}  \


	version on cdrom in src/util/ispell is 2.0.02

		updated with a bigger dictionary

	new version 3.0.09 is available (technically a beta version). As of Jan 
1994, it can be FTP'd from ftp.cs.ucla.edu, in /pub/ispell. \


	a version called 4.0 is available from GNU (see below), but it is actually 
less featured than 3.0.09. See question S3.

	contact: Geoff Kuenning

	email:  geoff@ITcorp.com


\bold{GNU software: groff, g++, gcc, gdb, gnuemacs, ... }\leftindent{\


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

}
\bold{transcript (psdit)}

	Contact: \


		Adobe

		1585 Charleston Road

		P.O. Box 7900

		Mountain View, CA 94039-7900

	phone: 1-800-833-6687


\bold{Documenter's WorkBench}

	AT&T / NCR Computer Division

		800 225 5627

	Gary Wagner  513 445 1475



\subsection{S2.  How can I use PostScript fonts other than those defined in 
/usr/andrew/X11fonts both in displayed and printed documents?}

\indent{
There are two aspects of this problem: screen display and print display.


Screen Display}: \



\indent{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:}\leftindent{


ez.bodyfont: myfont12


}	Print Display: \



\leftindent{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.}

\bold{\bold{
}}\subsection{S3.  How do I use the spell checker function in ez?  }\



\leftindent{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:


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


}You should try to find either ispell version 2.0.02 or the newer version 
3.0.09. (As of Jan 1994, 3.0.09 can be FTP'd from ftp.cs.ucla.edu, in 
/pub/ispell.) \


This is because ispell version 4.0 (the version released by the FSF) is 
missing a few features. If you use the standard distribution of ispell 4.0, 
ez will not be able to add words to your private dictionary, or accept 
words for the rest of the session. \



If you wish to use ispell 4.0 anyway, the following patch will add the 
required functionality. (Use this only on ispell 4.0, not any other 
version.) If you recompile ispell 4.0 with this patch, ATK will use it and 
work correctly. The patched ispell must, of course, be earlier than any 
other version of ispell in your shell path.


-------------------------------------

\smaller{\leftindent{\smaller{*** ../ispell-4.0/screen.c	Mon May 31 
19:45:29 1993

--- screen.c	Tue Jan 11 14:50:25 1994

***************

*** 845,850 ****

--- 845,862 ----

        if (verbose && len == 0)

  	continue;

  \


+       if (buf[0] == '*' || buf[0] == '@')

+         \{

+ 	  /* allow * and @ commands, which are

+ 	   used by the ATK spellchecker */

+ 	  (void) p_enter(buf + 1, 1, buf[0] == '*'); \


+ 	  if (verbose) \


+ 	    (void) printf ("ok\\n"); \


+ 	  else \


+ 	    (void) printf ("*\\n"); \


+ 	  continue; \


+         \}

+ \


        if (good (buf, strlen (buf), 0))

  	\{

  	  /* used to print + if rootword */

}}}-------------------------------------

This patch has been submitted to to FSF, but they have not yet released it.

}
\subsection{S4.  How do I debug Andrew applications?  }\



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



\leftindent{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.


% \bold{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) \bold{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 \bold{raster} dynamic object you would use 
this command on a Sun or a DECstation 
3100\footnote{\
\begindata{fnote,538360280}
\textdsversion{12}
the distributed version of gdb does not yet support ATK applications on the 
DS3100, but will do so in the very near future (1/15/91)\
\enddata{fnote,538360280}
\view{fnotev,538360280,1,0,0}}:

(gdb)\bold{ add-file raster.dog 0x10046594}


and on an RT:

(gdb) \bold{set-rel 0x10046594}

(gdb) \bold{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.}


\subsection{S5.  Why can't ez find ispell when I know it's installed? }\



\indent{Ispell must be on your path in order for ez to find it.  \


}
\section{Printing}


\subsection{P1. How can I print Andrew documents?}

\leftindent{
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:

\leftindent{*.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.


\italic{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.


\italic{ditroff - psdit}

This is the route we use at CMU.  \italic{ditroff} is the device 
independent troff which comes with the Documenters Work Bench portion of 
Unix System V.  \italic{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 \italic{troff}).  The PrintCommand should usually use the -n 
switch and the lpr daemon will run psdit.


Ditroff is part of the Documenter's WorkBench (DWB) which is under 
development by AT&T.  Universities can get source code, but others may have 
to get binaries.  The AT&T manager for DWB is Peter Nelson, 908 582 6078.

}\italic{
}\leftindent{\italic{groff }\


This package is free from the Free Software Foundation, the gnu people. 
 The only hitch is that to build \italic{groff} you must first build 
\italic{g++} and to build \italic{g++} you must first build \italic{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: \


	*.PreviewCommand: groff -pteZ -TX100 /tmp/%s.n | preview -f -o %s

	*.PrintCommand: groff -pte -E /tmp/%s.n | lpr -v


(You may want to use X75 if your display is closer to 75 dpi that 100dpi.)

}

\subsection{P2.  Ezprint outputs rasters in PostScript.  Can I print those 
rasters?}


\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

	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.


}\bold{P3. How can I adjust for other printer page sizes?}


\leftindent{Page size for all AUIS printing can be adjusted by modifying 
the file $ANDREWDIR/lib/tmac/tmac.atk.  Just after the copyright notice, 
you can insert these lines (without leading whitespace)


	.ll 20c

	.pl 30c


These set a line length of 20 centimeters and a page length of 30 
centimeters.


You can also adjust the default header and footer margins by changing the 
values assigned to HM and FM a few lines later.


If you want to change paper size for just one user, that user can copy 
tmac.atk into a private file, say /usr/you/tmac/tmac.atk.  To utilize this 
file, the user's preferences file should include a line like:


	*.tmacfile:/usr/you/tmac/tmac.atk}

\leftindent{

}\section{Applications}


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

}
\leftindent{You may see the following error message: \



\indent{|>> 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, but 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: \



\leftindent{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. }\



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


}
\leftindent{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: \



\indent{<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.}


\subsection{L3.  Why can't the help program find any help files?}


	\bold{Using a tree built from source: }\



\leftindent{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:


\leftindent{\smaller{\typewriter{make dependInstall SUBDIRS='helpindex'}}}


These operations can be repeated as desired.


\bold{Using a Release 5.2.1 binary distribution or running off the CDROM: }\



If you are running from the CDROM or are using the binary distribution 
available on the Consortium ftp server, ftp.andrew.cmu.edu, the solution is 
different.  The problem with help may have resulted because the tree was 
moved to a different location than where help is trying to find 
$ANDREWDIR/lib/help.index.  The indices map a help topic to a filename for 
the associated help file.  Since we provide binaries now, people are free 
to place the distribution anywhere, and this invalidates the filenames 
recorded in the indices.


There are two ways to solve the problem:


1) create an AndrewSetup file (/etc/AndrewSetup) and add this line:


HelpIndexDir: $ANDREWDIR/lib/help.index


Replace "$ANDREWDIR" above with the actual value for ANDREWDIR.


2) Use the INDEXER script from the top-level SCRIPTS directory to

rebuild the indices.  You would execute the INDEXER this way:


% INDEXER -D $ANDREWDIR/lib/help.index


You can use the INDEXER to build alternate sets of help indices.

If you don't re-build the indices "in place", then you'll still

need to add a HelpIndexDir line to your AndrewSetup file.


\bold{Using a Release 6.1 Binary Distribution for Linux: }}\



\leftindent{A binary distribution of AUIS 6.1 is available in 
ftp:/pub/Linux/X11/andrew on sunsite.unc.edu.  One of the known problems 
with this distribution is that the help application will not work if you do 
not also install andrew61.prog.tar.gz, which is where the help.index 
directory is located.    \


}
\section{Fonts}


\subsection{F1.  I'm not getting the right fonts.

}
\indent{When building Andrew from sources, fonts are not being installed 
properly.  There is a bug in the file ./xmkfontd/Imakefile that erroneously 
removes the $ANDREWDIR/X11fonts/fonts.alias file without re-installing it. 
 An informal patch follows.


***  ./xmkfontd/Imakefile 	Wed Jun 10 16:48:34 1992

--- ./xmkfontd/Imakefile.new	Wed Jun 10 16:17:12 1992

***************

*** 15,21 ****

  	$\{RM\} $\{DESTDIR\}/X11fonts/fonts.alias

  	$\{XMKFONTDIR\} $(DESTDIR)/X11fonts

  #ifdef ISO80_FONTS_ENV

! InstallFileToFile(non-andrew.fonts.alias, $\{INSTLIBFLAGS\}, 
$\{DESTDIR\}/X11fonts/fonts.alias)

  #else  /* ISO80_FONTS_ENV */

  #ifdef SCOunix

  #ifdef FONTS_TO_PCF_ENV

--- 15,22 ----

  	$\{RM\} $\{DESTDIR\}/X11fonts/fonts.alias

  	$\{XMKFONTDIR\} $(DESTDIR)/X11fonts

  #ifdef ISO80_FONTS_ENV

! install.time::

! 	$(INSTALL) $\{INSTLIBFLAGS\} non-andrew.fonts.alias 
$\{DESTDIR\}/X11fonts/fonts.alias

  #else  /* ISO80_FONTS_ENV */

  #ifdef SCOunix

  #ifdef FONTS_TO_PCF_ENV}


\subsection{F2. When using my NCD X terminal, sometimes text gets rendered 
in a scrambled way.}


\indent{The problem is fixed in the latest release of the NCD servers.  The 
problem exists in NCD 2.2.0 and does not exist in release 2.4.x. \


}
\subsection{F3. When I run Andrew applications on a remote X server, I get 
the wrong fonts or cursors.}\bold{

}\indent{\bold{
}    ATK applications attempt to set the X font path correctly, to pick up 
all the special fonts used for cursors and whatnot. However, if the X 
server and the ATK application are running on different machines, this may 
get confused. If so, you will have to set the font path yourself.

    The most important fonts are: \italic{icon12} (for cursors), 
\italic{shape10} and \italic{xshape10} (for grey shading). The basic Andrew 
text fonts have names starting with \italic{tim}, \italic{hel}, and 
\italic{sym} (Times, Helvetica, and Symbol). Other significant fonts are 
\italic{con10} and \italic{con12} (used by Console), \italic{msgs10} and 
\italic{msgs14} (used by Messages). \


    These are often installed in $ANDREWDIR/X11fonts, but may be in 
/usr/local/fonts or elsewhere, depending on how your site is configured. 
The filenames to look for will be the same as the font names, except that 
\italic{icon12} may be called \italic{icn16x16}. Most likely these files 
will have \italic{.pcf} extensions, but they may be installed as 
\italic{.bdf} or some other format appropriate to your X server.

    The directory on the server machine which contains those font files 
should be added to the X font path. Use the command \


\typewriter{\smaller{\indent{xset fp+ /directory/name/here/}}}

    Be sure to include the / at the end. \


    Once this is done, Andrew applications should run properly on that X 
server. The only possible remaining difficulty is that if you are using the 
"CacheShades" preference, the X server will have cached invalid grey-shades 
from the original (invalid) font path. Type

\typewriter{\smaller{\indent{xprop -remove ATK_SHADES -root}}}

to clear them out; they will be stored correctly once ATK runs with the 
proper font path.


    If you are absolutely unable to find the proper fonts, the critical 
ones can be downloaded from our FTP site. Type

\typewriter{\smaller{\indent{finger font-help@atk.itc.cmu.edu}}}

for instructions.


}___________________________________________________

\section{User Questions}


\section{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:


\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 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.}

\smaller{
}
\section{U1. Customizing your account

}
\bold{How can I customize my Andrew account?}

\leftindent{For info on your preferences file:

\typewriter{	help preferences}   (or \typewriter{help prefs})\typewriter{

}}
\bold{I edited my .cshrc, but now I get strange errors when I start 
\italic{typescript}}, or\bold{

I edited my .login, but now I get strange errors when I log in}, or\bold{

I edited my .plan, but now I get strange symbols when I \italic{finger} 
myself}, or\bold{

I edited my .Xresources, but now I get strange errors when I start X}, 
or\bold{

I edited this file, but now I get strange errors....}

\leftindent{If you use \italic{ez} to edit your .plan, .login, .logout, 
preferences, .cshrc, .Xresources, .Xclients, .Xmodmap, .signature, or any 
file like that: you \italic{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.

}

\section{U2. Playing with ATK things

}
\bold{How do I customize an ATK program?

}\leftindent{See the help file on it. The ATK help files are more friendly 
than average; lots of examples, no words over two syllables, etc.

}
\bold{How do I change the behavior, fonts, and so on in ATK windows and 
menus?

}\leftindent{Most of these are controlled by preferences:

\typewriter{	help preferences

	help menubar

}The lines described in these help files go in your \italic{preferences} 
file. For example, \


\typewriter{	*.Thumbscroll: yes

}will cause the text in any ATK window to swoop up and down when you wiggle 
the scroll bar.

\typewriter{	typescript.Thumbscroll: yes

}will cause that to happen only in \italic{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.)

\typewriter{	help cmenu

}The resources described in this help file go in your \italic{.Xresources} 
file. \


\typewriter{	*TitleFont: andysans22b

}will cause your menu card titles to be printed in a 22-point bold 
sans-serif font. \


\typewriter{	help*TitleFont: andysans22b

}will cause that to happen only in \italic{help} windows.

(Notice the format of an \italic{.Xresources} entry is different from a 
\italic{preferences} entry.)

}
\bold{I have a color display.  Can I get windows in colors other than black 
and white?}

\leftindent{Yes, set the colors in your preference file with lines like 
this:


\leftindent{# darker blue on lighter tan.  tan good.  (blue not really dark 
enough)

ez.foregroundcolor: #003ea2

ez.backgroundcolor: wheat

}
For colors you can run \italic{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:  \



\leftindent{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: \



\leftindent{?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

}}
\bold{How do I add styles to ATK documents?

}\typewriter{\leftindent{	help ez-styles

}}
\bold{How do I add tables of contents and footnotes to ATK documents?

}\typewriter{\leftindent{	help ez-contents

	help ez-footnotes

}}
\bold{How do I adjust line spacing and margins in ATK documents?

}\leftindent{\typewriter{	help ez

}and scroll down to "Formatting text: line spacing and margins".

}
\bold{What keystroke commands work in ATK programs?

}\leftindent{\typewriter{	help ez-keys

}Notice that most gnu-emacs keys work in ATK programs. \


}
\bold{How do I work with multiple ez windows or multiple buffers?

}\typewriter{\leftindent{	help ez-buffers

}}
\bold{How do I remove ATK formatting from an ATK document, to turn it into 
plain text?

}\leftindent{The easy way is to edit it with \italic{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 \italic{ez}, you can use \italic{ez2ascii}:

\typewriter{	ez2ascii filename

}
Another alternative is to type

\typewriter{	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

\typewriter{	help ez2ascii

	help rtfm

}}
\bold{How can I write my own \italic{console} layout?

}\leftindent{\typewriter{	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:

\typewriter{	console.default: consolefilename

}where consolefile is a full pathname (no ~'s), for example

/afs/andrew/usr99/userid/layoutfile

}
\bold{What is a help search path?

}\leftindent{Look at

\typewriter{	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:

\typewriter{	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 \italic{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.

}

\section{U3.  Mail and bboards

}\bold{
How do I set options for \italic{messages}?

}\leftindent{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 \italic{messages}.) \


There are a few, more obscure, options that you can set in your preferences 
file. Type

\typewriter{	help preferences

}and scroll down to "Andrew Messages System preferences". \


}

\section{U4. Strange file formats

}
\bold{How do I convert rasters, bitmaps, or images from one type to 
another?

}\leftindent{To convert old-style ATK rasters (.ras) to new-style ATK 
rasters (.raster) or vice-versa,

\typewriter{	help convertraster

}\italic{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, \


\typewriter{	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.

	PBM ("portable bitmap") is for simple black-and-white images like those 
produced by MacPaint or \italic{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 
(\italic{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 \italic{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.

	All the conversion programs (except convertraster) work as filters. See 
the examples below.

	There are two programs, \italic{atobm} and \italic{bmtoa}, which convert X 
bitmaps to and from ASCII files. There are no help files on them.

	The MacPaint to RLE program, \italic{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 \italic{dxpsview} and then take a window dump of the 
\italic{dxpsview} window (which produces an XWD file), and then convert 
that.


To convert an X bitmap to a PBM file, use

\typewriter{	cat file.bm | xbmtopbm > file.pbm


}To convert a PBM file to an X bitmap file, use

\typewriter{	cat file.pbm | pbmtoxbm > file.bm

}
To convert a GIF to PostScript, use

\typewriter{	cat file.gif | giftoppm | ppmtops > file.ps}


}\section{
U5.  Working with graphics and images

}
\bold{What drawing and painting programs are available on Andrew?

}\leftindent{(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, \italic{zip} (drawing) and \italic{raster} 
(painting). \italic{zip} is slow and somewhat buggy, and nobody uses it. 
\italic{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.

\typewriter{	help zip

	help raster

}}\section{
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 \italic{xxx}, add the line to ~/.\italic{xxx}init.

	\typewriter{help initfiles}


\bold{How can I execute an arbitrary expression?}

\leftindent{	\typewriter{help ness}

and read

	\typewriter{$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:

	\typewriter{addkey ness-dostmt  \\e\\e  view  }\


}
\bold{What is the "proctable"?}

\leftindent{\typewriter{	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 \italic{textview-backward-word}.  When such a function is called 
from Ness, however, the dashes are written as underscores: 
\italic{textview_backward_word}.  \



How can I find out what is in the proctable?

	\typewriter{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:

	\typewriter{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 to the list as more 
insets are loaded in.

}
\bold{How can I execute an arbitrary proctable function?}

\leftindent{	\typewriter{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 to the operation that calls a function 
without passing an argument add this line to .atkinit:

	\typewriter{addkey metax "\\ex" view metax}

}
\bold{How can I get file name completion in typescript?}

\leftindent{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 your .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).

}
\bold{Can I perform incremental search as in gnuemacs?

}\leftindent{\bold{	}\typewriter{help search}\bold{

}\typewriter{	help gsearch

}Yes, three different alternative search packages are available.  Dynamic 
search is described in the help file for search and a gnu-emacs clone is 
described in the gsearch helpfile.  (Unfortunately, when you ask for help 
on 'search', you get the gsearch helpfile;  you have to select 
\italic{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.

}
\bold{How can I convert paragraphs that have hard newlines within them to 
ATK paragraphs with newlines only at the ends?}

\leftindent{	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 \


	\typewriter{format_wrap()}

The selected text will be wrapped appropriately.

}

\section{U7. Programming in Ness and C}


\bold{Is there a way to bind a keystroke or menu to a simple combination of 
other operations?}

\leftindent{You could write a "package" following the model of incremental 
search, but it's lots easier just to write a short Ness function.  \


	\typewriter{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.


\bold{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:


\leftindent{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

}
\bold{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.


\indent{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

}}
\bold{How can I create the C code for a new inset?}

\leftindent{	\typewriter{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.

}
_______________________

\begindata{bp,538360456}
\enddata{bp,538360456}
\view{bpv,538360456,2,0,0}
Copyright 1992 Carnegie Mellon University.  All rights reserved.

/* \


	$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.

 $

*/

\enddata{text,538752284}
