Google
 

Trailing-Edge - PDP-10 Archives - decuslib20-03 - decus/20-0082/plot1.hlp
There is 1 other file named plot1.hlp in the archive. Click here to see a list.
      TABLE OF CONTENTS

        1   INTRODUCTION
            1.1  GENERALITIES
            1.2  PROGRAMMING CONVENTIONS
            1.3  GRAPHING CONVENTIONS
            1.4  ERROR DETECTION AND RECOVERY
            1.5  "GLOB" ANALYSIS
            1.6  DEMONSTRATION PROGRAMS

        2   SYSTEM SUBROUTINES

        3   PLOTTER SUBROUTINES
            3.1  PLOTS
            3.2  PLOT
            3.3  SYMBOL
            3.4  NUMBER
            3.5  WHERE
            3.6  SCALE

        4   FRAMING AND PAGE CONTROL
            4.1  PLT00
            4.2  PLTFR, PLTBO
            4.3  PLTEJ

        5   MARGIN CONTROL
            5.1  PLTMS
            5.2  PLTMC

        6   AXES, LABELS, AND MARKS
            6.1  PLTAX
            6.2  PLTLA
            6.3  PLTCI, PLTFM
            6.5  PLTUR

        7   GRAPHS TAKEN FROM ARRAYS
            7.1  PLTIG
            7.2  PLTGA, PLTFI

        8   COORDINATE CONVERSIONS

        9   CONTOUR PLOTS

        10  HIDDEN LINE SUBROUTINES

        11  MULTIPLE SURFACES

        12  COLOR COMPOSITES

        BIBLIOGRAPHY

        APPENDIX 1.  INDEX OF THE <PLOT> FILE
        APPENDIX 2.  "GLOB" ANALYSIS OF THE <PLOT> FILE
        APPENDIX 3.  PLOTTER DEMONSTRATION ABSTRACTS
...










     IT IS USUAL TO NOTE THAT COMMON LANGUAGE APPROPRIATES MANY WORDS AS
NOUNS OR ADJECTIVES, WHICH ARE IN REALITY REGISTERED TRADEMARKS. IN THE
PRESENT INSTANCE, THESE INCLUDE AT LEAST THE FOLLOWING:

          NAME       OWNER

          CALCOMP    CALIFORNIA COMPUTER PRODUCTS CORPORATION
          TELETYPE   TELETYPE CORPORATION
          IBM        INTERNATIONAL BUSINESS MACHINES CORPORATION
          PDP-10     DIGITAL EQUIPMENT CORPORATION

     LIKEWISE, THE PUBLICATION OF A TECHNICAL DESCRIPTION OF THE USE OF
INDUSTRIAL OR COMMERCIAL EQUIPMENT DOES NOT CONSTITUTE AN ENDORSEMENT OF
THE BRAND; NEITHER DOES AN ENUMERATION OF ITS DEFICIENCIES CONSTITUTE A
CONDEMNATION OF THE PRODUCT.  NOWADAYS THERE IS AN INCREASING TENDENCY
TO TAKE A PROPRIETARY VIEW OF MONITOR SYSTEMS, SUBROUTINE LIBRARIES, AND
PROGRAM COLLECTIONS.  TO THE EXTENT THAT THIS IS TRUE, THE SAME REMARKS
APPLY.

     IT IS ALSO CUSTOMARY TO WARN THE USER OF PROGRAM PACKAGES THAT SUCH
PACKAGES MAY CONTAIN DEFECTS, EVEN THOUGH EXPERIENCED USERS ARE WELL
AWARE OF THE THE LIMITATIONS OF PROGRAMS ACQUIRED FROM OTHERS, AND THUS
SHOULD NEED NO WARNING.  AT THE SAME TIME, IT IS CUSTOMARY TO EXTOL THE
VIRTUES OF THE PROGRAMS BEING PROMOTED, IN THE HOPE THAT THEIR USE WILL
GROW.
1.   INTRODUCTION

1.1  GENERALITIES

      THE <PLOT> FILE IS A COLLECTION OF SUBROUTINES FOR THE CALCOMP
