DrawHPGL is a program written in PostScript that aims to emulate a
Hewlett-Packard plotter.

This program and its documentation are copyright (c) 1990-1997, Alun
Jones & Texas Imperial Software.

Please read the note at the end of this file concerning control characters
in LaBel strings.

The commands expected to be supported in this version are:

AA - Arc Absolute - Draws an arc from the current point.
AF - Auto Feed - Closes drawing and feeds the page out.
AR - Arc Relative - Draws an arc from the current point.
CI - CIrcle - draws a polygon around the current point.
CO - COmment - ignores everything up to the next ; or \n.
CP - Character Plot - Moves by 'character' lines and columns.
CT - Chord Tolerance - Sets the chord angle's meaning (degrees/displacement)
DF - DeFault - resets all sorts of things.
DI - DIrection - sets the direction of printing.
DR - Direction Rotated - sets direction of printing, and rotates the font.
DT - Default Terminator - Sets the LB terminator (normally ^C)
EA - Edge Absolute - Draws a rectangle's edge.
ER - Edge Relative - Draws a rectangle's edge.
FT - Fill Type - Sets the fill method.
IN - Initialise - Resets all sorts of things.
IP - Input P1 and P2 (and change the font size if relative sizing is on)
IW - Input Window - Sets up clip region.
LB - Label - Outputs text.
LT - Line Type - Selects how lines are drawn.
PA - Pen Absolute - Sets draw mode to Absolute, and may move the pen.
PD - Pen Down - Puts the pen down, and may move it.
PG - PaGe feed - exactly the same as AF.
PR - Pen Relative - Sets draw mode to Relative, and may move the pen.
PS - Page Size - I think this selects the size of page in plotter units.
PU - Pen Up - Lifts the pen, and may move it.
PW - Pen Width - sets the width of lines in millimetres.
RA - Rectangle Absolute - Fills a rectangle's inside.
RO - Rotate - Shifts the direction of plot.
RR - Rectangle Relative - Fills a rectangle's inside.
SC - SCale - sets up scaling for subsequent plots.
SI - SIze - Sets character size.
SL - SLant - slants the text.
SP - Select Pen - Selects the pen colour
SR - Size Relative - Sets character size.


Current status of the commands:

Fully implemented (as far as I can tell):
AA, AR, CI, CP, CT, DF, DI, DR, DT, EA, ER, IP, IW, LB, LT, PA, PD, 
PG, PR, PS, PU, PW, RA, RO, RR, SI, SL, SP, SR

Partly implemented:
AF - I guess at the initialisations used after the page throw.
FT - User defined fills and shading don't do anything yet.
IN - Some initialisations have been commented out.
SC - Only scales anisotropically - only the first four arguments are used.

Any other commands will elicit a 'clean' response - in other words,
they will be ignored, but stored in the string InvalidString, which is
then printed as the last page.  If you want to add these commands
yourself, you are quite welcome to, although I would appreciate being
informed of any commands you feel this program should do.

Usage of DrawHPGL
=================

At its simplest level, DrawHPGL can be used by appending a plot file
to the end of the DrawHPGL code, and bumping the result out to a
PostScript printer (followed by a ^D if necessary).

e.g.
COPY HP19.PS+F18.PLT LPT1:

However, this is not possible if the plot file uses the LB (label)
instruction, since the default terminator for the label is a ^C
character, which most printers seem to mistake for external interrupt.
This causes them to stop immediately.

Because of this, I have written the file HPTOPS.EXE to convert the
HPGL file into something more useful.  HPTOPS.EXE should be run with
the following command:

HPTOPS <PLOT-FILE> <DrawHPGL-FILE>

e.g.
HPTOPS F18.PLT HP19.PS > LPT1:

and the PostScript output is produced to stdout.  The name of the
DrawHPGL-FILE in this release is hp19.ps, since it is version 1.9 of
DrawHPGL.  No version before 1.9 will work with this version of
HPTOPS.EXE, because of the way parameter reading has changed.

The HPTOPS.EXE program also does a fair job of removing most comments and
un-needed white-space from the PostScript file it creates.  The only
comments left in are inline ones.

The program assumes input is in A4 size.  To change the 'input size',
use the PS command, which tells DrawHPGL the size of the input area
in plotter co-ordinates.  This is then mapped into the current clip
path.  (The clip path is used instead of co-ordinates so that DrawHPGL
can be tinkered into producing EPS output.)
[Because the clip path is used, errors result from using GhostScript
with the -dNODISPLAY option.  Mind you, I'd not be surprised if I were
the only one using this option with DrawHPGL.]

Recommendation: before tacking an HPGL file onto DrawHPGL, run it
through a sed macro 's/%.*$//;/^$/d;s/^ *//' - it'll make the file
much shorter by stripping out comments and blanks.
Also, since most postscript printers barf on ^C characters,
please be careful when using the HPGL LB command.



Information useful in adding to DrawHPGL.
=========================================

DrawHPGL was my first ever PostScript program, and has grown quite a
lot since I first wrote it.  The intention was originally to have a
file that you could stuff to the printer, and it would emulate a
plotter until it received an end-of-file.  To an extent, I have
succeeded, in that the supported commands (as far as they are
supported) run as expected, unless a ^C character is sent to the
printer.  This means that the LB command does not work if stuffed to
the printer, unless the default terminator is changed by use of the DT
command.

The function called DrawHPGL is basically a parser, and all of that
parsing is done by HPTOPS.EXE when it is used.  For this reason,
DrawHPGL is not output to the printer by HPTOPS.EXE.  HPTOPS.EXE reads in the
entire DrawHPGL file in order to find which commands are 'known' by
DrawHPGL, so that it can give messages about unknown commands before
the printout is attempted.  HPTOPS.EXE can only do this if the first line
of any HPGL command's definition reads:

