The UNIX CD Bookshelf/OREILLY_TUCB_UNIX_CD.iso/upt/examples/SOURCES/IPL/PART01.Z/PART01

Text File | 1998-07-24 | 32.6 KB | 1,059 lines

Subject:  v21i032:  2D graphic system with table beautifier, Part01/14
Newsgroups: comp.sources.unix
Approved: [e-mail]
X-Checksum-Snefru: eda626f5 fdf50b5e ae715bc8 9011af1b

Submitted-by: Steve Grubb <uunet!lsr-vax!scg>
Posting-number: Volume 21, Issue 32
Archive-name: ipl/part01

[  Yes there are many shar files, but the size is small.  -r$ ]

ipl    a 2-D graphic production system with table beautifier

Version 1.0, January 1990.
  This directory contains the sources and examples for ipl,
a 2-D graphics production system.  It produces scatterplots,
lineplots, bargraphs, range displays, pie graphs, U.S./Canada
maps, schedule charts, boxes, arrows, text, etc.  Produces
Postscript or Sunview output, based on a user-supplied control
file.  Included are a gallery of several dozen examples.
Also includes:
  [] A table beautifier which is useful for taking plain text
tables, spreadsheet output, etc. and setting in a nice font.
  [] A low-level subroutine library for producing nearly equivalent
graphics (with shading) on Postscript and Sunview.

There are 14 shar files of 20-35 KBytes each.

    Steve Grubb
    uunet!lsr-vax!scg

# ipl part01
#    This is a shell archive.
#    Remove everything above and including the cut line.
#    Then run the rest of the file through sh.
#---------------------- cut here -----------------------------
#!/bin/sh
# shar:    Shell Archiver
#    Run the following text with /bin/sh to create:
#        README
#        src/Makefile
#        Cover
#        Introduction

mkdir src bin tplates examples

cat << \SHAR_EOF > README
ipl    a 2-D graphic production system with table beautifier

Version 1.0, January 1990.
  This directory contains the sources and examples for ipl,
a 2-D graphics production system.  It produces scatterplots,
lineplots, bargraphs, range displays, pie graphs, U.S./Canada
maps, schedule charts, boxes, arrows, text, etc.  Produces
Postscript or Sunview output, based on a user-supplied control
file.  Included are a gallery of several dozen examples.
Also includes:
  [] A table beautifier which is useful for taking plain text
tables, spreadsheet output, etc. and setting in a nice font.
  [] A low-level subroutine library for producing nearly equivalent
graphics (with shading) on Postscript and Sunview.

 Developed on a SPARC machine (Solbourne 5/600) running SunOS 4.0, with
Sunview and Apple Laser-writers.  Also verified on Sun-3.
 I won't be able to send fixes or answer mail after 2-28-90.
For anyone interested in converting to this XView-- sunview code is
contained in one file only: sunv.c.

Written by:     Steve Grubb
        Johns Hopkins University School of Medicine
        550 North Broadway, 9th Floor
        Baltimore, MD 21205  USA



TO VIEW THE SUNVIEW EXAMPLES: Do the following:
    cd examples
    demo.sipl
TO PRINT THE POSTSCRIPT EXAMPLES: Do the following:
    cd examples
    demo.pipl
TO READ ONLINE DOCUMENTATION: read the "Introduction" file
TO PRINT A COPY OF THE USER'S GUIDE: Enter run.manual
TO PRINT A COPY OF THE EXAMPLES GUIDE: Enter run.examples

TO INSTALL:
     Uses ~ 1116 blocks after building.
     Root permission is not required.
     Run the shell script run.install, which will:
        build an install.h file
    do a "make" on the contents of the src directory
     Executable will go in ./bin.
     You will have to create links in a "real" bin:
    cd /usr/local/bin  (or whatever)
    ln -s $d/bin/ipl tipl   # postscript
    ln -s $d/bin/ipl sipl   # sunview
    ln -s $d/bin/ipl vipl   # interactive annotator
    ln -s $d/bin/pipl pipl  # postscript to lpr(1)
    ln -s $d/bin/nicetab nicetab  # the table beautifier

