Gold Fish 3/goldfish_volume_3.bin/files/text/print/hwgpost/readme.first

Text File | 1995-09-18 | 20.2 KB | 532 lines

HWGPOST is not PD or 'free' SW!
*******************************

Users of previous HWGPOST versions, please note: This text has changed in
some places. Please read it again.


What is this?
=============

What you get here is the seventh version of HWGPOST that is publically
available. It is still rather raw. My intention is to abuse you as beta
tester. ;^)

HWGPOST is project that I started because I had some problems with
post.library 1.7 (and 1.86 where post.library stayed the same) not
handling some PostScript code correctly. So I built on the post 1.7
source. HWGPOST is IMHO a major step towards PostScript Level 2
already and as time and motivation permits it will hopefully become a
R&W book compliant PostScript Level 2 interpreter library with maybe
some Display PostScript extensions.

Currently this archive is probably mostly useful to users of
post.library up to 1.7 or users of applications like AmigaTeX which
rely on post.library.


Major new features for HWGPOST beta 7
=====================================

    - No longer math rounding errors due to different application
      math standards. MAJOR CHANGE!
    - The interpreter now has its own process. MAJOR CHANGE!
    - Improved datatype screen mode setting.
    - enumfonts.ps for easy font installation.
    - more compatibility hacks for lousy fonts.
    - A _very_ simple, no thrills, untested B&W PRTPS: handler. It
      depends on a working PIPE: to conserver memory. So you might
      want to get HWGQueue.lha from Aminet to replace the broken C=
      queue-handler in any OS version up to and including 3.1.

Sorry, setsystemparams and setpagedevice still have to wait.


Requirements
============

OS:      >=V37 (= KS2.04)

Memory: As much as possible. HWGPOST tends to need noticeable more
        memory than post.library 1.7 for complex PostScript files. You
        should have at least 2MB to have fun with it.

HD:     Suggested


Compatibility
=============

HWGPOST should be compatible to all applications using post.library
version 1.7 with the exception of the "callextfunc" and some other
special non standard operators, e.g. I have found no problems with
PostView. If you have any compatibility problems, please report them
to me.

    AmigaTeX

        The AmigaTeX postscript files installPSfont.pro, and pstopk.pro (in
        TEX:ps) contain redefinitions of the "findfont" operator. If you
        comment out these definitions and replace the init.ps, AmigaTeX
        works well with HWGPOST.


Legal stuff/Distribution/bla
============================

I need to explain something first. I started out with the post 1.7
sources by Adrian Aylward. He did an amazing job with post up to
and including 1.7. I do not claim to have put it all together
myself from the the very first byte. But I have thrown out or
reworked almost every single line of it and there is not much left
that is not replaced or truly unchanged. Adrian Aylward set up many
useful concepts. I reworked most of them and threw some out
completely for going towards PostScript Level 2.

While it may not look so from the outside, HWGPOST is a major step
away from its origins, and so I claim the right to have something new
here. Note that I did not take over any code from other sources than
post 1.7 except for some fixes to post 1.7 that people sent me (Thanks
especially to Tom Rokicki for his fixes and other unrelated things).
No GNU code, no IBM code, nor anything else. To be honest, I tried to
look at some ghostscript code once for a particular feature, but I
found it so ugly that I threw it out faster than you can say "out" (I
never even found the code for the feature I was looking for). This
means, that all that you read in the history file is only related to
my work.

***************************************************************************
    Because of all the above, there will be different rules on HWGPOST
    that start out right _now_ even with this beta version:
***************************************************************************

    - Unlike with post 1.7, I am restricting use somewhat:

          For use in other products, commercial or not, or claims of
          compatibility to HWGPOST to enhance the value of a product, you
          need to contact me first to work something out.

          (Except for Tom Rokicki. He may use HWGPOST whenever he
           finds it acceptable for AmigaTeX)

    - If you are just a user of HWGPOST, consider it Giftware. I like
      money, too, but it doesn't have to be money. Anything nice will
      do. Books, A3k-Accelerator/Networking boards, Ax000s, HDs, SW,
      non technical things, whatever. If you intend to use HWGPOST and
      forget about me intentionally, don't expect any support or bug
      fixes.

    - If you want to use HWGPOST commercially (e.g. to make money by
      using it in your office), I feel that you should consider this
      very fact when thinking about a gift. If you think HWGPOST to be
      good enough to support you making a living, you should value it
      as such.

    - This archive may be distributed only free of charge. It may
      not be modified or ripped apart without my permission.

