Copyright: Copyright ® 1993-1996 Roger Willcocks


contents
   RoPS-32 Help

opening a document
closing an open document
moving around within a document
moving around within a page
zooming and rotating the page
copying a page to the clipboard or a file
printing a page or pages
troubleshooting
configuration and other advanced options
compatibility
about the author

Remember !  RoPS is not free.  You must purchase a licence if you find the program useful.


Opening a document

To open a document select the 'open' option from the 'files' menu.  If the document is structured an index will be built.


Closing an open document

To close an open document select the 'close' option from the 'files' menu.  The document can be closed at any time  - even while it is being loaded.


Moving about within a document

Use the 'page' menu to move about within a document.  If the document is structured any page can be accessed directly.  However if the document is unstructured the pages can only be read in order.   Use the 'page down' key or the 'next' option from the 'page' menu to move on to the next page of an unstructured document.


Moving about within a page

Use the left mouse button to 'drag' the page around within the window, or use the scroll bars at the side and bottom of the window.


Zooming and Rotating a document

To zoom or rotate a document, use the 'view' menu.  If a structured document is open, the current page will be redrawn at the new size and orientation.

n.b. It is usually faster to set a convenient page size and rotation before opening a document.


Colour options

To flip between black and white (monochrome) mode and colour, use the 'preferences' option on the 'edit' menu.  Colour mode uses eight times as much memory as monochrome for a given page size.

If the Antialias option is selected black text will be rendered at twice normal size and averaged onto the screen.  Other colours remain ragged.


Structured documents

A structured document contains numbered pages and an index that describes where each page starts within the document's computer file.  If a document is not structured it is impossible to repaint a specific page.  Because of this, options that require the page to be repainted (such as zooming or changing the colour format) are disabled if the current document is not structured.

You can disable the building of an index (and thus force the document to be unstructured) by un-checking the 'build index' option on the edit/preferences menu.  This can be useful for debugging.


'undefined' error

The 'undefined' error occurs if a function required by the PostScript document is not available.  This may be because the document uses a language extension (such as colorimage) that is not defined in Level 1 PostScript (the language implemented by RoPS), or it may be due to a syntax error in the PostScript file.

Note: The symbol 'Type1BuildChar' will be reported as undefined if the document attempts to use type 1 font file data.  RoPS does not support type 1 fonts.


'limitcheck' error

The 'limitcheck' error occurs if a PostScript job requires more resources (path elements, half-tone dots etc.) than have been allocated by the interpreter.

The allocation of resources is set by variables in the rops.ini file. (See initialization file options.)  The resource that needs  increasing can be inferred from the PostScript operator that was active when the error occurred.


'undefinedfilename' error

The 'undefinedfilename' error occurs if the PostScript document includes another file and that file can't be found.


'dictfull' error
'dictfull error'

The 'dictfull' error occurs if an attempt is made to add an entry to a full dictionary.  All the 'system' dictionaries, including the font dictionary, are created in ropsboot._ps.  If a dictfull error occurs on a system dictionary you can increase its size by editing that file.


'VMerror' error

The 'VMerror' error occurs if the PostScript document uses too much virtual memory.  RoPS allocates a fixed amount of virtual memory at startup.  The amount it allocates is governed by the 'vmsize' variable.  (See initialization file options.) You can increase the value of this variable as necessary.

Note: the frame buffer is NOT allocated out of virtual memory.  If RoPS fails to create a frame buffer this is because there is not enough real memory (including swap space) available.


Copying a page to the clipboard or a file

The 'copy' option on the 'edit' menu copies the currently selected region, as an image, to the clipboard.  The 'copy to' option copies it to a file.

The 'copy text' option extracts the textual information from the currently selected region and copies it to the clipboard.

To select a region point at one corner and press the right mouse button; then - still holding down the button - drag the mouse to the opposite corner and release the button.

To enlarge a previously selected region, hold down the 'shift' key while you press the right button.

To select the entire page use the 'select all' option on the 'edit' menu.


Printing a page or pages

The 'print' option on the 'file' allows you to print the currently viewed page, all the pages, or (if the document is structured) a range of pages.  If the image is smaller than the paper, it will be centred on the paper.  Otherwise only the top left corner of the image will be printed.

RoPS does not redraw the page especially for the printer.  Instead it simply transfers the existing page bitmap (as seen on screen) to the printer, so that one pixel on the screen becomes one pixel on the printer.  If, as is usually the case, the pixels on the printer are much smaller than the pixels on the screen, the printed image may come out smaller than expected.

To fix this you should zoom the document two or three times so that it is big on the screen before you print it.  It will come out bigger on the printer too.

To change the zoom factor permanently, so that RoPS always creates big images, add an LPI (lines per inch) entry to the [framebuffer] section of the rops.ini file.  (See initialization file options.)  Use a value slightly smaller than the resolution of your printer.  For instance, if your printer operates at 300 lines per inch, add a line saying
     LPI=280
to the [framebuffer] section of the rops.ini file.  (The value needs to be slightly smaller than the resolution of the printer because most printers cannot print all the way to the edge of the paper.)  Note that this will change the size of pages drawn on the screen too.

Note: you can specify a different '.ini' file by putting a '-f' switch on the command line.  Thus you can create a printer-specific .ini file by copying rops.ini to, say, ropsprt.ini, editing the [framebuffer] section and running the program as 'rops -f ropsprt.ini'


