GView 1.52 (08-May-06)

Purpose:     GhostScript front-end
Author:      Martin Wrthner
Runs under:  RISC OS 3.1 or higher, tested under RISC OS 4, Adjust and 5,
             runs on the Iyonix and the A9Home.
Requires:    GhostScript (5.10 or higher, 6.01 or later preferred, 8.50 or
             later recommended, tested with 7.03, 8.50, 8.53), ChangeFSI,
             quite a bit of memory and processing power
Status:      FREEWARE (see [7] below)
             Please donate to support its development! (see [7] below)
WWW:         http://www.mw-software.com/software/gview/gview.html

GView is a front-end for GhostScript, a free PostScript and PDF interpreter.
GhostScript has been ported to RISC OS by Graham Jones and is available from
  http://www.acornusers.org/ghostscript/
A 32-bit version of the GhostScript executable only is available from
  http://www.mw-software.com/software/ghostscript/ghostscript.html
(you still need the rest of the GhostScript distribution from Graham's site).
This executable allows GhostScript to run on all RISC OS platforms including
all 26-bit platforms, the Iyonix and the A9Home.

GView turns GhostScript into a full desktop PostScript and PDF previewer. It
allows you to view individual pages of PostScript and PDF documents and save
them as sprites. GView can also turn multi-page PostScript and PDF files into
series of sprite files.

NEW: GView 1.50 allows PDF files to be viewed.

NEW: GView 1.41 allows EPS files to be viewed.
NEW: GView 1.30 multi-tasks when scanning the document, when processing the
     current page using GhostScript and when converting a whole range of pages
NEW: GView 1.20 uses GhostScript's new Sprite device for monochrome, 256 colour
     and 16 million colour images. This is considerably faster than feeding the
     image through ChangeFSI as previous version did. Other colour depths still
     use ChangeFSI. There is also a new "Greyscale" option.

1) Main features
================
GView offers the following features:
- handles multiple PostScript and PDF files simultaneously
- can be used to view PDF files that other RISC OS viewers cannot display, most
  notably files that just display random characters in other viewers
- displays each document in a separate window
- displays the number of pages the document contains in the title bar
- renders documents in monochrome, 16 colours, 16 grey scales, 256 colours,
  256 grey scales, 32 thousand or 16 million colours (more than 256 colours
  available only with RISC OS 3.5 or higher)
- runs in any screen mode

It allows you to:
- specify the desired resolution of the resulting Sprite
- move to the previous or next page
- jump to any page directly
- save single pages as Sprites
- save a range of pages of the document (or the whole document) as Sprites
- specify the page size and orientation
- scale the resulting sprite interactively

Although the name may suggest a connection with ghostview, which is available
for UNIX machines, the connection between GView and ghostview is only in
similar functionality and GView does not borrow any code from ghostview.

In order to use a PostScript document with GView, it must obey the Adobe
Document Structuring Conventions (DCS). Most PostScript files containing
multiple pages do conform to this convention, e.g. those produced by the
RISC OS PostScript printer driver.

GView and PDF files
-------------------
There are other PDF viewers for RISC OS, so why would you want to use GView?
The answer is that in general, you would not use GhostScript/GView for PDF
files because other previewers offer more features (most notably, Draw export)
and operate much faster. There are, however, documents that neither !PDF nor
RiScript can handle. For instance, there are  documents that display random
characters only (this happens when TrueType font subsets are embedded, which
the other viewers cannot handle), so using GhostScript/GView is the only way to
display these documents under RISC OS. In addition, GhostScript supports some
advanced PDF features that the other viewers do not support, most notably
graduated fills and all types of clipping.

2) Installation
===============
GView is useless without GhostScript, so if you do not already have a working
GhostScript setup (including fonts), there is no point in trying to use GView.
The recommended version of GhostScript to use is 7.03. At least version 6.01 is
required if you want to use the "Use GhostScript sprite device" option of GView
or if you want to set the anti-aliasing values to any other than 0. Older
GhostScript distributions may work as well, but some very old versions may
crash with certain combinations of options. Please do not ask me what to do if
your version of GhostScript does not work. The latest version of GhostScript
can be found at http://www.acornusers.org/ghostscript/. If you intend to run
the software on a 32-bit version of RISC OS (i.e., RISC OS 5 on the Iyonix or
on the A9Home), you also need to download the 32-bit version of the ghostscript
executable from http://www.mw-software.com/software/ghostscript/ghostscript.html.