INCREMENTAL DIGITAL PLOTTER, CONSISTING OF CONTOUR PLOTS, PERSPECTIVE
VIEWS WITH HIDDEN LINE SUPPRESSION, GRAPHS IN VARIED COORDINATE SYSTEMS,
AND SIMILAR MATERIAL.  ALL THE PROGRAMS WHICH THIS FILE CONTAINS ARE
ULTIMATELY BASED ON A SERIES OF PLOTTER SUBROUTINES FURNISHED BY THE
DIGITAL EQUIPMENT CORPORATION, AND WHICH HAVE BEEN INCORPORATED INTO
THE FORTRAN LIBRARY OF THE PDP-10 AT SALAZAR. THEY ARE VERY SIMILAR TO
THOSE USED IN OTHER MACHINES, ALL OF THEM PRESUMABLY ONCE HAVING HAD A
COMMON ORIGIN IN SOFTWARE WRITTEN FOR THE CALCOMP PLOTTER, WHICH IS
THE USUAL OUTPUT DEVICE DRIVEN BY ALL OF THEM.

     THESE SYSTEM PLOTTER PROGRAMS INCLUDE

          PLOTS     WHICH INITIALIZES THE PLOTTER
          PLOT      WHICH MOVES THE PEN
          SYMBOL    WHICH WRITES ASCII CHARACTERS
          NUMBER    WHICH WRITES INTEGER OR FLOATING POINT NUMBERS
          WHERE     WHICH REVEALS THE CURRENT PEN LOCATION
          SCALE     WHICH SETS UP SCALE FACTORS

     WE SHALL REFER TO MEMBERS OF THIS GROUP OF SUBROUTINES AS "PLOTTER
SUBROUTINES."  EACH OF THEM EMPLOYS THE CALCOMP CONVENTIONS REGARDING
COORDINATES.  FACING THE PLOTTER FROM THE FRONT, "Y" IS THE HORIZONTAL
COORDINATE AND IS POSITIVE TO THE LEFT.  "X" IS THE COORDINATE WHICH
EXTENDS LENGTHWISE OF THE PAPER, AND IS POSITIVE RUNNING UPWARDS OVER
THE DRUM.  THESE CONVENTIONS ARE OBVIOUSLY DERIVED FROM RECORDING A
TIME SERIES OF EVENTS ACCORDING TO WHICH THE PAPER IS UNROLLED FROM
BEHIND THE DRUM, AND RECORDING CONTINUES AS LONG AS THERE IS PAPER LEFT
IN THE  DISPENSING ROLL.  ACCORDING TO THIS VIEW THE PHENOMENON BEING
RECORDED IS SUPPOSED TO HAVE A LIMITED VARIATION BUT IT COULD GO ON
BEING RECORDED FOREVER.

     SINCE MOST OF THE PROGRAMS IN THE <PLOT> FILE ARE PLANNED SO AS TO
PRODUCE A SINGLE 8 1/2" X 11" PAGE WHICH WILL BE VIEWED HORIZONTALLY,
A CONVERSION IS NECESSARY BECAUSE THE NATURAL COORDINATE CONVENTION IN
THIS ORIENTATION DIFFERS BY 90 DEGREES FROM THE CALCOMP CONVENTION.  TO
PLOT A POINT WITH COORDINATES (X,Y) ON A HORIZONTAL LETTER SIZED PAGE,
ONE SHOULD CALL ONE OF THE PLOTTER PROGRAMS WITH COORDINATES (Y,-X).
MOST OF THE <PLOT> FILE WILL NEVER NEED THIS TRANSFORMATION, BECAUSE THE
PLOTTER ROUTINES ARE BURIED QUITE DEEPLY IN THE USER SUBROUTINES, AND
ARE THE ONLY ONES WHICH REQUIRE SUCH A SUBSTITUTION.  NEVERTHELESS,
ANYONE WHO WANTS TO USE THE PLOTTER ROUTINES HIMSELF, OR WHO WANTS TO
UNDERSTAND THOSE SUBROUTINES WHICH DO USE THE PLOTTER ROUTINES, MUST
BE AWARE OF THE DIFFERENCE IN CONVENTIONS.  NATURALLY, IN DESCRIBING THE
PLOTTER SUBROUTINES THEMSELVES THE CALCOMP COORDINATE CONVENTIONS WILL
BE ASSUMED THROUGHOUT.

     THE CALLING SEQUENCES OF THE SIX PLOTTER SUBROUTINES ARE EXPLAINED
IN SECTION 2, USING THE SAME FORMAT THAT IS FOUND IN THE LISTING OF THE
<PLOT> FILE.  IN THIS WAY IT IS POSSIBLE TO INCORPORATE THE PLOTTER
SUBROUTINES IN THE INDEX AND THE ABSTRACTS WITH A MINIMUM OF ALTERATION.
THE PLOTTER PROGRAMS THEMSELVES ARE WRITTEN IN PDP-10 MACRO ASSEMBLY
LANGUAGE, AND MAY BE CONSULTED IN THE LISTINGS OF THE FORTRAN LIBRARY
PROGRAMS.
1.2  PROGRAMMING CONVENTIONS

     THE <PLOT> FILE CONTAINS OVER A HUNDRED SUBROUTINES, WHICH IMPOSES
