NAME

DESCRIPTION

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

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

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

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

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 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

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

RESOURCE HANDLING

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

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

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

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 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

PATTERNS

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

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

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

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

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

AUTHOR