$VER: Post.texi V2.00 ©Christian Eibl

Post V2.00
**********

This file contains the documentation for Post V2.00, a PostScript viewer using the post.library.

Legal Stuff
***********

Disclaimer
==========

THERE IS NO WARRANTY FOR THIS PROGRAM TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHERE OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Copyright
=========

The original Post (up to V1.7) came from Adrian Aylward which was slightly improved by Robert Poole (V1.86enh, plus a bugfix). Adrian did an excellent job and without his work Post V2.00 would not exist. Therefore I included his name although my version of post has almost nothing to do with his work as you can see browsing through the sources. I also kept Poole's name because it was actually Post V1.86enh I started with. But please keep in mind that the copyright of Post V2.00 and later fully belongs to me (see Author).

The GUI designed with GadToolsBox (© Jan van den Baard).

License
=======

Distribution is allowed in all forms, such as BB systems, floppy or compact disks, and ftp sites. Post may be freely distributed if:

  * no  more  then a  reasonable  fee is charged  for  copying or down-loading.

  * no file in this distribution is changed, added or removed.

  * the distribution is not part of a commercial product. In case you want to use Post in a commercial product get in contact with me (see Author).

Post is Giftware, it is not Public Domain! If you use Post longer than two weeks you have to send a gift to me (see Author)!

As the source is included everyone has the chance to improve Post. But please do not distribute your own version of Post 'cause this will end up in a chaos. Please send me your suggestions, improvements or whatever. I'll try to implement them and take your name in the history and acknowledgements. And of course you do not have to send a fee if you help to improve Post!

Giftware
========

If you use Post longer than two weeks you should send a gift to me (see Author). Of course I'd like money best but if you can't effort 100 ATS (15 DM, 10 US Dollar, please don't send other currency) or do not want to send cash by smail you should send me a gift that's worth 100 ATS (or even more :-). Eurocheques and postal money orders should be in ATS (Austrian Schilling) only, since otherwise the bank is the only one that takes profit out of it.

You have to send this gift only once for all versions of Post (no update fees)!

Furthermore all persons listed in (see Acknowledgements) do not have to send me any fee!

Acknowledgements
================

All persons listed here do not have to send me any fee 'cause they were involved in the history of Post or did me a favour with their projects:

  * First of all: Adrian Aylward and Robert Poole

  * Manfred Moser and all members of the AUW

  * Peter and Didi from ProSystem

  * Fred Fish and all other people working on ADE

  * Georg Heßmann (PasTeX)

  * All people that are working on dvips, SpecialHost and other TeX related things

  * Jan van den Baard (GadToolsBox, I hope he accepts that as a gift)

Author
======

     Christian Eibl
     Steyrergasse 40
     A8010 Graz
     Austria

     chris@fph.tu-graz.ac.at

Introduction
************

Post is a PostScript viewer using the post.library. The user can view PostScript documents on screen, print them on any preferences supported printer or create an IFF-ILBM file. It has a powerful CLI, Workbench and ARexx interface.

This documentation only provides information for the usage of Post. If you need information about the library, fonts and so on you have to rely on the documentation supplied with the library!

Features
========

  * Works on public screens, custom screens and even (some) graphiccards

  * Arexx port

  * Bandrendering

  * Both a Shell and Workbench interface

  * Keyboard and mouse control

  * ASL file and screenmode requesters

  * Uses OS 3.0 features like Pen-Sharing, ...

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

Post itself does not require much:

  * OS 2.0 or higher.

  * A post.library. The old post.library (V 1.7 © Adrian Aylward) or the new HWG post.library (© Heinz Wrobel) will do. Both are on the aminet (text/print).

  * An assign to the drawer where Post lives in.

But please keep in mind that the libraries tend to consume lots of RAM and CPU power.

Installation
************

Just extract the lha-file to a temporary drawer of your joice. I assume that you have an installed post.library (V1.7, © Adrian Aylward or HWG post.library, © Heinz Wrobel) and the version of Post that comes with it. If you want to keep this old version rename it. You might also want to make a backup of the file init.ps. Then copy all you want from the temporary post drawer to the old post drawer (the only thing that is not obsolete is Post :-), but I suggest to keep all files but the source drawer if you are not interested in the source) If you use hwgpost.library you MUST NOT copy the file init.ps. The version that comes with Post is only a bugfix for the one of Post V1.86enh. Copy the contents of the drawer envarc to envarc:. Delete the temporary drawer. Make an assign POST: to your post drawer if you don't already have one (best to do in the user-startup). That's all, Post should run now.