TO MODIFY CODE:
     If IPL has already been installed and you are modifying
     code in the src directory, just do a "make".


SHAR_EOF
############################

cat << \SHAR_EOF > src/Makefile
# Makefile for IPL source    1-21-90 scg
#
#

IPL_OBJ = areadef.o areadress.o arrow.o bargraph.o boxplot.o \
distribution.o draw.o errorbars.o exit.o \
getdata.o initialize.o legend.o \
lineplot.o map.o nicetab.o page.o pie.o \
point.o polygon.o proc_call.o rangebar.o rect.o \
text.o vbargraph.o vector.o vrangebar.o

GRAPHIC_OBJ = graphic.o

PICK_OBJ = dataclick.o get_point.o pick.o siplmenu.o viplmenu.o

GDP_OBJ = main.o gget.o constraint_check.o util.o

DRIVER_OBJ = sunv.o iplps.o pcode.o

LIB_OBJ = lib.o


# Use the following when Sunview is not available..
# LIBES = -lm
# ipl: $(IPL_OBJ) $(GRAPHIC_OBJ) $(GDP_OBJ) $(PICK_OBJ) pcode.o iplps.o $(LIB_OBJ)
#    cc $(IPL_OBJ) $(GRAPHIC_OBJ) $(GDP_OBJ) $(PICK_OBJ) $(DRIVER_OBJ) $(LIB_OBJ) \
#      $(LIBES) -o ../bin/ipl

# Use the following when Sunview is available..
LIBES = -lm -lsuntool -lsunwindow -lpixrect
ipl: $(IPL_OBJ) $(GRAPHIC_OBJ) $(GDP_OBJ) $(PICK_OBJ) $(DRIVER_OBJ) $(LIB_OBJ)
    cc $(IPL_OBJ) $(GRAPHIC_OBJ) $(GDP_OBJ) $(PICK_OBJ) $(DRIVER_OBJ) $(LIB_OBJ) \
      $(LIBES) -o ../bin/ipl

$(GRPAHIC_OBJ) $(IPL_OBJ) $(GDP_OBJ) : ../install.h
$(GRAPHIC_OBJ) : graphic.h
$(GRAPHIC_OBJ) : graphic.x
$(GRAPHIC_OBJ) : graphic.d

$(IPL_OBJ) $(PICK_OBJ) : ipl.h
$(IPL_OBJ) $(PICK_OBJ) : ipl.x
$(IPL_OBJ) $(PICK_OBJ) : ipl.d
$(IPL_OBJ) $(PICK_OBJ) : graphic.h
$(IPL_OBJ) $(PICK_OBJ) : graphic.x
$(IPL_OBJ) $(PICK_OBJ) : graphic.d

$(GDP_OBJ) : gdp.h
$(GDP_OBJ) : gdp.x
$(GDP_OBJ) : gdp.d

map.o : mapdata.h
areadef.o nicetab.o : areas.h
sunv.o : shading.h
SHAR_EOF
############################

cat << \SHAR_EOF > Cover

        ______________________________________________________

                IPL Graphics Utility


                   Version 1.0, Jan. 1990

                     USERS GUIDE
        ______________________________________________________



            This guide contains the following:


        [] Manual pages for ipl and nicetab

        [] Introduction paper

            I.     Introduction
            II.     Control Files
            III.     The Graphics Environment
            IV.     Data Analysis Considerations
            V.    Postscript and Sunview Drivers
            VI.    Adding and Customizing
            VII.    NT graphics primitives library


        [] Template listings: Each IPL procedure has a template
          which defines every implemented parameter, its data type,
          and its default value if any.

        [] Example control files and graphic output.
SHAR_EOF
############################

cat << \SHAR_EOF > Introduction
_______________________________________________________________________

ipl(1)                                                      ipl(1)


NAME:
    ipl - a 2-D graphics production system


SYNOPSIS:
    pipl controlfile [arg2 arg3.. argN]
    tipl controlfile [arg2 arg3.. argN]
    sipl controlfile [arg2 arg3.. argN]
    vipl controlfile [arg2 arg3.. argN]


