SysIII/usr/src/man/docs/graf_adm

.ds :? Graphics Administrative Information
.PH "''''"
.OH "'\s9\f2\*(:?\fP''\\\\nP\s0'"
.EH "'\s9\\\\nP''\f2\*(:?\^\fP\s0'"
.TL
Administrative Information for the UNIX Graphics Package
.AU "Ruth L. Chen" RLC  PY 3782 7160
.AU "Diane E. Pinkston" DEP PY 3782 4795
.AU "Arthur Guyton \s-2(4/1/80 revision)\s+2" AG PY 3646 4162
.MT 4
.SP 4
.H 1 "INTRODUCTION"
This document is a reference guide for system
administrators who are using or establishing
a Graphics facility [1] on \s-1UNIX\s+1\*(Tm.
It contains information about directory structure, installation, makefiles, hardware
requirements, and miscellaneous facilities of the Graphics Package.
.H 1 "Graphics STRUCTURE"
Figure 1 contains a graphical representation of the directory structure of Graphics.
.DF
.sp 8.75i
.DE
In this paper, the \fIShell\fR variable \s-1SRC\s+1 will represent the 
parent node for Graphics source and is usually set to /usr/src/cmd.
.P
The \fIgraphics\fR command (see \fIgraphics\fR(1)) resides in
/usr/bin.  All other Graphics executables are located in /usr/bin/graf.
/usr/lib/graf contains text for \fIwhatis\fP documentation (see \fI
gutil\fR(1)) and editor scripts for \fIttoc\fR (see \fItoc\fR(1)).
.P
Graphics source resides below the
directory \s-1$SRC\s+1/graf.
\s-1$SRC\s+1/graf is broken into the following subdirectories:
.BL
.LI
include \(em contains the following header files:  debug.h,
errpr.h, gsl.h, gpl.h, setopt.h, and util.h.
.LI
src \(em contains source code partitioned into subdirectories by subsystem.
Each subdirectory contains its own Makefile (or Install file for whatis.d).
.BL
.LI
glib.d \(em contains source used to build the graphical subroutine library, \s-1$SRC\s+1/graf/lib/glib.a.
.LI
stat.d \(em contains source for numerical manipulation and plotting routines.
.LI
dev.d \(em contains source code for device filters partitioned into subdirectories.
.BL
.LI
lolib and uplib \(em contains source used to create device independent libraries.
.LI
hp7220.d \(em contains source for \fIhpd\fP (a Hewlett-Packard Plotter display function).
.LI
tek4000.d \(em contains source for \fIged\fR (the graphical editor), \fItd\fR
(a Tektronix display function), and other Tektronix dependent routines.
.LE
.LI
gutil.d \(em contains source for utility programs.
.LI
toc.d \(em contains source for table of contents drawing routines.
.LI
whatis.d \(em contains \fImm\fP files and the installation
routine for on-line documentation.
.LE
.LI
lib \(em contains glib.a which contains commonly used
graphical subroutines.
.LE
.sp
User manual entries for Graphics reside in /usr/man and consist of the following files:
graphics.1, gutil.1, stat.1,
gdev.1, toc.1, ged.1 and gps.5.
.H 1 "INSTALLING Graphics"
Procedures for installing
\s-1G\s+1raphics:
.DL
.LI
To build the entire Graphics package,
execute (as super-user)
.DS
.in 8
.nf
 \fB ./:mkcmd graf\fR
.fi
.in 0
.DE
while residing in 
/usr/src.
.LI
To build a particular graphics subsystem
use the \fIShell\fP variable \s-1ARGS\s+1,
.DS
.in 8
.nf
\fB\s-1ARGS\s+1=\fIsubsystem\fB ./:mkcmd graf\fR
.fi
.in 0
.DE
.LE
.sp
A
.I subsystem
is either
.I glib\c
,
.I stat\c
,
.I dev\c
,
.I toc\c
,
.I gutil
or
.I whatis\c
\&.
\fIGlib\fR must exist before other subsystems can be built.
Write permission in /usr/bin and /usr/lib
is needed,
and the following libraries
are assumed to exist:
.VL 35 2
.LI "/lib/libc.a\fR"
Standard C library, used by all subsystems.
.LI "/lib/libm.a"
Math library, used by all subsystems.
.LI "/usr/lib/macros/[nt]pwbmm.m\(**"
Memorandum macros for [\fInt\fR]\fIroff\fR,
used by the \fIwhatis\fP subsystem.
.LE
.sp
The complete build process takes approximately
two hours of system time.  If the build must be stopped, it
is a good idea to restart from the top.
Upon completion, the following things will be created and owned by ``bin''.
.VL 35 2
.LI "/usr/lib/graf"
A directory for data and editor scripts.
.LI "/usr/bin/graf"
A directory for executables.
.LI "/usr/bin/graphics"
Command entry point for Graphics.
.LE
.P
Makefiles use executable \fIShell\fR procedures \fIcco\fR and \fIcca\fR.
\fICco\fR is 
used to compile C source
and install load modules
in /usr/bin/graf.
The \fIcca\fR command 
compiles C programs and loads object code into archive files.
.P
Whatis.d contains source files for \fIwhatis\fR and
the executable command \fIInstall\fR.
.DS
.in 8
.nf
\fBInstall \fIcommand-name\fR
.fi
.in 0
.DE
calls \fInroff\fR
to produce \fIwhatis\fP documentation for \fIcommand-name\fR in /usr/lib/graf.
To install the entire \fIwhatis\fP subsystem, use
\fI:mkcmd\fP as described above.
.H 2 "Makefile Parameters"
Makefiles use various macro parameters, some of which can be specified
on the command line to redirect outputs or inputs.
Parameters specified in higher level  Makefiles are passed to lower levels.
Below is a list of specifiable parameters for Makefiles followed 
by their default values in parentheses and an explanation of their usage.
.AL 1
.LI
\s-1$SRC\s+1/graf/graf.mk
.VL 23 2
.LI "\fB\s-1BIN\s+11 \fR(/usr/bin)"
installation directory for the \fIgraphics\fR command.
.LI "\fB\s-1BIN\s+12 \fR(/usr/bin/graf)"
installation directory for other graphic commands.
.LI "\fB\s-1SRC\s+1 \fR(/usr/src/cmd)"
parent directory for source code.
.LE
.LI
\s-1$SRC\s+1/graf/src/Makefile
.VL 23 2
.LI "\fB\s-1BIN\s+11 \fR(/usr/bin)"
installation directory for the \fIgraphics\fR command.
.LI "\fB\s-1BIN\s+12 \fR(/usr/bin/graf)"
installation directory for other graphic commands.
.LI "\fB\s-1LIB\s+1 \fR(/usr/lib/graf)"
installation directory for \fIwhatis\fP documentation.
.LE
.LI
\s-1$SRC\s+1/graf/src/stat.d/Makefile
.VL 23 2
.LI "\fB\s-1BIN\s+1 \fR(../../bin)"
installation directory for executable commands.
.LE
.LI
\s-1$SRC\s+1/graf/src/toc.d/Makefile
.VL 23 2
.LI "\fB\s-1BIN\s+1 \fR(../../bin)"
installation directory for executable commands.
.LE
.LI
\s-1$SRC\s+1/graf/src/dev.d/Makefile
.VL 23 2
.LI "\fB\s-1BIN\s+1 \fR(../../bin)"
installation directory for executable commands.
.LE
.LI
\s-1$SRC\s+1/graf/src/dev.d/hp7220.d/Makefile
.VL 23 2
.LI "\fB\s-1BIN\s+1 \fR(../../../bin)"
installation directory for executable commands.
.LE
.LI
\s-1$SRC\s+1/graf/src/dev.d/tek4000.d/Makefile
.VL 23 2
.LI "\fB\s-1BIN\s+1 \fR(../../../bin)"
installation directory for executable commands.
.LE
.LI
\s-1$SRC\s+1/graf/src/gutil.d/Makefile
.VL 23 2
.LI "\s-1\fBBIN\s+1 \fR(../../bin)"
installation directory for executable commands.
.LE
.LE
.sp
The following example will make a new version of the graphical editor,
\fIged\fR, installing it in
/a1/pmt/dp/bin:
.DS
	\fBcd \s-1$SRC\s+1/graf/src/dev.d/tek4000.d
	make \s-1BIN\s+1=/a1/pmt/dp/bin ged\fR
.DE
(This assumes, of course, that necessary libraries
were previously built.)
.H 1 "Hewlett-Packard Plotter"
The Graphics display function \fIhpd\fP uses the
Hewlett-Packard 7221A Graphics Plotter.
The HP plotter can be connected to the computer in series with a terminal
via a dedicated or dial-up line.
This arrangement allows the plotter to intercept plotting instructions
while passing other data to the terminal unaltered and thus
providing for normal terminal operation.
Plotter switch settings should match those of the terminal.
See the plotter operating manual for a more complete discussion [4].
.H 1 "Tektronix Terminal"
The Graphics display function \fItd\fR and the graphical
editor \fIged\fR both use Tektronix Series 4010 storage tubes.
Below is a list of device considerations necessary for Graphics operation.
.H 2 "Inittab Entry"
When a Tektronix 4010 series terminal is connected to UNIX 
via a dedicated 4800 or 9600 baud line, \fI/etc/inittab\fP should reference
speed table entry 6 (may vary locally) of \fIgetty\fP.
Speed table entry 6 is designed specifically for the Tektronix 4014
and, among other things, sets a form-feed delay so that the screen
may be cleared without losing information and clears the screen
before prompting for a login.
See \fIinittab\fR(5) and \fIgetty\fR(8) for more information.
.H 2 "Strap Options"
The standard strap options as listed below 
should be used (see the Reference Manual for the Tektronix 4014 [3]):
.AL 1
.LI
LF effect \(em LF causes line-feed only.
.LI
CR effect \(em CR causes carriage return only.
.LI
Del implies loy \(em Del key is interpreted as low-order y value.
.LI
Graphics Input terminators \(em None.
.LE
.H 2 "Enhanced Graphics Module"
The Enhanced Graphics Module (\s-1EGM\s+1) for Tektronix terminals is required for Graphics.
The \s-1EGM\s+1 provides different line styles (solid, dotted, dot-dashed,
dashed, and long-dashed), right and left margin cursor location, and 12-bit cursor addressing
(4096 by 4096 screen points).
.H 1 "MISCELLANEOUS INFORMATION"
.H 2 "Announcements"
The \fIgraphics\fR command provides
a means of printing out announcements to users.  To set up
an announcement facility, create a readable text file containing
the announcements named
\fBannounce\fR.  Also in \fI/usr/bin/graphics\fP redefine 
the \fIShell\fR variable \fB\s-1GRAF\s+1\fR
to be the directory pathname of the file \fBannounce\fR.
.H 2 "Uselog"
The \fIgraphics\fR command also provides
a means of monitoring its use by listing
users in a file.  To set up a uselog facility create a writeable
file named \fB.uselog\fR (in the same directory
as \fBannounce\fR if announcements are being used) and redefine the
\fIShell\fR variable \fB\s-1GRAF\s+1\fR within \fI/usr/bin/graphics\fP 
to specify the directory location.  Each
time a user executes \fIgraphics\fR, an entry of 
the login name, terminal number, and system date
are recorded in \fB.uselog\fR.
.H 2 "Restricted Environments"
Restricted environments can be used to limit user access to 
the system (see \fIrsh\fR(1)).
A restricted environment for Graphics can be set up by creating
the directories /rbin and /usr/rbin and populating them with
restricted versions of commands from /bin and /usr/bin so that
the environment can not be compromised.
In particular, the commands 
\fIed\fR, \fImv\fR, \fIrm\fR, and \fIsh\fR
require restricted interface programs which do not allow users to move or remove
files that begin with ``\fB.\fR''[2].
.P
To create a restricted environment for Graphics:
.AL 1
.LI
Create a restricted \fIged\fR command in /usr/rbin as follows:
.sp
	\fBexec /usr/bin/graf/ged \-\s-1R\s+1\fR
.sp
.LI
Create restricted logins for users or create a community login
with a working directory (reached through \fB.profile\fR)
set up for each user.  A restricted login
specifies /bin/rsh as the terminal interface program
and is created by adding /bin/rsh to the end
of the \fI/etc/passwd\fP file entry for that login.
.LI
Call \fBgraphics \-r\fR from \fB.profile\fP.
.LE
.sp
The execution of \fBgraphics \-r\fR changes \fB\s-1$PATH\s+1\fR to look for commands
in /rbin and /usr/rbin before /bin
and /usr/bin and executes a restricted \fIShell\fR.
The \fB\-\s-1R\s+1\fR option is appended
to the \fIged\fR command so that the escape 
from \fIged\fR to UNIX (\fB!\fIcommand\fR) will also use
a restricted \fIShell\fR.
.HU ACKNOWLEDGEMENTS
We wish to thank A. R. Feuer for his valuable contributions,
suggestions, and careful reading of this document.
We also thank M. J. Petrella for his help in supplying
information concerning the \s-1UNIX\s+1 environment.
.SG ""
.HU REFERENCES
.RL
.LI
Feuer, A. R.
.I "PWB/Graphics Overview."
Bell Laboratories, June 1979.
.LI
Petrella, M. J. 
.I "Restricted Access to PWB/UNIX \-"
DRAFT.  Bell laboratories, May 1979.
.LI
Tektronix. 
.I "Users's Manual for 4014 and 4014-1 Display Terminal."
July 1974.
.LI
Hewlett-Packard.
.I "7221A Graphics Plotter Operating and Programming Manual."
November 1977.
.LI
.I "UNIX Users's Manual"
\*-Release 3.0.
.LE
.sp
.I "April 1980"