NAME
pslib - Library to create PostScript files
DESCRIPTION
pslib is a library to create PostScript files with a set of about 50
functions for line drawing, text output, page handling, etc. It is
very similar to other libraries like panda, cpdf or pdflib which
produce PDF. pslib can to a certain degree replace those libraries if
the PostScript file is converted to PDF with ghostscripts excellent pdf
writer. The results achieved with pslib can be even better when it
comes to text output, because it supports kerning, ligatures and
hyphenation.
pslib is a C-library but there are bindings for Perl, Python, Tcl and
PHP. This documentation will only describe the functions of the C-
library, though most of what is said here can be applied to the other
language bindings. The PHP extension of pslib is documented in PEAR.
The extension is called ps.
GETTING STARTED
Programs which want to use pslib will have to include the header file
libps/pslib.h and link against libps. Before doing any document
creation the library should be initialized with PS_boot(3). It will set
the locale and selects the messages in your language as defined by the
environment variable LC_ALL. Your locale settings will affect
hyphenation which uses isalpha(3) and tolower(3) to prepare the word
for hyphenation. German umlauts will be filtered out if the locale is
not set properly. The library should be finalized by PS_shutdown(3).
A PostScript document is represented by a pointer to PSDoc. Such a
document can be created with PS_new(3) and destroyed with PS_delete(3).
PS_new(3) returns a pointer to PSDoc. You can handle several documents
at the same time. The following example will do the basic preparation
without creating a document on the disk.
...
#include <libps/pslib.h>
main(int argc, char *argv[]) {
PSDoc *psdoc;
PS_boot();
psdoc = PS_new();
PS_delete(psdoc);
PS_shutdown();
}
In order to actually create a PostScript document on disk you will have
to call
int PS_open_file (PSDoc *psdoc, const char *filename);
or
int PS_open_fp (PSDoc *psdoc, FILE *fp);
PS_open_file(3) will create a new file with the given file name, while
PS_open_fp(3) will use an already open file. Both require a pointer to
PSDoc.
If the document shall not be created on disk but in memory, which can
be very handy in web application, one can use
int PS_open_mem (PSDoc *psdoc, (*writeproc) (PSDoc *p, void *data,
size_t size));
The second parameter is a function which is called instead of pslib’s
own output function.
Extending the previous example with one of the former three functions
to open a document will at least create an initial empty PostScript
document. It has to be closed with PS_close(3). PS_close(3) will only
close the file if it was opened by PS_open_file(3).
...
#include <libps/pslib.h>
main(int argc, char *argv[]) {
PSDoc *psdoc;
PS_boot();
psdoc = PS_new();
PS_open_file(psdoc, "test.ps");
PS_close(psdoc);
PS_delete(psdoc);
PS_shutdown();
}
There are more sophisticated funktions to start a new PostScript
document. They are used when error handling and memory management shall
be controlled by the calling application. Check the manual pages
PS_new2(3) and PS_new3(3) for a detailed description or read the
section about memory management and error handler below..
PAGE HANDLING
A PostScript document contains one or more pages. pslib provides the
function
int PS_begin_page (PSDoc *psdoc, float width, float height);
and
int PS_end_page (PSDoc *psdoc);
to start a new page with the given size in points and to end a page.
All functions that draw any visible output will only work within a
page. The page size has no meaning for the PostScript interpreter but
will be used by ghostscript or Acrobat Distiller to set the page size
in the PDF document. Some PostScript viewer also use the size to resize
the output window.
Starting the first page of a document will internally end the
PostScript header. This may have impact on resource handling. For more
information see the section about resource handling.
COORDINATE SYSTEM, SCOPE
PostScript defines a coordinate system with its origin in the lower
left corner of a page. Its base unit is point which is 1/72 of an inch.
Unless the coordinate system is scaled all values will be expected in
point.
pslib provides many functions which may not be called at any time. For
example, drawing and text output functions may only be called within a
page, path constrution functions may only be called within a path.
pslib defines so called scopes which are checked before executing a
function. Those scopes are prolog, document, page, pattern, template,
path and object. If for example, one tries to output text outside of a
page or within a path, then an error will be issued.
DRAWING, PATH CONSTRUCTION
PostScript does not have any functions to draw a line directly but uses
a two pass mechanism. First a path is constructed which is then drawn
(stroken). The path can also be used for filling an area or to clip
further drawing. A path must not be a continues line, it may consist of
several subpaths.
Each path is started with
void PS_moveto (PSDoc *psdoc, float x, float y);
If this function is called within a path, it will just start a new
subpath. The path can be constructed with one of the following
functions.
void PS_lineto (PSDoc *psdoc, float x, float y);
void PS_rect (PSDoc *psdoc, float x, float y, float width, float
height);
void PS_circle (PSDoc *psdoc, float x, float y, float radius);
void PS_arc (PSDoc *psdoc, float x, float y, float radius, float alpha,
float beta);
void PS_arcn (PSDoc *psdoc, float x, float y, float radius, float
alpha, float beta);
void PS_curveto (PSDoc *psdoc, float x1, float y1, float x2, float y2,
float x3, float y3);
Once a path is constructed it can be optionally closed by
void PS_closepath (PSDoc *psdoc);
Closing a path means to add a segment from the last point to the
starting point of the path. It is helpful if an area is to be filled.
In most cases the path is used for drawing which is done with
void PS_stroke (PSDoc *psdoc);
In such a case you would not want to close the path. As already
mentioned a path can also be filled or even both with the functions.
void PS_fill (PSDoc *psdoc);
void PS_fill_stroke (PSDoc *psdoc);
PS_fill_stroke(3) does first fill and than stroke a path. This is
important to realize because the stroken line may cover parts of the
filled area, depending on how wide it is.
TEXT OUTPUT
Text output is definetly one of the strongest parts of pslib. pslib
supports kerning, protusion, ligatures and hyphenation. All of it is in
a wide range customizeable by parameters. The hyphenation algorithmn is
based on the one used by TeX without the ability to take a whole
paragraph into acount.
Text output requires at least the Adobe font metric files, even for the
standard PostScript fonts. pslib has not, like other libraries, the
font metrics for the standard fonts compiled in. They are freely
available in the internet. If the font is to be embedded into the
document, then the font outline (.pfb file) is also needed.
Additional files are needed for more sophisticated text output. It
will be explained later in this documentation.
Before being able to output any text a font has to be loaded with
int PS_findfont (PSDoc *psdoc, const char *fontname, const char
*encoding, int embed);
It returns a unique id for the font. The fontname is the filename of
the Adobe font metrics file without the extension .afm. If the font
shall be embedded into the document, then the last parameter must be
set to 1 and the file fontname.pfb must be present.
The encoding specifies the font encoding to be used in the PostScript
document. It defaults to TeXBase1, which is a reasonable set of glyphs
covering most western languages, when the empty string or NULL is
passed. The special encoding ’builtin’ stands for the encoding as
provided by the font itself. It is usually AdobeStandardEncoding which
is a smaller set of glyphs than TeXBase1. If unsure leave the encoding
parameter empty.
Calling PS_findfont(3) is a sensitive matter. Thought it may be called
in almost every scope it is highly recommended to call it either within
a page or before the first page (within the prolog). Especially when
the font is to be embedded or uses a non default encoding. This
limitation has to be enforced in order to be able to extract certain
pages from the document without corruption. Programs like psselect
extract a page by taking the prolog of the PostScript document and the
selected page. Resources, like fonts, not being part of the page or the
prolog will not be included into the resulting document and using those
resources will provoke errors. pslib will output a warning in case of
potential problems.
int PS_setfont (PSDoc *psdoc, int fontid, float size);
sets the font which was loaded with PS_findfont(3) in a given size.
After calling this function everything is prepared to output text with
one of the following functions. Each text output function uses kerning
pairs and ligatures if available.
int PS_show (PSDoc *psdoc, const char *text);
outputs text at the current text position and moves the x position to
the end of the text. If text is to be output at a certain position on
the page the function
int PS_show_xy (PSDoc *psdoc, const char *text, float x, float y);
can be used. Both functions also exist in a version which requires the
length of the string as the third parameter. The are called PS_show2(3)
and PS_show_xy2(3).
The functions mentioned so far will print all text into one line. If
one would like to wrap a longer text into a box, the function
int PS_show_boxed (PSDoc *psdoc, const char *text, float left, float
bottom, float width, float height, const char *hmode, const char
*feature);
should be usesd. It breaks the text into lines of length width and
fills the box until there is no space left. The function returns the
number of remaining chars which did not fit into the box. This number
can be used to create a second, third, ... box for the remaining text.
Text can be left and/or right justified or centered depending on the
parameter hmode. Hyphenation is turned off by default, because it
needs to be set up before it can be used.
Once again, working with fonts is an error prune issue, because it is
important at what position in the document the fonts are loaded. At a
rule of thumb you should load fonts which are used on several pages of
the document before the first page, and fonts only used on a single
page within that page. For a more detailed discussion see the section
on resource handling.
HYPHENATION, KERNING, LIGATURES, PROTUSION
pslib’s advanced text output features cover hyphenation, kerning,
ligatures and protusion. Kerning and ligatures are turned on by default
and will be used if the current font supports it. Some ligatures are
built into pslib, just in case the font has the glyphs but misses the
command to build the ligature. Those ligatures are fi, fl, ff, ffi, and
ffl. Both ligatures and kerning can be turned off by setting the
parameter ’ligature’ respectively ’kerning’ to false. pslib
automatically inserts a ligature if the character sequence of that
ligature is found. If a ligature is not to be used then its character
sequence must be broken up with a broken bar character. Ligatures will
never be used if charspacing has a value unequal to zero.
If a font provides more ligatures as those mentioned before, they are
usually at places not conform to the Adobe Standard Encoding. There
glyph name is often the name of the glyph supposed to be at that
position in the Adobe Standard Encoding. pslib can utilize those
ligatures when a so called encoding file is supplied. The encoding file
contains an font encoding vector and definitions for extra ligatures.
An encoding file is very similar to encoding files used by dvips and
usually found in /usr/share/texmf/dvips/base. Adding a ligature
requires a line like the following:
% LIGKERN char1 char2 =: ligature ;
If ’char1’ is followed by ’char2’ they will be both replaced by the
glyph ’ligature’. This replacement may not be used exclusively for
ligatures like ’fi’ or ’ff’ but for any combination of characters.
Quite common is a hyphen followed by a hyphen, which is replaced by an
endash.
In order to set up hyphenation you will first need a hyphenation
dictionary for your language. Since pslib uses a well know hyphenation
algorithmn used not just by TeX, but also by openoffice and scribus,
one can take the dictionary from those programs. If you have scribus
installed on your system, you will find the dictionaries for many
languages in /usr/lib/scribus/dicts.
Hyphenation is turned on when the parameter ’hyphenation’ is set to
true and the parameter ’hyphendict’ contains the file name of the
hyphenation dictionary.
Protusion is an advanced method to improve the appearance of text
margins. It is only used by the function PS_show_boxed(3) if the
horizontal mode is set to ’justify’. A margin may not look straight if
lines end or begin with characters with a ’light’ appearance like a
period, hyphen or comma. Those characters should reach into the margin
to make it look straight. pslib tries to read a so called protusion
file whenever a font is loaded with PS_findfont(3). If it cannot be
found a warning is issued. The file must be named ’fontname.pro’ and
contains a line for each character with protusion information. Finding
reasonable protusion values can be a tedious work.
N hyphen ; M 0 650 ;
N comma ; M 0 650 ;
N period ; M 0 650 ;
N semicolon ; M 0 500 ;
The syntax is similar to an .afm file. The protusion values for the
left and right margin are the last two numbers.
LOADING FILES
All files which are being loaded by pslib are searched for in the
current directory and the ’SearchPath’. ’SearchPath’ is a parameter
which is set by PS_set_parameter(3). PS_set_parameter(3) can be called
multiple times to add several directories to the search path. Function
which are affected by the search path are PS_findfont(3) for loading
.afm, .pfb, and .enc files, PS_include_file(3).
RESOURCE HANDLING
Resources in pslib are fonts, patterns, templates, spot colors, and
images. Templates and images are treated equally. A resource is usally
loaded or created and can be used repeatingly afterwards. Resource
handling is somewhat sensitve, in terms of the position in the document
where they are loaded or created. Plain PostScript does not care about
where a resource is defined as long as it is known before it is used.
PostScript documents are not always printed but quite often displayed
on the screen or processed by software. Most software which reads
PostScript documents does not just interpret the PostScript code but
also so called Document Structuring Conventions (DSC). Such
instructions are helpful to provide further information about the
document and to partion the document into sections like a prolog and
pages. Programs evaluating those instructions can easy determine the
page size, the creator, title or author, the number of pages and can
jump straight to a certain page without interpreting the PostScript
code before that page. Especially isolating certain pages requires the
document to be created stringly following the DSC. This means that all
resource which are used through out the document must be either created
on each page where they are used (not very sensible if the resource is
used more than once) or within the prolog right before the first page.
pslib will put everything before the first page into the prolog. On
the other side the prolog may not contain any PostScript code that does
output something. pslib makes sure this rule is not violated.
In practice the above rules do not apply equally to all resource but
can be seen as a general rule of thumb. Fonts can under certain
circumstances be loaded at any time (see the section on ’Text output’).
The same is currently true for images, which is likely to be changed in
the future.
IMAGES
Placing images on a page in the PostScript document is similar to font
handling. First the image has to be loaded with
int PS_open_image_file (PSDoc *psdoc, const char *type, const char
*filename, const char *stringparam, int intparam);
or
int PS_open_image (PSDoc *psdoc, const char *type, const char *source,
const char *data, long length, int width, int height, int components,
int bpc, const char *params);
and than it can be placed on the page with the function
int PS_place_image (PSDoc *psdoc, int imageid, float x, float y, float
scale);
Images are currently not real resources. Each call of PS_place_image(3)
will write the complete images into the PostScript file.
TEMPLATES
Templates are a bit like images created within the document itself.
Their big advantage is its reusability on any page thoughout the
document by simply referencing them. This saves a lot of disk space if
the template is placed many times. They are often used for logos or
headers which are to be placed on each page. A template is started with
the function
int PS_begin_template (PSDoc *psdoc, float width, float height);
Like a page or an image a template has a boundig box. Within that box
almost any operation for drawing, text output, etc. can be called.
Everything beyond the bounding box is clipped. A template is ended and
ready for use with
int PS_end_template (PSDoc *psdoc);
Each template has its own id which was returned by
PS_begin_template(3). This id is like an image id and can be passed to
PS_place_image(3). This makes a template identical to an image in terms
of handling. Any call of PS_place_image(3) will only place a reference
to the template into the document which results in a small document
size.
COLORS
pslib supports all colorspaces available in PostScript including spot
colors. Opposed to the PostScript color modell which knows just one
current color, pslib distinguishes between a stroke and fill color.
Colors are set with
int PS_setcolor (PSDoc *psdoc, const char *type, const char
*colorspace, float c1, float c2, float c3, float c4);
type determines if the fill, stroke or both (fillstroke) colors are set
by the function. The colorspace can be any of ’gray’, ’rgb’, ’cmyk’,
’spot’, or ’pattern’. The colorspace ’pattern’ is somewhat special and
will be discussed in the next section. The float parameters contain
the actual values of the color. Depending on the colorspace not all
parameters will be evaluated. Spot colors need to be created before
with
int PS_makespotcolor (PSDoc *psdoc, const char *name, floatreserved);
The name of the spot color can be any string value, thought one will
usually take the official name of the spot color, e.g. PANTONE 114 C.
Each spot color has a color in an alternative colorspace which is used
when the spot color itself cannot be used. This is always the case when
the PostScript file is viewed on a computer screen or printed by an ink
printer. If the PostScript document is separated for professional
printing, the alternative color has no meaning. The alternative color
is taken from the current fill color. This means, that you have to call
PS_setcolor(3) and set the current fill color before calling
PS_makespotcolor(3). PS_makespotcolor(3) can only handle fill colors
in the colorspace ’gray’, ’rgb’, or ’cmyk’.
PS_makespotcolor(3) returns the id of the spot color which is passed as
parameter c1 to PS_setcolor(3). All spot colors used in the document
should be defined before the first page, otherwise they will not be
included into the list of custom colors within the document comments
section at the beginning of the file.
COLOR SEPARATION
Printing a document sometimes requires to separate colors because
certain printers print each color separately. Color separation is
often done on the multi color document by the printing company.
However, pslib can separate colors very easily by setting the value
’separationcolor’ on a value from 1 to 4, depending on the color you
would like to separate (1=cyan, 2=magenta, 3=yellow, 4=black). This has
to be done before creating a page. The resulting document will contain
only those parts in the separated color. Consequently, one has to
create four identical pages, each called with a different value for
’separationcolor’.
PATTERNS
Filling an area can be done with a single color or a self designed
pattern. Such a pattern can be any drawing. Actually, it can be
everything which can be put on a page. If a pattern is used for filling
it is repeatingly placed in horizontal and vertical direction with a
given distance. Pattern are started with
int PS_begin_pattern (PSDoc *psdoc, float width, float height, float
xstep, float ystep, int painttype);
and ended with
int PS_end_pattern (PSDoc *psdoc);
Within those two functions almost any output operation can be used for
creating the pattern. Once a pattern is created, it can be used like a
color for filling. Just pass the string "pattern" and the pattern id
(returned by PS_begin_pattern(3)) to PS_setcolor(3). Any following
drawing and/or filling operation will now use the pattern.
HYPERLINKS, BOOKMARKS
PostScript itself does not support any hyperlink functions like PDF
does. Nervertheless, one can embed hyperlinks into a PostScript
document which will be used if the document is later converted to PDF.
Such commands for embedding hyperlinks are called pdfmarks. pdfmarks
allow to store any feature in a PostScript document which is available
in PDF. The PostScript interpreter itself will not care about the
pdfmarks. This features makes pslib a viable alternative to libraries
creating PDF directly.
Some functions of pslib will place a pdfmark silently into the
document. The most prominent function is PS_begin_page(3) which stores
the page size with the help of pdfmarks.
pslib supports several types of hyperlinks, which are inserted with the
following function.
int PS_add_weblink (PSDoc *psdoc, float llx, float lly, float urx,
float ury, const char *url);
int PS_add_pdflink (PSDoc *psdoc, float llx, float lly, float urx,
float ury, const char *filename, int page, const char *dest);
int PS_add_locallink (PSDoc *psdoc, float llx, float lly, float urx,
float ury, int page, const char *dest);
int PS_add_launchlink (PSDoc *psdoc, float llx, float lly, float urx,
float ury, const char *filename);
Each of the above function requires a rectangle with its lower left
corner at llx, lly and its upper right corner at urx, ury. The
rectangle will not be visible in the PostScript file and marks the
sensitve area of the link. When the document is concerted to PDF, the
rectangle will become visible. Its appearance can be set with the
functions.
int PS_set_border_style (PSDoc *psdoc, const char *style, float width);
style can be either ’solid’ or ’dashed’.
int PS_set_border_color (PSDoc *psdoc, float red, float green, float
blue);
int PS_set_border_dash (PSDoc *psdoc, float black, float white);
pslib also supports to add bookmarks which will be displayed by PDF
viewers as a table of contents next to the document. Bookmarks have a
title and point to a page in the document. The can be added with
int PS_add_bookmark (PSDoc *psdoc, const char *text, int parent, int
open);
To build up a hierachical tree of bookmarks, one can pass a parent
bookmark when creating a new one. The parent bookmark is referenced by
its id as it is returned by the function itself. A bookmark is always
added for the current page. It is shown open if the parameter open is
greater 0.
TYPO3 FONTS
PostScript knows several types of fonts. The most common is called
Type1 which are usally supplied by many font manufactures as .pfb
files. pslib can read those fonts and use them right away. Another
type of font is called Type3. Type3 fonts distinguish from Type1 fonts
by the way its glyphs are constructed. Glyphs in Type3 fonts are
created with regular PostScript commands and can easily be created with
pslib. All you need to do is start a new font with
int PS_begin_font (PSDoc *psdoc, const char *fontname, int reserved,
double a, double b, double c, double d, double e, double f, const char
*optlist);
and end finish it with
int PS_end_font (PSDoc *psdoc);
Each font contains of a number of glyphs which are created with a pair
of
int PS_begin_glyph (PSDoc *psdoc, const char *glyphname, double wx,
double llx, double lly, double urx, double ury);
and
int PS_end_glyph (PSDoc *psdoc);
Within a glyph each command is allowed to create a path and to stroke
or fill it. Once a font is created it can be used like any other font
by calling PS_setfont(3).
The font cannot be saved to a file and used by other applications but
it can used within the pslib document which has several advantages when
certain symbols, e.g. logos are used through out a document.
MEMORY MANAGEMENT, ERROR HANDLING
pslib uses by default its on memory management and error handling
functions. In many cases the calling application has its own memory
management and error handling. pslib can be told to use those functions
by calling PS_new2(3) instead of PS_new(3).
int PS_new2 (PSDoc *psdoc, (errorhandler *) (PSDoc *p, int type, const
char *msg, void *data), (allocproc *) (PSDoc *p, size_t size, const
char *caller), (reallocproc *) (PSDoc *p, void *mem, size_t size, const
char *caller), (freeproc *) (PSDoc *p, void *mem), void *opaque);
The errorhandler and the last parameter opaque allow to pass arbitrary
data as the last parameter to its own errorhandler. This is quite often
used if errors are being output in a widget of a graphical toolkit. The
pointer to that widget can be passed as opaque and pslib will pass it
forward to the error handler.
DOCUMENT INFORMATION
PostScript documents usually contain a header made of comments with
information about the document. The printer usually disregards this
information but many PostScript viewer use it. Besides that, one can
also place pdfmarks into the PostScript document which contain the
title, keywords, author and other information. pslib provides the
function PS_set_info(3) to set those fields.
int PS_set_info (PSDoc *psdoc, const char *key, const char *value);
PS_set_info(3) must be called before the first page. Calling it later
will have no effect and produces a warning. The function may also be
used to set the bounding box of the document. Usually there is no need
for it, because the dimension of the first page will be used for the
bounding box.
SEE ALSO
The detailed manual pages for each function of the library.
AUTHOR
This manual page was written by Uwe Steinmann <uwe@steinmann.cx>.
24 November 2009