DESCRIPTION:
    Produces 2-D graphics, based on a user-supplied controlfile,
    on Postscript and Sunview devices.  Arg2.. argN are optional,
    and will be substituted into the control file at $2, $3, etc.

    There are four different commands which are all really links
    to the same executable:
    pipl - emits Postscript and sends it directly to lpr(1);
    tipl - emits Postscript on standard output;
    sipl - draws graphics under SunOS sunview(1);
    vipl - allows interactive placement of text, arrows, boxes,
        etc. under SunOS sunview(1).

    Ipl produces scatterplots, lineplots, bargraphs, range displays,
    pie graphs, U.S./Canada maps, schedule charts, boxes, arrows,
    text, etc.  There is also a text table beautifier.  Field-
    oriented plot data (separated by white-space) is expected.
    You can run the demo shell scripts (see below) to see for
    yourself.

    Often, graph development is done as follows:
    - Copy an existing control file.  A number are supplied as
    examples (see EXAMPLES, below);
    - Edit the control file in a text editor.  It is helpful to
    have template listings while doing this;
    - Display using sipl if you have access to a workstation
    running sunview, or pipl otherwise;
    - Add annotations using vipl;
    - Print using pipl or tipl.

    All files are located within the source distribution directory.
    Your system administrator can tell you where this is.


FILES:
    ./Introduction   - user information
    ./tplates/[A-Z]* - templates for all graphics functions