!!  - ANY USER OF HWGPOST IS REQUIRED TO REGISTER the use of HWGPOST
!!    with me via email or smail.
***************************************************************************

All (important) rights reserved, so to speak. This is currently a
private undertaking for fun, but I have not yet lost hope that there
is maybe some reward in it for me, too. :-)

If you don't like the above, I don't want you to use HWGPOST. In fact
I dare to declare use of HWGPOST then outright illegal. You should
live with post 1.7 or something else then.

Oh well, if you are one of those using pirated [KS/WB] SW, don't
bother asking for help. I won't help you and I specifically _don't_
allow you to use HWGPOST either in this case.

Some legal mumbo jumbo I should not forget: "PostScript" is copyrighted by
Adobe Systems Incorporated.

If I forgot to point to any other important trademarks or copyrights, it is
not out of malice, but just an oversight. Please point it out to me and I
will correct it for the next public release. All
trademarks/copyrights belong to their owner and should be
respected.


Why this beta?
==============

A lot of stuff is in place within HWGPOST already even though it is
probably still far from completion. Actually it is so much that I hope
to find bugs with your help now. I do not have test cases and
PostScript files anymore to test all that PostScript Level 2. You will
read some "untested" comments in the history file. I have checked for
basic functionality with all my changes, but nobody knows where the
bugs hide yet. So I am asking you for bug reports to make HWGPOST get
better.

I am interested in:

    - Enforcer hits, mungwall problems, reproducable crashes
    - deviation of behaviour compared to Adobe Level 2 products
    - _Short_ and precise PostScript example files that break with HWGPOST

and I need your complete computer and OS configuration with any bug
report including any non C= WB things that you run like
MagicMenu/ReqTools/CpuBlit.

I am also interested in a short note if you have files using specific
Level 2 features available with HWGPOST that _don't_ break.

Thank you for your help!


************************
* Common Problems, Q&A *
************************

This will evolve into a list of problems people run into that are
definitely not bugs in HWGPOST.

    Problem: PS files fail because the name "SymbolEncoding" is not known.

    Solution: Throw out the "Symbol" font you have, buy the Adobe Type
              Manager and/or install a working Symbol font. You are
              using a Symbol font that violates Adobe PostScript specs
              by relying on an external definition of SymbolEncoding.
              This name does not exist in the standard. Your current
              Symbol font is broken.


    Problem: A font does not work right or causes errors.

    Solution: Have you preregistered it correctly in HWGPOSTResources? If
              you depend on the PATH_FONT feature, is the file name truly
              correct including case? Have you double checked?

              NOTE: If there is a bug with a font, I will need the font
                    to fix it. If it is a commercial font, you have to
                    smail me one legal copy for my own use if I don't
                    have it already. I won't and can't buy fonts just
                    to get your problems fixed.


    Problem: A PS file causes "undefinedresource" errors.

    Solution: The most likely cause is that a font could not be found.

              Depending on your setup do some of this:

                - Check what fonts are needed (by reading the PS file
                  or checking on the font search with a tool like
                  SnoopDos)

                - If you don't have the font, you need to get it.

                - Check if the HWGPOSTResources entry is correct if
                  applicable.

                - Check if ENV:HWGPOST/PATH_FONT is set up correctly
                  if applicable.

                - Set /@DefaultFontName (as in init.ps) to a default
                  font name of your choice. Of course this font must
                  exists!

              Always remember that _file_names can be changed,
              PostScript _font_names must match.

    Problem: The error "page size not set in preferences" pops up.

    Solution: You need to run the "PrinterGfx" prefs editor and set
              the limits to something other than "Ignore or
              "Multiply".


    Problem: I got new type 1 fonts and it is a a hassle to set
             them up in HWGPOSTResources. Is there some easy way?

    Solution: Yes. Copy your new fonts into PSFONTS:. Then do the
              steps outlined below.

              - Run the frontend and the C:sort command

                post init.ps enumfonts.ps >t:allfonts
                sort t:allfonts t:sortedfonts

              - Now check t:sortedfonts and HWGPOSTResources for
                duplicate fonts or fonts that you don't want to have
                installed.

              - Insert whatever is left of t:sortedfonts into your
                HWGPOSTResource file.

              That's it. If it doesn't work then, it's most likely
              the font or the document that is broken.


    Problem: I only get dots printed instead of letters.

    Solution: Quite likely you don't have the font needed
              installed. At least it isn't installed correctly. So
              HWGPOST reverts to its default setting of a dummy dot
              font. This default setting is done in init.ps.
              it can be changed of course. Check which fonts are
              needed with e.g. the SnoopDos tool and install them
              as described above. This should get you going.


    Problem: Somehow I can't find the right solution to my problem
             here. What should I do?

    Solution: I admit that the documentation is not that great.
              You get what you pay for. ;^) Search through the
              "History" file as well. Among all the technical stuff
              you'll find quite a few hints on how to do things
              right. If even this doesn't help, just send some
              email.