/?? {  %% HPGL function

where ?? is the name of the HPGL command to be emulated.

The current dictionary usage is around about 170, depending on which
commands are used.  This fits most dictionaries, but there are users
who have had problems in the past with the dictionary filling up.  I
think I've got over this now.

Every variable used attempts to have a person-readable name, and I
have tried to keep the comments up-to-date with the source code.
Obviously, I'd be glad to help if there are any parts not understood.


Information about HPTOPS.EXE
==========================

Source code for HPTOPS.EXE is supplied as HPTOPS.C.  HPTOPS.EXE was
compiled under the Microsoft C compiler, but should work with most
other major DOS compilers.  In addition, it compiles under UNIX, and
should work under most operating systems that run C.

HPTOPS.C isn't pretty - it was knocked up in a half-hour, and looks
like it.  I make absolutely no guarantees that it'll work in all
cases, but it seems fairly safe to me.  Don't winge about bad
programming, and lack of buffering - I know about it, but I can't be
bothered to fix it at the present.  It works as good as it needs to,
really.

It converts each command from the form :

??<parameters>;

to the form :

(<parameters>;)??

where ?? is the individual command.  The only exception to this is the
pen control commands.  PA, PD, PU, PR are all translated into a
command to set the appropriate boolean value (PenState Up/Down, and
Absolute True/False), followed by a sequence of PostScript commands of
the form:

<x> <y> DrawOrMove

This is done because (particularly on CAD files), a helluvalotta (TM)
pen commands tend to be sent per page.  This used to seriously overrun
the string storage space (which I'm told is pronounced Vee-Em).
Storing these as integers means they are removed from memory once
they're used.

HPTOPS.EXE also outputs a very rudimentary Encapsulated PostScript
style header at the top of its output.  Included with this is a
(commented-out) clip-path which matches the BoundingBox declared in
the header.  This was useful in testing, and may be useful for you.
As far as I know, this output complies with the Encapsulated
PostScript standard for any plotfile which contains only one page.
(EPS is a standard for describing one page of output so that it may
be included in other drawings)



WARNING - THERE IS NO WARRANTY EITHER EXPRESSED OR IMPLIED, TO COVER
THIS PACKAGE.  IT IS SUPPLIED AS-IS, WITH THE HOPE THAT IT MAY BE OF
USE.  NEITHER ALUN JONES, NOR ANY OF HIS PAST OR PRESENT EMPLOYERS,
ARE RESPONSIBLE FOR ANY LOSS OR DAMAGE CAUSED BY THIS PROGRAM.

If you find any bugs, please send me details - particularly if you
think you can fix it.  If you find any commands that aren't supported,
but that you would like to be, please tell me.  But if you can, please
check that the command is sensible on a printer - for example, any
requests for the VS (Velocity Select), or the NR (Not Ready) commands
will be met with ridicule.

Bugs already known about:

DT should allow a numeric second parameter. (atp, it ignores it).
Line Type 0 is definitely wrong - a special case needs to be made.
The other line types might be wrong, too.  On most printers, ^C is
interpreted as interrupt.  There is no way for me to work around this
- you will have to run your plot through HPTOPS if you use the LB
command with the default terminator.

If you use this program, or like it, or have any comments at all to
make, please mail me - I like user feedback.

email me at:

alun@texis.com

or SnailMail me at:

Alun Jones, 47 Sugden Road, Long Ditton, Surrey KT7 0AD, ENGLAND.
Alun Jones, 1602 Harvest Moon Place, Cedar Park, TX 78613-1419, USA
            +1 (512) 257 2578 - phone, 2579 - fax.
(The England address is a forwarding address)

This program is free for personal use only.  The copyright is owned by
Alun Jones of Texas Imperial Software, and this program has not been
released into the public domain.

If you distribute any part of this program, if you make a profit from
its use, or if you use any part of it in your work, please ask me
about licencing costs.  If you need this program altered, please ask
me about consulting rates.

Visit our web site at http://www.abol.com/texas/index.html


     IF YOU HAVE ENJOYED THIS PROGRAM, PLEASE TELL YOUR FRIENDS!!
     ============================================================
(And me)


Things which need still to be done:

Add functions SM, PM. (And others as time allows)
Add Poly buffer into the rectangles commands. (in preparation for PM)
Use in-built PostScript scaling to make the program run (a little) faster


Control Characters and Label Strings.
====================================

It has recently been discovered that different HPGL plotters do
different things when they encounter control sequences in LB commands.
All control characters are handled within the procedure /LBinternal in
this program, and to recreate the same text presentation as on the
plotter you wish to emulate, you may need to make tests.

The file lbtest.plt is provided for such a purpose.  It tests each
control character that the program currently knows about, so that you
can decide how to modify LBinternal.  You should get the following
printed out:

* - <CR> test - o and x should be superimposed.

* - <BS> test - o and x should be superimposed.

x
 o - <LF> test - o should be under and to the right of x.

 o - <VT> test - o should be above and to the right of x.
x

@x - <HT> test - the o should either:
1. be closer to the 1st x than the 2nd.
2. be eight characters after the first x,
but right next to the 2nd.

(The symbol * represents an o overprinted on an x, and the symbol @
represents an x with an o very close up to [and maybe overprinting]
it).

If the output differs from this, you will need to edit the LBinternal
function - there are instructions on how to do this in the LBinternal
function's comments.
