<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>PSLIB</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
></A
>PSLIB</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN15"
></A
><H2
>Name</H2
>pslib -- Library to create PostScript files</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN18"
></A
><H2
>DESCRIPTION</H2
><P
>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.
</P
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN22"
></A
><H2
>GETTING STARTED</H2
><P
>Programs which want to use pslib will have to include the
header file <TT
CLASS="LITERAL"
>libps/pslib.h</TT
> and link against libps.
Before doing any document
creation the library should be initialized with
<CODE
CLASS="FUNCTION"
>PS_boot(3)</CODE
>. 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
<CODE
CLASS="FUNCTION"
>isalpha(3)</CODE
> and <CODE
CLASS="FUNCTION"
>tolower(3)</CODE
>
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 <CODE
CLASS="FUNCTION"
>PS_shutdown(3)</CODE
>.</P
><P
>A PostScript document is
represented by a pointer to <TT
CLASS="LITERAL"
>PSDoc</TT
>. Such a document
can be created with <CODE
CLASS="FUNCTION"
>PS_new(3)</CODE
> and destroyed
with <CODE
CLASS="FUNCTION"
>PS_delete(3)</CODE
>. <CODE
CLASS="FUNCTION"
>PS_new(3)</CODE
>
returns a pointer to <TT
CLASS="LITERAL"
>PSDoc</TT
>. You can handle several
documents at the same time. The following example will do the basic
preparation without creating a document on the disk.</P
><PRE
CLASS="PROGRAMLISTING"
>...
#include <libps/pslib.h>
main(int argc, char *argv[]) {
PSDoc *psdoc;
PS_boot();
psdoc = PS_new();
PS_delete(psdoc);
PS_shutdown();
}
</PRE
><P
>In order to actually create a PostScript document on disk you will
have to call</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN38"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_open_file</CODE
>(PSDoc *psdoc, const char *filename);</CODE
></P
><P
></P
></DIV
><P
>or</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN47"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_open_fp</CODE
>(PSDoc *psdoc, FILE *fp);</CODE
></P
><P
></P
></DIV
><P
><CODE
CLASS="FUNCTION"
>PS_open_file(3)</CODE
> will create a new file
with the given file name, while <CODE
CLASS="FUNCTION"
>PS_open_fp(3)</CODE
>
will use an already open file. Both require a pointer to
<TT
CLASS="LITERAL"
>PSDoc</TT
>.</P
><P
>If the document shall not be created on disk but in memory,
which can be very handy in web application, one can use</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN60"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_open_mem</CODE
>(PSDoc *psdoc, (*writeproc) (PSDoc *p, void *data, size_t size));</CODE
></P
><P
></P
></DIV
><P
>The second parameter is a function which is called instead of pslib's
own output function.</P
><P
>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 <CODE
CLASS="FUNCTION"
>PS_close(3)</CODE
>.
<CODE
CLASS="FUNCTION"
>PS_close(3)</CODE
> will only close the file if it
was opened by <CODE
CLASS="FUNCTION"
>PS_open_file(3)</CODE
>.
</P
><PRE
CLASS="PROGRAMLISTING"
>...
#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();
}
</PRE
><P
>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
<CODE
CLASS="FUNCTION"
>PS_new2(3)</CODE
> and <CODE
CLASS="FUNCTION"
>PS_new3(3)</CODE
> for
a detailed description or read the section about memory management
and error handler below..</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN77"
></A
><H2
>PAGE HANDLING</H2
><P
>A PostScript document contains one or more pages. pslib provides
the function</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN80"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_begin_page</CODE
>(PSDoc *psdoc, float width, float height);</CODE
></P
><P
></P
></DIV
><P
>and</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN91"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_end_page</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
>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.</P
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN99"
></A
><H2
>COORDINATE SYSTEM, SCOPE</H2
><P
>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.</P
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN103"
></A
><H2
>DRAWING, PATH CONSTRUCTION</H2
><P
>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.</P
><P
>Each path is started with</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN107"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_moveto</CODE
>(PSDoc *psdoc, float x, float y);</CODE
></P
><P
></P
></DIV
><P
>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.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN118"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_lineto</CODE
>(PSDoc *psdoc, float x, float y);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN128"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_rect</CODE
>(PSDoc *psdoc, float x, float y, float width, float height);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN142"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_circle</CODE
>(PSDoc *psdoc, float x, float y, float radius);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN154"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_arc</CODE
>(PSDoc *psdoc, float x, float y, float radius, float alpha, float beta);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN170"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_arcn</CODE
>(PSDoc *psdoc, float x, float y, float radius, float alpha, float beta);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN186"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_curveto</CODE
>(PSDoc *psdoc, float x1, float y1, float x2, float y2, float x3, float y3);</CODE
></P
><P
></P
></DIV
><P
>Once a path is constructed it can be optionally closed by</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN205"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_closepath</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN212"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_stroke</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
>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.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN219"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_fill</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN225"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void PS_fill_stroke</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
><CODE
CLASS="FUNCTION"
>PS_fill_stroke(3)</CODE
> 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.</P
><P
> </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN234"
></A
><H2
>TEXT OUTPUT</H2
><P
>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.</P
><P
>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.</P
><P
>Additional files are needed for more sophisticated text output.
It will be explained later in this documentation.
</P
><P
>Before being able to output any text a font has to be loaded
with</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN240"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_findfont</CODE
>(PSDoc *psdoc, const char *fontname, const char *encoding, int embed);</CODE
></P
><P
></P
></DIV
><P
>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
<CODE
CLASS="PARAMETER"
>fontname</CODE
>.pfb must be present.</P
><P
>The <CODE
CLASS="PARAMETER"
>encoding</CODE
> 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.
</P
><P
>Calling <CODE
CLASS="FUNCTION"
>PS_findfont(3)</CODE
> 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 <B
CLASS="COMMAND"
>psselect</B
>
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.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN259"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_setfont</CODE
>(PSDoc *psdoc, int fontid, float size);</CODE
></P
><P
></P
></DIV
><P
>sets the font which was loaded with
<CODE
CLASS="FUNCTION"
>PS_findfont(3)</CODE
> 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.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN271"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_show</CODE
>(PSDoc *psdoc, const char *text);</CODE
></P
><P
></P
></DIV
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN280"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_show_xy</CODE
>(PSDoc *psdoc, const char *text, float x, float y);</CODE
></P
><P
></P
></DIV
><P
>can be used. Both functions also exist in a version which requires
the length of the string as the third parameter. The are called
<CODE
CLASS="FUNCTION"
>PS_show2(3)</CODE
> and <CODE
CLASS="FUNCTION"
>PS_show_xy2(3)</CODE
>.
</P
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN296"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_show_boxed</CODE
>(PSDoc *psdoc, const char *text, float left, float bottom, float width, float height, const char *hmode, const char *feature);</CODE
></P
><P
></P
></DIV
><P
>should be usesd. It breaks the text into lines of length
<CODE
CLASS="PARAMETER"
>width</CODE
> 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 <CODE
CLASS="PARAMETER"
>hmode</CODE
>.
Hyphenation is turned off by default, because it needs to be set up
before it can be used.
</P
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN320"
></A
><H2
>HYPHENATION, KERNING, LIGATURES, PROTUSION</H2
><P
>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.</P
><P
>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 <B
CLASS="COMMAND"
>dvips</B
>
and usually found in <TT
CLASS="FILENAME"
>/usr/share/texmf/dvips/base</TT
>.
Adding a ligature requires a line like the following:</P
><PRE
CLASS="PROGRAMLISTING"
>% LIGKERN char1 char2 =: ligature ;
</PRE
><P
>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.</P
><P
>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 <TT
CLASS="FILENAME"
>/usr/lib/scribus/dicts</TT
>.</P
><P
>Hyphenation is turned on when the parameter 'hyphenation' is set
to true and the parameter 'hyphendict' contains the file name of the
hyphenation dictionary.</P
><P
>Protusion is an advanced method to improve the appearance of text
margins. It is only used by the function
<CODE
CLASS="FUNCTION"
>PS_show_boxed(3)</CODE
> 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 <CODE
CLASS="FUNCTION"
>PS_findfont(3)</CODE
>. 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.</P
><PRE
CLASS="PROGRAMLISTING"
>N hyphen ; M 0 650 ;
N comma ; M 0 650 ;
N period ; M 0 650 ;
N semicolon ; M 0 500 ;
</PRE
><P
>The syntax is similar to an .afm file. The protusion values for the
left and right margin are the last two numbers.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN336"
></A
><H2
>LOADING FILES</H2
><P
>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 <CODE
CLASS="FUNCTION"
>PS_set_parameter(3)</CODE
>.
<CODE
CLASS="FUNCTION"
>PS_set_parameter(3)</CODE
> can be called multiple
times to add several directories to the search path. Function which
are affected by the search path are <CODE
CLASS="FUNCTION"
>PS_findfont(3)</CODE
>
for loading .afm, .pfb, and .enc files,
<CODE
CLASS="FUNCTION"
>PS_include_file(3)</CODE
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN343"
></A
><H2
>RESOURCE HANDLING</H2
><P
>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.
</P
><P
>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').
</P
><P
>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.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN348"
></A
><H2
>IMAGES</H2
><P
>Placing images on a page in the PostScript document is similar
to font handling. First the image has to be loaded with</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN351"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_open_image_file</CODE
>(PSDoc *psdoc, const char *type, const char *filename, const char *stringparam, int intparam);</CODE
></P
><P
></P
></DIV
><P
>or</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN366"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_open_image</CODE
>(PSDoc *psdoc, const char *type, const char *source, const char *data, long length, int width, int height, int components, int bpc, const char *params);</CODE
></P
><P
></P
></DIV
><P
>and than it can be placed on the page with the function</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN391"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_place_image</CODE
>(PSDoc *psdoc, int imageid, float x, float y, float scale);</CODE
></P
><P
></P
></DIV
><P
>Once an image is not needed anymore it should be closed to free
the resources.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN406"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_close_image</CODE
>(PSDoc *psdoc, int imageid);</CODE
></P
><P
></P
></DIV
><P
>Until version 0.4.4 of pslib images are not real resources. Each
call of
<CODE
CLASS="FUNCTION"
>PS_place_image(3)</CODE
> 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 <CODE
CLASS="FUNCTION"
>PS_open_image(3)</CODE
> or
<CODE
CLASS="FUNCTION"
>PS_open_image_file(3)</CODE
>) and replayed as often as
desired with <CODE
CLASS="FUNCTION"
>PS_place_image(3)</CODE
>. 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.</P
><P
>Please note, that everything sayed about resources becomes true
for reusable images, too.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN420"
></A
><H2
>TEMPLATES</H2
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN423"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_begin_template</CODE
>(PSDoc *psdoc, float width, float height);</CODE
></P
><P
></P
></DIV
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN434"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_end_template</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
>Each template has its own id which was returned by
<CODE
CLASS="FUNCTION"
>PS_begin_template(3)</CODE
>. This id is like an image id and
can be passed to <CODE
CLASS="FUNCTION"
>PS_place_image(3)</CODE
>. This makes a
template identical to an image in terms of handling. Any call of
<CODE
CLASS="FUNCTION"
>PS_place_image(3)</CODE
> will only place a reference to
the template into the document which results in a small document
size.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN444"
></A
><H2
>COLORS</H2
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN447"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_setcolor</CODE
>(PSDoc *psdoc, const char *type, const char *colorspace, float c1, float c2, float c3, float c4);</CODE
></P
><P
></P
></DIV
><P
><CODE
CLASS="PARAMETER"
>type</CODE
> 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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN467"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_makespotcolor</CODE
>(PSDoc *psdoc, const char *name, floatreserved);</CODE
></P
><P
></P
></DIV
><P
>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
<CODE
CLASS="FUNCTION"
>PS_setcolor(3)</CODE
> and set the current fill color before
calling <CODE
CLASS="FUNCTION"
>PS_makespotcolor(3)</CODE
>.
<CODE
CLASS="FUNCTION"
>PS_makespotcolor(3)</CODE
> can only handle fill colors in
the colorspace 'gray', 'rgb', or 'cmyk'.</P
><P
><CODE
CLASS="FUNCTION"
>PS_makespotcolor(3)</CODE
> returns the id of the spot
color which is passed as parameter <CODE
CLASS="PARAMETER"
>c1</CODE
> to
<CODE
CLASS="FUNCTION"
>PS_setcolor(3)</CODE
>. 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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN485"
></A
><H2
>COLOR SEPARATION</H2
><P
>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'.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN488"
></A
><H2
>PATTERNS</H2
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN491"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_begin_pattern</CODE
>(PSDoc *psdoc, float width, float height, float xstep, float ystep, int painttype);</CODE
></P
><P
></P
></DIV
><P
>and ended with</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN508"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_end_pattern</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
>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 <CODE
CLASS="FUNCTION"
>PS_begin_pattern(3)</CODE
>)
to <CODE
CLASS="FUNCTION"
>PS_setcolor(3)</CODE
>. Any following drawing and/or
filling operation will now use the pattern.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN517"
></A
><H2
>HYPERLINKS, BOOKMARKS</H2
><P
>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.</P
><P
>Some functions of pslib will place a pdfmark silently into the
document. The most prominent function is
<CODE
CLASS="FUNCTION"
>PS_begin_page(3)</CODE
> which stores the page size with
the help of pdfmarks.</P
><P
>pslib supports several types of hyperlinks, which are inserted
with the following function.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN523"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_add_weblink</CODE
>(PSDoc *psdoc, float llx, float lly, float urx, float ury, const char *url);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN539"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_add_pdflink</CODE
>(PSDoc *psdoc, float llx, float lly, float urx, float ury, const char *filename, int page, const char *dest);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN559"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_add_locallink</CODE
>(PSDoc *psdoc, float llx, float lly, float urx, float ury, int page, const char *dest);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN577"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_add_launchlink</CODE
>(PSDoc *psdoc, float llx, float lly, float urx, float ury, const char *filename);</CODE
></P
><P
></P
></DIV
><P
>Each of the above function requires a rectangle with its lower
left corner at <CODE
CLASS="PARAMETER"
>llx</CODE
>, <CODE
CLASS="PARAMETER"
>lly</CODE
>
and its upper right corner at <CODE
CLASS="PARAMETER"
>urx</CODE
>,
<CODE
CLASS="PARAMETER"
>ury</CODE
>. 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.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN598"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_set_border_style</CODE
>(PSDoc *psdoc, const char *style, float width);</CODE
></P
><P
></P
></DIV
><P
><CODE
CLASS="PARAMETER"
>style</CODE
> can be either 'solid' or 'dashed'.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN610"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_set_border_color</CODE
>(PSDoc *psdoc, float red, float green, float blue);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN622"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_set_border_dash</CODE
>(PSDoc *psdoc, float black, float white);</CODE
></P
><P
></P
></DIV
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN633"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_add_bookmark</CODE
>(PSDoc *psdoc, const char *text, int parent, int open);</CODE
></P
><P
></P
></DIV
><P
>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
<CODE
CLASS="PARAMETER"
>open</CODE
> is greater 0.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN647"
></A
><H2
>TYPE3 FONTS</H2
><P
>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</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN650"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_begin_font</CODE
>(PSDoc *psdoc, const char *fontname, int reserved, double a, double b, double c, double d, double e, double f, const char *optlist);</CODE
></P
><P
></P
></DIV
><P
>and end finish it with</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN675"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_end_font</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
>Each font contains of a number of glyphs which are created
with a pair of</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN682"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_begin_glyph</CODE
>(PSDoc *psdoc, const char *glyphname, double wx, double llx, double lly, double urx, double ury);</CODE
></P
><P
></P
></DIV
><P
>and</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN701"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_end_glyph</CODE
>(PSDoc *psdoc);</CODE
></P
><P
></P
></DIV
><P
>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 <CODE
CLASS="FUNCTION"
>PS_setfont(3)</CODE
>.</P
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN710"
></A
><H2
>MEMORY MANAGEMENT, ERROR HANDLING</H2
><P
>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 <CODE
CLASS="FUNCTION"
>PS_new2(3)</CODE
> instead of
<CODE
CLASS="FUNCTION"
>PS_new(3)</CODE
>.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN715"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_new2</CODE
>(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);</CODE
></P
><P
></P
></DIV
><P
>The errorhandler and the last parameter <CODE
CLASS="PARAMETER"
>opaque</CODE
>
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 <CODE
CLASS="PARAMETER"
>opaque</CODE
> and pslib will pass it
forward to the error handler.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN734"
></A
><H2
>DOCUMENT INFORMATION</H2
><P
>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 <CODE
CLASS="FUNCTION"
>PS_set_info(3)</CODE
> to set those fields.</P
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN738"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int PS_set_info</CODE
>(PSDoc *psdoc, const char *key, const char *value);</CODE
></P
><P
></P
></DIV
><P
><CODE
CLASS="FUNCTION"
>PS_set_info(3)</CODE
> 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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN750"
></A
><H2
>SEE ALSO</H2
><P
>The detailed manual pages for each function of the library.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN753"
></A
><H2
>AUTHOR</H2
><P
>This manual page was written by Uwe Steinmann <CODE
CLASS="EMAIL"
><<A
HREF="mailto:uwe@steinmann.cx"
>uwe@steinmann.cx</A
>></CODE
>.</P
></DIV
></BODY
></HTML
>