A CONSIDERABLE BURDEN ON THE MEMORY OF THE USER WHO WISHES TO BECOME
FAMILIAR WITH ALL OF THEM.  TO ASSIST IN THE RECOLLECTION OF DETAILS,
INCLUDING THE PURPOSE OF THE SUBROUTINE, OR THE SIGNIFICANCE OF ITS
ARGUMENTS, SEVERAL PROGRAMMING CONVENTIONS HAVE BEEN INSTITUTED, AND AN
EFFORT MADE TO FOLLOW THEM WHILE WRITING THE SUBROUTINES.

     THE NAMING OF A SUBROUTINE FOLLOWS THE PATTERN XXXYY, IN WHICH XXX
IS A MNEMONIC DESIGNATING A CATEGORY OF SUBROUTINES, AND YY SIGNIFIES
AN INDIVIDUAL SUBROUTINE WITHIN THIS CATEGORY.  USUALLY XXX WILL BE THE
COMMON PREFIX OF ALL THE SUBROUTINES WITHIN A SINGLE DISK FILE, BUT FOR
A VERY LARGE FILE SUCH AS <PLOT>, THERE MAY BE SEVERAL PREFIXES.  FOR
EXAMPLE, THE PREFIXES TO BE FOUND WITHIN <PLOT> ARE

          KON   CONTOUR PROGRAMS FOR FUNCTIONS STORED IN AN ARRAY
          PLT   SUBROUTINES SERVICING THE CALCOMP PLOTTER
          PVI   SUBROUTINES FOR COLOR COMPOSITES OR PARTIAL VIEWS
          VIS   SUBROUTINES INVOLVING THE SUPPRESSION OF HIDDEN LINES

     TO FORM A LABELLED COMMON FOR A SUBROUTINE CATEGORY XXX, PREFERENCE
WILL BE GIVEN TO THE NAME /XXX/.  SO FAR THERE IS NO DEFINITE RULE FOR
LABELLING MORE THAN ONE COMMON WITHIN A PROGRAM CATEGORY.  THE GUIDING
PRINCIPLE IS THAT CONFLICTING COMMON LABELS BETWEEN DIFFERENT PROGRAM
CATEGORIES THAT MIGHT BE LOADED SIMULTANEOUSLY SHOULD BE AVOIDED.

     THE MOTIVE FOR RESTRICTING PROGRAM NAMES TO FIVE LETTERS IS PARTLY
TO ENSURE COMPATIBILITY WITH IBM 1130 FORTRAN, AND PARTLY BECAUSE THE
COMBINATION OF 7-BIT ASCII AND 36-BIT WORD LENGTH IN THE PDP-10 IMPLIES
THE STORAGE OF A FIVE CHARACTER NAME IN A SINGLE FORTRAN VARIABLE.

     THE SUFFIX YY IN A SUBPROGRAM NAME CONSISTS OF TWO MOST SIGNIFICANT
LETTERS IN A WORD OR SHORT PHRASE DESCRIBING THAT SUBPROGRAM.  SOMETIMES
A LITTLE INGENUITY IS NEEDED TO AVOID DUPLICATION AND STILL TO GIVE THE
ABBREVIATION A HIGH SIGNIFICANCE VALUE.  WHEN A CATEGORY BECOMES SO VERY
CROWDED THAT ONE'S INGENUITY IS TAXED BEYOND ENDURANCE, IT IS PREFERABLE
TO OPEN UP A NEW CATEGORY AND REARRANGE THE FILE TO TAKE ADVANTAGE OF
THE NEW OPPORTUNITIES.

     ALTHOUGH THE STRUCTURE XXXYY SEEMS AT TIMES TO BE STRAINED, OUR
EXPERIENCE REVEALS THAT IT IS PREFERABLE TO THE USE OF POPULAR NAMES OR
ADJECTIVES WHEN A VERY LARGE NUMBER OF PROGRAMS HAVE TO BE NAMED IN A
REASONABLY SYSTEMATIC WAY.  IT IS PARTICULARLY UNDESIRABLE TO USURP FOR
LIBRARY USE THOSE FAMILIAR NAMES, SUCH AS "COPY," WHICH ARE TEMPTING TO
USE BUT BY NO MEANS HAVE A UNIVERSALLY AGREED MEANING.  IT IS EQUALLY
POINTLESS TO MAKE WHOLESALE USE OF THE NAMES OF FLOWERS, HINDU DEITIES,
GIRLS, OR EVEN OBSCENITIES IN A DIVERSITY OF FOREIGN LANGUAGES, IF THE
OBJECTIVE IS AN UNDERSTANDABLE AND ORGANIZED NOMENCLATURE.

     THE SYNTAX OF A FORTRAN REPLACEMENT STATEMENT PLACES THE VARIABLE
