docs: Added UNIX V10 Manuals

1 files changed, 205 insertions, 0 deletions

diff --git a/static/v10/man1/icon_pi.1 b/static/v10/man1/icon_pi.1
new file mode 100644
index 00000000..2fc07e27
--- /dev/null
+++ b/static/v10/man1/icon_pi.1
@@ -0,0 +1,205 @@
+.ds M \fH
+.de Ds
+.nf
+.in +.5i
+.ft H
+.sp .5
+..
+.de De
+.ft R
+.in -.5i
+.fi
+.sp .5
+..
+.TH ICON_PI 1 "The University of Arizona \- 5/6/86"
+.SH NAME
+icon_pi \- construct personalized interpreter for Icon
+.SH SYNOPSIS
+\*Micon_pi\fR
+.SH DESCRIPTION
+A personalized interpreter is
+a version of Icon in which the run-time system can be easily
+augmented and modified by the user.
+.PP
+To set up a personalized interpreter, a new directory should
+be created solely for the use of the interpreter; otherwise
+files may be accidentally destroyed by the set-up process.
+For the purpose of example, suppose this directory is
+named \*Mmyicon\fR. The set-up process consists of
+.Ds
+mkdir myicon
+cd myicon
+icon_pi
+.De
+Note that \*Micon_pi\fR must be run in the area in which the personalized
+interpreter is to be built.
+.PP
+The shell script \*Micon_pi\fR constructs three subdirectories:
+\*Mh\fR, \*Mstd\fR, and \*Mpi\fR. The subdirectory \*Mh\fR
+contains header files that are needed in C routines. The subdirectory
+\*Mstd\fR contains the portions of the Icon system that are needed
+to build a personalized interpreter. The subdirectory \*Mpi\fR
+contains a \*MMakefile\fR for building a personalized interpreter
+and also is the place where source code for new C functions normally
+resides.
+.PP
+The \*MMakefile\fR that is constructed by \*Micon_pi\fR
+contains two definitions to facilitate building personalized
+interpreters:
+.IP \*MOBJS\fR .5i
+a list of object modules that are to be added to or replaced
+in the run-time system. \*MOBJS\fR initially is empty.
+.IP \*MLIB\fR
+a list of library options that are used when the run-time system
+is built. \*MLIB\fR initially is empty.
+.PP
+Performing a \fImake\fR in \*Mmyicon/pi\fR creates four additional files
+in \*Mmyicon\fR:
+.Ds
+.ta 1i
+picont	\fRcommand processor\*M
+pilink	\fRlinker\*M
+piconx	\fRrun-time system\*M
+piconx.hdr	\fRheader for linker output\*M
+.De
+A link to \*Mpicont\fR also is constructed in \*Mmyicon/pi\fR so that
+the new personalized interpreter can be tested in the directory in
+which it is made.
+.PP
+The file \*Mpicont\fR normally is built only on the first \fImake\fR. The
+file \*Mpilink\fR is built on the first \fImake\fR and is
+rebuilt whenever the repertoire of built-in functions is changed.
+The file \*Mpiconx\fR is rebuilt whenever the source code in the
+run-time system is changed.
+.PP
+The user of the personalized interpreter uses \*Mpicont\fR in
+the same fashion that the standard \*Micont\fR; see \fIicont(1)\fR.
+(Note that the accidental use of \*Micont\fR in place of
+\*Mpicont\fR may produce mysterious results.)
+In turn, \*Mpicont\fR translates a source program using the
+standard Icon translator and links it using \*Mpilink\fR.
+The resulting icode file uses \*Mpiconx\fR.
+Note that the location of \*Mpiconx\fR is built into the icode file.
+.PP
+The relocation bits and symbol tables in
+\*Mpiconx\fR can be removed by
+.Ds
+make Stripx
+.De
+in \*Mmyicon/pi\fR. This reduces the size of this file substantially
+but makes the use of debuggers impractical.
+.PP
+If a \fImake\fR is performed in \*Mmyicon/pi\fR before any
+run-time files are added or modified, the resulting personalized
+interpreter is identical to the standard one. Such a \fImake\fR can
+be performed to verify that the personalized interpreter system
+is performing properly.
+.PP
+Note that a personalized interpreter inherits the parameters and
+configuration of the locally installed version of Icon in \*Mv6\fR, including
+optional language extensions.
+The file \*Mmyicon/h/config.h\fR contains configuration information.
+The definitions in this file should not be changed.
+.PP
+To add a new function to the personalized interpreter, it is first
+necessary to provide the C code, adhering to the conventions and
+data structures used throughout Icon.
+Some useful functions are
+contained in \*Mv6/pi/pil\fR, where \*Mv6\fR is the root
+of the source hierarchy for the Icon system.
+The directory
+\*Mv6/src/iconx\fR contains the source code for the standard built-in
+functions, which also can be used as models for new ones.
+.PP
+Suppose that \*Mgetenv\fR from \*Mv6/pi/pil\fR is to be
+added to a personalized interpreter. The source code can be obtained by
+.Ds
+cp v6/pi/pil/getenv.c myicon/pi
+.De
+(Note that the actual paths depend on the
+local hierarchy.)
+.PP
+Four things now need to be done to
+incorporate this function in the personalized interpreter:
+.IP 1. 5n
+Add a line consisting of
+.Ds
+FncDef(getenv)
+.De
+to \*Mmyicon/h/fdef.h\fR in proper alphabetical order.
+This causes the linker and the run-time system to know about the new function.
+.IP 2.
+Add \*Mgetenv.o\fR to the definition of \*MOBJS\fR in
+\*Mmyicon/pi/Makefile\fR.
+This causes \*Mgetenv.c\fR to be compiled and the resulting
+object file to be loaded with the run-time system when a \fImake\fR is performed.
+.IP 3.
+Add a dependency line in \*Mmyicon/pi/Makefile\fR for \*Mgetenv.o\fR
+to reflect the file that it includes, namely
+.Ds
+getenv.o:   ../h/rt.h
+.De
+.IP 4.
+Perform a \fImake\fR in \*Mmyicon/pi\fR.
+This produces
+new versions of \*Mpilink\fR and \*Mpiconx\fR in \*Mmyicon\fR.
+.LP
+The function \*Mgetenv\fR now can be used like any other built-in
+function.
+.PP
+More than one function can be included in a single source file.
+If a function requires a library to be loaded, that library should
+be added to the definition of \*MLIB\fR in the \*MMakefile\fR.
+.PP
+The use of personalized interpreters is not limited to the addition
+of new functions. Any module in the standard run-time system can
+be modified as well.
+To modify an existing portion of the Icon run-time system,
+copy the source code file from the standard system to \*Mmyicon/pi\fR.
+(Source code for a few run-time routines is placed in \*Mmyicon/std\fR
+when a personalized interpreter is set up. Check this directory
+first and use that file, if appropriate, rather than making
+another copy in \*Mmyicon/pi\fR.) When a source-code file in
+\*Mmyicon/pi\fR has been modified, place it in the \*MOBJS\fR
+list just like a new file and perform a \fImake\fR. Note that
+an entire module must be replaced, even if a change is made to
+only one routine.
+Any module that is replaced must contain all the global variables in
+the original module to prevent \fIld(1)\fR from also loading the
+original module. There is no way to delete routines from the run-time
+system.
+.PP
+The directory \*Mmyicon/h\fR contains header files that are included
+in various source-code files.
+The file \*Mmyicon/h/rt.h\fR contains declarations and definitions that
+are used throughout the run-time system. This is where the declaration
+for the structure of a new type of data object would be placed.
+.PP
+Care
+must be taken when modifying header files not to make changes that
+would produce inconsistencies between previously compiled components
+of the Icon run-time system and new ones.
+.SH FILES
+.ta 1i
+.nf
+\*Mv6/pi\fR	code for building personalized interpreters
+\*Mv6/src/iconx\fR	run-time system
+.fi
+.SH SEE ALSO
+icont(1)
+.LP
+\fIPersonalized Interpreters for Version 6.0 of Icon\fR, Ralph E.
+Griswold, TR 86-12, Department of Computer Science, The University
+of Arizona, May 1986.
+.LP
+\fIThe Icon Programming Language\fR,
+Ralph E. Griswold and Madge T. Griswold,
+Prentice-Hall Inc.,
+Englewood Cliffs, New Jersey,
+1983.
+.LP
+\fIVersion 6.0 of Icon\fR, Ralph E. Griswold, William H. Mitchell, and
+Janalee O'Bagy,
+TR 86-10,
+Department of Computer Science, The University of Arizona,
+May 1986.