EXAMPLES:
    ./examples/demo.sipl ./examples/demo.pipl - demos
    ./examples/*.g   - control file examples


AUTHOR:
    Steve Grubb, Johns Hopkins University School of Medicine

_______________________________________________________________________

nicetab(1)                                                  Nicetab(1)


NAME:
    nicetab - a text table beautifier


SYNOPSIS:
    nicetab tablefile [btextsize areaname ttextsize]


DESCRIPTION:
    Takes a text table (as produced in a text editor or by a
    program) and attempts to set it up in a nice font.  Shading
    and rulings can also be added.  Your finished table will get
    sent to the printer.

    Tablefile is the file containing the text table.  The three
    optional arguments must either all be given, or all omitted.
    They are: btextsize (text size of table body in points); areaname
    (predefined IPL area name, see Areadef template); and ttextsize
    (text size of title in points).

    Nicetab is handy for obtaining publication quality tables
    quickly, without having to set up for tbl(1).

    This is really a shell script which invokes pipl and gives
    it a control file, and exists for convenience.

    Things work best if you use two or more blank lines to
    separate the title from the body; and use two or more spaces
    to separate different cells on a row.  See the IPL Nicetab
    template for more information.

FILES:
    ./tplates/Nicetab - ipl template

EXAMPLES:
    All files are located within the source distribution directory.
    Your system administrator can tell you where this is.

    Try the following:
        cd ./examples
        nicetab table10


_______________________________________________________________________


INTRODUCTION

  IPL is a program which produces two-dimensional graphics, for data

analysis and presentation.  It is written in C under SunOS 4.01 (Unix),

and produces similar displays on Postscript printers or under Sunview.

  Its design goals include: good presentation-quality output, a rich set of

features and user-controllable parameters, and a simple, intuitive user

interface.  IPL is intended for any Unix environment where Postscript

printers are available.  If Sunview is available, development time (and

paper use) can be reduced by using the Sunview previewer.

  Any number of plots and tables can be combined or overlaid on a page.

Many graphic details can be controlled if desired-- however, many

come with defaults, so that a decent looking plot can be composed

quickly, with a minimum of specification.


TO TRY:

  Go to the directory where IPL was installed.  To find out what this

directory is, look at the end of this Introduction, where it should be

listed as the last in the installation history.  Enter: "cd examples".

You can now run a series of pre-made examples (on the laser-printer) by

entering the command "demo.pipl".  Beware-- this will run several dozen

pages worth of examples, and may tie up the printer for a while.  If you

are at a Sun monitor running Sunview you can view the examples there, by

entering "demo.sipl".  Press return to see each graph.  The examples

can be run individually also.

  The files here which end in .g are the control files which produce

the examples.  Perhaps the easiest way to get started is to copy some

of these control files to your working directory and change them to suit

your requirements.  Then run them using either the "pipl" command (for

laser printer) or the "sipl" command (for Sunview), as described below.




THIS "INTRODUCTION" DOCUMENT:

  The document includes I) this introduction; II) a description of the

parameter files you use with IPL;  III) a description of the graphics

environment; IV) data analysis considerations; V) differences between

the Sunview previewer and Postscript output; VI) customizing IPL;

VII) the NT graphics primitive library.


GENERATING A USER'S GUIDE:

  The complete User's Guide contains additional material.  To generate a

User's Guide, go to the IPL directory (see above) and execute "run.manual".

A large set of examples can be generated by executing "run.examples".

Again, each of these will generate several dozen pages of printed output.



NOTICE:

  All code in the distribution directory has been placed into the public

domain and may be freely redistributed, as long as the following remains intact:

IPL Version 1.0 Jan. 5, 1990.  Copyright 1990.  Written by:

    Steve Grubb
    Wilmer Clinical Trials and Biometry
    Johns Hopkins University School of Medicine
    550 North Broadway #900
    Baltimore, MD 21205

Use of any IPL code in products developed for profit is not allowed.

  No responsibility will be assumed for the correctness or completeness of this

software nor results or consequences suffered as a result of installing or

using this software.  Users are entirely responsible for the correctness of

their results.  The data in the examples is completely fictitious.  Good luck!



BUGS:
|
| Lineplots using the stairstep option and not starting at the x minima
| may go wild.
|
| Nicetab shaded blocks sometimes cover up bits of text descenders.
|
| On the Sunview previewer text appearance and size are just an approximation
| of the Postscript result.  Same for shading darkness.
|

II. CONTROL FILES

  Control files are the files which tell IPL what to do.  They are supplied by

the user and made using the editor.  They could also be generated by a

program.  All the .g files in the examples directory are control files.

GENERAL FORMAT: The general format for these files is:

|        Proc Procname:
|          Parametername:    value
|          Parametername:    text
|                    more text
|          Parametername:    value
|
|        Proc Procname:
|          Parametername:    value
|          Parametername:    value
|            ...etc


SYNTAX: An attempt has been made to make the syntax easy and intuitive to

use.  Blank lines and spacing (as long as there is at least one blank or

tab) are optional and a matter of style.  Capitalization of proc and parameter

names is required, as are the colons.  The word "Proc" is required at the

beginning of each procedure specification.  Note that text parameters may

use one of more lines.  Paramters that are lists must be contained on one line.



PROCS: Within the control file are one or more "procs".  Each proc performs

an isolated function:


| Procedure    Function is:
| --------        ----------------------------------------------
| Areadef     setting up a current graphics area on the page, including
|           scaling, axes, subtitles, etc;
| Bargraph     producing a bar graph;
| Boxplot    producing a Tukey box distribution representation;
| Distribution  producing a scatter plot or bar distribution;
| Draw        producing miscellaneous lines and rulings;
| Errorbars    producing error bars;
| Getdata     specifying plot data source and reading data;
| Lineplot     producing a line plot;
| Legend    adding a legend;
| Map         producing a United States / Canada map and state distributions;
| Nicetab    beautifying tables;
| Page         specifying page title, paper position, and global parameters;
| Pagebreak    force a page eject;
| Pie        produces pie graphs
| Polygon    drawing miscellaneous outlined and/or shaded polygons;
| Rangebar    distribution representations in Y
| QuitAppend    suppress final page eject so subsequent runs can be appended;
| Text        adding labels, blocks of text, etc.;
| Vbargraph    producing a vertical bar graph (same as bargraph above
|        except that bars go from left to right);
| Vector        produces vector or arrow displays
| Vrangebar     same as Rangebar but bars go from left to right.
|

  The procedures are executed in the order given.  A suggested sequence

would include "Page" to set up the page title, then "Getdata" to read in

some data.  Then, for every graphics area (window) on the page, "Areadef" to

set up a area to draw or plot in, then finally Bargraph or another of the

above to produce graphics within that window.


PROC TEMPLATES: The proc templates (located under "tplates" in the distribution

directory) define the set of viable parameters, along with data types, default

values, and English language descriptions.  There is one template per proc.

It is helpful to have listings of these templates with you when you work.



PARAMETERS: Most procs have some parameters.  In your control file, you may

specify as many parameters as you wish; those left unspecified will default

to the value shown in the template.  Next to the parameter's name in the template

file is its data type.

| Parameter data types used in IPL control files:
|
|                          Data type              Sample legal value
| Class:                    --------------------       --------------
| numeric range            n to m, e.g. 0 to 5    2
| any number             number            3.1415
| a set                {center,left,right}    left
| a data field number        dfield            3
| character size         charsize        6
| a shade (0 to 1)        color            0.9
| a font name            font            /Helvetica
| a word             token            hello
| an (x,y) coordinate pair    coordpair        3.55 2.00
| free form text         text            Hello world,
|                            Are you there?

Sometimes, a parameter's data type entry in a template will be followed by

a modifier in parentheses, such as (list10) which indicates that a list of

up to 10 items of the given type will be expected; or (M) which indicates

a mandatory parameter.  Other modifiers exist but are used internally.


  COMMENTS are indicated by making the first non-white-space character on

the line a '#'.  Everything following will be ignored by the processor.


  COMMAND LINE ARGUMENTS can be substituted into the parameter file as

parameter values using the '$' followed by argument number.  $1 will

become the first argument string, $2 the second, etc.  Since the parameter

file is usually the first command line argument, the first usable command

line argument will be the second, which can be accessed using $2.  The

'$' operator cannot be mixed with other text, e.g. "Subtitle: $1 Study"

is not allowed.  Example:     pipl "Number of Books Read" "During 1990"

                Subtitle:    $2
                        $3


  CLONING: The "Saveas" and "Clone" parameters, which are available

for all procs, can be used to save and load environments to and from

files, meaning that only parameters that differ need to be specified again.

See examp12.g, in the examples.   Because of implementation limits,

"Clone" and "Saveas" can not be used in the same proc.


  COMMON USER MISTAKES: Among the most common of user errors is the

mis-spelling of a parameter name (the parameter will be ignored silently!!),

omission of a colon, etc.  Make sure that any colons (:) that appear in

continuation lines of parameters are preceded with a backslash (\).

Be sure that the Areadef parameters Xticfmt and Yticfmt are appropriate

for your data range-- for example if your Y range is from 0 to 1, you

have to set Yticfmt to %4.1f.  Note that if you misspell a Postscript

font name or use a negative linewidth, chances are you won't get any

laser printer output.  When doing bar graphs be sure that the

Areadef parameter Xstart.0or1 is set to 1.  Other mistakes to avoid are:

inconsistencies or extraneous matter in the data fields; not defining

scaling or scaling increment properly; or giving a wild text, token,

or list value.




III. THE GRAPHICS ENVIRONMENT

  COORDINATE SYSTEM is always in inches, with the origin (0,0) in the lower

left corner (a slight margin may exist).  Graphics areas are rectangles

on the display or page whose dimensions are specified in inches.  The user

can specify desired scaling within the graphics area, which becomes the

DATA coordinate system, since it is often set up to fit some data.  The

raw inch units described above are the ABSOLUTE coordinate system.

  TYPE can be of varied size and font.  Size is expressed in point sizes.  In

the templates, any parameter ending in "size" refers to a character size.  Gen-

erally, normal size is 10 to 12 point, with 8 point becoming small and 13

tending to be fairly large.  A point is equal to approx. 1/72 inch.

Paramters ending in "font" allow you to select a font by name from

available Postscript fonts.  Postscript font names start with a slash

(/).  The available fonts vary from printer to printer, but usually

the following are available:

|  /Helvetica
|  /Helvetica-Oblique
|  /Helvetica-Bold
|  /Helvetica-BoldOblique
|  /TimesRoman
|  /Times-Bold
|  /Times-Italic
|  /Times-BoldItalic
|  /Courier
|  /Courier-Oblique
|  /Courier-Bold
|  /Courier-BoldOblique
|  /Helvetica-Narrow
|  /Helvetica-Narrow-Oblique
|  /Helvetica-Narrow-Bold
|  /Helvetica-Narrow-BoldOblique
|  /Symbol

  POINTS can generally be marked by the use of a point symbol.  There are a

number of pre-defined symbols which can be accessed using the word "sym"

followed by a digit, indicating the shape, and a lower-case letter,

indicating the style.  For example, "Mark: sym1f" will produce lightly

shaded, outlined, triangles in Proc Distribution.  A display of available

shapes and styles is included in the examples.

  LINES can sometimes be controlled in regards to line thickness and dash

pattern.  Any parameter ending in "linethick" will allow you to set the

line thickness.  A value of "1" is usually the default, with lower values

producing thinner lines, and higher values producing thicker lines.  Any

parameter ending in "linetype" will allow you to set the dash pattern of

lines.  A linetype of "0" produces a solid line.  For the dash patterns

and their linetype numbers see the accompanying example (example0.g).

Any parameter ending in "Magnify" will allow you to control the density

of the dash pattern, if a dash pattern is being used.  A smaller number

will cause more repetitions of the pattern to be drawn within any given

segment, while a higher "magnify" value will have the opposite effect.

"3" is a normal value for "magnify".

  SHADING can be specified by parameters ending in "..shade".  The

range of values is normally 1.0 for white to 0.0 for black.  The number of

gradients actually available depends on the printer hardware, but should

be at least eight.



IV. DATA ANALYSIS CONSIDERATIONS

   IPL follows the Unix philosophy in that incoming data is assumed to be

newline-terminated records containing data items delineated by white space

(spaces or TABS).  For plotting purposes, these items are recognized as

"fields", beginning with field 1, up to the default maximum of 24 fields per

record.  The default maximum number of records is 1000.  The default number

of characters allowed in a field is 20.  The Getdata proc

is used to read in data from a file, or Unix command pipeline.  Data can

also be defined in the parameter file itself.  Data fields can be numeric,

alphabetic, or special characters.  Getdata includes joining, appending,

and field selection capabilities.

  Plotting procs access data by field number, e.g. "Field: 3".  An effort

has been made for the plotting procs to handle non-numeric data fields (such as

missing codes) gracefully.



V. POSTSCRIPT AND SUNVIEW DRIVERS:

  Although ideally they should produce identical output, there are

some differences in the graphical output that is produced by the two

drivers.  Most of these are due to the resolution capability of the

hardware-- while laser printers offer 300 dots per inch or better,

the standard Sun screen is about 64 dots per inch.  This effects the

quality of shading and fonts rendering.  In general, the Sunview

displayer should be used as a previewer, then the output should

be finalized on the laser printer, with particular attention paid to

text.


  "..WINDOW NOT PASSED IN ENVIRONMENT": If you see this or a similar

message when starting sipl or vipl, it is because of a Sunview bug

which occurs when you do an "su -" to another UID and then try to

create a window.


  CHARACTER FONTS: The laser-printer driver uses high resolution

Postscript fonts.  The Sunview driver uses the fixed-width fonts

supplied with Sunview, which are available for most (but not all)

point sizes.  It tries to use the "cour.b" (Courier bold) series,

but may use other styles for certain point sizes.  Some point

sizes may not be available at all, in which case the closest available

size will be used.  When this happens, things may not line up the

same way that they will on the laser printer (such as blocks of text).

Also, since the graphics are scaled to the window size (while characters

are rendered at an absolute size), changes in the window size can also

cause discrepancies in output.  IPL expects the Sunview fonts to be in

the directory /usr/lib/fonts/fixedwidthfonts.

  IMPORTANT: The Sunview driver does not display characters running

vertically (such as the Y axis identifying label).  They are handled normally

by the Postscript driver.



  SHADING: The shading on the Sunview driver has been set up to correspond

closely to the equivalent Postscript shading, however it is coarser and

some shades contain visible patterns of pixels, again because of the lower

resolution available.   Currently the Sunview driver works on standard,

gray-scale, and color displays, but does not exploit the gray-scale or

color capabilities.



  EPS CONSIDERATIONS: An attempt has been made towards making the Postscript

code generated by IPL compatible with the EPS guidelines.  All units are standard

1/72 inch units, and each page is preceded by a save and followed by a restore.

The code does however, contain "showpage" commands which cause the page to get

printed and ejected.  These should be filtered out (i.e. with sed(1)) before

combining with other images.



VI. ADDING AND CUSTOMIZING:

  It is possible to modify the graphics code, or add additional procedures
to IPL.  It is also possible to use the NT low-level graphics library
in your own software.  The NT graphics library is a collection of routines
which produce equivalent graphic output on Postscript and Sunview.

To add or modify a procedure do the following:

1) Write (modify) the C subroutine to perform the desired function, using
the NT low-level graphics calls.  It should be put in the ./src directory,
unless there is a good reason to do otherwise.  Pipl emits Postscript
code on standard output-- so make sure any messages you generate go to
standard error.  The header "ipl.x" should be #included.  The NT graphics
calls are macros and can be found in ./src/graphic.d.
   Wherever a parameter is needed, use the gget() routine, and create a name for
the parameter, such as "File".  For example, suppose we are writing a (trivial)
procedure for removing a file.
    Remove( )
        {
        char fname[60];
        gget( fname, "File" ); /* retrieve the "File" parameter value
                    and place it in variable "fname" */
        unlink( fname );
        }