WHICH IS MODIFIED FIRST IN A LINE OF CODE, TO THE LEFT OF AN EQUAL SIGN.
USING THIS MODEL, ALL ARGUMENTS OF A SUBROUTINE WHICH ARE MODIFIED BY
THAT SUBROUTINE ARE TO BE LISTED FIRST, FOLLOWED BY ANY ADDITIONAL
VARIABLES WHICH ARE NOT MODIFIED.  OF COURSE, IN A FUNCTION SUBPROGRAM,
NO MODIFICATION OF VARIABLES IS PERMITTED, AND ONLY UNMODIFIED VARIABLES
REMAIN.  IF THERE IS SOME LOGICAL ORDER, EITHER THE CHRONOLOGICAL ORDER
OF THEIR MODIFICATION OR SOME TRADITIONAL ORDER IN WHICH THEY WOULD BE
ENUMERATED, THIS ORDER SHOULD BE FOLLOWED IN LISTING THE ARGUMENTS IN A
SUBROUTINE CALL.
     FORTUNATELY THIS CONVENTION IS COMPATIBLE WITH THE ORDER IN WHICH
F40 SAVES AND UNSAVES THE VARIABLES IN A SUBROUTINE CALL, BUT IT IS NOT
COMPATIBLE WITH STRETCH FORTRAN, FOR EXAMPLE.  COMPATIBILITY BECOMES A
SERIOUS ISSUE WHEN THERE ARE REPEATED ARGUMENTS IN A CALL STATEMENT.
IF THERE ARE REPEATED ARGUMENTS, AND THE SUBROUTINE MODIFIES THEM IN ONE
ORDER BUT THEY ARE RESTORED IN A DIFFERENT ORDER BEFORE RETURNING FROM
THE SUBROUTINE, THE NET EFFECT WILL PROBABLY BE DIFFERENT FROM WHAT THE
PROGRAMMER EXPECTED, AND EXCRUCIATINGLY HARD TO DEBUG.

     IT FURTHER SEEMS REASONABLE TO FOLLOW ARRAY NAMES BY ANY VARIABLES
DEFINING RANGES OF THEIR INDICES AND TO GROUP TOGETHER THOSE ARRAY NAMES
HAVING COMMON INDEX RANGES.  LIKEWISE, IF THE ELEMENTS OF THE ARRAY X
LIE BETWEEN THE LIMITS X1 AND X2, THE ORDER OF PRESENTATION X1,X,X2 IS
RELATIVELY EASY TO REMEMBER.

     VARIABLE NAMES SHOULD BE CHOSEN WITH THE SAME EMPHASIS ON THEIR
SYSTEMATIC AND MNEMONIC CONTENT AS ARE SUBPROGRAM NAMES.  SINGLE LETTERS
SHOULD BE RESERVED EITHER FOR VARIABLES WITH A UNIVERSAL SIGNIFICANCE,
SUCH AS N FOR AN ARRAY DIMENSION, OR FOR VARIABLES CONFINED TO THAT ONE
SINGLE PROGRAM, SUCH AS I AS THE INDEX VARIABLE IN A DO LOOP.  DEBUGGING
WITH TECO, AND ESPECIALLY REVISIONS AND REARRANGEMENTS, IS FACILITATED
BY NAMES WITH DOUBLE OR TRIPLE LETTERS, SINCE THEY ARE MORE LIKELY TO BE
UNIQUE.  HOWEVER, USING AS MANY AS SIX LETTERS TENDS TO MAKE THE PROGRAM
MORE CONFUSING, ESPECIALLY SINCE THAT MANY LETTERS ARE RARELY NEEDED FOR
CLEAR DISTINCTIONS BETWEEN VARIABLES.

     MANY SUBROUTINES HAVE EXTERNAL VARIABLES AS ARGUMENTS.  WHERE SUCH
ARGUMENTS OCCUR, THEY HAVE BEEN PLACED AT THE END OF THE ARGUMENT LIST.

     STATEMENT NUMBERS ARE ALWAYS ARRANGED IN INCREASING ORDER, AND ARE
