Postscript interpreter - README =============================== Post V1.4 Copyright Adrian Aylward 1989, 1991 This distribution was released as the archive file "post13.lzh", ??-???-90 Files in this distribution: README This file Post.info Icon file post User interface post.doc Documentation file postband Band printing driver postband.doc Documentation file postlj LaserJet printing driver postlj.doc Documentation file post.library Shared library for Amiga 500/1000/2000 post.library.2620 Shared library for Amiga 2500 etc. (68020/030, 68881/2) init.ps Standard postscript startup file icon.ps The postscript program that built the icon Source files (user interface only), for programmers: post.c User interface, C main program postband.c Band printing driver, C main program postlj.c LaserJet printing driver, C main program postasm.a User interface, assembler support postlib.h Library interface header postlib.doc Documentation file makefile Make file You will also need: arp.library Arp library, V39+ conman ConMan, V1.3+ You should find these on "All Good BBS's/disk libraries" I have tested Post under WorkBench V1.3 only. If you have 2.0 it should work, but you may need a more recent version of ConMan. You may also need to use the CONDEV option to use ConMan instead of the standard console handler. You will need at least a megabyte of memory. Even with a megabyte you will have not be able to generate a full page in colour on the screen. For high density printer output (A4 at 300 dpi.) you will need 2 megabytes! If memory is very tight, try running from the CLI, before workbench has been loaded. Before using Post you will need to copy the library (post.library or post.library.2620) into your libs: directory. If you have a 32 bit cpu (68020/030/040) and a floating point unit (68881/68882 or 68040) you can use the 2620 version of the library, which is compiled to use hardware floating point instructions and runs about twice as fast. Otherwise you must use the standard library - if you try the 2620 version it will refuse to open. Examples ======== The examples and demo programs are now being distributed separately. Look out for the file "psdemos1.lzh". (If you have the prerelease "post02.lzh" or one of the earlier releases there is no need to download them, as they have not changed significantly). The PostScript Language ======================= If you don't know any PostScript I recomend obtaining a suitable tutorial book. Try the "blue book" from Adobe: "PostScript Language Tutorial and Cookbook" Adobe Systems Incorporated, Addison-Wesley 1985, ISBN 0-201-10179-3 If you want to learn PostScript, Post is a valuable learning tool, as you run it interactively and view the output one the screen. Without some basic knowledge you may find it difficult to understand what is happening if you have problems getting started. The startup file ================ The standard startup file "init.ps" should be run before most programs. You should read it and the comments within it, as you may wish to customise it. It defines useful operators to mimic a standard PostScript printer. It also handles automatic font downloading (see below). Getting started =============== Make sure that you have ConMan (V1.3+) and the ARP library installed. Copy the file post.library into your libs: directory. If you have a 68020 or 68030 cpu and a 68881 or 6882 floating unit you can use the 2620 version of the library instead - copy it to libs:post.library. From the CLI you can just type "post init.ps screen", assuming that all the files are in the current directory. You should see a new screen with a big requestor window appear. Click on "OK" and wait while Post executes the startup file, then you are ready to go. If it says that it can't get enough memory (if you have only 1 megabyte) try selecting "Black and White" on the requestor window, and selecting the "Close WBench" option. For a quick check of the graphics, pick File/Interactive on the menu. Then type into the narrow window at the top: 200 200 150 0 360 arc stroke The result should be a circle appearing in the lower window. When you have finished playing, type "quit". Then "Project/Quit" will return you to the CLI. If you don't have any fonts yet all text output will just print as big dots. (Read the section below on fonts). Make a "PSFonts:" directory and copy all your PostScript fonts into it. (Don't confuse these with Amiga bitmapped fonts - these will NOT work, nor will .AFM font metric files) Their names should be the same as their PostScript names - e.g. "PSFonts:Times-Roman", "PSFonts:Times-Bold". The files can either be ASCII text or in IBM PostScript font format. If you have copied them from an IBM disk you will have to change the names; since MSDOS can only handle 8 character names its stores Times-Roman as "TI______.PFB" and Times-Bold as "TIB_____.PFB". Then Post will load the fonts automatically as they are needed. To use the workbench startup click on the icon. You will probably want to set up the tooltypes to execute the startup file "init.ps"; for now you can enter it in the requestor. Fonts ===== As there are no fonts built in to the interpreter, all fonts must be loaded from the disk, as PostScript source. The standard startup file redefines the findfont operator to automatically load fonts from the disk the first time they are referenced. To use this, build a directory "PSFonts:" containing your PostScript fonts. The file names should be the same as the PostScript names, without the '/'. You can add an extension if you wish, by editing the startup file. You can also make it search more than one directory. The startup file also defines a default font, which will be substituted if the font your program requests cannot be found. The initial default font as set up by the standard startup file is a dummy font that prints big dots, but at least allows most text operations to proceed without producing errors. This means that if you don't have the font loading set up properly the only text output you will get is big dots. So if that is what you see when you run Post it probably means that you don't have any fonts, rather than a problem with Post itself. Since a font is loaded into the vm just like any other PostScript code, it will be discarded when the vm is restored. This means that in a multiple page document the fonts will likely be reloaded on every page. To save time, it is usually much better to preload the fonts you are going to need. You can do this using the "load font" menu command, or you can write yourself a little PostScript program to load your favourite fonts. (Exercise for the user: write a driver to extract the font names from a conforming PostScript program and preload them.) If you are using a large number of different fonts at once you may need to increase the default vm size to contain them. There are a number of commercial sources for fonts. Both the Adobe type 1 (encrypted) fonts and type 3 (standard downloadable) fonts are supported. Since type 1 fonts can contain special "hints" to improve the quality at small point sizes on low or medium resolution devices they usually give much higher quality results. You can get type 1 fonts from Adobe, or a number of other vendors. A good source of the standard set of 35 fonts as come on most PostScript printers is the Adobe Type Manager (13 fonts) and its associated Plus Pack (22 fonts). The IBM version contains the fonts in a format which can be read by Post. Various utility programs (e.g. CROSSDOS) are available to copy file from IBM 3.5 inch disks onto Amiga files. Just copy the .PFB files into your PSFonts: directory, changing the names to their PostScript names. The Mac version contains the fonts too, but you need a utility program to change the file format. The quality of the Adobe fonts is excellent; the printed output from Post on my LJIIP rivals that of a LaserWriter. If you have any of the additional CompuGraphic outline fonts supplied by Gold Disk for use with their DTP programs you can generate type 3 fonts from them using their conversion program. The quality is not as good as the original Compugraphic fonts but is acceptable for proofing purposes. There are some freely copyable fonts tht were originally distributed with the GhostScript project (another freeware PostScript interpreter available on Unix). The quality of these is not high, as they appear to have been generated by tracing bitmap outlines, but they will serve to get you started, and they are free. There are also various shareware and PD fonts available. Many of these were derived from the Mac or IBM. They may still be in a foreign file format. The file should be converted to readable ASCII, with no strange control characters. Some of the fonts have Mac encoding vectors. You won't notice the difference for the standard ASCII characters, as they are the same, but you may have to convert to the standard encoding to get more unusual characters like the trademark sign to work. (Programs like Adobe illustrator do their own font encoding anyway.) You will need to know some PostScript to make this change. If you see the sequence "/Helvetica findfont /Encoding get" or " /MacVec get" try replacing it with "StandardEncoding". You are recommended to ensure all your fonts have UniqueID's. This makes the font caching code more efficient. Often all you have to do is uncomment them in the source. Any number will do for the ID (up to 2**24 - 1), as long as it is different for each of your fonts. Make it a multiple of 4, as Adobe recommend adding 1 or 2 to the ID when modifying the font. Each font should have a FontName entry. This isn't actually required by Adobe, but certain programs such as Adobe Illustrator copy the font directory when recoding the font. If the name is missing, you get a dictionary full error after the name has been added. WorkBench 2.0 ============= I don't have 2.0 myself, so I am not able to test Post under it. But I understand that it works OK. You need to set up ConMan it you want to run interactively. It you mount it as "CNC:" the you can use the CONDEV option to access it. Otherwise you will find the console output is going to the WorkBench screen. Common problems =============== Printers -------- Some people have difficulty in getting Post to work correctly with printer output. The first thing to check is that you have your printer preferences set up properly. Post uses the printer values to set the size and density of its page buffer, so if you have silly values set it may pick a silly value for its buffer size and fail due to running out of memory. So Run Preferences, go to the graphic 2 screen, and check the page limits. If you set the limits to "Absolute" then width and height should be in inches; if you choose "Pixels" then the dimensions are in dots. Turn smoothing and centering off. On the graphic 1 screen, set the Aspect to horizontal, the image to positive, and the shade to black and white or colour according to your printer. If the output comes out distorted, to a silly scale, or with circles turned into ellipses, and takes forether to print, it is probably because the page size is wrong and the printer device is laboriously scaling it to fit. If you are having problems with the printer setup, it is better to run Post interactively. Then you can look at the values in the page size gadgets in the requestor window to check they are all sensible. Most page printers (lasers, DeskJet) will give the best quality with density set to the highest value. For matrix printers try both the highest and the next highest - as the pins usually overlap at high densities the quality may not be any better. If you are very tight on memory then a lower density will reduce the amount needed for the page buffer. The Workbench printer drivers print bitmapped graphics dumps within the text margins, whereas PostScript expects it bitmaps to begin right at the edges of the paper. You can line things up properly by setting the page offset gadgets in the requestor window. Once you have experimented to determine the proper values to can put them in a shell script, or set them in the WorkBench icon, so you don't have to type them every time. If you have a LaserJet printer or one that emulates it, you should use the special driver "postlj". It is faster, supports all the paper sizes in both posrtrait and landscape orientation, and avoids all the problems with the standard Workbench drivers interface. I have tested it on my HP LJIIP, but it should work on other LaserJet compatibles. Fonts ----- Most of the remaining troubles relate to fonts. I personally recommend the Adobe fonts: the quality is excellent and you are assured of maximum compatability. There are many other sources for fonts. Even the shareware fonts normally work. However being constructed slightly differently from the Adobe ones, they sometimes fail when programs attempt to modify them to change the character set encoding or character widths or obtain special effects. Other troubles with fonts usually relate to not not being able to find the font file on the disk. Read the comments in the init.ps file to see what directories in you filing system it is searching, also check whether you font files have extensions. I prefer to keep my fonts without extensions, so for example on my machine "Times-Roman" is in the file "PSFonts:Times-Roman". But you may want to keep the ".PFB" extension on your font filesif they are in IBM format - if you have other packages that like them that way. You can easily change this by editing init.ps. N.B. if you have some files with ".AFM" extensions they are NOT PostScript fonts. The are font metric files that define the character widths and other data for use by application programs; they do not define the characters outlines themselves. Ther are of no use to Post. Use with other packages ----------------------- I have used Post extensively with PPage (V1.3). Early versions of PPage had a bug in the PostScript prologue that caused a limitcheck error when doping patterened fills, but this has been fixed for a while now. I find that printing using postlj is about five times faster than printing direct from PPage. It solves the page offset problem. Also, it gives access to the Adobe type 1 font range, which is considerably more extensive than the hinted versions of the Compugraphic fonts that are presently available. I have tested a PageStream file. There was a problem with the prologue not being compatable with downloaded Adobe fonts. If you load all your fonts beforehand, using the "Load font" menu selection, it should work OK. Hopefully this will eb fixed soon. I have printed Excellence! files successfully. AmigaTeX with the PostScript driver should work OK. I have seen a TeX example (from another system) that failed - it was trying to define a font with an encoding vector only 128 entries long. If you meet this problem you can fix it if you are prepared to edit the PostScript file. vector only 128 entries long. Debugging --------- If your PostScript program is failing, if you know a little PostScript is usually quit easy to find out what is going wrong. In fact if you are developing PostScript code Post is a much better debugging tool than your average PostScript printer. It is normally best to use interactive mode for debugging. Start up Post on the screen and pick the "interactive" option. Then run you program from the interactive window. To run your program, type: > (filename.ps) run If it fails with an error message, you can then type interactive commands to see what happened. To display the contents of the operand stack, type: > pstack To display the contents of the execution stack at the point of the last error, type: > $error /estack get == To display the contents of any named variable, type: > varname == To see what is in the current dictionary, type: > currentdict {== ==} forall If you have no idea how far your program got before it failed, try adding a few lines "1001 ==" "1002 ==" "1003 ==" to trace how far it got. As PostScript files are pure ASCII text they are easy to inspect any modify with any editor. Postscript interpreter - user documentation =========================================== Post V1.4 Copyright Adrian Aylward 1989, 1991 Free use and non-commercial reproduction of the binaries of the interpreter library (post.library) is permitted, providing that the copyright notices are not removed. Distribution by disk libraries is permitted provided only a nominal copying fee is charged. You may freely copy, use and modify the user interface program (post). The source is included in the distribution. All other rights are reserved. For queries and bug reports write to the author: Adrian Aylward, 20 Maidstone Road, SWINDON, Wiltshire. UK. No responsibilities accepted for bugs, but please let me know so I can fix them. Introduction ============ "Post" is a software based PostScript interpreter, presently running on the Amiga. The source code is written in C, and should be fairly portable to other machines. It supports the full Adobe language, with only minor variations. Prerequisites ============= Post uses the Arp library (V39+), primarily for its file requestor. For interactive working you also need ConMan (V1.3+). Both these programs are widely available; any good BBS or PD/shareware library should have them. (ConMan is shareware.) You may well have them installed on your machine already. If you prefer not to install ConMan as your standard console handler, you will need to access it via an alternative device name, which you must specify by the CONDEV option. You will need at least a megabyte of memory, more for high density printer output. Command line interface ====================== usage: post [files...] [IFF file] [SCREEN] [PRINTER] [INTERACTIVE] [SIZE xyod..s..p.bc.] [MEM fhlv..] [CLOSEWB] [CONDEV con] If you forget, type "post ?" to display this. The input files --------------- The interpreter reads the input files in turn. When running interactively the input files are treated as startup files, and are rerun whenever the interpreter is restarted. So you would normally specify just the standard startup file "init.ps", or an alternative of your own. When running non-interactively you should in addition specify all the files you want to interpret, up to 5 in total; when the last is finished the interpreter will exit. Printer output -------------- This is the default if neither the IFF nor SCREEN options are used, when running non-interactively. The output is sent to the printer device as a graphic dump. The interpreter will obtain default values for the page size, density, and number of colors from the current preferences. If you use the default sizes make sure you have set the page size: run preferences and on the graphic 2 screen set the width and height limits - either bounded or absolute or in pixels. The output defaults to black and white or 3 colour, according to the preferences. IFF file output --------------- This option will send the output to an IFF file. Each IFF file contains a single FORM ILBM. So that multiple pages may be created in a single run of the interpreter, sequence numbers are automatically generated: IFF path/fred*.pic will generate path/fred1.pic, path/fred2.pic ... and IFF path/fred??.pic will generate path/fred01.pic, path/fred02.pic ... The default page size etc. is the same as for screen output. SCREEN output ------------- This option will send the output to a window on the interactive screen. It implies interactive working. You can generate screen, printer and IFF output at the same time. But since screen output has to use chip memory and printer output at high resolution needs a large page buffer (about a megabyte for an A4 page at 300 dpi.) you will probably run out of memory if you attempt the two simultaneously. The default screen size is the same as the workbench screen, but in interlace mode. The default page size is A4, with a density of 75 pixels per inch. The default number of colours is 3. The page size is rounded up to the maximum size of the window. The INTERACTIVE option ---------------------- This option causes the interpreter to run interactively. A screen is opened and on it appears a requestor window for the parameters. If you click on OK two windows will be opened, one for console input and output, and the other to display the page buffer. Use the menus. The SIZE option --------------- The SIZE option sets the page size and density etc.. SIZE "x..y..s..xo..yo..[x]d..[y]d..p.bc." Up to 5 SIZE options are allowed; later values override earlier ones. The page sizes ("x..y..s..") are in pixels, as decimal numbers; "s" sets the size of the bands, for band rendering to the printer. The page offsets (xo..yo..) are in pixels, shifting the location of the bottom left of the bitmap relative to the PostScript logical page (origin at (0,0) in the initial user space). Densities ([x]d..[y]d..) are in pixels per inch; "xd" or "yd" set the x or y density, and "d" sets both. The printer density can be set by "p"; its value should be in the range 1 to 7. The number of colours is: "b" for black and white (1 bit plane), "c" or "c3" for 3 colour rgb (3 bit planes), and "c4" for 4 colour cmyk (4 bit planes). The MEM option -------------- The MEM option controls the amount of memory allocated for workspace. MEM "v..f..l..h.." Up to 5 MEM options are allowed; later values override earlier ones. Default Minimum ------- ------- f60000 1000 Font cache h20000 1000 Halftone cache v50000 5000 Virtual machine memory segment size l10000 1000 Line drawing workspace segment size In addition memory is allocated for the page buffer (one bit per pixel) and for drawing and imaging buffers. Since most of the workspace is allocated automatically you will not usually need to adjust these options. If your program is so large that you do need to increase any of these values, be aware that it is unlikely that it will run on any standard PostScript printer. The font cache is used to store character bitmaps; it saves recalculating them each time they are needed, so text rendering becomes many times faster. The default value is reasonable for average sized machines; if you are trying to shoehorn things into a small machine you could try reducing it. Or if you are printing a document using a large number of different characters, fonts, and sizes you may be able to imrove performance by increasing it. The halftone cache holds halftone patterns used for simulating gray values. The default value will normally be satisfactory, but you might possibly need to increase it if you are using very large halftone patterns, for example for complex patterned fills. The virtual machine memory is automatically allocated in segments as they are needed, up to a maximum of 63. For most purposes you will not need to alter the segment size, but if you are running a gigantic program you might possibly need to increase it. The line drawing workspace holds the current path, together with all the paths saved by a gsave operation. It is automatically allocated in segments, up to a maximum of twenty. The default size is sufficient for about 4000 path elements, enough for all normal programs. The CLOSEWB option ------------------ If memory is tight, you can try using this option to close down WorkBench while Post is running. This only works if there are no application windows open on the WorkBench screen. The CONDEV option ----------------- If you do not have ConMan installed as the default console handler, you must use this option to specify its device name (without the ":"). Examples -------- To run postscript programs interactively, rendering to the screen: post init.ps screen To print a file with many big characters using a large font cache and increasing the path limit: post init.ps myfile.ps printer mem f500000l200000 To render a series of 640 * 512 pictures at 762 dpi. to iff files t:i01, t:i02 etc.: post init.ps mypics.ps iff t:i?? size x640y512d72 The WorkBench interface ======================= Just click on the icon. It always runs interactively. You can set up default arguments by setting the ToolTypes; add a string "ARGS=...." and it will be parsed just like the CLI startup. For example "ARGS=init.ps screen" will define the standard startup file and make the screen the default output. The Menus ========= Project Restart Takes you back to the parameters requestor, after which the interpreter is reinitialised. Quit Quit from the program File Load font Loads a file from the PSFonts: directory by default Load file Loads a file, without saving or restoring the VM Run file Runs a file, saving VM before and restoring after Interactive Interprets interactive input Control Pause every page Toggles pause every showpage/copypage Continue after pause Does just that Interrupt Sends a break; equivalent to CTRL/C Before and after executing a file the operand stack is cleared. This is to prevent invalidrestore errors, particularly if interpretation ended in error with values on the stack. If you need to leave things on the stack you will have to run the files from a driver file, or from the interactive window. At the end of the file, (after any restore), the page is erased. If you use the automatic font loading, as defined in the standard startup file "init.ps", the font will be discarded when the VM is restored. To avoid repeated reloading of common fonts it may be better to use the "Load font" menu item to preload the ones you want. N.B. there is no check to stop you loading the same one twice; it will probably work but it will waste memory. Compatability ============= The interpreter is based upon the language (version "23.0") as described by the (red) book: "PostScript Language Reference Manual" Adobe Systems Incorporated, Addison-Wesley 1985, ISBN 0-201-10174-2 The 4 colour operators are also supported as described by the document: "PostScript Language Color Extensions" Adobe Systems Incorporated (23-Jan-90) File handling ------------- The files %stdin, %stdout, %stderr are permanently open as far as the operating system is concerned. Attempts to close them will invalidate the file object but not close them to the operating system. If they are connected to a terminal they will be unbuffered, so output will be transmitted immediately, without waiting for a "flush". The special files %statementedit and %lineedit are not supported. There is no end of file control character. Error handling -------------- All the standard Adobe error conditions are supported. There also some additional errors: The error "invalidstop" will be generated if a "stop" operator is executed not within any encolsing "stopped" context. The error "memoryallocation" will be executed if the interpreter is unable to obtain sufficient memory from the operating system. The execution stack ------------------- The exact contents of the execution stack are not defined by the language reference manual, and cannot therefore be guaranteed to be the same as other implementations. Dumping the stack is likely to yield useful debugging information but is not recommended for normal programming. Colour mapping -------------- The interpreter can run with one bit plane (for black and white printers), 3 bit planes (red, green, blue) or 4 bit planes (cyan, magenta, yellow, black). For screen output 3 bit planes are appropiate. For a colour printer the 3 or 4 colour model can be used. The output is always in binary; gray scale is supported only via the halftone mechanism. For low resolution colour printers the 3 colour model is probably best. The 4 color model is for high resolution colour printers that can generate high frequency halftone screens, where a fourth screen is used to improve the quality of the blacks and grays. (N.B. the preferences printer drivers only handle 3 colour model, so if you want to use the 4 colour model you will probably need to generate an IFF file and write your own print dump program. They will however automatically use black the ribbon/ink if the printer has one) The transformations between the RGB and the HSB models are based on those in the book: "Procedural Elements for Computer Graphics" David F. Rogers, McGraw-Hill 1985, ISBN 0-E07-053534-5. Band Rendering -------------- For a high resolution printer the page buffer can be quite large (a megabyte or so). If you don't have enough memory to hold the entire page at once you can render each one in several bands. Set the "SIZE s..." option to the largest band size you have space for. (For matrix printers it will probably be best to make it a multiple of the number of printer pins times the number of vertically displaced passes). Then run the postscript program generating each page once for each band, using the "setband" operator, which is described below, to set the base for each band. Start at a base of zero and increment the base by the band size until you reach the page height. Each band is sent to the printer as a separate graphic dump; the last band generates a form feed to eject the page. You can use the "currentband" operator to calculate the number of bands needed: currentband 1 sub { setband pageproc } for 0 setband will execute "pageproc" once for each band (remaining) on the page. The procedure should execute copypage (or showpage) exactly once per iteration. This technique is only suitable for printer output. There is a special driver program "postband" that handles this automatically for programs that conform to the Adobe structuring conventions. Fonts ----- There are no fonts built in to the interpreter; they must all be downloaded. The findfont operator will execute the error invalidfont if the font you request is not present in the font dictionary. You can redefine it, perhaps to search the Unix/Amiga filing system to automatically download fonts or to substitute a default font. See the standard startup file. Both type 1 (Adobe encrypted format) and type 3 (standard PostScript as per the red book) fonts are now supported. In addition the IBM font format can be read directly. The font caching will work significantly better if all your fonts have UniqueID's. Then repeated makes of the same font with the same matrix will be cached, and cached character bitmaps can be retained even if the font is removed by a restore operation. N.B. if fonts are downloaded after a save they will be removed by the corresponding restore; in the interests of efficiency it may therefore be better to preload them. Other features -------------- Names of the form //name are looked up immediately by the scanner, and packed arrays have been implemented. These features were not on the original Adobe red book, but were added to the language specification later. When scanning the contents of a string, if there any embedded strings the escape sequences are interpreted just as they are in a file. This follows the specification of the more recent Adobe interpreters (including display PostScript) and not the original red book. Operators omitted or changed ---------------------------- banddevice Not appropiate for the Unix/Amiga environment. bytesavailable Since we can't tell how many bytes are available we always return -1. copypage For printer output this works like the standard. The number of pages printed is equal to #copies. For screen output it does not need to do anything, as the screen is not buffered. For IFF file output it writes the page to the next file. echo Not appropiate for the Unix/Amiga environment. eexec This is implemented as per the Adobe type 1 fonts book. Its operand must be a file, which must match the object on top of the execution stack. It can be terminated only by a closefile (which terminates the eexec but does not actually close the file). So the sequences "currentfile eexec" and "currentfile closefile" as described in the book will work, but other combinations will likely fail. executive There is no executive, as the interpreter supports interactive usage directly. findfont Looks in the FontDirectory. If it can't find the supplied key, it executes the error invalidfont. flushfile We don't check for errors when flushing an input file, to prevent recursion in the error handler. framedevice Not appropiate for the Unix/Amiga environment. prompt Not called by the interpreter. See "prompts" instead. renderbands Not appropiate for the Unix/Amiga environment. resetfile Does nothing. showpage See the notes for copypage above. usertime Returns the time elapsed since the interpreter started, with a resolution of one second. Operators added --------------- currentband "currentband" base size height Returns the base of the current band, size of each band, and total height of the page. setband base "setband" Sets the base height of the band being rendered. The value must be greater than or equal to zero and less than the total height of the page. fontfile (filename) "fontfile" Opens a file for reading. If the first byte is hex "80" the file is assumed to be in IBM font format, and its contents are converted to standard ascii/binary as they are read. The standard input file (%stdin) is never in IBM font format. invalidstop (error) A "stop" has been executed for which there is no dynamically enclosing "stopped" context. prompts string string "prompts" The first string is used as the prompt when the interpreter is scanning terminal input and executing it immediately; the second string is used when execution is defered while scanning the contents of a procedure "{ ... }". No prompt is given when a newline is encountered within a string. vmhwm "vmhwm" hwmused maximum Returns two integers: the high water mark of the amount virtual memory used since the program was first started or the last "vmhwm", and the maximum available amount of memory. callextfunc result arg1 arg2 ... argc func "callextfunc" result Calls an external function using a C calling sequence. This operator is not available for use by ordinary PostScript programs; it can only be used when the library is called with an external function table supplied as an argument (see the library interface documentation for details). The "func" argument is the index of the function in the external call table, and "argc" is the number of parameters; both must be non-negative integers. The result is the object in which the result will be placed. If it a null then no result will be returned and the null object will be discarded; otherwise it must match the type of the result returned from the function. For both result and parameters bool and integer types will work OK; real types will work if your C compiler passes them just like ints (use ANSI prototypes so it does not expand them to double). For string parameters the address is passed. Arrays may be passed as parameters, but they are only useful if you know their PostScript object representation. The maximum number of parameters permitted is 20. Miscellaneous ------------- The system dictionary is left writeable so that standard preludes can add things to it - possibly removing write permission when they have finished. Similarly FontDirectory is writeable, so that it is possible to add entries without using definefont. Device space ------------ The largest device that the interpreter can handle is 30000 by 30000 pixels. In practice you will probably run out of memory long before reaching this limit. Known Bugs ========== If you close down WorkBench the menus sometimes get truncated and slightly corrupted. I suspect this is a Workbench/Intuition problem. If you type CTRL/C to abort if the printer is not ready then strange things may happen on subsequent attempts to print. N.B. if you run very low on memory, Intuition may behave strangely, and refuse to resize windows etc.. This is not a bug in Post. If you type CTRL/backslash in the interactive window you won't be able to run interactively again until a restart. Post tries to keep the console window active, so that all keyboard input goes there. It will probably be incompatible with mouse handlers that automatically activate the window under the cursor. Versions ======== V0.0 14-Nov-89 (prerelease) The original. V0.1 06-Dec-89 (prerelease) Image routines added. Range checks eased on gray levels and colours etc.. Area filling speeded up, matrix manipulation and colour mapping rewritten, numeric conditioning improved for path fill. Bugs fixed: syntax error, == string escapes, error handling and quit when recursing, vm error handling, integer overflow in path fill, matrix save, interrupt after printing page, dictionary second save, name table restore, boolean type checking, multiple halftone screens memory allocation. V0.2 07-Jan-90 (prerelease) Font and character routines added. Null device added. Band rendering of printer output added. Matrix manipulation rewritten again. Interpreter recursion rewritten. Allocate stacks dynamically. Bugs fixed: missing access checks on strings, scan token negative chars, depth check in path flattening, pathbbox, strings or null objects as dictionary keys, shade after grestore(all), fill/image with clip region, clip unclosed subpath, dictstack/execstack. V1.0 12-Feb-90 Support for big scrollable windows added. Menu handler added with port name option. Workbench startup added with parameters requestor window. Hex string scan optimised. Break now CTRL/C only, not CTRL/D. Bugs fixed: aspect ratio in iff file, clipping pictures much wider than the page. V1.1 27-Mar-90 Interpreter made into shared library. Message port interface removed. Band printing driver now included. Immediate lookup of //name added. Packed arrays added. CR and CRLF now converted to LF for readline and when scaning tokens from a file. Copypage now takes account of #copies. Bugs fixed: slow images where strings are not rectangles, attributes after copy and bind, charpath with fonts using gsave, iff run compression, setundercolorremoval now conforms to Adobe spec, make errorname literal, slow images repositioned by 1/2 pixel. V1.2 14-Oct-90 Allow multiple SIZE and MEM options. Page offset option added, page size defaults to A4, integer gadgets checked for +ve values. Type 1 fonts, IBM font format, encrypted files, eexec operator added. Bugs fixed: location zero not zero, printer device signals, proc arrays not executable, bind packed arrays, restore closing files, makefont matrices not commutative, makefont with translation, error handling during recursion, graphics state within buildchar proc, miterlimit less that sqrt(2), cvs copying too many bytes, solid lines after dashes, floating point error trap recursion (2620 version on 68882), check for fpu present, charpath with null character path, error handling loading file, invalid restore check, writehexstring. V1.3 27-Oct-90 LaserJet driver added. Interface fixes: Menus no longer ghost after startup file error and restart, pause status is now retained over a restart, printer preferences page size is now handled correctly, no longer crashes if arp.library is missing. Bugs fixed: IBM binary eexec sections beginning with white space, funny characters in error message command names, hints with stems of negative width, font character cache sizing, tune baseline alignment and flex, eexec lines ending in CR (not CRLF), aload packed arrays, zero length charstrings, font character cache hash chains. V1.4 ??-???-?? External function call interface added. New flexible memory allocation for vm and paths; new error "memoryallocation". More flexible font cache limit. Interface fixes: Memory Fonts/Paths gadgets transposed, drag scroll bars under 2.0. Bugs fixed: writehexstring, zero height clipped paths, $error in userdict, undocumented charstring codes, halftone cacheing, mixed type 1 and 3 fonts. PostScript LaserJet printing driver (PostLJ, with Post V1.4) ============================================================ Copyright Adrian Aylward 1990, 1991. You may freely copy, use and modify this program (postlj). The source is included in the distribution. The program calls the PostScript interpreter library to render a series of PostScript files to LaserJet printer connected to the parallel port. It supports all the possible page sizes, i portrait or landscape orientation. It has been tested on a LaserJet IIP. It will likely work with the other current models in the LaserJet family or emulations thereof. It is run from the CLI command line. There is no workbench startup. The CLI interface is very simple. No attempt has been made to provide fancy keywords for the options; if you can't remember them write yourself a script. There are no status checks on the printer device, so it the output hangs check that your printer is plugged in and switched on. Is is advisable to switch the printer on before starting, otherwise the first few characters may be lost, and the printout corrupted. Usage ===== postband [-options ...] [files...] [TO tofile] [MEM fhlv..] The filename defaults to "par:" the parallel device handler. You can specify an alternative name if you want to save the output in a file, or send it to a different handler. The options are indicated by an initial "-". They are single letters, followed by a numeric value. page size s0 legal s1 letter s2 executive *s3 A4 (default) s4 COM-10 s5 monarch s6 C5 s7 DL page orientation *l0 portrait (default) l1 landscape begin printing at page number *b0 all pages b999 any value from 1 to 9999 end printing at page number *e0 all pages e999 any value from 1 to 9999 number of copies *n0 use #copies, or 1 if zero or more than 99 (default). n99 any value from 1 to 99 graphics compression c0 disabled c1 enabled (default) If you have an earlier model LaserJet that does not support graphics compression (the model II, I think) you must disable it. The "files..." are the PostScript files to be interpreted. Usually these will be the standard startup "init.ps" followed the by file you wish to print. The TO filename defaults to "par:" the parallel device handler. You can specify an alternative name if you want to save the output in a file, or send it to a different handler. The MEM options are passed directly to Post. Up to 5 are allowed; later values override earlier values. See the file post.doc for details. For example, to print pages 10 through 15 (inclusive) of a document on a LaserJet connected to the serial port, in letter format, landscape orientation: postlj -s1 -l1 -b10e15 init.ps doc.ps to ser: PostScript band printing driver (PostBand, with Post V1.4) ========================================================== Copyright Adrian Aylward 1990, 1991. You may freely copy, use and modify this program (postband). The source is included in the distribution. The program calls the PostScript interpreter library to render a file to the printer in a series of bands. It can therefore be run on machines with insufficient memory for a full page buffer; it should be possible to run it on a 1 megabyte machine. Since it has to rerun the interpreter for each band it is going to be several times slower than printing directly. It also depends upon the file being conformant to the PostScript structuring programs. Usage ===== postband [files...] PRINT file [SIZE xyod..s..p.bc.] [MEM fhlv..] The "files..." are the startup files for Post. Usually this will be the standard startup "init.ps". The PRINT option is the name of the PostScript source file to be printed. The SIZE and MEM options are passed directly to Post. Up to 5 of each are allowed; later values override earlier values. See the file post.doc for details. Since the default for the SIZE option is to render the entire page at once you will in practice always need to supply this option. You are recommended to experiment until you find a suitable set of values and then create a shell script for them. As a starting point for a 1 megabyte machine, try: postband init.ps print ... size s480 mem v150000f30000l30000h5000 The exact amount of memory you have available depends on how many disks you have, and how many programs you have resident etc.. N.B. as PostBand copies the print file to a temporary file in the t: directory, it is probably a good idea to make sure t: is assigned to a disk and not a ram drive. The default value for the VM size is 280000, as for earlier versions of Post, not 600000. N.B. the aspect of the printer dump is always horizontal. File structuring ================ The PostScript file structuring conventions basically assume that a program consists of a prologue that is executed once at the beginning, and a series of pages that can be executed independently - saving and restoring the vm. All PostBand is looking for is simply the comments dividing the sections. The first line must begin: %!PS-Adobe- Then follows the prologue. Each page begins: %%Page: At the end of the file is the trailer, which begins: %%Trailer: N.B. EPSF files, such as demos and clip art, do not fit this structure. But since they only contain a single "page" you can run the entire file once for each band; or if you prefer simply edit in the required "%%Page:".