1 What is GraphPS ?

GraphPS is a Caml library that generates PostScript files from Caml graphics drawings.
With GraphPS you can print your Caml drawings or easily incorporate them into another document.

GraphPS provides a module similar to the usual graphics drawings module Graphics of the regular Caml distribution. This module, also named Graphics, has (almost) the same signature as the original Graphics module. Thus, using the GraphPS Graphics module, your Caml drawing programs transparently generate PostScript files (that can be encapsulated into TeX or L^AT_EX files), instead of drawing graphics directly onto the screen. You can also use GraphPS to send your drawings to a PostScript interpreter or print them on any printer that understands PostScript or for which gs has a driver.

2 Download and Licence

GraphPS is distributed under the LGPL license.

You can freely obtain the latest version of GraphPS from the following URL:

ftp://ftp.inria.fr/INRIA/Projects/cristal/caml-light/bazar-ocaml/graphps-1.2.tar.gz.

3 Using GraphPS

3.1 The overall picture

Intended usage of this library could be seen as a three phases process:

write a regular Caml program (either batch or interactive) using the regular Graphics library.
use the GraphPS library instead of the regular Graphics library (for instance you can just change the Caml library load path to obtain linking of GraphPS in place of Graphics). Recompile your Caml program to obtain a new executable that produces PostScript commands instead of Graphics commands.
run the new executable to produce a PostScript file that exactly corresponds to the drawing produced by your Caml program.

3.2 Generation a file with GraphPS

A PostScript program corresponding to your Graphics sequence of commands is printed to the standard output of the program when close_graph () is evaluated (hence your program should normally end by close_graph ()).

Manual production: simply redirect the output of the program to whichever file you want. GraphPS generates encapsulated PostScript files, which means that a so-called bounding box (that gives the size of the drawing) is calculated and inserted at the beginning of the PostScript file to help L^AT_EX to insert it into the document. Hence you should normally redirect to a .eps suffixed file.
Automatic generation of files: whence the program generates the correct drawing, you can specify to GraphPS the file you want to create, either a PostScript or an encapsulated PostScript file:
- open_ps : string -> unit Opens the file where the PostScript code corresponding to the Caml drawing is written. At the end of the Caml program, this file will contain a stand alone PostScript file, suitable for direct visualization or printing.
- open_eps : string -> unit Opens the file where the encapsulated PostScript code corresponding to the Caml drawing is written. At the end of the Caml program, this file will contain an encapsulated PostScript file, suitable for insertion into a TeX file.

4 Using the PostScript files produced by GraphPS

4.1 Direct visualization

You can visualize directly the files using any PostScript visualizers, for instance ghostview, gs, or gv.

4.2 Including PostScript files into your L^AT_EX files

This is not exactly a GraphPS problem, but a simple example may help to solve this L^AT_EX problem.

A very simple way to include your caml_drawings.eps file, is as follows:

use the graphicx package of L^AT_EX, writing the following line into your L^AT_EX document:
```
\usepackage[dvips]{graphicx}
```
then order L^AT_EX to include the caml_drawings.eps file into the document by writing the line:
```
\includegraphics{caml_drawings.eps}
```

For instance, the following line will draw the drawings of the file euro.eps, centered in the current line.

\centerline{\includegraphics[width=10cm]{euro.eps}}

5 Fonts

The fonts suitable for PostScript output are not the X fonts. Hence, when drawing characters, you must set the font to one of the available PostScript fonts, that is one of:

Times, Times-Bold, Times-Italic, Times-BoldItalic, Times-Roman,
Courier, Courier-Bold, Courier-Italic, Courier-BoldItalic,
Helvetica, Helvetica-Bold, Helvetica-Italic, Helvetica-BoldItalic.

If you try to set the font to something else GraphPS will emit a warning and raise Failure with argument set_font.

6 Trouble shooting

6.1 Caml problems

Most of the time, your original Caml program should work just fine with no modification when using the Graphics module provided by GraphPS.

However, some Graphics commands are not supported by the GraphPS library, since they have no meaning for PostScript files (e.g. mouse events handling commands). If the original program uses such commands, you should remove them.

6.2 PostScript problems

To ensure proper inclusion of generated PostScript files, GraphPS does not add any showpage order at the end of the file.

If you want to send the produced PostScript file directly to a PostScript printer, you may be obliged to add a showpage order at the end of the file.

This document was translated from L^AT_EX by H^EV^EA.