The routine gget() will get the file name from the user's control file, or if
not found there, it will check the default template file.
   The first letter of proc names should be capitalized.

2) Add (modify) the template for your procedure to the directory ./tplates.
Give the template the same name as your subroutine.  All parameters used in your
subroutine must have an entry in the template.  Also, the parameters "Saveas" and
"Clone" must be present.  Check some of the other template files to get the
idea.  For our example:
|
| Proc Remove:
| File:        token    :    : file to be removed
| Saveas:    token    :    : for saving parameter set
| Clone:    token    :    : for loading parameter set
| #
| # This will remove the given file.
|
Since IPL 1.0 uses compile-time information instead of the template files,
the following must by done: 1) Add the template information to ./gdp/template.h;
2) Update the indexes in ./gdp/template.h (each integer corresponds to number
of lines in the respective template); 3) Make sure that the template information
in ./template.h matches the information in the template file, since the latter
is what users will go by.

3) Add a line to ./src/proc_call.c. so that your subroutine will be invoked:
| ...
| else if( strcmp( proc, "Draw" )==0 ) Draw( );
| else if( strcmp( proc, "Polygon" )==0 ) Polygon( );
| else if( strcmp( proc, "Pagebreak" )== 0 ) { NTshow(); NTpaper( 0 ); }
| else if( strcmp( proc, "Remove" )==0 ) Remove();  /* <<<-------  */
| ..etc