GROUPED INTO RELATED SECTIONS.  WHEN THE SUBROUTINE IS RELATIVELY LONG,
THE STATEMENT NUMBERS ARE INTENDED TO SERVE AS AN INDEX TO SUBSECTIONS
OF THE PROGRAM.  FORMAT STATEMENT NUMBERS CONSIST OF FOUR DIGITS, AND
FOLLOW A MIXTURE OF NUMERICAL SEQUENCE AND REFERENCES TO THE READ OR
WRITE STATEMENTS WHICH INVOKE THEM.

     WE HAVE PREFERRED TO HAVE A LARGE NUMBER OF SUBROUTINES, EACH WITH
A SIMPLE AND CLEARLY DEFINED PURPOSE, TO HAVING A SMALLER NUMBER OF MORE
COMPLICATED PROGRAMS.  THIS TECHNIQUE UNDOUBTEDLY SUFFERS FROM A CERTAIN
OVERHEAD BECAUSE OF FORTRAN'S STYLE OF SAVING AND UNSAVING VARIABLES IN
SUBROUTINE CALLS, BUT OFFERS THE COMPENSATION OF MAKING THE PROGRAMMING
HIGHLY MODULAR.

     IT WAS DECIDED TO FOLLOW FORTRAN CONVENTIONS TO THE LETTER UNLESS
SOME STILL GREATER INCONVENIENCE RESULTED.  IN PARTICULAR, THE IMPLICIT
CONVENTIONS DISTINGUISHING REAL AND INTEGER VARIABLES HAVE BEEN RIGIDLY
OBSERVED, THE ONLY POSSIBLE EXCEPTION BEING THE SITUATION WHERE THE NAME
OF ITS CATEGORY WOULD CONFLICT WITH THE IMPLICIT TYPE OF A FUNCTION.
ALTHOUGH FORTRAN PERMITS EXPLICIT AND IMPLICIT TYPE DECLARATIONS, OUR
EXPERIENCE IS THAT THE USE OF SUCH OPPORTUNITIES IS TOO VULNERABLE TO
ERRORS ON THE PART OF PROGRAMMERS WHO DO NOT PAY ATTENTION TO THESE
TYPE EXCEPTIONS, WHO SIMPLY FORGET THEM, OR FIND VARIATIONS FROM ONE
SUBROUTINE TO ANOTHER TOO CONFUSING.

     MIXED MODE EXPRESSIONS HAVE BEEN SCRUPULOUSLY AVOIDED, AND ALL
TRANSFORMATIONS BETWEEN FIXED AND FLOATING POINT HAVE MADE EXPLICIT USE 
OF THE FUNCTIONS IFIX AND FLOAT.
     FOR SIMILAR REASONS, AND TO FACILITATE THE EXCHANGE OF THE <PLOT>
FILE WITH OTHER COMPUTER CENTERS, IT WAS DECIDED TO AVOID SOME OF THE
FANCIER EMBELLISHMENTS OF FORTRAN, SUCH AS NONSTANDARD RANGES OF INDICES
OR ARITHMETIC EXPRESSIONS DEFINING THE LIMITS IN A DO STATEMENT. EVEN SO
SOME INCOMPATIBILITIES HAVE BEEN REPORTED TO US.  SOME FORTRAN COMPILERS
WILL NOT ALLOW QUOTED LITERALS TO APPEAR WITHIN ARITHMETIC EXPRESSIONS,
BUT INSIST THAT THEY BE DEFINED WITHIN A DATA STATEMENT, OR OCCUR ON THE
TOP LEVEL OF THE ARGUMENT LIST OF A SUBROUTINE CALL.  NOT ALL COMPILERS
PERMIT A LOGICAL IF TO TERMINATE A DO LOOP.  SOME PROBLEMS OF DOUBLE
PRECISION HAVE ARISEN FROM MACHINES WITH LESS THAN A 36-BIT WORD LENGTH.

     SINCE MOST SUBROUTINES OCCUPY LESS THAN A PAGE OF LISTING, THEY
CONTAIN VERY FEW COMMENTS INTERSPERSED WITH THE FORTRAN CODE. THE SCHEME
OF DOCUMENTATION USUALLY EMPLOYED SIMPLY CONSISTS OF AN INITIAL SERIES
OF COMMENTS, NAMELY THE FOLLOWING:

          [THE MNEMONIC PHRASE GIVING THE SUBROUTINE ITS NAME]
          AN EXPLANATION OF THE PURPOSE OF THE SUBROUTINE
          AN EXPLICIT IDENTIFICATION OF EACH ARGUMENT
          [THE LAST DATE ON WHICH MODIFICATIONS WERE MADE]

     THE IDENTIFICATION OF ARGUMENTS SHOULD BE COMPLETE AND EXHAUSTIVE.