Usage
*****

CLI-Interface
=============

Post accepts many Options. Here is the template with description:

  * STARTUP-FILES/M: One or more startup-files to be used.

  * X-PAGESIZE=X/K/N, Y-PAGESIZE=Y/K/N, X-OFFSET=XOFF/K/N, Y-OFFSET= YOFF/K/N: The dimension and offset of the page.

  * X-DENSITY=XDEN/K/N, Y-DENSITY=YDEN/K/N, DENSITY=DEN/K/N: Density in x and y direction. Use DEN if you want to set both to the same value.

  * BW/S, RGB/S, CMYK/S: Color model to be used.

  * FONTMEM/K/N, HALFTONEMEM/K/N, VIRTUALMEM/K/N, LINEMEM/K/N: See documentation of the post.library.

  * BANDSIZE/K/N: see Bandrendering

  * IFF-FILE=IFF/K: If specified Post will save the PostScript file as an IFF-ILBM file. For example:

          IFF path/iff*.pic  : path/iff1.pic,  path/iff2.pic  ...
          IFF path/iff??.pic : path/iff01.pic, path/iff02.pic ...

     NOTE: IFF path/iff.pic genearates only one IFF-ILBM file that contains the last page.

  * PRINTER/S: Output will go to the printer. See Printing hints.

  * FILE/K: The PostScript file to display, print or save as IFF-ILBM file.

  * FROM/K/N, TO/K/N: see Bandrendering

  * NOFORMFEED/S, CENTERPAGE/S, PRINT-DENSITY=PRDEN/K/N: Print options.

  * TEMPPATH/K, BUFSIZE/K/N: Before a PostScript file is interpreted Post tries to split it (see Bandrendering). TEMPPATH specifies the path where the temporary files are stored (should be in RAM: for speed benifits). If you have to choose a disk as destination due to memory limitations BUFSIZE should be set to a higher value than 1024.

  * GRAPHICCARD/S: Sometimes it helps to work with graphiccards but costs one more bitplane (see Technical Info).

  * VERBOSE/S, CONWIN/S: Post will print out more messages if VERBOSE is specified. Output will go to STDERR if Post prints out a page or generates an IFF-ILBM file (useful for batch processing). Otherwise (or with CONWIN) output goes to the console window Post opens for I/O.

  * CUSTOMSCREEN/S, PUBSCREEN/K: Self explaining.

  * OPTFILE/K: Post will use this options file.

When Post is started it uses its default options, then searches for the options file (in ENVARC:) and then interprets options given in the command list. When you quit Post it stores the options for the next session (like Options Use). If you want to make things permanent just save the options before you quit.

WB-Interface
============

Post can be run by double-clicking on its icon or by clicking on the icon of Post and then double-clicking the icon of the file to be displayed. Following tooltypes are supported:

IFF, PRINTER, STARTUP-FILES, VERBOSE, NOFORMFEED, CENTERPAGE, CUSTOMSCREEN, PUBSCREEN, X, Y, BANDSIZE, XOFF, YOFF, XDEN, YDEN, DEN, PRDEN, BW, RGB, CMYK, FONTMEM, HALFETONMEM, VIRTUALMEM, LINEMEM, TEMPPATH, BUFSIZE, GRAPHICCARD.

See CLI-Interface for discription.

The Options Window
==================

See CLI-Interface for discription.

ARexx-Interface
===============

Post supports many ARexx commands (they are not case sensitive):

  * Window functions: OPENWINDOW, CLOSEWINDOW, WINDOWTOFRONT, WINDOWTOBACK, ACTIVATEWINDOW, ZIPWINDWOW, CHANGEWINDOWBOX left, top, width, height

  * Screen functions: SCREENTOFRONT, SCREENTOBACK, CUSTOMSCREEN, PUBSCREEN pubscrname

  * Scroll functions: LEFT n, RIGHT n, UP n, DOWN n

  * OPEN file, RUN file, LOADFONT font, CLEAR, INTERRUPT, KILL

  * Page control functions: NEXTPAGE, PREVIOSPAGE, GOTOPAGE n

  * Miscellaneous: QUIT, GETSTATUS, SETOPTS optfile

Every ARexx command not listed above is sent to the interpreter. Please see PostRexxDemo.rexx for more information.