4) Update the Makefile, and do a make.

5) Test by making a small control file and running:
|
| Proc Remove:
| File: temp
|

6) Document what you did in the ./src/README file.


To use the NT graphics library in other software:

1) Make sure ./src/graphic.h or ./src/graphic.x are #included in your source
files.

2) Be sure to call NTinit( d ) early in your program to initialize the system.
The argument to NTinit() should be 't' for Postscript or 's' for Sunview.


VII.  The NT low-level graphics primitive library

  This collection of subroutines can be used by other software for producing
graphics.  The object files sunv.o, iplps.o, pcode.o, and graphic.o must be
included at load time.  The header file "graphic.x" must be included in your
C source files.
  There are two kinds of units: Absolute units are equivalent to inches, with
the origin in the lower-left; Data units are set up by the user.
  Shaded areas are done as in Postscript-- by defining a "fill path" consisting
of a number of points, then shading the polygon defined by those points.


NTinit( dev )
char dev;
  This initializes the system based on the type of display device.  Currently
't' and 's' are supported--  't' causes Postscript output to be emitted (on
standard output), while 's' causes graphics to be generated under sunview.

NTpaper( x )
double x;
  This sets paper orientation (0.0 = portrait, 1.0 = landscape).

NTmov( x , y )
double x, y;
  Moves "current position" to the given absolute location.