3) Usage
========
On start-up GView checks whether GhostScript and ChangeFSI have already been
seen by the Filer. If not, GView refuses to start. Display a Filer window
for the directories containing GhostScript and ChangeFSI first or make sure
they are *Filer_Booted by your boot sequence.

In order to view a PostScript file, double-click on it or drag it to the GView
icon on the icon bar (make sure that is has the correct filetype or GView will
reject it).

In order to view a PDF file, drag it to the GView icon on the icon bar. If the
choices option "Claim PDF files" is ticked, you can double-click on PDF files
as well in order to display them using GView.

In either case, GView will open a window displaying the first page of the
document. If not, please see below "If things go wrong".

The title bar of the window shows the file name and the two numbers [a/b]
where a is the current page number (sequential, not logical) and b is the
total number of pages in the document.

You can go to the next or previous page by pressing Page down (or DOWN) or
Page up (or UP) respectively. You can scroll the current page to the top or
bottom by pressing the arrow Up and Down keys.

The main menu entry 'Goto' allows you to go to any page immediately by entering
the number in the writable field and pressing Return (or clicking on OK). Note
that again, the number you enter is the sequential (i.e. physical) page number
as opposed to the logical page number that might appear on the page.

Other main menu entries are: 'Next page', 'Previous page' (obvious) 'Save' and
'Zoom'. 'Save' allows you to save the current page only as a Sprite file. If
you want to convert the whole document into a series of Sprites, use
'Document => Save' instead (see below). Note that the colour depth of the
Sprite is the one you have chosen in 'Choices...' (from the icon bar menu).
'Zoom' leads to a standard RISC OS magnifier box that allows you to scale the
sprite. Please note that this only scales the representation that has already
been computed, it does not recompute the sprite at a higher resolution. If you
want to do that, you have to change the resolution in the 'Choices' box and
choose Document => Reprocess from the main menu, see below.

The 'Document' sub-menu leads to a document info box ('Info') and three entries:
'Save', 'Reprocess' and 'Reread file'.

Whenever a document is first loaded, the current settings in the 'Choices'
dialogue box are taken and are then bound to the window even if the values are
modified later. The 'Reprocess' menu item forces the current values (as entered
in the 'Choices' box and confirmed by clicking on 'OK') to be read and to
replace the values that were in effect when the window was first opened. So, if
you want to change the colour depth of a window, simply modify the setting in
the 'Choices' box, click on 'OK' and then choose 'Reprocess'. This causes the
current page to be reprocessed with the new settings. Changing screen mode does
not automatically change the colour depth of open windows (although increasing
the colour depth might mean that open windows are displayed in better quality)
unless the colour depth setting was 'Current' when the document was loaded. In
this case, the next page which is processed after a mode change has the new
colour depth.

In contrast, 'Reread file' retains the settings for the document, but forces
the PostScript file to be reread from disc. Usually, this is not necessary
because GView notices when the file has changed on disc and rereads it
automatically. However, this is only done when you go to a different page in
the document, so this menu entry allows you to redisplay the current page from
the changed file on disc. You also need to use this option if the file has
changed and you want to use the 'Save' entry (see below) before displaying any
pages from the changed file in a window: The 'Save' entry displays an error if
the file on disc differs from what is displayed in the window and asks you to
use the 'Reread file' menu entry first.

The 'Save' entry in the 'Document' sub-menu is very powerful in that it allows
you to specify a range of (physical) pages to save. Drag the directory icon
to the destination directory and the pages are saved as files 'Page000',
'Page001', 'Page002 etc. into that directory. This feature is similar to the
one in DVIView (by Paul Field) where I got this idea from. The colour depth of
the generated sprites is that of the window.