IN PARTICULAR, ALL RESTRICTIONS ON RANGES OR TYPE SHOULD BE GIVEN.  IF
THE ARGUMENT DEFINES A SWITCH, THE MEANING OF EACH ALTERNATIVE SHOULD BE
STATED.

     THE DATE ASSOCIATED WITH A SUBROUTINE IS THE DATE OF THE LATEST
MODIFICATION, ALTHOUGH CHANGES IN COMMENTS ALONE DO NOT ALWAYS JUSTIFY
A NEW DATE.  THIS IS THE CLOSEST APPROXIMATION TO VERSION NUMBERS AND
UPDATE NUMBERS TO BE FOUND IN OUR DOCUMENTATION.

     THE BRACKETS USED IN THE COMMENTS ARE IMPORTANT, SINCE TECO USES
THEM IN AUTOMATIC INDEXING AND ABSTRACTING.

     A NEAT ARRANGEMENT OF THE DECLARATIONS COMPRISING A PROGRAM HAS
CONSIDERABLE MERIT, ALTHOUGH WE HAVE NOT GONE SO FAR AS TO DELINEATE
THE RANGES OF DO LOOPS BY INDENTATION. A PARTICULARLY USEFUL CONVENTION,
FROM THE POINT OF VIEW OF TECO EDITING, HAS BEEN TO WRITE CALL.XXXXX
TOGETHER WITH SUBROUTINE..XXXXX, WHERE . DENOTES A BLANK, AND XXXXX IS
THE SUBROUTINE NAME.  THE PAGE CONTAINING THE SUBROUTINE DEFINITION CAN
BE FOUND QUITE RAPIDLY, BECAUSE THAT IS LIKELY TO BE THE ONLY PLACE
WHERE TWO BLANKS PRECEDE THE SUBROUTINE NAME.


1.3  GRAPHING CONVENTIONS

     THE CALCOMP CONVENTIONS REGARDING THE ORIENTATION OF THE COORDINATE
AXES HAVE ALREADY BEEN DESCRIBED.  THE X-COORDINATE LIES UPWARD OVER
THE DRUM,  WHILE THE Y-COORDINATE EXTENDS TO THE LEFT, BOTH SEEN WHILE
STANDING IN FRONT OF THE PLOTTER.  THEY ARE ONLY NEEDED WHEN ONE OF THE
PLOTTER SUBROUTINES IS TO BE CALLED.  ALL OTHER <PLOT> SUBROUTINES USE A
HORIZONTAL PAGE FORMAT, BUT THERE IS STILL A WIDE VARIETY OF SCALES AND
ORIGINS WHICH CAN BE EMPLOYED.

     THE SUBROUTINES PLTMC AND PLTMS WHICH ACTUALLY MAKE PEN MOVEMENTS
ASSUME THE PAGE CENTER TO BE THE ORIGIN, AND USE A SCALE OF INCHES.
     IT IS TYPICAL OF THE CONTOURING PROGRAMS THAT THE FUNCTION VALUES
ARE PRESENTED IN AN ARRAY, AND THAT THE IMPLIED COORDINATES MAY NOT BE
NECESSARILY CARTESIAN.  AMONG THE COORDINATES AVAILABLE ARE SPHERICAL
POLAR, TRIANGULAR, ELLIPTICAL, AND PLANAR POLAR COORDINATES.  IT IS
NECESSARY TO STANDARDIZE THE RANGES OF ALL THESE VARIABLES, INCLUDING
THE CARTESIAN COORDINATES, TO MAKE ALL THE PROGRAMS WHICH PROCESS THEM
INTERCHANGEABLE.  A REASONABLE CHOICE SEEMS TO BE THE UNIT INTERVAL,
(0.0 .LE. X .LE. 1.0).  HOWEVER, THIS IMPLIES CIRCULAR MEASURE AND NOT
RADIAN MEASURE FOR ANGLES, BESIDES BEING SLIGHTLY INCOMPATIBLE WITH THE
RECTANGULAR FORM OF THE PLOTTER PAGE EVEN FOR CARTESIAN COORDINATES.
STILL, IT IS THE CONVENTION ASSUMED BY THE MAJORITY OF PROGRAMS NOT
DIRECTLY INVOLVED WITH PEN MOVEMENT; SPECIFICALLY, IT IS ASSUMED BY THE
CONTOURING AND HIDDEN LINE PROGRAMS.

     FURTHER TRANSFORMATIONS OF ORIGIN AND SCALE ARISE WHEN SEVERAL