#define NTlin( x , y )
double x, y;
  Draws a line to the given absolute location.

NTpath( x , y )
double x, y;
  Includes the given absolute location in the current fill path.

NTshade( x )
double x;
  Fill the current fill path with shade x.  X should be from 0.0 to 1.0.

NTtext( s )
char s[];
  Generate text in the current font, size, and direction, starting at the
current location.

/* center text between current location and a point w ABSOLUTE units away in the current text direction */
NTcentext( s , w )
char s[];
double w;
  Centers text between the current position and a point w absolute units away
in the current text direction.

NTrightjust( s, w )
char s[];
double w;
  Right justify text bewteen current location and a point w ABSOLUTE units
away in the current text direction.

NTfont( s )
char s[];
  Set current font to s.  S must be a Postscript font name, must start with
a '/', and must be available on the printer being used.  This must be called
before producing text.

NTptsize( x )
double x;
  Set the current character size to x.  X is in points (approxomately 1/72 inch).

NTchardir( x )
double x;
  Set the current text rendering direction to x.  X is in degrees counter-clockwise.
Zero degrees is normal, i.e., horizontal.  Note that anything other that 0 will
not show up under sunview.


/* select line attributes-- dash pattern string, line width, dash magnifier  */
NTlinetype( s, x, y )
char s[];
double x, y;
  Sets current line drawing attributes.  S is the dash pattern ("0" through "8",
see the IPL legend example), x is the line width (default is 1.0), and y is the
dash pattern magnification factor (default is 3.0).