Choices
-------
In the 'Choices' dialogue box (obtained by choosing 'Choices...' from the icon
bar menu or by clicking Select on the icon bar icon) you can specify the
default colour depth, paper size and page orientation to be used for newly
loaded documents. If you do not know the paper size to be used, you can select
'Unspecified'. This will cause GhostScript to use whatever its default is
(might be 'Legal' which is normally not a good guess or GhostScript might read
the paper size from the document). The best option is usually to set it to A4.
You can change the paper size later by changing it in the 'Choices' box and
choose 'Document => Reprocess' from the document's main menu.

Note that a 'Custom' paper size sometimes conflicts with the paper size
specified in the PostScript document. This will cause GhostScript to report
a "configurationerror --setpagedevice-- Additional information: [/PageSize
xxx xxx]". If this happens, simply select 'Unspecified' as paper size and
things should work OK. If you definitely want to override any paper size
information in the PS document, then you can switch on 'Ignore document size
info'. This forces GhostScript to use the paper size you specify.

There are three orientations. 'Portrait' should be obvious. 'Landscape' is the
sort of landscape printing Impression does, i.e. the page is rotated by 90
anticlockwise. If your document appears the wrong way round with 'Landscape',
try 'Seascape' which rotates the page in the opposite way. Note that the
'Width' and 'Depth' parameters in the paper size group always refer to the
dimensions of the portrait page, so they do not change if you select
'Landscape' or 'Seascape'.

The 'Colour depth' settings determine the number of colours used for the bitmap
GhostScript is asked to generate. This need not be the same as the colour depth
currently used on screen, however by selecting 'Current' you can force this to
happen.

Note that you can speed up the application considerably by choosing a small
colour depth. For most documents (manuals etc.), monochrome should be enough.
This also reduces memory usage.

If you switch on "Greyscale", then the output will contain shades of grey only,
i.e. "16 colours" then effectively means "16 greys" and "256 colours" means
"256 greys". Combining "Greyscale" with "monochrome", "32 thousand" or "16
million" has no effect.

Beneath the colour depth options, you can find the resolution options. You can
either specify the resolution in dpi (dots per inch, where 90 dpi is the
value that renders the PostScript file at its original size) or as a percentage
scaling factor. Please note that in contrast to the scaling factor you specify
in the Zoom dialogue box when finally viewing the Sprite file afterwards, this
scaling really determines the size of the computed bitmap, so if you specify a
high value in the 'dpi' or '%' field, you should have the required amount of
free memory. The radio icons in front of the 'dpi' and '%' input fields can be
used to switch between the two ways of specifying the resolution.

The "anti-aliasing" options allow you to specify the number of alpha bits that
are used for anti-aliasing text and graphics. The maximum number is 4 and there
is rarely any reason for using any less than that. So, normally, you should
leave these values at 4. Anti-aliasing is automatically switched off by GView
if you use "monochrome" or "16 colour" output because there are not enough
grey scales available to do it properly.

If the "Use GhostScript sprite device" button is enabled, then GView will try
and use the new sprite device available in GhostScript 6.01 or higher. This
speeds up the rendering process considerably because, in most cases, there is
no need to call ChangeFSI to postprocess the image.

Please note that currently there are only sprite devices for "monochrome",
"256 colours" and "16 million". If you choose any other colour depth (or if
you choose "Use current" and the current colour depth is none of the above),
then ChangeFSI still has to be called, so using the sprite device does not help
much.

There is a small drawback when using the Sprite device: Normally, ChangeFSI is
used to rotate the image if the orientation is not portrait. If, however, the
ChangeFSI call can be avoided, then GView will rotate the image itself. This
slows down the redraw of the displayed page because the rotation is done on the
fly when redrawing. If redraw is too slow for you try switching off the "Use
GhostScript sprite device" option. Then, the rotation will take place in
ChangeFSI (which, of course, takes even longer, but only once).

Normally, GhostScript only produces textual output when there is an error.
However, some (rare) PostScript files cause GhostScript to produce textual
output and still produce the desired bitmap output as well. Previous versions
of GView refused to process such files because the textual output was
interpreted as an error message. If the option "Continue after GhostScript
error" is set, GView will attempt to process the output file from GhostScript
even after there has been textual output from GhostScript. This option should
not normally be set.

