README.PT file for Magus PageTurner version 1.0.2 for OS/2 2.1
and later. Copyright (c) 1994, 1995 by Magus.  
All rights reserved.


Installation
===========-

1) Insert Diskette 1 into drive A (or B).

2) Either open an OS/2 Window and type A:INSTALL (or B:INSTALL) 
   or open a Drives window on drive A (or B) and 
   double-click the mouse on INSTALL.EXE.

3) Select the drive letters and directories into which you wish 
   the files to be installed.  The font directory must be the
   directory in which your PostScript Type 1 fonts are installed.
   OS/2 ships with 13 of these fonts (whose files end with a
   .PFB extension), which are normally installed in C:\PSFONTS.

   The installation procedure will put the PageTurner icon into 
   the OS/2 Programs folder.  You may move the icon elsewhere
   if you wish.

4) If you intend to print from PageTurner, you must set the 
   'Printer-specific format' option on and the 
   'Print while spooling' option off on the 'Queue options' page
   of your printer object's Settings notebook.  Otherwise 
   attempts to print more than about 4 pages will cause 
   excessive swapping and severe performance penalties.

5) Reboot your computer before running PageTurner.  Start 
   PageTurner by double-clicking the mouse on the icon, by
   dragging a PostScript file icon from a Drives window and
   dropping it on the PageTurner icon, or by typing 'PAGETURN'
   on the command line (optionally followed by a PostScript
   file name).


Known Limitations
=================
PageTurner may not work with color displays which allocate 16 
bits (65,000 colors) per pixel.  If you have such a display, you
may need to operate it in 8-bit (256 color) or 24-bit (16.7
million color) mode for use with PageTurner.

Since PageTurner relies on a non-reentrant interpreter for all
rendering, printing and viewing are handled through the same 
thread, so viewing is suspended while a document prints.  (We 
hope to provide multi-thread support in a future release.)



Additions to Chapter 7: If Problems Arise
=========================================
Printing Many Pages is Very Slow

OS/2 spools (copies to a temporary disk file) each print job 
prior to sending it to the printer.  By default, the spool files
are stored in the form of OS/2 metafiles, which essentially 
contain the sequence of function calls OS/2 relies on to
construct a graphic image of the data.  Metafiles have the
advantage of being device-independent, and allow the user to 
preview a print job by double-clicking on the print job's icon in
the printer object window.

Unfortunately, OS/2 not only writes the metafile information to 
disk as a spool file, but also maintains the entire metafile in 
memory until the spooling process is complete.  This means that 
as the spool file grows, so does the amount of memory OS/2 
requires to deal with it.  Text files have a relatively compact 
metafile representation, so one does not normally encounter 
resource problems in printing them, but PageTurner produces a 
full-page bitmap for every page, not textual data.  The metafile
representation for each of these bitmaps is usually quite large
(easily over 1 MB).  The result of PageTurner's need to print 
bitmaps and OS/2's spooling architecture guarantees that OS/2
quickly runs out of memory when PageTurner prints more than about
4 pages.  The consequences include essentially constant
swapping and severe performance degradation, to the point of 
halting the machine completely.

Fortunately, a workaround for this printing problem is available. 
Simply open the printer's Settings notebook and go to the
'Queue options' page.  Then set the 'Printer-specific format'
option on and the 'Print while spooling' option off.  (OS/2 
cannot readily handle printing PageTurner's bitmap output while 
simultaneously spooling it.)  Note that these settings are the 
exact opposite of the default settings.

We regard this printing problem as an unfortunate deficiency in 
the design of the OS/2 spooler.  We are urging IBM improve the 
spooling process to alleviate the resource demands.

The PostScript printer driver for OS/2 Warp suffers from another
problem which is independent of the above issues, namely that it 
generates very large spool files for print jobs from PageTurner
(e.g. 16 MB per page for a 300-dpi printer).  The large files
presumably arise due to an inefficient storage format for large 
bitmaps.  Fortunately, users with PostScript printers will 
normally print by selecting the pass-through option, which 
bypasses the printer driver.


