For Xerox Internal Use Only -- September 7, 1976

For PARC Alto Users        September 7, 1976                          1




1. PARC Information



1.1. Getting Started

New Alto disks are stored in a cabinet in the Maxc room.  Please record
the serial number  of any new  disk that you take  on the log  which is
attached to the front to the cabinet..

The  BASIC ALTO  DISK is  in a  rack near  the Alto  in the  Maxc room.
Procedures  for  copying the  Basic  Alto  Disk to  your  new  disk are
described  in section  6  of the  Operating  System Manual  and  in the
CopyDisk document.


1.2. Alto Directories

The <ALTODOCS> directory contains documentation for the  subsystems and
subroutine packages.

The  <ALTO>  directory  contains  current  versions  of  all  the  Alto
programs.   Programs are  normally kept  in executable  form;  thus the
CopyDisk  program appears  as <ALTO>CopyDisk.Run.   In addition  to the
executable file, some programs also have a symbol file on  <ALTO>.  The
symbol file name has the  extension .Syms.  This file is useful  to the
author  when something  goes  wrong with  a  subsystem, but  it  is not
normally needed by  users.  Subsystems which  need more than  one file,
either  because they  have overlays  or because  they need  data files,
should have the individual  files stored, together with a  command file
which  may be  run to  retrieve each  file via  FTP.  The  command file
should have the extension .CM.  Definition files have the extension .D.
These files are useful only to programmers.

Subroutine packages are kept on <ALTO> with an extension of .BR.

The <ALTOSOURCE> directory contains the source files for the subsystems
and  subroutine  packages.  It  also  contains the  PUB  files  for the
documentation which is on <ALTODOCS>.


1.3. Alto Software Releases

The maintainer of  a subsystem or subroutine  package handles a  new or
revised release in the following manner:

A.  Copy a dump file with  a name of the form subsystemname.DM  and the
following contents to <ALTOSOURCE>:

      1) The source files from which the subsystem may be created.

      2) The  command files  which are needed  to create  the subsystem
      from  the   enclosed  source.   The   following  are   the  usual
      requirements:

            a)  A command  file  containing statements  to  compile the
            enclosed source.  Compiler messages should be written  to a
            file.  For example:

            BCPL/F FOO.BCPL.
           For Xerox Internal Use Only -- September 7, 1976

For PARC Alto Users        September 7, 1976                          2




            The filename should be in the format, COMPILEsubsysname.CM.

            b) A command file  containing statements to load  the files
            which were produced in step a.  For example:

            BLDR FOO

            The filename should be in the format, LOADsubsysname.CM.

                  If the subsystem is small, the two command  files may
                  be  combined into  one.  The  name should  be  in the
                  format,  CREATEsubsysname.CM.  The  following example
                  will create the package for subsystem, FOO.

                  BCPL/F FOO.BCPL

                  BLDR FOO

            c) A command  file containing statements save  all relevant
            files  in  subsysname.DM, e.g.  the  file  DUMPFOO.CM would
            contain;

            DUMP FOO.DM FOO.BCPL CREATEFOO.CM DUMPFOO.CM

B.   When  you have  a  change to  make  to documentation,  or  wish to
introduce new documentation into the system, the following  three steps
are required:

      1. Retrieve the relevant  .PUB file from <ALTOSOURCE>.   The file
name  is  in  the format,  sys.PUB,  where  'sys' is  the  name  of the
subsystem  or  subroutine  package.   If  you  are  creating  brand new
documentation,  see  the  file  <ALTOSOURCE>ALTODOCTEMPLATE.PUB  for an
example.

      2. Edit the  pub file.  Pass  it to PUB--  a .TTY version  of the
documentation will be produced.

      3. When you are finished, copy the pub file back to <ALTOSOURCE>,
and copy the .TTY version to <ALTODOCS>.

Please be sure to copy the pub files from <ALTOSOURCE> afresh each time
you edit them, because they may have been edited to  produce expurgated
versions (for  distribution outside PARC),  to produce  indexes, remedy
formatting problems, etc.

Please try  to avoid  needless references to  PARC or  Maxc facilities.
For example, it  is frowned upon to  mention the <ALTO> directory  as a
place to find  something.  That is  assumed for PARC  users. Similarly,
avoid needless references to GEARS or EARS.

C.  Copy files  needed for the new  release to <ALTO>.   After updating
files   on   <ALTO>,   you   should   run   the   MAXC   command   file
<ALTO>ALTOMAINT.CMD    to   delete    excess   verisons    and   update
<ALTOSOURCE>MAXLOG,  the  file  used  by  the  UPDATE  procedure.   For
example:

            @CONNECT ALTO ISFWGI
            @COPY <SPROULL>CHAT.RUN CHAT.RUN
            @COPY <SPROULL>CHAT.SYMS CHAT.SYMS
            @RUNFIL ALTOMAINT.CMD
           For Xerox Internal Use Only -- September 7, 1976