If memory is tight, it is worth switching on the option "Close window before
processing next page". If this option is set and you move from one page in the
document to another, then the current page is discarded from memory before the
next page is being processed. This makes more memory available to processing
the next page (this is how previous versions of GView used to work). If you
have enough memory, then it is better to leave the option unticked because
then, you can still read the current page while the next one is being
processed.

Since there are other PDF viewers for RISC OS, GView does not claim
double-clicked PDF files by default, so you need to drag PDF files to the GView 
icon on the icon bar to view them. If the option "Claim PDF files" is ticked,
then GView will display double-clicked PDF files, but only if it is already
running. If you want double-clicked PDF files to launch the GView application,
you need to modify GView's !Boot file (see instructions in the !Boot file).

The 'Default' button resets the dialogue box to the recommended default
options.

The 'Save' button allows you to save the settings as the default to be used
next time GView is launched. This is particularly important if you launch GView
by double-clicking on a PS document as the default choices will be used to
process this document.

4) If things go wrong
=====================
GView has a very rudimentary error handling. Basically, it simply calls
GhostScript and if the requested output file exists after the call has
returned, GView assumes that everything was OK and passes it to ChangeFSI.
After the call to ChangeFSI has returned, GView reads the generated Sprite
file. If either GhostScript or ChangeFSI report an error, then it is likely
that there was something wrong with the PostScript file. Errors reported by
GhostScript are displayed in a text window.

Check whether you have enough space in !Scrap. This is particularly important
if you have chosen 32 thousand or 16 million colours as in this case GView will
ask GhostScript to generate a 24bpp representation of the image which can take
lots of disc space. In addition to the .PCX (or .PPM) generated, there must be
enough space for the Sprite generated by ChangeFSI. To render an A4 page at a
resolution of 90 dpi in 16 million colours, you need about 11M of free disc
space!

If the PostScript file contains the paper size, then GhostScript will report
an error if you specify a differing 'Custom' paper size. In case of doubt
select 'Unspecified'.

Memory can be a problem, too. If GhostScript complains because of a lack of
memory then increase the value in the "GhostScript WimpSlot" field in the
Choices window. If ChangeFSI complains, then try increasing the slot given to
it in the file !GView.!CFSI. Note that they run one after another, so you need
only the maximum of both values as free memory, not the sum. When modifying
the *Wimpslot command in !CFSI make sure you do not change anything else! Take
a backup copy of the original file before modifying it.

Please do not contact me if you have problems setting up GhostScript in the
first place. As said above, there is no point in using GView unless GhostScript
works already. If GView fails, try rendering the document using the GhostScript
command line. If that works, then there is a GView problem and I will be happy
to solve it. However, if the command-line driven GhostScript fails as well,
then you have a problem with your GhostScript setup.

If GhostScript does not report an error but does not produce an output file
either, then GView reports 'Cannot find GhostScript output file'. The most
common problem in this case is that the file is an EPS file without a
'showpage' command at the end. Adding a line reading 'showpage' at the end of
the PS file solves this problem in most cases.

5) History
==========
1.52 (08-May-06)
- default slot size for GhostScript is 3500k if there is no configuration file
- if GhostScript$Version is set and 8.x or higher, then the slot size read from
  the configuration file is raised to 3500k automatically

1.51 (07-Feb-06)
- detects maximum WimpSlot size rather than assuming it is 28MB - allows larger
  pages to be viewed on systems supporting it (only the Iyonix at the moment)
- different "WimpSlot limit exceeded" error messages for non-RO5 systems and
  the Iyonix (which is only limited when Aemulor is running)
- bitmap file in Scrap is removed immediately after the above WimpSlot error

1.50 (03-Feb-06)
- allows PDF files to be viewed
- added "Claim PDF files" option
- uses StubsG and hence runs on all RISC OS platforms without the need to
  install a specific SharedCLib