Menus of Post
=============

They are self explaining (hopefully :-)

Keyboard features
=================

Besides the menu shortcuts Post also supports the following keys for scrolling and turning pages:

Scrolling within a page
-----------------------

You can scroll one line within a page with the cursur keys. Combined with the SHIFT key you can scroll 90% of the visible part of the page. Combined with the CTRL key Post scrolls to the borders.

Turning pages
-------------

With ENTER or + you can get to the next page, with BACKSPACE or - to the previous page. The scrollers will change their position by pressing the keys from the numeric keyboard. SPACE scrolls down 90% of the visible part of the page until the bottom is reached. Then the page is turned and you are at the top of the next page.

NOTE: You can only turn to lower pages if the file is successfully split into multiple pages.

Bandrendering
=============

Post supports bandrendering which means that a large page (an A4 paper at 360 dpi has about 3000x4000 pixels) is rendered in a series of bands (Post reruns the interpreter for each band). Therefore  printing is still possible on machines with few memory or in situations when there is no large memory block available. But the file has to be conformant with the PostScript file structuring conventions: There should be a prologue that is executed once at the beginning and a series of pages that can be executed independently (and maybe afterwards a trailer). The first line has to start with:

     %!PS-Adobe-

then follows the prologue. Each page is detected by:

     %%Page:

and the trailer begins with:

     %%Trailer:

If your file does not fit this structure you have to edit it by hand!

With TEMPPATH/K you can specify the drawer where the temporary files are stored (best place would be RAM: if you have enough memory) and with BUFSIZE/K/N you can specify the amount of I/O buffer.

You can use FROM/K/N, TO/K/N, Goto Page and Previous Page only if the file is successfully split!

Printing hints
==============

First you have to calculate the page size in pixels:

     width [in pixel] = width [in inch] * resolution [in dpi]

You will have to play with the XOFF / YOFF values and the size of the page until the printing output is placed right. POST.print is the options file I use for my BJ200 for printing with 360 dpi.

You should use the same resolution for rendering and printing a page (e.g. 180 dpi for the interpreter and 180 dpi for printing) but you don't have to. 180 dpi -> 360 dpi simply generates a printing of halve size. If you do not use a whole page you can specify NOFORMFEED to put multiple pages generated by the interpreter on one printed page or CENTERPAGE to center them.

Miscellaneous
*************

Support
=======

First of all: I am afraid I do not have enough time for Post! And nothing and nobody is perfect and maybe Post will never be bug free. But I will try to improve it and upload new versions to aminet. You can also ask me for help (best via email, please preface your header with POST). But as I have to finish my studies please don't mail bomb me with a problem you might solve yourself by thinking it over for a few more minutes :-)

If you found a bug please be sure it can be reproduced and include a detailed description (KS/WB version, CPU type, running commodities and other utilities ...)

Technical Info
==============

The source is split up in several files and almost not documented but there are many small functions that are self explaining. Post was compiled with gcc 2.7.2.1.

History
=======

When I first saw Post V1.86enh I was disappointed because of the poor CLI and Workbench interface, the missing ARexx-Port, the nasty GUI ... and after a look at ghostscript and PostView I decided to improve Post V1.86enh. But unfortunately the TODO list grew even faster on bottom than it was shrunk on top. Therefore, because of lack of time and because of my programming style (which caused lack of documentation) history is rather rudimentary up to Post V2.00 as you can see below :-).

History starts here:

  * Post V2.00: first public release

Known bugs
==========

  * Post complains that it can't get the colors on a pubscreen in CMYK mode although there are enough colors: this is no bug. Post tries to obtain colors with ObtainPen but the colors needed for CMYK on a pubscreen are obtained by the mouse pointer and therefore not free.

  * With HWG post.library the current directory cannot be changed and therefore files that are loaded via (files.ps) run, ... are not found.

  * Post uses the feature of the OS that a plane pointer with value -1 is interpreted like a plane with all pixels set. Some graphic cards do not support this and you have to specify GRAPHICCARD. Then a plane will be allocated and all pixels are set in it (needless to say that this is a waste of memory :-) But still some graphiccards don't work and I need help here 'cause I don't own one by myself!

To Do
=====

  * Localization

  * Better documentation

  * More graphic card support (I need some help here!)

  * More colors (I need some help here, too)

  * Installer script

  * Beautiful icons

  * ...