For PARC Alto Users        September 7, 1976                          3




            @CONNECT

D.  Send a message to  Alto users describing the changes which  will be
effective with this  release.  The list of  Alto users is on  the file,
<SECRETARY>ALTOUSERS.MSG.   The subject  of the  message should  be the
name of the  subsystem or subroutine package.  Try to keep  the message
short.

Passwords:  The password  to all  Alto-related directories  on  MAXC is
ISFWGI.  Software  maintainers are  cautioned to  alter only  files for
which  they  will  take  responsibility.   Feel  free  to  archive  old
versions, but please leave the current version of all files.


1.4. Alto Documentation

Formal documentation is provided in two forms: a "perusal"  form, which
can be conveniently typed  at a TI or  VTS terminal on Maxc  or perused
with Bravo on an Alto, and a "notebook" form, which can only be printed
on ears,  and may have  fancy illustrations or  fonts in  it.  Informal
"message"  documentation can  be extracted  from  the <ALTO>MESSAGE.TXT
file.

A. The "perusal" documentation  is always stored on <ALTODOCS>  under a
file name  like sys.TTY,  where "sys" is  the name  of the  subystem or
package you are  interested in.  For  example, the documentation  for a
subroutine package, FOO, would be found on <ALTODOCS>FOO.TTY.  There is
one exception to this rule: for very simple subsystems (e.g.,  DUMP and
LOAD), the documentation is in <ALTODOCS>SMALLSUBSYSTEMS.TTY.

B.  The  "notebook" documentation  is  packaged in  larger  packages to
reduce  storage  overhead  and  to  provide  more  manageable  sets  of
documentation  for  printing.    Currently,  the  following   files  on
<ALTODOCS> may be copied to lpt: for notebook-style documentation:

      NPALTO.EARS.  "The Non-Programmer's Guide to the Alto."

      BRAVO.EARS,  MARKUP.EARS, DRAW.EARS  (etc),  NSIL.EARS, SIL.EARS,
            GYPSY.EARS.   Currently,  these subsystems  have  their own
            separate ears documentation.

      OS.EARS.  Operating System manual.

      BCPL.EARS.  A new, revised BCPL manual.

      SUBSYSTEMS.EARS.  Documentation for most Alto  subsystems (except
            those  listed below).   These are  arranged alphabetically,
            with headings to indicate which system is  being described.
            A directory at the front of the file contains documentation
            about  very simple  subsystems.  The  last section  of this
            manual contains  special information  relating to  Altos at
            PARC--where to find the software, how to maintain it, etc.

      PACKAGES.EARS.   This  contains  documentation  for  the software
            packages available for the Alto.

      ALTOHARDWARE.EARS.  This is  the "hardware" manual for  the Alto.
            The Trident disk interface is described in TRIDENT.EARS.

These files are formatted, and should therefore be printed with
           For Xerox Internal Use Only -- September 7, 1976

For PARC Alto Users        September 7, 1976                          4




      @COPY FOO.x LPT: [confirm] ('x' is either TTY or EARS)

To print all the short documents on EARS, you can just say

      @COPY <ALTODOCS>*.TTY LPT:DEFONT.EP cr

The  "notebook" documentation  for  all the  subsystems  and subroutine
packages may be obtained by:

      @COPY <ALTODOCS>SUBSYSTEMS.EARS to LPT: [confirm]

      @COPY <ALTODOCS>PACKAGES.EARS to LPT: [confirm]

C. The file <ALTO>MESSAGE.TXT contains all of the information which has
been sent to Alto users with SNDMSG.  Information about  recent changes
to a specific subsystem may  be selected by using the  'subject string'
option of the MSG subsystem.  For example, you may type

      MSG <ALTO>MESSAGE.TXT T S FOO

Or you can read the entire file by saying

      File: <ALTO>MESSAGE.TXT

to READMAIL.   Every six months  this file will  be purged and  its old
contents left on the next version of OLDMESSAGE.TXT.



1.5. Obscure <ALTO> facilities

In  addition to  the subsystems,  packages, and  definition  files, the
following occasionally needed (somewhat obscure) files may be  found on
the <ALTO> directory:

      ALTOMAINT.CMD: a maxc command  file to be run each  time anything
      new is copied onto the <ALTO> directory.

      FORM.DM: a dump file containing standard forms in BRAVO format.

      NEWDISK.CM: a command file for creating a minimal system on a new
      disk.   (See  the  Newdisk  procedure,  documented  in  the  Alto
      Subsystems manual.)

      NPDISK.CM: the Non-Programmer's supplement to NEWDISK.CM.

      PDISK.CM: the Programmer's supplement to NEWDISK.CM.

      STATUS.LOG: a file identifying the author, type, and distribution
      status of all Alto software.


1.6. Miscellaneous

The  Operating  System was  designed  by Butler  Lampson  and initially
implemented by  Gene McDaniel.   It is  currently being  maintained and
extended by Butler Lampson and Bob Sproull.

e12