Andrew Toolkit Frequently Asked Questions Release 6.1 Last Update: 1/31/94 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). All patches assume you are in the top-level source directory, i.e., the directories atk, ams, atkams, ... exist. New items added since the last FAQ was posted are noted with an N, and updated items are noted with a U. You can send suggestions and comments to these people or directly to the consortium's mailing list/bulletin board: info-andrew@andrew.cmu.edu. Send bug reports to: info-andrew-bugs@andrew.cmu.edu For information about the consortium you can contact: Wilfred J. Hansen, Director Andrew Consortium Carnegie Mellon University Smith Hall 106 Pittsburgh, PA 15213 wjh+@andrew.cmu.edu 412 268 6710 General Information G1. What is Andrew? U G2. How do I obtain the latest release? G3. Which platforms has Andrew been ported to? G4. What books have been written for Andrew and where can I obtain them? G5. What is the Remote Andrew Demo Service? N G6. What is the Andrew Consortium and what benefits do the members receive? N G7. Will there be the restrictions on distributing non-source applications that are developed? N G8. What are the restrictions on non-members who develop using the X Consortium distribution? Common Problems/Questions Building Andrew Building AUIS B1. Why doesn't my macro expand in site.mcr? B2. Why does the distribution as made available on MIT's X.V11R5 tape install files as links instead of actual files? B3. Which configuration variables are most commonly used? B4. Should I modify the Imakefile or the Makefile? N B5. If I have resolver_env turned on, the andrew build fails while trying to build amsn.do. This only happens on a Sun 4 platform. Did I do something wrong? N B6. Building Andrew from source fails on the SGI Indigo in andrew/atkams/messages/lib while running makedo on amsn.o. Messages/Mail M1. How can I instruct "messages" to use /usr/spool/mail for mail drop? M2. When using UCB sendmail, are aliases in /usr/lib/aliases case-sensitive? N M3. Why wasn't queuemail installed automatically? AUIS on AFS A1. Why do I get errors when building Ultrix 4.2 against AFS 3.1 libraries? U A2. Do I need to have AFS to run the Andrew Message System (AMS)? N A3. What is AFS and how can I get more information? Auxiliary Software S1. How can I get other useful software? S2. How can I use PostScript fonts other than those defined in /usr/andrew/X11fonts both in displayed and printed documents? U S3. How do I use the spell checker function in ez? S4. How do I debug Andrew applications? N S5. Why can't ez find ispell when I know it's installed? Printing P1. How can I print Andrew documents? P2. Ezprint outputs rasters in PostScript. Can I print those rasters? Applications L1. How can I fix the error message in my console about Cannot open /dev/kmem? L2. I get the following error in my console: X error BadValue, integer parameter out of range ... How can I fix this? U L3. Why can't the help program find any help files? Fonts N F1. I'm not getting the right fonts. N F2. When using my NCD X terminal, I get the wrong fonts. N F3. When I run Andrew applications on a remote X server, I get the wrong fonts or cursors. User Questions (Extracted from CMU's FAQ) U0. Introduction U1. Customizing your account U2. Playing with ATK things, including ez, typescript, console, and help U3. Mail and bboards, including messages U4. Strange file formats U5. Working with graphics and images U6. Fancy key bindings U7. Programming in Ness and C ___________________________________________________ General Questions G1. What is Andrew? The Andrew Toolkit (ATK) is a portable user-interface toolkit that runs under X11. It provides a dynamically-loadable object-oriented environment wherein objects can be embedded in one-another. Thus, one could use our 'generic-object' editor (ez) to edit text that, in addition to containing multiple fonts, contains embedded raster images, spreadsheets, drawing editors, equations, simple animations, etc.. These embedded objects could themselves contain other objects, including text. With the toolkit, programmers can create new objects that can be embedded as easily as those that come with the system. Many objects, including those mentioned above, along with a help system, a system monitoring tool (console), an editor based shell interface (typescript), and support for printing multi-media documents, are included in the release, making it useful to programmers and non-programmers alike. The Andrew Message System(AMS) provides a multi-media interface to mail and bulletin-boards. AMS contains many advanced features including authentication, return receipts, automatic sorting of mail, vote collection and tabulation, enclosures, audit trails of related messages, and subscription management. It also provides a variety of interfaces that support ttys and low-function personal computers in addition to the high-function workstations. G2. How do I obtain the latest release? This release, 5.1, can be obtained in several ways. The entire X distribution is available via anonymous ftp from the Internet host ftp.x.org (Internet address: (198.112.44.100)). The sources of ATK and AMS are located in the contrib/andrew tree, one of the contributed toolkits. Andrew, as well as a variety of CMU software and the latest patches, is also available via anonymous ftp from the Internet host, emsworth.andrew.cmu.edu (Internet: 128.2.30.62). Due to its size, the compressed tar'd tree is split into 11 files, andrew.aa through andrew.ak (about 1MB each) in the split/ directory. You should cat andrew.* together into andrew.tar.Z, uncompress the tree then tar -xvpf. NOTE: If you obtain Andrew from the X tape or the ./pub/R5/contrib-3 directory, you will receive Release 5.0. You should review the file ANNOUNCE.5 in the contrib/andrew directory for instructions on fixing build problems you will encounter. G3. Which platforms has Andrew been ported to? The (intended) available machine types are: Machine Type Operating System IBM RT AOS December 1988 rt_aos4 IBM RT AIX 2.2.1 rt_aix221 IBM RS/6000 AIX 3.1 rs_aix31 IBM PS/2 M70/80 AIX 1.2 ps_aix12 Sun 3 SunOS 3.5 sun3_35 Sun 3 SunOS 4.0 sun3_4 Sun 3 SunOS 4.1 sun3_41 Sun 4 SunOS 4.0 sun4_40 Sun 4 SunOS 4.1 sun4_41 Sun4 SunOS 4.1-Mach sun4_mach DEC Vax Ultrix 3.0 vax_3 DEC Vax BSD (4.3) vax_43 HP 300 HP UX hp300 HP 900 HP UX hp800 Macintosh II MacMach mac2_51 Apollo DomainOS apollo68k DEC MIPS Ultrix 3.0 pmax_3 DEC MIPS Ultrix 4.1 pmax_41 DEC MIPS Ultrix 4.2 pmax_42 DEC MIPS Ultrix 4.2-Mach pmax_mach SGI IRIX 4.0 sgi_4d SCO SCO sco_i386 G4. What books have been written for Andrew and where can I obtain them? Nathaniel S. Borenstein's book: Multimedia Applications Development with the Andrew Toolkit (Prentice-Hall). ODA Project Book: Multi-media Document Interchange: ODA and the EXPRES Project (Springer Verlag). G5. What is the Andrew Remote Demo Service? 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. HOW TO USE THE SERVICE To use the Remote Andrew Demo service, run the following command on your machine: finger help@atk.itc.cmu.edu The service will give you any further instructions that may be necessary. G6. What is the Andrew Consortium and what benefits do the members receive? The principal activity of the Andrew Consortium is to maintain 'the' central sources for the 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. G7. Will there be the restrictions on distributing non-source applications that may be developed? 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. G8. What are the restrictions on non-members who develop using the X Consortium distribution? 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. ____________________________ Common Problems/Questions Building Andrew Building AUIS B1. Why doesn't my macro expand in site.mcr? Tabs are not allowed before macro declarations in the site.mcr. Although the error is not reported as such, the macro is not expanded properly and thus not noticed by imake. Use spaces. 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. The distribution defaults to install links instead of files. To change this, #undef LINKINSTALL_ENV in your site.h file. If you want to build using LINKINSTALL_ENV, you will have to change the following two files: overhead/class/lib/Imakefile: 29,32d28 < #ifdef LIBDL_ENV < install.time:: libclass.a < $(INSTALL) $(INSTLIBFLAGS) libclass.a $(DESTDIR)/lib < #else /* LIBDL_ENV */ 34d29 < #endif /* LIBDL_ENV */ xmkfontd/Imakefile: 18c18 < $(INSTALL) ${INSTLIBFLAGS} non-andrew.fonts.alias ${DESTDIR}/X11fonts/fonts.alias --- > InstallFileToFile(non-andrew.fonts.alias, ${INSTLIBFLAGS}, ${DESTDIR}/X11fonts/fonts.alias) B3. Which configuration variables are used most often? AFS30_ENV AFS31_ENV AMS_DELIVERY_ENV WHITEPAGES_ENV SNAP_ENV ANDREW_MALLOC_ENV DEBUG_MALLOC_ENV MK_BASIC_UTILS MK_AUTHORING MK_AUX_UTILS MK_AUX_INSETS MK_EXAMPLES RUN_AMDS_ENV ANDREW_PRINTING_ENV LINKINSTALL_ENV CONTRIB_ENV PRE_X11R4_ENV DPS_ENV DEFAULT_ANDREWDIR_ENV BUILDANDREWINSTALL_ENV ISO80_FONTS_ENV FONTS_TO_PCF_ENV CDEBUGFLAGS = -g MAKEDODEBUG = -g AFSBASEDIR = /usr/local XMKFONTDIR = /usr/local/bin/mkfontdir XFC = /usr/local/bin/bdftosnf XLIBDIR = /usr/local/lib XINCDIR = /usr/local/include RESOLVLIB = ${AFSBASEDIR}/lib/res/libresolv.a RESINC = -I$(AFSBASEDIR)/include/res INCLUDES = -I${BASEDIR}/include -I$(BASEDIR)/include/atk $(RESINC) -I$(AFSBASEDIR)/include -I${XINCDIR} B4. Should I modify the Imakefile or the Makefile? Changes should never be made to the Makefile. All changes should be made to Imakefile; "make Makefile" to regenerate that one file, or "make Makefiles" to regenerate the Makefiles in all subdirectories, recursively. "make clean" and "make Clean" do not delete the Makefile, so a subsequent "make Makefile" says it is up to date, i.e., comparing its own timestamp against itself. Beware: once you remove the Makefile from a directory, you can't say "make Makefile" there again, You can, however, rename Makefile to another name and say "make Makefile -f newname". B5. If I have resolver_env turned on, the andrew build fails while trying to build amsn.do. This only happens on a Sun 4 platform. Did I do something wrong? Here is an informal patch that fixes a problem with an undefined symbol in amsn.do. This patch is only necessary for SunOS4.1 platforms. *** ./atkams/messages/lib/Imakefile Thu Mar 19 14:33:36 1992 --- ./atkams/messages/lib/Imakefile.new Fri May 22 15:48:25 1992 *************** *** 6,11 **** --- 6,15 ---- BSDLIB = -lbsd #endif + #ifdef RESOLVER_ENV + RESOLVER_LIB = ${RESOLVLIB} + #endif /* RESOLVER_ENV */ + LOCALINCLUDES = -I${BASEDIR}/include/ams #ifdef SNAP_ENV *************** *** 39,45 **** LIBS = ${BASEDIR}/lib/libmsshr.a \ ${BASEDIR}/lib/libmail.a ${BASEDIR}/lib/liberrors.a \ ! ${UTILLIB} SLIBS = ${BASEDIR}/lib/libcui.a ${BASEDIR}/lib/libcuis.a \ --- 43,49 ---- LIBS = ${BASEDIR}/lib/libmsshr.a \ ${BASEDIR}/lib/libmail.a ${BASEDIR}/lib/liberrors.a \ ! ${UTILLIB} ${RESOLVER_LIB} SLIBS = ${BASEDIR}/lib/libcui.a ${BASEDIR}/lib/libcuis.a \ B6. Building Andrew from source fails on the SGI Indigo in andrew/atkams/messages/lib while running makedo on amsn.o. One of the SGI system libraries (libmld.a) causes the symbol _end to be sucked in to amsn.o. This symbol is defined in /lib/crt0.o but we can assume that it will be in runapp so we need to alter the machine-specific class code in andrew/overhead/class/machdep/sgi_mips such that the symbol is allowed to go undefined. Here is an informal patch that is necessary for SGI "Indigo" only. *** ./overhead/class/machdep/sgi_mips/globals.c.new Sat Jun 6 11:58:15 1992 --- ./overhead/class/machdep/sgi_mips/globals.c Thu Jan 23 12:22:09 1992 *************** *** 45,51 **** globalref(_sproced) globalref(_us_rsthread_stdio) - globalref(_end) /* do not delete the following line - make depends on it */ --- 45,50 ---- *************** *** 97,103 **** globalref(_sproced) globalref(_us_rsthread_stdio) - globalref(_end) /* do not delete the following line - make depends on it */ --- 96,101 ---- *** ./overhead/class/machdep/sgi_mips/getlist.awk.new Sat Jun 6 11:47:27 1992 --- ./overhead/class/machdep/sgi_mips/getlist.awk Thu Jan 23 12:22:08 1992 *************** *** 65,71 **** want[definer["_sproced"]] = "Y"; want[definer["_sprocmonstart"]] = "Y"; want[definer["_us_rsthread_stdio"]] = "Y"; - want[definer["_end"]] = "Y"; # END ADDED SGI ## Stuff for the class system want[definer["class_RoutineStruct"]] = "Y"; --- 65,70 ---- Messages/Mail M1. How can I instruct messages to use /usr/spool/mail for mail drop? Although the following lines are in /usr/andrew/etc/AndrewSetup: AMS_NonAMSDelivery: yes AMS_MailBoxPrefix: /usr/spool/mail Messages says, "/usr/user/Mailbox" could not be properly read and > delivered (0 success, 0 failure)". You should create a file $HOME/.mailrc and put in this line: unset hold WARNING: Once you start reading mail with messages, your incoming mail will be stored within directories maintained by messages. It is possible to return to other mail handling systems, but it may not be easy. M2. When using UCB sendmail, are aliases in /usr/lib/aliases case-sensitive? If you build your UCB sendmail with the ``DBM'' option set, aliases in /usr/lib/aliases are case-sensitive; if you build it without that option, they're case-insensitive. For purposes of validating user names, AMS assumes that aliases in /usr/lib/aliases are case-insensitive. This might mean that a name that validates OK with AMS might be rejected by UCB sendmail, if that sendmail uses DBM to do its alias lookup. M3. Why isn't queuemail installed automatically? 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. AFS A1. Why do I get errors when building Ultrix 4.2 against AFS 3.1 libraries? You need to define AFS_ULTRIX in your site.h file. A2. Do I need to have AFS to run the Andrew Message System (AMS)? 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. Regarding the ability to use "private" AMS bboards without AFS, Nathaniel Borenstein at Bellcore has patches which are about 90% complete to make AMS able to do private bboards without AFS. They will be made available to CMU soon, but if you want an early version of the 90% patch, along with a description of the remaining bug, please let send mail to nsb@thumper.bellcore.com. A3. What is AFS and how can I get more information? 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 Adjunct Software S1. How can I get other useful software? Enormous quantities of software are available for free from the internet. Many of the pieces are also available via electronic mail. Subsequent paragraphs list some software that may be of value as an adjunct to ATK/AMS. archie - archive locator A major source of information about the location of software on the network is 'archie'. Send mail to archie@archie.rutgers.edu In the body of the message include line(s) of the form prog name where name is the name of the software you would like to find out about. For more information, the body can contain the line help The listing returned from a 'prog' request will list ftp sites containing information with the name you gave. A site with a name ending in .com, .edu, or .gov will be in the United States and will be the best place to try. ftp - file transfer package To retrieve information via ftp over the internet: Give the command ftp The response will ask for your login; reply anonymous the response will ask for your email address; type it in. Now you can give the help command to see the commands. I generally use ls, dir, cd, lcd, pwd, and get. on the ATK cd-rom Some useful non-ATK software is included in the ATK cd-rom. For details see subsequent paragraphs. binaries only: X11 for RS6000, Sun 4, Dec Pmax, and HP700 binaries and source: metamail imake makedepend patch source only: ispell, psroff, pbmplus X Windows System: X11, imake, makedepend, patch Screen management and graphics software Binaries on cdrom in /X11/... Bdf fonts on cdrom in src/util/bdffonts imake, makedepend, and patch source on cdrom in src/util/... objects on cdrom in /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 metamail Converter for implementing MIME multi-media internet standard. newer version due early April, 1992 contact: Nathaniel Borenstein Bellcore Room 2A-274 Morristown, NJ 07962-1910 phone: (201) 829-4270 email: nsb@thumper.bellcore.com ftp: thumper.bellcore.com, see pub/nsb/README source: $ATKSRC/overhead/mail/metamail pbmplus Portable bit map conversion and transformation software version in cdrom:/src/util/pbmplus is from 10 December 1991 contact: Jef Poskanzer email: jef@well.sf.ca.us psroff Software augmenting troff and providing printer drivers. on cdrom: src/util/psroff is version 3.0 patch level 07 contact: Chris Lewis psroff-request@ferret.ocunix.on.ca ispell version on cdrom in src/util/ispell is 2.0.02 updated with a bigger dictionary new version 3.0.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 GNU software: groff, g++, gcc, gdb, gnuemacs, ... Free software, eventually replacing Un*x ftp: prep.ai.mit.edu see pub/gnu/GNUinfo/FTP and pub/gnu/etc/DISTRIB email: gnu@prep.ai.mit.edu mailing address: Free Software Foundation, Inc. 675 Massachusetts Avenue Cambridge, MA 02139 USA phone: +1 617-876-3296 transcript (psdit) Contact: Adobe 1585 Charleston Road P.O. Box 7900 Mountain View, CA 94039-7900 phone: 1-800-833-6687 Documenter's WorkBench AT&T / NCR Computer Division 800 225 5627 Gary Wagner 513 445 1475 S2. How can I use PostScript fonts other than those defined in /usr/andrew/X11fonts both in displayed and printed documents? There are two aspects of this problem: screen display and print display. Screen Display: To have your own fonts used by ATK applications for displaying text you must first create those fonts and place them in a directory, possibly set up a fonts.alias file, run mkfontdir to get a fonts.dir file, and finally add that directory to your X fontpath. Also, you'll have to specify in your preferences file the fontname: ez.bodyfont: myfont12 Print Display: To get these fonts to print you have to create the appropriate troff device-specific font description files (see /usr/lib/font/devpsc for the Postscript fonts). Question: Are there tools around that let you create a troff font? Furthermore, you'd have to alter the ATK-to-troff text translator (../andrew/atk/text/txtroff.c) to recognize your new font family and to make the appropriate mapping from your fontname to the troff fontname. Currently, the only fonts used for printing are Times, Helvetica, and Courier. S3. How do I use the spell checker function in ez? If ispell, the spelling checker used by ez, is not available at your site or is not along your path, ez will not be able to perform this function. ispell is widely available (e.g. via anonymous FTP off of uunet.uu.net). All an installer has to do to get ez spell checking to work is to install ispell somewhere along the user's path. The following .atkinit line will then be useful: addmenu "spell-check-document" "Search/Spell~1,Check Spelling~30" textview 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. ------------------------------------- *** ../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. S4. How do I debug Andrew applications? In order to debug ATK applications you will need to have gdb version 3.5 or greater from the Free Software Foundation. See Q11, How can I get other useful software? above for information on how to contact the FSF. To compile the system such that symbol tables exist add these two lines to your site.mcr: CDEBUGFLAGS = -g MAKEDODEBUG = -g To debug the raster application you would first load the statically-linked portion of the ATK run-time system, called runapp, into gdb. It is important that the above make.1 macros are set to include the -g switch so that the symbol table is created. There is no use attempting to use gdb if the system has not been built with the -g switch. % gdb runapp GDB, Copyright (C) 1987 Free Software Foundation, Inc. There is ABSOLUTELY NO WARRANTY for GDB; type "info warranty" for details. GDB is free software and you are welcome to distribute copies of it under certain conditions; type "info copying" to see the conditions. Reading symbol data from runapp... done. Type "help" for a list of commands. (gdb) run -d ezapp foo.ras -d Starting program: runapp -d ezapp foo.ras -d Starting ez (Version 7.0, ATK 15.0); please wait... raster: text = 0x10046594 data = 0x10049280 entry = 0x100498a8 rasterview: text = 0x1004f820 data = 0x1005cc60 entry = 0x1005f8d8 rasterimage: text = 0x1006701c data = 0x100675d0 entry = 0x10067810 pixelimage: text = 0x1006e758 data = 0x100703bc entry = 0x1007068c To load the symbol table for the raster dynamic object you would use this command on a Sun or a DECstation 3100[An Andrew ToolKit view (a footnote) was included here, but could not be displayed.]: (gdb) add-file raster.dog 0x10046594 and on an RT: (gdb) set-rel 0x10046594 (gdb) add-file raster.dog Note that the addresses passed to these gdb commands come from the text address that runapp outputs when the -d switch is used (the second -d switch prevents runapp from forking itself to become an orphaned process). To determine which module to load in the fashion described above compare the various text addresses with the address at which the program failed. For example, if the program died at address 0x1004a520 you would find that address between what was reported as the start of the text segments for raster and rasterview. Since the raster module was loaded first, we can conclude that the failure was somewhere in the raster module. S5. Why can't ez find ispell when I know it's installed? Ispell must be on your path in order for ez to find it. Printing P1. How can I print Andrew documents? Printing requires two steps, text formatting and then driving the printer. ATK utilizes troff for text formatting. That is adequate for printing documents with styled texts, but some insets such as rasters and zip require that the printer be driven with PostScript. Print processing is controlled via the FormatCommand and PrintCommand options, which can be specified in site.h during system build, the global preferences in $ANDREWDIR/lib/global.prf, or the user's ~/preferences file. The most general defaults are: *.FormatCommand: eqn -Tpsc /tmp/%s.n | troff -Tpsc - | *.PrintCommand: lpr -n The -Tpsc flags specify that the troff output is ultimately intended for a PostScript printer. If you do not have one, this value must be set to whatever is appropriate for your printer. ATK documents containing only styled text can be printed via most versions of troff and most print drivers. To print ATK documents via PostScript printers, you have three options: troff - psroff ditroff - psdit groff These differ in cost and the difficulty of installation. See Q8 for hints on acquiring these packages. troff - psroff Standard Unix systems are often delivered with an old troff which generates output for the "CAT" typesetter. This troff can be used to print ATK documents by sending the output through the psroff processor, available freely on the internet. See the psroff documentation. ditroff - psdit This is the route we use at CMU. ditroff is the device independent troff which comes with the Documenters Work Bench portion of Unix System V. psdit is part of the "Transcript" package available from Adobe software. Both ditroff and Transcript cost money. Adjust the FormatCommand to utilize the ditroff version of troff (it is usually called troff). The PrintCommand should usually use the -n switch and the lpr daemon will run psdit. 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. groff This package is free from the Free Software Foundation, the gnu people. The only hitch is that to build groff you must first build g++ and to build g++ you must first build gcc. We have compiled groff without any problems with g++-1.39.1. g++ also compiled gpic, geqn, gtbl. Groff includes gtroff to do text formatting and grops to generate PostScript. To To use both, have this specification: *.formatcommand: groff -pte -E /tmp/%s.n | *.PrintCommand: lpr -v Note: The -pte switches tell it to run gpic, gtbl, and geqn before running gtroff. The output of gtroff is automatically piped into grops, which generates the PostScript. (This assumes that /usr/gnu/bin (or wherever groff is installed) is on one's path.) The drawback of this simple approach is that the ATK preview option will no longer work. To retain the preview command, I believe, one can use specifications something like this: *.FormatCommand: cat /tmp/%s.n | gpic|gtbl|geqn|gtroff -Tpsc | *.PrintCommand: grops | lpr -v P2. Ezprint outputs rasters in PostScript. Can I print those rasters? If you just want to print one raster from an Andrew document, you can extract the raster from the troff output with a raw text editor and print it directly. You may have to add the line 20 20 translate to get it out of the bottom corner. You may also have to add an initial line containing only %! If you haven't got a postscript printer, the raster image can still be massaged with the pbm package. pbm understands the Andrew format or you can use the output of ezprint -t which will include the raster encoded in PostScript / hex form. Applications L1. How can I fix the error message in my console about Cannot open /dev/kmem? You may see the following error message: |>> console: 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: 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. L2. I get the following error in my console: X error BadValue, integer parameter out of range ... How can I fix this? Some users do not remember to run mkfontdir in the ${DESTDIR}/X11fonts directory after the dependInstall operation is complete. If you do not do so, you will see an error message similar to the following: 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. L3. Why can't the help program find any help files? Using a tree built from source: If help files cannot be found or the alias database is missing, the following make operations from the root of the object tree may help: make dependInstall SUBDIRS='helpindex helpaliases' These operations can be repeated as desired. Using a binary distribution or running off the CDROM: If you are running from the CDROM or are using the binary distribution available on emsworth, 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. Fonts F1. I'm not getting the right fonts. 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 F2. When using my NCD X terminal, sometimes text gets rendered in a scrambled way. 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. F3. When I run Andrew applications on a remote X server, I get the wrong fonts or cursors. 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: icon12 (for cursors), shape10 and xshape10 (for grey shading). The basic Andrew text fonts have names starting with tim, hel, and sym (Times, Helvetica, and Symbol). Other significant fonts are con10 and con12 (used by Console), msgs10 and 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 icon12 may be called icn16x16. Most likely these files will have .pcf extensions, but they may be installed as .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 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 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 finger font-help@atk.itc.cmu.edu for instructions. ___________________________________________________ User Questions U0. Introduction This section has been extracted from a larger FAQ file maintained at CMU by Andrew Plotkin (ap1i+@andrew.cmu.edu). Its permission information reads: Everything in this file is public domain. You can copy it, mail it to people, put bits of it in other files, print it out in 500-point type and staple it to the walls, whatever you want -- I'm happy to give you the opportunity, and I couldn't do a thing about it if I wanted to. Thanks to the multiple people who provided me with questions and answers. U1. Customizing your account How can I customize my Andrew account? For info on your preferences file: help preferences (or help prefs) I edited my .cshrc, but now I get strange errors when I start typescript, or I edited my .login, but now I get strange errors when I log in, or I edited my .plan, but now I get strange symbols when I finger myself, or I edited my .Xresources, but now I get strange errors when I start X, or I edited this file, but now I get strange errors.... If you use ez to edit your .plan, .login, .logout, preferences, .cshrc, .Xresources, .Xclients, .Xmodmap, .signature, or any file like that: you must get rid of any styles you put in. You can't have sections of bold, or typewriter, or italics, or different text sizes, or indentation. (Not even in your .plan file or .signature, although that would be nice.) Use "Plainest" on the whole file if you have to. U2. Playing with ATK things How do I customize an ATK program? See the help file on it. The ATK help files are more friendly than average; lots of examples, no words over two syllables, etc. How do I change the behavior, fonts, and so on in ATK windows and menus? Most of these are controlled by preferences: help preferences help menubar The lines described in these help files go in your preferences file. For example, *.Thumbscroll: yes will cause the text in any ATK window to swoop up and down when you wiggle the scroll bar. typescript.Thumbscroll: yes will cause that to happen only in typescript windows. A major exception is the appearance of the pop-up menus you get when you press and hold the middle button. These are controlled by X resources (when you are running X.) help cmenu The resources described in this help file go in your .Xresources file. *TitleFont: andysans22b will cause your menu card titles to be printed in a 22-point bold sans-serif font. help*TitleFont: andysans22b will cause that to happen only in help windows. (Notice the format of an .Xresources entry is different from a preferences entry.) I have a color display. Can I get windows in colors other than black and white? Yes, set the colors in your preference file with lines like this: # darker blue on lighter tan. tan good. (blue not really dark enough) ez.foregroundcolor: #003ea2 ez.backgroundcolor: wheat For colors you can run xcolorpick or edit the file /usr/lib/X11/rgb.txt. Color names are recognized by X only if they are in rgb.txt. If you want colors just for one execution of a program, you can set them on the command line: typescript -fg black -bg burlywood Here's a technique for setting color preferences based on the value of the environment variable ISCOLOR, which you can set in your .login file as follows: set TTY = `tty` if ($TTY == /dev/console || \ $TTY == /dev/hft/0 || \ $TTY == /dev/ttyaed || \ $TTY == /dev/ttyapa16 || \ $TTY == /dev/ttyap16 || \ $TTY == /dev/tty8514 || \ $TTY == /dev/pty/ttyse || \ $TTY == /dev/ttymono) then set consolelogin = 1 echo -n "Color display? [y/n]: " set answer = $< if ($answer" =~ [Yy]*) then setenv ISCOLOR 1 echo "color console login" else echo "console login" endif unset answer endif You can then reference this variable in your preferences file: ?E=ISCOLOR=1:ez.backgroundcolor: antiquewhite1 ?E=ISCOLOR=1:console.backgroundcolor: cornsilk ?E=ISCOLOR=1:typescript.backgroundcolor: cornsilk3 ?E=ISCOLOR=1:help.backgroundcolor: cornsilk3 ?E=ISCOLOR=1:messages.backgroundcolor: cornsilk2 ?E=ISCOLOR=1:bush.backgroundcolor: #e5d7c6 How do I add styles to ATK documents? help ez-styles How do I add tables of contents and footnotes to ATK documents? help ez-contents help ez-footnotes How do I adjust line spacing and margins in ATK documents? help ez and scroll down to "Formatting text: line spacing and margins". What keystroke commands work in ATK programs? help ez-keys Notice that most gnu-emacs keys work in ATK programs. How do I work with multiple ez windows or multiple buffers? help ez-buffers How do I remove ATK formatting from an ATK document, to turn it into plain text? The easy way is to edit it with ez, select (highlight) the entire document, and select "Plainest". This will not work if the document has pagebreaks, footnotes, or insets (such as embedded rasters.) If you don't want to start up ez, you can use ez2ascii: ez2ascii filename Another alternative is to type rtfm -f filename This produces output with terminal formatting. It will look ok in an xterm, and underlining and boldface will show up correctly. However, it will fail nastily in a typescript, or if you put the output in a file and edit it. For more info, see help ez2ascii help rtfm How can I write my own console layout? help lacc The publically-available console layouts are in /usr/local/lib/consoles. If you want to write your own, it's best to start with one of these and modify it. Once you've written your console layout file, add this line to your preferences: console.default: consolefilename where consolefile is a full pathname (no ~'s), for example /afs/andrew/usr99/userid/layoutfile What is a help search path? Look at help preferences and scroll down to "Help preferences." (Redundant, aren't I? And repetitive.) The default help search path includes the help directories for all the standard Andrew programs, and everything in /usr/contributed. To add, for example, the help directory for the Computer Club's programs, you would add this line to your preferences: help.searchpath: /afs/andrew.cmu.edu/usr0/cl0x/man If you have more than one directory in this line, they should be separated by colons, not spaces. The search path is read in when you start help. If help is already running, you can add a directory to the search path by choosing "Add Search Directory" from the menu. This change is only temporary and will go away when you quit help. To permanently add a directory, you have to put it in your preferences. U3. Mail and bboards How do I set options for messages? Select "Set Options" on the "Other" menu card. This will bring up a long list of options where the message titles usually are, and explanations and switches where the message bodies usually are. You can scroll through either list, and click on the switches to change things. (Some of these changes take effect immediately; for others, you have to quit and restart messages.) There are a few, more obscure, options that you can set in your preferences file. Type help preferences and scroll down to "Andrew Messages System preferences". U4. Strange file formats How do I convert rasters, bitmaps, or images from one type to another? To convert old-style ATK rasters (.ras) to new-style ATK rasters (.raster) or vice-versa, help convertraster convertraster claims to be able to convert MacPaint files that you have ftp'd to Andrew. This may not be reliable. To convert other image types, including X bitmaps, MacPaint files, and GIFs, help pbm help pnm and also see the help files on all the little programs they mention. Some notes: PBM, PPM, and PGM are special image file formats which are designed to be "intermediate" conversion formats. That is, you can convert anything to these formats, and then convert it to anything else. PBM ("portable bitmap") is for simple black-and-white images like those produced by MacPaint or bitmap. PGM ("portable greymap") is for images with shades of grey, and PPM ("portable pixmap") is for full-color images. PNM ("portable any-map") is not a file format; a program called "pnm-something" can handle PBM, PPM, or PGM files. PBM, PGM, and PPM can be interconverted with the appropriate programs (ppmtopgm, pgmtopbm.) Both of these lose information, of course: ppmtopgm reduces the color image to shades of grey, and pgmtopbm changes shades to grey to black-and-white (although it will simulate grey by mixing black and white dots.) Also, a PGM file can be used whenever a PPM file is expected (ie, as input to ppm-something), and a PBM file can be used whenever either of the other two formats is expected. This is reasonable, since a bitmap is just a greyscale image with only two shades of grey, and a greyscale image is just a color image with only grey colors. All the conversion programs (except convertraster) work as filters. See the examples below. There are two programs, atobm and bmtoa, which convert X bitmaps to and from ASCII files. There are no help files on them. The MacPaint to RLE program, painttorle, is not reliable for large (full-screen) MacPaint files. PostScript files are designed only to be printed, so they're hard to convert to any other format. If you want to do that, you should view the file with dxpsview and then take a window dump of the dxpsview window (which produces an XWD file), and then convert that. To convert an X bitmap to a PBM file, use cat file.bm | xbmtopbm > file.pbm To convert a PBM file to an X bitmap file, use cat file.pbm | pbmtoxbm > file.bm To convert a GIF to PostScript, use cat file.gif | giftoppm | ppmtops > file.ps U5. Working with graphics and images What drawing and painting programs are available on Andrew? (Drawing programs are the ones like MacDraw, that let you put down geometric objects and then move them around, change their sizes, and so on. Painting programs, like MacPaint, let you splot paint down on a raster, possibly in geometric shapes, and edit it pixel by pixel.) There are the ATK versions, zip (drawing) and raster (painting). zip is slow and somewhat buggy, and nobody uses it. raster is very primitive, and nobody uses it. However, they have the advantage of letting you put zip-drawings or rasters into ATK documents along with text. help zip help raster U6. Fancy key bindings Some packages commonly used by developers are not normally bound to keys in order to simplify the user interface. If you want to bind them, add the given line to your ~/.atkinit file or to apply the binding just to application xxx, add the line to ~/.xxxinit. help initfiles How can I execute an arbitrary expression? help ness and read $ANDREWDIR/doc/atk/ness/nesshack.doc The normal binding of this function is ESC-ESC, though some people find this too easy to type by mistake (and Ness does take a couple of seconds to load the first time it is called). To get the ESC-ESC binding add to your .atkinit the line: addkey ness-dostmt \e\e view What is the "proctable"? help procs Menu entries and key sequences are not bound directly to functions in C code. Instead they are bound to routines made available by the C code for the various insets. For instance, the operation on text usually bound to ESC-b, which moves the cursor backward by one word, is the proctable function textview-backward-word. When such a function is called from Ness, however, the dashes are written as underscores: textview_backward_word. How can I find out what is in the proctable? help deskey The deskey package offers several proctable functions which can be bound to keys or menu entries. My own usage is given by these lines in my ~/.atkinit: addkey deskey-describe-bound-keys ^XK im addkey deskey-describe-proctable ^XP im Then control-X-shift-K opens another window showing all the current key bindings and control-X-shift-P opens a window showing all functions currently in the proctable. More functions are added to the list as more insets are loaded in. How can I execute an arbitrary proctable function? help metax The metax package offers two operations to bind to keys. They prompt for a function to execute and provide name completion by examining the proctable for function names. To bind ESC-x to the operation that calls a function without passing an argument add this line to .atkinit: addkey metax "\ex" view metax How can I get file name completion in typescript? If you are typing a file name to ez, you can get file name completion with space and question mark. The same functionality is available in the typescript window, but it is better to bind it to other keys. The following in 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). Can I perform incremental search as in gnuemacs? help search help gsearch Yes, three different alternative search packages are available. Dynamic search is described in the help file for search and a 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 twice the menu option Show More Documentation.) A simplified incremental search package with no documentation can be bound with addkey incsearch-forward ^S textview addkey incsearch-backward ^R textview Note that incsearch-forward MUST be bound to ^S or it will do backward searches. How can I convert paragraphs that have hard newlines within them to ATK paragraphs with newlines only at the ends? read $ANDREWDIR/lib/ness/format.n To convert text in messages or DOS files to ATK format, you need to wrap the lines. This can be done with a query replace changing newlines to spaces, but this is not always satisfactory because multiple spaces are needed after sentence ending punctuation. When you have a binding for ness-dostmt you can use a Ness function. Select the text to be wrapped, type ESC-ESC or your binding for ness-dostmt, and then answer the prompt with format_wrap() The selected text will be wrapped appropriately. U7. Programming in Ness and C Is there a way to bind a keystroke or menu to a simple combination of other operations? You could write a "package" following the model of incremental search, but it's lots easier just to write a short Ness function. help ness A simple approach is to create a directory ~/nesslib and put in it the files--say f.n and g.n--with the Ness functions. Then in your .atkinit or other .XXXinit file, add the lines load ness call ness-load /usr/you/nesslib/f.n call ness-load /usr/you/nesslib/g.n Substitute the full path to your nesslib directory. Do the "load ness" line only once. Example 1: Provide a menu operation to start up a typescript. (This was written for a user whose window manager and typescripts died often; if any window was left the user could start a typescript.) The Ness code is: extend "view:frame" on menu "File,Typescript~85" system("typescript" -- launch typescript -- and don't wait: ~ " >/dev/null &1 &") end menu end extend Example 2: Add to messages a menu option "FollowUp-To" which sets up a reply to the sender of the current message, excerpts the body of the message into the reply, and warps the mouse to the sendmessage window. This code was the subject of a "call ness-load" in ~/.messagesinit. extend "view:messwind" on menu "This Message,Followup-To" messages_reply_to_sender(currentwindow) messages_sendmessage_compound(currentwindow, "sendmessage-excerpt-body;" ~ "sendmessage-focus-on-body") frame_next_window(currentwindow) textview_end_of_text(currentinputfocus) end menu end extend How can I create the C code for a new inset? help createinset This program creates a directory and puts seven files in it which constitute a working, though not useful, inset. You need only modify the appropriate portions to make an inset which does what you want. _______________________ Copyright 1992 Carnegie Mellon University. All rights reserved.