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 partition the document into sections like a prolog and pages.
Programs evaluating those instructions can easily 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').
Please note, that starting from 0.4.5 of pslib images are treated as resources
as well, though this behaviour can be turned of by setting `imagereuse' to
`false' if existing code shows unexpected side effects.
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);
Once an image is not needed anymore it should be closed to free the resources.
int PS_close_image (PSDoc *
psdoc, int imageid);
Until version 0.4.4 of pslib images are not real resources. Each call of
PS_place_image(3) wrote the complete image into the PostScript file.
Starting with version 0.4.5 images are by default reusable objects which are
saved once into the PostScript file (with
PS_open_image(3) or
PS_open_image_file(3)) and replayed as often as desired with
PS_place_image(3). This behaviour can be turned off if `imagereuse' is
set to `false'. Reusing images usually has the advantages of smaller file
size, faster processing of the PostScript file and the possibility to place
images into templates which was not allowed till version 0.4.4. If an image is
placed into a template and is not needed anymore, it can be closed right after
ending the template.
Please note, that everything sayed about resources becomes true for reusable
images, too.
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,
float reserved);
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.
TYPE3 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.
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>.