@make(report) @definefont(Userfont, 1=, 2=, 3=, 4=, 5=, 6=) @modify(hd2, font userfont, facecode 2, flushright, below 1 inch) @modify(hd3, font userfont, facecode 4, left margin -2) @modify(copyrightnotice, flushright) @Style(Font computermodernroman11) @Style(spacing 1,indent 0) @Style(leftmargin 1.0inch) @Style(Linewidth 6.5inches) @Blankspace(1 inch) @begin(MajorHeading,Flushright,Font Userfont, FaceCode 1) Documentation Catalog @end(Majorheading) @begin(flushright, Font Userfont, FaceCode 4) L. B. Merims MIT Project Athena Revision B March 8, 1985 @end(flushright) @blankspace(4 inch) @copyrightNotice(Massachusetts Institute of Technology) @newpage @section(What Is Available?) This Project Athena @i(Documentation Catalog) tells you what to read and where to find it when you want to learn how to use some aspect of the Athena system. Athena documentation is available in these major forms: @begin(Description) @begin(multiple) @b(Free Introductory "Essentials")@\Athena tries to provide free introductory documents for each of its major systems. These documents, often called the @p(Essential) series, teach you how to use the system in its simplest form. They are intended to get you started doing something useful quickly. @b(Where to find it:) @i(Essentials) and other free documents such as certain quick-reference cards are available in all of the major Athena terminal clusters, and also at the IS Publications office in 11-209. @end(multiple) @begin(multiple) @b(Reference Manuals and User Guides)@\Most Athena systems are documented in complete supplier-published user guides and reference manuals. These manuals provide "the complete story" on how to use the software facility. They also cost money, anywhere from 60 cents for a pocket reference card to $50 for a three-volume manual. @b(Where to find it:) You can buy these manuals at the IS Publications Office in 11-209. Currently, the IS Publications Office is open from 11 a.m. to 3 p.m. Monday through Friday. Their phone number is (25)3-6325. The Publications Office accepts checks, cash, and MIT requisitions. Projects can use their funding to buy documentation. @end(multiple) @b(Manual Reference Racks)@\Each major Athena cluster has a complete set of documentation for all Athena systems in a public reference rack. @begin(multiple) @b(Online Documentation):@\All Unix commands are documented in online @p(man pages). A typical Unix user will reference these online man pages many times in a terminal session to search for useful commands or look-up a forgotten option. In addition, almost all of the Unix systems have writeups that describe their use. Although Athena sells these writeups bundled together as manuals, the writeups are available online as files in the @p(/usr/doc) directory. You can also print copies of the ones that interest you on Athena line printers. @b(Where to find it:)To find out how to access online man pages, type this command while logged into an Athena terminal: @example[man man] To explore online writeups, use the @i(cd) command to change to the @i(/usr/doc) directory and the @i(ls, more,) and @i(cd) commands to browse. Most of these writeups will first have to be formatted with some variation of the @i(nroff) command. Explore the files @i(README), @i(run), and the subdirectories themselves to figure out how to format the writeup. Finally, print the result with the @i(lpr) command. @end(multiple) @begin(multiple) @b(Newsletter)@\Athena publishes a monthly newsletter that contains articles about changes to the system, new software, seminars, and gives helpful advice on using Athena. Users are strongly encouraged to read the Project Athena @i(Newsletter) to keep up with what is happening on the system. Athena will also publish appropriate reader contributed articles. @b(Where to find it:) The @i(Newsletter) is available free in the terminal clusters, online in the directory @i(/usr/doc/newsletter), and by free subscription (phone (25)3-1300). @end(multiple) @end(description) @newpage @section(Project Athena) @subsection(What is Project Athena?) @p(An Introduction to Project Athena), first published in October, 1983, provides a general description of Athena's history and goals. It was prepared by the Athena Executive Committee and distributed to all faculty. It is now somewhat out of date. This booklet is available by request only. Call (617) 253-1300. @p(Faculty/Student Projects). Athena periodically publishes a booklet describing each of the faculty curriculum development projects. Available by request only. Call (617) 253-1300. @subsection(How Do I Get An Account? What Can I Do Once I Have One?) The @p(Essential Athena) document describes the basics of Athena such as administration, user accounts, terminal cluster locations, what software is available, hardware, and consulting. The @p(Project Athena Quick Reference) card summarizes much of this information, including a cluster map and telephone numbers. Both are free. Available in Athena terminal clusters. @subsection(Dialing In) The free Athena document @p(Dial-Up Access) explains how to phone in to Athena machines from your terminal at home. @newpage @section(Unix System) @subsection(Getting Started) @p(Essential Unix) and its accompanying @p(Unix Quick Reference) will help you get logged on to Unix and explain the most common Unix operations. Both are available free in the terminal clusters. @subsection(Learning More About Unix) @p(An Introduction to the C shell) explains how to take advantage of the Unix's most convenient system feautures, (strictly speaking, how to use the command interpreter called "the C shell"). It is for sale at the IS Publications Office for around $2, and in the terminal cluster manual racks. The @p(C Shell Summary) card has the same material in "quick reference" form. It is very hard to learn how to use Unix from the "official" Unix documentation. Many books have been published about Unix to fill this lack and more come out every day. Athena recommends @p(Introducing the Unix System) by McGilton and Morgan, published by McGraw-Hill, for the non-programmer who just wants to learn to use the system more effectively, and @p(The Unix Programming Environment) by Kernighan and Pike, published by Prentice-Hall, for the programmer who must build software tools in the Unix environment. You can buy @i(Introducing the Unix System) at the IS Publications Office for about $20. @i(The Unix Programming Environment) can be found intermitently at the Coop and in area book stores. Reference copies of both books are kept in the Athena terminal cluster manual racks. @subsection(Standard Unix Reference) The Athena @p(Unix User's Guide) contains the following standard Unix writeups of interest to all Unix users: @begin(format, leftmargin +5) Introduction to the C Shell Bug Fixes and Changes in 4.2BSD The Unix Time-Sharing System mh - A Mail Handling System for Unix Notesfile Reference Manual Writing Tools -- The Style and Diction Programs Awk -- A Pattern Scanning and Processing Language Sed -- A Non-Interactive Text Editor dc -- An Interactive Desk Calculator bc -- An Arbitrary Precision Desk Calculator Language A Guide to the Dungeons of Doom @end(format) The Athena @p(Unix Programmer's Guide) contains the following Unix writeups of interest to programmers trying to develop software: @begin(format, Leftmargin +5) Unix Programming and Standard I/O Library Make -- A Program for Maintaining Computer Programs Screen Updating and Cursor Movement Optimization: A Library Package A Tutorial Introduction to ADB (a debugger) gprof: a Call Graph Execution Profiler The M4 Macro Processor Lex -- A Lexical Analyzer Generator Yacc: Yet Another Compiler-Compiler RCS -- Revision Control System SPMS -- Software Project Management System 4.2BSD System Manual A Fast File System for Unix A 4.2BSD Interprocess Communication Primer Changes to the Kernel in 4.2BSD @end(format) Both manuals are for sale at the IS Publications Office. Reference copies are kept in the cluster manual racks. These writeups are also available individually in files under the @i(/usr/doc) directory. The Athena @p(Unix Commands) manual provides detailed descriptions of all Unix commands. The @p(Unix Functions) manual describes all Unix subroutines, functions, system calls, and files. These two taken together form the fundamental Unix reference work. Both are for sale at the IS Publications Office. Reference copies are in the cluster manual racks. All of the material in the @i(Unix Commands) and @i(Unix Functions) manual is available online through the @p(man) command. You can also print individual "man pages" using the following command: @example[man @i(pagename) | lpr] This will print the man page on your local laser printer. See the command @i(man man) or @i(Essential Unix) for more information on how to use the @i(man) command. (The Athena @i(Unix Commands) (sections 1 and 6) and @i(Unix Functions) (sections 2, 3, 4, 5, 7, and 8) manual together make Volume 1 of the traditional Unix manual. The @i(Unix User's Guide) and @i(Unix Programmer's Guide) are a re-organized subset of Volume 2 of the traditional Unix manual.) @newpage @section(Editors and Formatters) @subsection(Emacs Editor) The free documents @p(Essential Emacs) and the Athena @p(Emacs Quick Reference) card will get you started using the Athena-standard Emacs text editor. Emacs also has an interactive tutorial designed to teach you the editor while at a terminal. Type: @i(teach-emacs) (do put in the -). The Emacs editor and all its many options are described completely in the @p(CCA Emacs Reference Manual). This document is for sale at the IS Publications Office. Reference copies are available in each cluster's manual rack. Emacs has an extensive online help facility. Type CTRL-? or CTRL-_ while on the system to see your choices. Note in particular the @i(a) (for apropos) subcommand. @subsection(Scribe Formatter) Scribe is the Athena-supported text formatting program. At present, there is no free @i(Essential Scribe) document. To learn how to format your documents, see the @p(Scribe Users Manual). The first few chapters serve as the tutorial introduction to Scribe while the remainder explains how to use all of Scribe's many options. There is also a @p(Scribe Pocket Reference) booklet. Both documents are sold through the IS Publications Office (the pocket reference may be out of stock) and copies are kept in the cluster reference manual racks. To learn how to actually run Scribe once you have entered the formatting commands, type @p(man scribe) while logged in. The @p(Scribe Database Administrator's Guide) is a technical reference manual that explains how Scribe works internally and how to modify it. It is suitable only for the true Scribe "hacker." You will have to order copies individually from supplier Unilogic through the IS Publications Office. Athena may stock reference copies in manual racks in the future. The curious may also wish to study the directory @p(/usr/athena/lib/scribe/database). @newpage @section(Languages) All languages require two main kinds of documentation: a "Language Reference" manual that describes the language itself, its statements, keywords, and syntax; and a "Programmer's Guide" that explains how to run the compiler, compiler options, libraries, linking, and debugging. The first defines the language, the second explains the process of using the language on a particular system. @subsection(C) Unix does not come with an extensive C "language reference" manual. You will have to buy a book to serve this need. There are many C books published. Which you select will depend upon whether you are trying to learn how to program using C, or whether you already know how to program and just want to learn C. Athena does not currently recommend any book for people learning C as their first programming language. We suggest you browse through the C books at the Coop. If you are a programmer just wanting to pick up C, the standard work (although maybe not the best) is @p(The C Programming Language) by Kernighan and Ritchie, published by Prentice-Hall. IS Publications stocks this book. It is also generally-available. Copies are kept in the reference manual racks. As the "programmer's guide," you will need to assemble several pieces. The Athena @p(C) manual is the main piece. It includes the @i(C Reference Manual), the @i(Unix Programming) writeup, the @i(Lint) manual, and relevant man pages. Next you will need to study sections 2 and 3 of the Athena @i(Functions) manual. You can also view these online. Produce a table of contents for these sections by saying: @i[apropos '(2)'] and @i[man 3 intro] and @i(man 2 intro). We also strongly recommend that the serious C programmer buy @p(The Unix Programming Environment) by Kernighan and Pike. @subsection(Fortran) For a "language reference" manual, we recommend that you buy any of the many excellent Fortran 77 books available on the market. @p(Fortran 77 for Humans) by Page, Didday, and Alpert, published by West and stocked by the IS Publications Office is a good choice. Although it teaches programming using Fortran and may thus seem too elementary for the seasoned Fortran programmer, it does contain excellent reference material, including a clever last-page index that makes it very easy to find syntax definitions. Reference copies are in the cluster manual racks. Athena's free @p(Essential Fortran) is your starting place for "programmer's guide" information. A free @p(More Fortran) should be published by the end of March, 1985 that will continue the story. The serious Fortran programmer should also buy Athena's @p(Fortran) manual. This contains the document @i(A Portable Fortran 77 Compiler) that explains the features of the Unix @i(f77) compiler such as language extensions and I/O to files. It is for sale at the IS Publications Office. Reference copies are available in the cluster manual racks. You should also type: @p(man 3f intro) and @p(man 3 intro) to begin to find out what library calls are available to you. @subsection(Lisp) The Athena @p(Lisp) manual contains both the "language reference" manual and "programmer's guide" material for the Franz Lisp compiler Athena uses. However, the text assumes a fairly high level of Lisp sophistication. It is for sale at the IS Publications office; reference copies are in the cluster manual racks. If you are just learing to program in Lisp, there is an good book that explains both the language for neophytes, and how to use the Franz interpreter you will see on Athena. It is called @p(Lispcraft) by Wilensky, published by Norton. IS Publications stocks it; it is in the cluster manual racks. Many other Lisp books are available commercially. You should be careful because Lisp comes in many non-compatible dialects. @subsection(Pascal) The "programmers guide" for Pascal is the Athena @p(Pascal) manual. It explains how to use both the Pascal compiler and interpreter. IS Publications sells this manual; it is in the cluster manual racks. If you are just learning to program, we recommend @p(Oh! Pascal!) by Cooper and Clancy, published by Norton. The standard "language reference" manual for Pascal is the @p(Pascal Users Guide and Report), second edition, by Jensen and Wirth. This latter is not suitable for people unfamiliar with languages. IS Publications stocks @i(Oh! Pascal!). The Jensen and Wirth book is widely available in book stores. @i(Oh! Pascal!) is in the cluster reference manual racks. @subsection(Debuggers) @i(dbx) is the standard debugger for higher-level languages on Unix. For information on @i(dbx) type: @p(man dbx) @newpage @section(Graphics) @subsection(Penplot) The Penplot library of graphics subroutines is documented in two pieces. The package itself is described in the @p(Penplot Graphics Control System Reference Manual). This is for sale at the IS Publications Office. However, this manual was originally written for the Joint Computer Facility's implementation of Penplot under the VMS operating system. The free Athena supplement, @p(An Athena Guide to Using the Penplot Graphics Library) explains how to use Penplot specifically in the Athena Unix environment. There are reference copies of both documents in the cluster manual racks. The @p(man penplot) command shows how to link to Penplot. @subsection(BLOX) The BLOX user interface design tool and its accompanying CORE library are meant to be used only by projects developing software for courses by special arrangement with Athena applications consultants. Call Jennifer Pinkus at (25)3-1530 for information on BLOX. @newpage @section(General-Interest Utilities) @subsection(Mail) The free Athena document @p(Essential Mail) explains how to use the Athena standard MH mail system, including a description of sending network mail. If you want a quick list of mail commands while you are logged in, type: @p(apropos mh) and then use the @i(man) command to look at individual entries. A detailed discussion of the MH mailer is found in the document, @p(MH, A Mail Handling System for Unix). This is part of the Athena @i(Unix Users Guide), or you can just print the file @i(/usr/doc/MHman). @subsection(RS/1: The Electronic Laboratory Notebook) @p(Essential RS/1) will get you started using this tool for entering, graphing, modeling and manipulating laboratory data. The @p(RS/1 Reference Card) available for under $1 from IS Publications summarizes all RS/1 commands in a convenient inexpensive form. The 3-volume @p(RS/1 User's Guide) documents RS/1 completely--for a $50 price tag. It is available from IS Publications or in the cluster reference manual racks. RS/1 itself has an extensive interactive help facility. Once in RS/1, type @p(help) for more information. @subsection[Numerical and Statistical Libraries] The NAG library contains over 500 mathematical and statistical routines callable from C and Fortran. The @p(NAG Fortran Mini Manual) provides introductory material on using the NAG library and pointers into the more extensive documentation. Athena has reference copies only in the clusters. IS Publications will order copies. For information on linking to NAG, see @p(man nag). NAG routines are documented thoroughly in the @p(NAG Library Manual). This is made up of six large volumes providing a detailed catalog of all NAG routines. Athena stocks reference copies only in the clusters. IS Publications may order copies ($>200). @newpage @section(Networking) @subsection(File Transfer) You can transfer files between Athena machines with the @p(rcp) command. Type @i(man rcp) while logged into the system. See also the March, 1985 issue of the Athena @i(Newsletter's) article titled, "Consultant's Corner: Living on More than One Machine." This is available online in @P(/usr/doc/newsletter/85-03-05). You can also transfer files between Athena's IBM PC floppy disks and Athena Unix machines. This procedures is described in the free Athena document @p(Transferring Files between Athena and PC/XT Floppies), available in all Athena terminal clusters. Other forms of file transfer are not universally supported right now. See a student consultant. @subsection(Network Mail) The free Athena document @p(Essential Mail) has one section that describes how to send mail between Athena and the major other networks. Obtain it in the terminal clusters. @subsection(Remote Login) @p(man rlogin) describes how to login to other Athena machines when you have an account on more than one host. Other common forms of remote login such as telnet and chaosnet remote login are not universally supported right now. @newpage @section[Short List of Athena Documents] Free documents can be picked up at Athena clusters. The rest are sold at the IS Publications Office (11-209) from 11 a.m. to 3 p.m. weekdays, unless noted otherwise. Reference copies of most all documents are available in terminal cluster reference manual racks. @bar() @begin(format) @tabclear @tabset(4.5 inch) @b(Project Athena History & Goals) An Introduction to Project Athena @\by request x1300 Faculty/Student Projects @\by request x1300 @b(Athena Administration) Essential Athena @\free Dial-Up Access@\free Newsletter, montly @\free @b(Unix) Essential Unix @\free & Unix Quick Ref @\free Introducing the Unix System, McGilton + Athena Reading Guide The Unix Programming Environment, Kernighan@\not stocked at IS An Introduction to the C Shell Unix User's Guide Unix Programmer's Guide Unix Commands Unix Functions @b(Languages) C Language Ref: The C Programming Language, Kernighan Pgmr's Guide: Athena C Manual Fortran Language Ref: Fortran 77 for Humans, Page Athena Fortran Manual Pgmr's Guide: Essential Fortran@\free Pascal Language Ref: Oh! Pascal!, Cooper Pascal Users Guide and Report, Wirth@\not stocked at IS Pgmr's Guide: Athena Pascal Manual Lisp Language Ref: Lispcraft, Wilensky Athena Lisp Manual Pgmr's Guide: Lispcraft, Wilensky Athena Lisp Manual dbx debugger@\man dbx @b(Emacs Editor) Essential Emacs and Emacs Quick Ref@\free CCA Emacs Reference Manual @b(Scribe Text Formatter) Scribe Pocket Guide Scribe Users Manual @b[Mail Handler (mh)] Essential Mail @\free Mh Manual (in Unix User's Guide) @b(Penplot Graphics) Penplot Reference Manual Athena Guide @\free @b(NAG Numerical & Stat Library) NAG Mini Manual & Library Manual reference copies only @b(RS/1) Essential RS/1@\free RS/1 User's Guide @b(File Transfer) Transferring Files between Athena and IBM PC/XT Floppies@\free man rcp @end(format)