What should a bug report look like?
===================================

I prefer bug reports created with the C= 'report' tool. You can find
this tool on Fish Disk 920. Any bug report _must_ contain step by step
instructions to reproduce the bug on a standard WB setup. Telling me "You
need to install this pack of special OS hacks to make the bug appear or
those non standard libraries from somewhere" usually leads to no result. If
it is a bug related to a PostScript program, I'd need a short example
program to reproduce it. If the bug is dependent on the exact layout of the
program (e.g. with eexec problems), you should think about using lha and
uuencode to preserve any spaces, tabs, newlines, or other special
characters in the file that might otherwise be lost in email.

_AN_ABSOLUTE_MUST_ is the output of C:VERSION FULL (or a version
comment in the file or printed in a window if C:VERSION does not yield
useful results) _and_ C:LIST for any program involved. This includes
but is not limited to:

    - The OS (Use ShowConfig)
    - The frontend (post, postband, postview, etc)
    - The library post.library
    - The support files init.ps, HWGPOSTResources
    - For printing, the printer driver

If you don't give me this information with each bug report, I might
decline to look at it.

Oh, and please don't swamp me with hundreds of kilobytes of email
without asking first. Thank you.


What is included?
=================

    - README.FIRST      (This file)

    - post.library      (Using C= IEEE libs for all Amigas)

    - post.library.20   (Compiled for >=68020 using inline coprocessor math)

    - History           (Informal overview on the changes since post 1.7)

    - init.ps           (A new init.ps. You _will_ have to use it)

    - HWGPOSTResources  (Example declaration of available external
                         resources, e.g. fonts. Referenced by init.ps)

    - PATH_FONT         (Example file to demonstrate automatic font lookup
                         by the resource mechanism. This should be copied
                         into a directory "ENV:HWGPOST".)

    - postlib.h         (The include file with some infos on how to use
                         new features of HWGPOST)

    - hwgpostlib.doc    (Docs on how to use the programmers interface of
                         HWGPOST for your own programs)

    - post              (A hacked up post 1.7 frontend to try out HWGPOST.
                         Nothing fancy)

    - devs/datatypes/PostScript
    - devs/datatypes/PostScript.info
    - devs/datatypes/PostScriptBIN
    - devs/datatypes/PostScriptBIN.info

                        (The datatype descriptor files for >= OS 3.0.
                         To be placed into DEVS:datatypes)

    - classes/datatypes/HWGPOST.datatype

                        (The datatype for >= OS 3.0. To be placed into
                         SYS:classes/datatypes)

    - devs/dosdrivers/PRTPS
    - devs/dosdrivers/PRTPS.info

                        (Driver files for >= OS 2.1 to mount the PRTPS:
                         handler. To be placed into DEVS:DosDrivers)

    - l/prtpost-handler (The PRTPS: handler itself. To be placed into L:)



Don't ask me for my sources. Currently I have no plans whatsoever to
release them in full or part to anyone. After reading through the History
you might understand why.


Special note on the 'post' frontend
===================================

The included 'post' frontend is a major (ugly) hackup of the original
(ugly) source to suit my testing needs. It may or may not do what you
expect and it might or might not be compatible to the original 'post'.
Anything can happen. If you don't get the output you expect, please
send me a detailed bug report and fall back on PostView or the old
'post' frontend for now.

To get more information on the supported options try 'post ?' and type
another '?' at the command line template. For gray scale displays,
play with the MAXDEPTH option. On an A2024, 'MAXDEPTH=2' and
'DISPLAYID 0x41000' give rather nice results compared to the standard
B&W setup.

You won't be able to use your display HW to the fullest as the hacked
up frontend does not check the display database at all.


Special note on the HWGPOST.datatype
====================================