NTnormline()
  Resets line drawing attributes to a "normal line", i.e. all defaults.

NTshow()
  Ejects page (printers).  Clears screen (sunview).

*** The following are used for setting up a user data space ***

setscale_x( xlow, xhi, datalow, datahi )
double xlow, xhi, datalow, datahi;
  Sets up data units in x, for an area from absolute location xlow to xhi, scaled
from datalow to datahi.

setscale_y( ylow, yhi, datalow, datahi )
double ylow, yhi, datalow, datahi;
  Sets up data units in y, for an area from absolute location ylow to yhi, scaled
from datalow to datahi.

NTm( x , y )
double x, y;
  Move to the given point in data units.

NTl( x , y )
double x, y;
  Draw a line to the given point in data units.

NTp( x , y )
double x, y;
  Add the given point (data units) to the fill path.

double da_x( d ) Translate the given data x location to absolute x.
double da_y( d ) Translate the given data y location to absolute y.
double ab_x( d ) Translate the given absolute x location to data x.
double ab_y( d ) Translate the given absolute y location to data y.
yymm_to_i( m ) Translate the given yymm (year/month) location to integer.

*** The following can be used for interactive mouse-oriented applications ***
*** See ./src/pick.c for more information. ***
getpick( rtn, proc, new, draw )
get_event( x, y, e )
get_string( s, p )
get_text( buf, p )
get_string_box( s, p, x1, y1, x2, y2 )
get_text_box( s, p, x1, y1, x2, y2 )
get_text_box_tp( s, p, x1, y1, x2, y2 )

*** Misc. ***
NTbatch_on() These invoke batching which increases efficiency.
NTbatch_off()


INSTALLATION HISTORY:
--------------------
011990 IPL installed on helios at: /usr/home/550/pub/src/ipl_1.0
012290 IPL installed on helios at: /usr/home/550/pub/src/ipl_1.0
012290 IPL installed on helios at: /usr/home/550/pub/src/ipl_1.0
012290 IPL installed on helios at: /usr/home/550/pub/src/ipl_1.0
SHAR_EOF
############################