Printing Part of a Document Fails

Some PostScript files violate the Document Structure Conventions
by defining procedures on the first page of the document which 
are required for use on following pages.  Such files will not
print properly unless the first page is included in the print 
job.

Solution
--------
Include the first page of the document in the list of pages to be
printed.  You may also wish to complain to the vendor whose 
software produced the improperly-structured file.

(If you are knowledgeable about the internals of PostScript 
files, you can reduce wastage by doing the following:

1) Copy the file to a new name,

2) Edit the new file to delete all pages between the first page 
   in the file and the first page you wish to print.  Note: If
   the file contains binary data, using a standard text editor
   will corrupt the file.

3) Delete the comment %MagusViewTrailer and all subsequent lines.

4) Print from the new file, including the first page.

This approach will result in only one wasted page.)


Errata
======
The instructions in Chapter 6 for creating a PostScript file 
under OS/2 2.1 direct you to go to the Printer Driver page
of the printer object's Settings notebook, then click 
on the 'Job Properties...' and 'Options...' button to find
the radio button which specifies that PostScript output is
to be saved to a file.  However, the 'Output' page of the
Settings notebook also contains an 'Output to file' checkbox
which serves the same purpose.  Our experiments have given
conflicting evidence as to which avenue is the correct one,
so the best guidance we can give is to suggest that you try
the second approach if the first does not work.


Improvements in Version 1.0.2
=============================
The requirement for this upgrade came from the unfortunate 
discovery that PageTurner 1.0.1 would not run under OS/2 Warp 
3.0, due to a compiler problem.  Our compiler vendor recently 
issued the final fixes to the compiler, allowing us to issue a 
revision which runs properly under OS/2 Warp.

The image management code was completely rewritten for this 
release.  The rewrite reduces the resources required to render 
PostScript files, drastically so in the case of files containing 
complex graphics.  The imaging operations are also more robust 
and reliable than before, particularly with respect to printing.
This rewrite was extensive enough to justify its own major 
version number, but we are incorporating it as part of 
the Warp fix.

PageTurner no longer displays jumbled or missing characters when
viewing PostScript files which contain TrueType fonts and which
have been produced by Microsoft Windows.

The problem of extreme performance degradation when printing from
PageTurner, which has been present in previous versions, has
finally been traced definitively to OS/2 itself.  Fortunately, a 
workaround exists, and is described above.

PageTurner now senses the size and resolution of the display on
loading, and automatically appears in the most appropriate 
size and orientation.

Some users have complained that PageTurner would hang their 
machines with a General Protection Fault (GPF), often while 
opening a file.  Our understanding of one such failure mode has 
improved, and we believe that this release is less likely to 
cause such hangs.  However, we will continue to work on
improving stability.

Many minor bugs have been corrected.


Improvements in Version 1.0.1
=============================
File and page searches now display their status and can be interrupted.
Initial file scan for new PostScript files is 2-3 times faster.
Installation procedure associates filenames ending in .PS or .EPS
  with PageTurner so that they are automatically viewed on double-clicking.
  A 'PostScript file' type is also associated with PageTurner.
Scroll bar's slider now scales to reflect portion of page displayed.
Page-Up and Page-Down keys now scroll the image window.
PageTurner displays a warning if it cannot find the fonts it needs.
PageTurner usually displays a warning if the PostScript file is not 
  viewable (although perfect detection is not possible).


Problems in Version 1.0.0 which are fixed in Version 1.0.1
==========================================================
Opened files never close.
Table-of-contents numbers are sometimes displayed incorrectly.
Pass-through PostScript printing sometimes fails to spool all text.


Copyrights
==========
Magus is a registered trademark, and Magus PageTurner is a trademark, of 
Magus.  All other trademarks are the property of their respective owners.