Initialization file options

The following options are recognized in the [rops] section of the rops.ini file (which is usually found in the c:/windows directory):

vmsize - virtual memory size, in kilobytes - default: 400
pathsize - number of elements in path - default: 2400
tokensize - maximum length of a token - default: 3000
cachesize - number of bytes in font cache - default: 30000
imbuffsize - number of pixels in image operator buffer - default: 3000
screensize - number of pixels in halftone screen - default: 400

bootfile - full path to boot file - default: a:/ropsboot.ps
helpfile - full path to help file - default: a:/rops.hlp
jobname - full path of last job executed
filter - which file-open filter to use (ps = 0, eps = 1, all = 2)
colour - monochrome (0) or colour (1) operation
antialias - ragged (0) or smoothed (1) operation
nohatch - normal (0) or alternative (1) colour scheme
structure - ignore (0) or obey (1) document structure convention (build index)

The following options are recognized in the [framebuffer] section of the rops.ini file:

ScreenFreq - halftone dots per inch - default: 28
ScreenAngle - halftone screen angle in degrees - default: 57
WidthMM - width of frame buffer in mm - default - 210
DepthMM - depth of frame buffer in mm - default - 297
LPI - lines per inch - default: 100


Configuration and other advanced options

colour options
adding extra fonts
initialization file options


TrueType Fonts

RoPS draws characters by using Windows TrueType fonts.  However, many PostScript documents contain fonts with names that are different to those of the TrueType ones.  If a font is not available, RoPS uses the Courier font instead.  RoPS requires that the Courier font be available.

The [fontlist] section of the rops.ini file (which is usually found in the c:/windows directory) converts PostScript names to TrueType ones.  For instance, the TrueType font 'Times New Roman Regular' is the same as the PostScript font 'Times-Roman', so rops.ini has a line saying:

[fontlist]
Times-Roman=Times New Roman Regular

Normally the 'fontscan' program is used to create a name mapping table but you can also edit rops.ini by hand.


Troubleshooting

If your printed pages come out smaller than you expected, read the section on printing.

PostScript is an interpreted computer language with built-in error handling.  Many documents / programs contain their own error-handling routines and RoPS will use these wherever possible.  The normal RoPS error handler pops-up a dialog box containing the name of the error and the name of the PostScript operator that generated it.  Error handlers loaded from documents may attempt to print additional information onto the page itself.

There are 22 different PostScript errors.  They can be caused by four sorts of problem: syntax errors in the PostScript program itself; insufficient memory in the interpreter; missing files or language elements in the interpreter environment; and attempts to bypass security features of the language.

In addition RoPS contains a number of internal consistency checks.  If a check is violated, a fatal error occurs and RoPS will exit immediately.

RoPS attempts to parse structured documents and build a page index.  According to convention, in a structured document each page should be independent of all the others.  However some documents break the rules; this can result in pages not appearing at all, appearing on top of each other, or various PostScript errors.  Viewing the document with 'build index' turned off can sometimes help in this situation.  This forces RoPS to display the document 'as is', without further interpretation.


Compatibility

RoPS is a full implementation of Level 1 PostScript, with the following limitations:

     Type 1 fonts are not handled. (RoPS uses TrueType fonts)
     Documents with more than 1000 pages are truncated to 1000 pages
     The 'stroke' boolean argument to 'charpath' is assumed to be false

RoPS has the following language extensions:

getenv: read an environment variable
     [string | name] /getenv/ false     (not found)
     [string | name] /getenv/ string true     (found)

getprofile: read a section of rops.ini
     [string | name] /getprofile/ false     (not found)
     [string | name] /getprofile/ dict true     (found)

dumprect: dump the framebuffer to a DIB file
     int int int int string /dumprect/ -
     (left top right bottom filename); Coordinates are specified at 72 dpi


About the author

Roger Willcocks (rkww@centprod.demon.co.uk) is a consultant programmer specializing in graphics and low-level system programming.  He wrote RoPS as a programming exercise; initially on a Unix system to become familiar with the PostScript language and later on a PC platform to understand the finer points of MFC and Windows.  He would be very happy to receive comments and suggestions about the program.

Incidentally, RoPS is available in both 16- and 32-bit versions, both as an executable program and as a DLL.  Source and binary licences are available.  Contact the author for more information.


Fatal errors

RoPS contains a number of internal consistency checks, known as 'assertions'.  If an assertion fails a fatal error is generated.  Please inform the author if you encounter an assertion error.

The fatal errors 'stop: no stop context' and 'error raised during error processing' generally indicate a syntax or other error in the ropsboot._ps startup file.


PostScript errors

The limitcheck and VMerror errors occur if a document needs more resources than have been allocated by the interpreter.   The undefined and undefinedfilename errors occur if a file or language element is missing from the program's environment.

The following errors are usually caused by syntax errors in the PostScript program / document.  For Further information refer to a PostScript language manual.

dictfull
dictstackoverflow
dictstackunderflow
execstackoverflow
invalidfont
invalidrestore
nocurrentpoint
rangecheck
stackoverflow
stackunderflow
syntaxerror
typecheck
undefinedresult
unmatchedmark

The following errors occur if a PostScript document attempts to bypass security features of the language.

invalidaccess
invalidexit
invalidfileaccess

Finally, 'ioerror' occurs if a file cannot be written / read.