DRAWINGS ARE TO BE PLACED ON THE SAME PAGE; FOR EXAMPLE A CONTOUR PLOT
IS TO BE PLACED AT THE BOTTOM OF THE PAGE AND A PERSPECTIVE DRAWING AT
THE TOP, OR TWO HALVES OF A STEREOPAIR ARE TO BE PLACED SIDE BY SIDE.


1.4  ERROR DETECTION AND RECOVERY

     AS TIME GOES ON AND MORE USER EXPERIENCE ACCUMULATES WE WILL MOST
LIKELY INCREASE THE AMOUNT OF TESTING FOR POSSIBLE ERROR SITUATIONS. AT
PRESENT MOST RELIANCE HAS BEEN PLACED UPON WRITING STRAIGHTFORWARD CODE
WITH THE EXPECTATION THAT IT WOULD BE LESS ERROR PRONE.  ALTHOUGH THE
PROTECTION AFFORDED BY THIS STRATEGY IS RELATIVELY MODEST, IT IS BY NO
MEANS NEGLIGIBLE.

     DIMENSIONS OF ARRAYS ARE REGULARLY CHECKED, PARTICULARLY THOSE USED
IN HIDDEN LINE SUBROUTINES, TO AVOID EXCEEDING THEIR LIMITS.  NO OVERT
MESSAGES ARE WRITTEN, BUT AUTOMATIC INCREMENTING OF INDICES TERMINATES.
WHEN THAT HAPPENS IT PRODUCES SOME CHARACTERISTIC ABERRATIONS IN THE
DRAWINGS, CERTAIN BLANK AREAS, WHICH ONE SOON LEARNS TO RECOGNIZE. THREE
YEARS OF OPERATING EXPERIENCE, WITH DATA ARRAYS OF A MAXIMUM DIMENSION
OF 100 X 100, HAS APPARENTLY LEAD TO AN ADEQUATE BALANCE BETWEEN DATA
ARRAYS AND WORKING ARRAYS.  A DIMENSION OF 700 FOR THE LATTER SEEMS TO
SUFFICE.  FOR A DIFFERENT ARRANGEMENT OF ARRAY SIZES SOME ADJUSTMENT
WOULD PROBABLY HAVE TO BE MADE.

     MOST GRAPHING SUBROUTINES CHECK FOR THE NUMBER OF POINTS WHICH THE
GRAPH WILL CONTAIN, EXITING IMMEDIATELY IF THE NUMBER IS NEGATIVE, ZERO,
OR ONE.

     THE HIDDEN LINE SUBROUTINES PRESENT NUMEROUS OPPORTUNITIES FOR
FLOATING DIVIDE CHECKS, PARTICULARLY SUBROUTINES WHICH USE COORDINATES
WHICH CAN PRODUCE VERTICAL LINE SEGMENTS, OF WHICH POLAR, ELLIPTICAL AND
SPHERICAL ARE TYPICAL. THE SUBROUTINE MOST VULNERABLE TO SUCH ERRORS WAS
VISLI, AND FOR A LONG TIME A TEST FOR ZERO DENOMINATOR WAS PROGRAMMED
INTO IT.  SUCH A TEST INCREASED THE RUNNING TIME OF THE HIDDEN LINE
SUBROUTINES APPRECIABLY, BUT HARDLY EVER ENCOUNTERED A ZERO DENOMINATOR.
FINALLY IT WAS ABANDONED.  SOME OCCASIONAL SPURIOUS LINES APPEAR AS A
RESULT, AS WELL AS SOME CLOSURE IRREGULARITIES IN THE CRITICAL REGIONS.
SUBROUTINES WHICH CALL VISLI ARE OBLIGATED TO AVOID INTERVALS OF ZERO
LENGTH, EITHER THROUGH THE PROGRAM LOGIC OR BY EXPLICIT TESTING.
     SOME BALANCING IS AFFECTED BY THE WORD LENGTH OF THE COMPUTER.  IT
IS IMPORTANT THAT THE EPSILON USED IN VISSL IS LESS THAN THE SQUARE OF
THE EPSILON USED IN VISBO, WHICH IN TURN IS DETERMINED BY THE RESOLUTION
OF THE PLOTTER.  A 36 BIT WORD LENGTH COINCIDES VERY NICELY WITH AN
INCREMENT OF 0.01" OUT OF A TOTAL OF 11".  32 BIT COMPUTERS REQUIRE SOME
VERY CAREFUL JUGGLING.

   A CONSIDERABLE AMOUNT OF MARGIN CHECKING IS DONE.  BESIDES BEING THE
