PsView is a PostScript file previewer. It can either use the Display PostScript extension of DIGITAL's X11 server (Ultrix Worksystem Software release 4.2 or higher) or the public-domain "ghostscript" PostScript interpreter (release 2.4 or higher).
PsView is designed to work very much like the xdvi DVI file previewer. The program works best on PostScript files that follow Adobe's structuring conventions (PS-Adobe-2.0). Other PostScript files can also be browsed, but then scrolling and paging backward are much slower.
The user gives commands to PsView using both the mouse and the keyboard. These commands can control the size of the page, the way the page is fit to the viewing window, the portion of the page selected for viewing, the way one page is replaced by another, and many other options. These are decribed in detail below. The "Help" and "?" keys give a quick on-line summary of these commands.
If the input file is "-", PsView reads the PostScript file from its standard input.
A special mode enables PsView to act as a PostScript display server (see "STREAM MODE" below).
If something goes wrong, consult the "REMARKS", "BUGS" and "BUG REPORTING" sections at the end of this manual page.
PsView works in four different viewing modes. The first one, called "full page mode", automatically adjusts the scale factor to make the entire page fit in the window whenever the window is resized. This mode is the default mode at startup.
The second one, called "full width mode", adjusts the scale factor to make the page occupy the window's full width.
The third one, called "full height mode", adjusts the scale factor to make the page occupy the window's full height.
Finally, "fixed scale mode" maintains the scale factor when the window is resized.
Full page mode and fixed scale mode will automatically resize (shrink) the window to reflect the document's aspect ratio, unless the "fixedGeometry" X resource is set to "yes", in which case, PsView will never attempt to change the window's size and position.
Note that the size of the window cannot exceed the size of the screen.
Viewing modes are selected through the "s", "f", "F", "w", "W", "h" and "H" commands (see "COMMANDS" below).
Every structured PostScript file has a bounding box defined in its prologue. PsView uses this bounding box to fit the page to the size of the window/screen. This bounding box is valid for the entire document. When the document has no bounding box, an A4 page format is assumed.
The document's default bounding box can be overridden by using the "-b" and "-B" command line switches (see below). It can also be changed dynamically by selecting part of the document using the mouse and holding down the "SHIFT" key. Selecting a portion of the document without holding down the "SHIFT" key displays, in the window's title bar, the bounding box corresponding to the selected rectangle, but does not change the document's bounding box. When the bounding box is changed, the scale factor is recomputed, full page mode is automatically turned on, and the window is refitted on the entire screen (i.e. the window is zoomed to the maximum size permitted by the new bounding box).
Bounding boxes changes are kept in a stack. You can revert to a previous bounding box by using the "r" (revert) command (see below for a detailed description of this command). The "SHIFT-DRAG" action can therefore be used as a (multi-level) zoom.
Selecting a region with your mouse while holding down the "CONTROL" key creates a new "Post-It" window sized and zoomed to the selected region. This command forks a new PsView process.
You can save the current bounding box of a file by using the "S" (save) command. A backup file named "file~" will automatically be generated in this case, unless the "backup" X resource is set to "no". Note that saving a bounding box does not change the way your document is printed, since a bounding box is only a PostScript commment. This feature can be used to select part of a figure for inclusion in a TeX/LaTeX document using the "\psfig" macro. Moreover, when you examine the file again using PsView, the new bounding box will be used.
It is possible to rotate the document by an arbitrary angle. You can either use the "-R" switch when starting PsView or change that angle dynamically using the "R" command (see "COMMANDS" below). Note that the angles are always specified in degrees and clockwise.
PsView automatically checks the PostScript file every second, and rereads it if it has changed. This way, you can launch PsView once and regenerate the file as you wish without losing your current settings. There is also a "U" (update) command to refresh the window.
This auto update feature can be disabled by using the "u" command, the "-u" switch, or the "autoUpdate" X resource (see "X RESOURCES" below). When "auto update" mode is disabled, "Up to date" is displayed in the title bar while the file is up to date, and "Out of date" is displayed when the file becomes out of date. When "autoUpdate" is disabled, you can reread the file by using the "u" command twice.
Note that since there is no clean way under Ultrix to know that a process is accessing a file, PsView attempts to "guess" that a process has finished updating a file by waiting for the modification time to stabilize. This might fail if the process does not write the file continuously. By default, PsView checks the modification time every two seconds. If this delay is too short, it can be changed through the "-D" switch or the "updateDelay" X resource (see below).
In any case, you are advised to update your PostScript files atomically, in which case you can safely set the update delay to 0. For instance, when generating files with "dvips", you should do the following:
%dvips file.dvi -o tmp.ps %mv tmp.ps file.ps
By default, PsView draws directly into the window, so that whenever the window is partially obscured, the entire page has to be regenerated by the PostScript interpreter. This mode is called "watch progress" mode, and is the default mode. It is very fast and "light".
There is also another mode, called "pixmap mode", that uses a pixmap buffer and therefore avoids update events. This mode is handy for files that take a long time to print, and is mandatory for unstructured files since redrawing the current page of an unstructured file would require reprocessing the document from the beginning. You should be aware that this mode consumes a lot of memory and might cause your X server to grow. The default mode can be specified by the "mode" X resource and overridden by the "-W" switch, which toggles the default mode.
Note that PsView never asks the X server to use backing store in "watch progress" mode unless the "backingStore" X resource is set to "no" (because of a bug in the DPS extension).
PostScript prologues can be specified through the "-I" and "-J" switches or through the "includeFile" X resource. A prologue can be any PostScript file, and doesn't have to begin with "%!". In stream mode, the prologues are sent to the PostScript interpreter before printing the first page, and every time the page has to be reprocessed. Note that every permanent modification of the transformation matrix and every function definition should be placed in the prologues.
The presentation mode ("-P" switch) can be used to display slides with a nice fade-out effect. Try it, you'll like it! In this mode, the left and right mouse buttons are used to go to the previous and next pages, and the middle mouse button is used to change the document's bounding box. Note: this mode turns on "pixmap mode" to allow the fade-out effect. Different effects can be specified (-P1 or -P, -P2, -P3). The default is -P1.
PsView automatically adds scroll bars when the entire page is not visible in the window. By definition, there are no scroll bars in full page mode, since the scale factor is adjusted so that the entire document fits in the window. To have scroll bars, you should therefore select one of the three other PsView modes using one of the "s", "w", "W", "h" and "H" commands.
In pixmap mode, PsView makes a smooth scrolling. When the scale factor is important, this feature can consume a lot of memory and cause your X server to grow. It can be disabled by setting the "smoothScrolling" X resource to "no", through the "-L" switch, or via the "L" command. Note that smooth scrolling is automatically disabled when the server is unable to allocate the requested pixmap.
The "constrainedGeometry" X resource can be used to force PsView to use the startup geometry as the default geometry every time the window is refitted to the entire screen ("F", "W", "H", "z", "R", and bounding box selection commands).
The "path" resource specifies a path to scan when opening files. The current working directory is always searched first. For each directory, PsView attempts to open the files "file", "file.ps" and "file.PS".
PsView can be customized using the X11 resources mechanism. These resources override the program's defaults, and can themselves be overridden using command line switches. Some boolean switches act as a toggle with respect to the default (either the program's default or the resource's default). For every toggle switch, such as "-C" for instance, an absolute value can be specified by specifying either "-C+" or "-C-".
See the "X RESOURCES" section of the manual page below.
The user can interact with PsView using the keyboard. Here are the keyboard commands.
PsView defaults can be specified using the following resources (defaults, where they exist, in brackets []):
PsView.autoUpdate: [yes] | no
PsView.backingStore: yes | [no]
PsView.backup: [yes] | no
PsView.bitmapImages: [yes] | no
PsView.clearPage: [yes] | no
PsView.clip: yes | [no]
PsView.constrainedGeometry: yes | [no]
PsView.engine: [dps] | gs
PsView.fixedGeometry: yes | [no]
PsView.smoothScrolling: [yes] | no
PsView.verbose: yes | [no]
PsView.watchProgress: [yes] | no
PsView.mode: [fullPage] | fullHeight |
fullWidth | fixedScale <scale>
PsView.pixmapFileName: <pixmap file name> [Pixmap]
PsView.postScriptFileName: <PostScript file name> [PostScript]
PsView.printCommand: <print command> [lpr %s]
PsView.scrollBarWidth: <width> [20]
PsView.updateDelay: <delay> [3]
PsView.boundingBox: x0 y0 x1 y1 (<style name>) ...
PsView.geometry: <geometry>
PsView.gs: <ghostscript executable>
PsView.helpFile: <help file>
PsView.includeFile: <prologue file>
PsView.path: <colon-separated path>
If the "clip" resource is set to "yes", the page is clipped to the document's bounding box (useful for rotated documents). This option is not available with ghostscript. Note that the location of the ghostscript executable, the help file, and the prologue file may be private or site-dependent. The print command is site-dependent (-P, etc.).
When no file name is specified at startup, or when a UNIX socket name is specified through the "-S" switch, PsView enters a special mode called "stream mode". This mode is meant to be used in conjunction with other programs to make PsView act as a PostScript display server. In this mode, every input datum (read either from the standard input or from the specified socket) is incrementally sent to the PostScript interpreter. When reading from a socket, PsView first deletes the socket if it already exists, creates a new socket, waits for a client to connect, and finally creates the display window.
Every "%%BoundingBox" specification is ignored in this mode, so the only way to specify a bounding box is either to use the "-b" or "-B" switches, or to interactively select a bounding box with "SHIFT-DRAG". The default bounding box corresponds to an A4 page format.
When a "showpage" is encountered, the page is erased, and the PostScript description of the current page internally kept by PsView is discarded. This mode is therefore single-page and acts as a real printer. Note that the "showpage" command be sent literally and musn't be called from another PostScript procedure. Finally, note that each atomic "write" to the input stream must be terminated by a complete PostScript token (i.e., word).
"Post-It" windows are not supported under this mode for obvious reasons.
Since streams are anonymous, the "S" (save) command will save the current page description in files named "PostScript000.ps", "PostScript001.ps". A different name can be specified through the "postScriptFileName" X resource.
Finally, you can force PsView to quit when the end of the input stream is encountered through the "-q" (quit) switch.
A special mode enables PsView to create a child window of a given window ("-#" switch). Under this mode, PsView adjusts the size of its window to the size of its mother window and keeps all the information about its internal state on the title bar ("WM_NAME" property) of its window, as follows:
<m***> PsView message or warning <fp>, <fw>, <fh>, <fs> Full page, full width, full height or fixed scale mode <s***> Scale factor <b***> Bounding box <R***> Rotation angle <f***> File pathname (none in stream mode) <P***> Page number <U+>, <U-> AutoUpdate mode <W+>, <W-> Watch progress <I+>, <I-> Bitmap images <L+>, <L-> Printable file <S->, <S+> Smooth scrolling <r->, <r+> "Revert stack" non empty <p->, <p+> Previous page? <n->, <n+> Next page?
PsView should work fine with properly structured files. You can work with unstructured PostScript files, but the results are not guaranteed. In particular, the last page of a PostScript document shouldn't close the working dictionary ("end" command) before the "%%Trailer" comment, or some of the prologue-defined commands might become undefined, in which case you would get the following message:
%%[ Error: undefined; OffendingCommand: <command> ]%%
Files starting with "PS-Adobe-1.0" are considered unstructured by PsView. But in many cases, you can get a structured file just by changing the "1.0" suffix into "2.0". This will be much more pleasant to work with.
Finally, PsView interacts a lot with the window manager to find out the size of the title bar and the window's border width, and attempts to enforce its desired window's placement. This implies that PsView is not, strictly speaking, a well behaved X application. Therefore, PsView should not be used without running a not-too-exotic, ICCCM-compliant window manager. PsView has has been successfully tested under the following window managers: mwm, twm, tvtwm, gwm and dxwm. Note that since dxwm doesn't allow applications to iconify/deiconify windows, PsView will always starts iconified under dxwm.
You should be aware that the "clippath" operator in a Display PostScript context (as opposed to a printer context) will return a path corresponding to the current window, but not the path corresponding to the page. Therefore, well behaved PostScript documents should avoid using "clippath" to determine the page size of the printing device, and "intelligent" documents trying to automatically adjust their scale factor and position to the page size will not behave as expected when browsed using PsView. In particular, some "troff" prologues use the "clippath" operator. In such a case, try changing the "/useclippath true def" line into "/useclippath false def", or create a file "clippath.ps" containing:
/clippath{newpath00moveto0800lineto550800lineto5500
linetoclosepath}binddef
and include it in the prologue:
psview-Iclippathfoo.ps
If your document prints fine but cannot be correctly browsed using PsView, it is almost certainly the case that the PostScript is not properly structured. There is unfortunately almost nothing that can be done automatically to correct this. For instance, the following ill-behaved structured file will print correctly, but the scale factor will double every time the window is refreshed.
%!PS-Adobe-2.0 %%BoundingBox: 0 0 100 100 %%Page: 1 1 2 2 scale 0 0 moveto 50 50 lineto stroke %%TrailerNote that this file will behave correctly under the "unstructured mode" ("-U" switch), since a new Display PostScript context will be started every time the page is reprocessed. To make this file behave correctly under the "structured mode", a save/restore pair should be added at the beginning and at the end of the page description, as follows:
%!PS-Adobe-2.0 %%BoundingBox: 0 0 100 100 %%Page: 1 1 /SavedState save def 2 2 scale 0 0 moveto 50 50 lineto stroke SavedState restore %%Trailer
If PsView crashes your X server (and your working session for that matter), chances are that this is not PsView's fault but rather a server bug. These bugs should be reported to the X server developers.
Please make sure that your PostScript file is not faulty before sending a bug report. A good way to do this is to run PsView on a PostScript file generated by a different tool ("dvips" is a good candidate).
xpsview(1)
PostScript Language Reference Manual
PostScript Language Tutorial and Cookbook
PostScript is a trademark of Adobe Systems Incorporated.
Name: Francois Bourdoncle Organization: Ecole des Mines de Paris Email: Francois.Bourdoncle@ensmp.fr Home Page: http://www.ensmp.fr/~bourdonc