Man Linux: Main Page and Category List


       pslib - Library to create PostScript files


       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

       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.


       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;

            psdoc = PS_new();

       In order to actually create a PostScript document on disk you will have
       to call

       int PS_open_file (PSDoc *psdoc, const char *filename);


       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

       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;

            psdoc = PS_new();
            PS_open_file(psdoc, "");

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


       A PostScript document contains one or more pages.  pslib  provides  the

       int PS_begin_page (PSDoc *psdoc, float width, float height);


       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.


       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

       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.


       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

       void PS_lineto (PSDoc *psdoc, float x, float y);

       void  PS_rect  (PSDoc  *psdoc,  float  x,  float  y, float width, float

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

       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.


       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

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


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


       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.


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


       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

       Images are currently not real resources. Each call of PS_place_image(3)
       will write the complete images into the PostScript file.


       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


       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

       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.


       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


       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.


       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

       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

       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

       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.


       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

       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

       int PS_begin_glyph (PSDoc *psdoc, const  char  *glyphname,  double  wx,
       double llx, double lly, double urx, double ury);


       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.


       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.


       The detailed manual pages for each function of the library.


       This manual page was written by Uwe Steinmann <>.

                               24 November 2009