To make the datatype work, you need to have post.library available,
and an assign POST: to where init.ps is located for best results.

The datatype will render all PS files per default with 75 dpi in B&W.
If no BoundingBox comment can be found in the file header the data
type will currently default to an A4 page size (this might change
though). You should read the History file for now to find out what
kind of PostScript files the datatype will accept. Reading the History
file might not be a bad idea in any case.

You can override this behaviour by setting an environment variable.
These are the docs taken straight from the History file:

        - The datatype now optionally handles color displays,
          densities and other default sizes. How? Via a new
          environment variable: "ENV:HWGPOST/DATATYPECONFIG"

          The first line of this environment variable is evaluated in
          DOS ReadArgs() style with this template:

              COLORS/K/N,BPC/K/N,XDEN/K/N,YDEN/K/N,DENSITY/K/N,
              DEFWIDTH/K/N,DEFHEIGHT/K/N,MODEID/K

            COLORS:     Either 1 or 3. Only B&W or RGB supported!
            BPC:        Bits per color. Anything from 1 to 8. Note
                        that BPC*COLORS must be <= 8 or strange things
                        may happen due to the OS limit of 8 bitplanes.
            XDEN,YDEN:  Densities (dpi). Default is 75 dpi.
            DENSITY:    Convenience operator to set both densities.
            DEFWIDTH,
            DEFHEIGHT:  If no bounding box is specified in the file,
                        these values are used. You need to specify
                        them in units of 1/100 inch though, not in
                        1/72 inch like PostScript likes it. The
                        default values for these parameters will give
                        an A4 like bitmap size.
            MODEID:     A hex screen mode id (e.g. 41000 for an A2024)
                        to override the OS settings or the default
                        monitor.

           This environment variable should do the job for a while.

Note that the datatype will always display only the first page of any
file. This is intentional as there is no reliable, easy, or fast way
to render an arbitrary page.

I tested the datatype only with OS 3.1.


Special note on PSPRT:
======================

I haven't much to say about this one. If it works for you, fine. I
hacked it up as better test bed for my replacement queue-handler
quite a while ago even though the date doesn't show it. It might
not even work for you. Currently I see it as a major hack. There
are no config options whatsoever and is B&W only. Colour would eat
some amount of memory and it doesn't do strip printing. I included
a simple mount file for OS >=2.1 to be placed into DEVS:DOSDrivers.


Installation
============

0. Check out the "History" file. Even if you are not a PostScript
   wizard, there is probably useful information for you in there.

1. Save your existing post.library, init.ps, and post. HWGPOST might
   break your setup and I don't want you to be out in the cold.

2. I am sure you have the POST: and PSFONTS: assigns that are needed
   for post 1.7. If not, create them, and put all your type 1 fonts
   into PSFONTS: While neither assign is truly needed by post.library
   itself, they are a somewhat useful standard by now. The datatype likes
   to find init.ps in POST: and the default font lookup configurations are
   set up up for PSFONTS:.

3. Put init.ps, HWGPOSTResources, and (if you want to) post into POST:

3.1 Edit HWGPOSTResources for _your_ font setup in PSFONTS: You'll
    probably need to throw out and add some lines.

3.2 Put PATH_FONT into "ENV:HWGPOST". Edit it to suit your needs. For
    a permanent setup, copy it into ENVARC:HWGPOST, too!

4. Copy your choice of post.library[.020] into LIBS:

5. Shut down any running applications using post.library and do an
   "avail flush".

6. If you run >= OS 3.0, you can install the datatype files. You might
   want to reboot after doing so to be on the safe side.

7. If you want to, you might want ot install the PRTPS: handler
   now. for OS 2.04, you'll need to hack up a mount file from the
   included driver file. Let mes suggest that you upgrade to 3.1.

8. Try HWGPOST and send me detailed bug reports with reproducable
   examples!


My TODO list
============

Well, lots of stuff as time permits:

    - Finish up Binary Object Sequences
    - User path operators
    - missing filters
    - device parameters
    - insideness operators
    - missing color spaces
    - rest of the Level 2 graphics stuff
    - VM garbage collection
    - whatever else is needed for a languagelevel of 2


My Address
==========

 *  Heinz Wrobel
 *  Karlstr. 16
 *  82131 Gauting
 *  Germany
 *  FAX [phone] (I don't like phone calls)
 *  <[e-mail]>

Have fun!

Heinz Wrobel