- while application is busy the choices window cannot be opened
- error window capacity increased to cope with longer error messages
- error buffer is terminated correctly if the GhostScript error message is
  longer than the buffer space of the error window

1.41 (21-Apr-04)
- allows EPS files to be viewed
- no longer displays an error if its internal Choices file is not found - this
  means that the application can be distributed without a choices file making
  it less likely that users overwrite their Choices files when upgrading

1.40 (08-Jan-03)
- first 32-bit safe release, requires 32-bit SharedCLibrary

1.31 (25-Sep-02)
- 'Document => Reread file' menu entry added
- GView notices if the PostScript file has changed on disc when you move to
  another page and rereads the file if necessary
- GView notices if the PostScript file has changed when you start a 'Save'
  operation for a range of pages and advises you to choose 'Reread file' first
- Select click on icon bar icon opens the Choices box
- Setting text or graphics anti-aliasing bits to 0 caused a GhostScript error -
  this has been fixed
- Default button correctly deselects Scaling radio button
- Appropriate error message if the sprite is too big to be displayed (bigger
  than RISC OS application slot limit)
- Sprite file is not left open if GView runs out of memory when reading it
  (prevented further operations in GView in older versions)

1.30 (30-Jul-02)
- initial document scan multi-tasks
- GhostScript is called via the TaskWindow module and thus multi-tasks
- fixed problems with certain combinations of output parameters (e.g., 16
  colours, greyscale and "Use GhostScript sprite device") and with page
  orientations other than Portrait in conjunction with "Use GhostScript sprite
  device")
- the complete GhostScript output is shown in a proper text window instead
  of being shown truncated in a Wimp error box
- added "Continue after GhostScript error" option
- added "Close window before processing page" option
- finally got rid of all command line length problems

1.20 (28-Sep-00):
- uses GhostScript sprite device
- allows the number of AlphaBits for text and graphics rendering to be
  specified
- new greyscale mode
- allows the memory slot size for GhostScript to be specified
- many internal changes

1.11 (31-Jul-00):
- corrected Templates, so the resolution radio icons can be selected
  independently from the colour depth radio icons
- corrected date in 'Version' field of info box

1.10 (06-Feb-00):
- resolution field in the Choices dialogue box
- Return key works properly in Choices dialogue box
- added 'Ignore document size info' button

1.01 (02-Jun-98):
- scale dialogue box added (document menu entry 'Zoom')
- Up/Down arrow keys (scroll to top/bottom of page)
- 'Goto page' dialogue box has up/down arrows
- GView traps double-clicks on PS files (both when seen by the Filer and while
  it is loaded)

1.00 (27-May-97):
- first public release

6) Credits
==========
Many thanks to Dominik Symes and Darren Salt for Zap, to Paul Fields for
DVIView from which I borrowed several good ideas for this application, to
Michael Dennis-Biemans for porting GhostScript 4.03, to Graham Jones for
porting GhostScript 5.10 to 7.03, to Dick Alstein for TemplEd and to Acorn
Computers for the DrawFile module which is used by GView.

Acknowledgements
----------------
PostScript is a trademark of Adobe Systems Inc.
UNIX is a trademark of AT&T.
The DrawFile module used by this application is  Acorn Computers Ltd.

7) Copyright message
====================
This application, GView, is  Martin Wrthner, 1997-2006 and is FREEWARE.
This means that you may copy it freely provided that
(a) all files of this application are distributed together without
    modification
(b) this application is not sold for profit without my explicit written
    permission (this includes distribution on CD)

This application contains the DrawFile module which is  Acorn Computers Ltd.

This software is FreeWare, so you are allowed to use the application without
paying anything. However, if you want to support the further development of
this application, please send a cheque for 10 Pounds (payable to Martin
Wuerthner) to me or make an online donation with your credit card (see the
GView home page http://www.mw-software.com/software/gview/gview.html for
details).

Contacting me
-------------
Martin Wuerthner
Mannheimer Str. 18
67655 Kaiserslautern
Germany

Phone: +49-(0)631-3608205
Fax:   +49-(0)631-3608203

e-mail: martin@mw-software.com
WWW:    http://www.mw-software.com/