ENTIRE REASON FOR THE EXISTENCE OF THE SUBROUTINES PLTMS AND PLTMC, IT
IS INCORPORATED INTO THE CONTOUR PLOTTING SUBROUTINES AS PART OF THEIR
SEARCH STRATEGIES.


1.5  "GLOB" ANALYSIS

     THE INTERRELATIONSHIPS BETWEEN THE PROGRAMS OF THE <PLOT> FILE IS
USEFUL TO KNOW, AND FORTUNATELY IS AVAILABLE THROUGH THE USE OF A PDP-10
MONITOR PROGRAM KNOWN AS "GLOB," GLOBAL ANALYSIS.  WHEN APPLIED TO ANY
RELOCATABLE BINARY PROGRAM, IT PRODUCES A LISTING OF THE GLOBAL SYMBOLS
TOGETHER WITH THEIR RELOCATABLE ADDRESS, SUBROUTINES IN WHICH THEY ARE
DEFINED, AND ALL THE SUBROUTINES WHICH MAKE REFERENCE TO THEM. AMONG THE
GLOBAL SYMBOLS ARE THE SUBROUTINE NAMES, FORTRAN LIBRARY FUNCTIONS OR
SUBROUTINES WHICH ARE CALLED, AND COMMON LABELS.  THE GLOB LISTING ALSO
MARKS THE STATUS, SUCH AS UNUSED, UNDEFINED, OR MULTIPLY DEFINED, FOR
EACH SYMBOL.

     IN APPENDIX 2 IS REPRODUCED AN EXTRACT OF THE GLOB LISTING FOR THE
<PLOT> FILE, CONSISTING OF THREE COLUMNS CONTAINING THE GLOBAL SYMBOLS,
THEIR SITE OF DEFINITION, AND THE PLACES IN WHICH THEY ARE REFERENCED.
APPENDIX 2 CAN THEREFORE BE USED AS AN INDEX OF THE SUBROUTINES PRESENT,
AS WELL AS TO DETERMINE WHICH SUBROUTINES ARE CALLED BY OTHERS.  THOSE 
SYMBOLS WHOSE "DEFINED" COLUMN IS BLANK ARE MOSTLY FOUND IN THE FORTRAN
LIBRARY, ALTHOUGH THE PLOTTER SUBROUTINES ALSO HAVE THIS CHARACTERISTIC.

     IT SHOULD BE NOTED THAT PLOT.HLP IS NOT ALWAYS REVISED AT THE SAME
TIME THAT MODIFICATIONS ARE MADE TO THE <PLOT> FILE, SO THAT THE GLOB
LISTING IN THE APPENDIX MAY BE SLIGHTLY OUT OF DATE.  IT IS MARKED WITH
THE DATE ON WHICH IT WAS LAST REVISED, FOR PURPOSES OF COMPARISON WITH
DATES OF SUBROUTINES IN THE <PLOT> FILE.  OF COURSE, USERS OF THE PDP-10
AT SALAZAR MAY GENERATE THEIR OWN GLOB LISTINGS FROM PLOT.REL WHENEVER
THEY WISH.


1.6  DEMONSTRATIONS

     OVER THIRTY DEMONSTRATION PROGRAMS ARE AVAILABLE, ALTHOUGH THEY ARE
NOT INCLUDED IN THE <PLOT> FILE ITSELF.  MOST OF THEM ORIGINATED IN THE
DEVELOPMENTAL PHASE OF VARIOUS SUBROUTINES, FOR DEBUGGING AND CHECKING
SPECIFICATIONS.  HOWEVER, THEY COVER A VARIETY OF TYPICAL APPLICATIONS,
AND MAY BE STUDIED TO GAIN FAMILIARITY WITH THEIR ARGUMENTS, OR HOW TO
GENERATE SUITABLE DATA FOR THEM.

     SINCE THEY ARE NOT PART OF THE NORMAL CONTENTS OF <PLOT> THEY ARE
ABSTRACTED IN APPENDIX 3. IT SHOULD BE NOTED THAT THESE ABSTRACTS MAY
NOT ALWAYS BE UP TO DATE, SINCE CONTINUAL MODIFICATIONS ARE ALSO BEING
MADE IN THE DEMONSTRATION PROGRAMS.  THE DEMONSTRATION PROGRAMS FOLLOW
THE SAME DOCUMENTATION STANDARDS AS THE <PLOT> SUBROUTINES, SO THAT
DISCREPANCIES CAN READILY BE DETECTED BY COMPARING DATES.