Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PSLIB(3)							      PSLIB(3)

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 pro-
       duce 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 hy-
       phenation.

       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-li-
       brary, 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 cre-
       ation 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  hyphena-
       tion  which  uses isalpha(3) and	tolower(3) to prepare the word for hy-
       phenation. 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 doc-
       ument 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	 docu-
       ment.  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 sec-
       tion 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	 Post-
       Script  header. This may	have impact on resource	handling. For more in-
       formation 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 sub-
       path. 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  al-
       pha, 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	start-
       ing  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  men-
       tioned 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 im-
       portant 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	 para-
       graph 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	avail-
       able 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 *encod-
       ing, 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 pro-
       vided 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 limita-
       tion 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  re-
       sources	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. Af-
       ter  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 *fea-
       ture);

       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, liga-
       tures 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 posi-
       tion 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	encod-
       ing  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 lig-
       atures  like 'fi' or 'ff' but for any combination of characters.	 Quite
       common is a hyphen followed by a	hyphen,	which is replaced  by  an  en-
       dash.

       In  order  to set up hyphenation	you will first need a hyphenation dic-
       tionary for your	language. Since	pslib uses a well know hyphenation al-
       gorithmn	 used not just by TeX, but also	by openoffice and scribus, one
       can take	the dictionary from those programs. If you  have  scribus  in-
       stalled	on  your  system, you will find	the dictionaries for many lan-
       guages 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 hy-
       phenation dictionary.

       Protusion is an advanced	method to improve the appearance of text  mar-
       gins.  It is only used by the function PS_show_boxed(3) if the horizon-
       tal 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 when-
       ever 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  cur-
       rent  directory and the 'SearchPath'. 'SearchPath' is a parameter which
       is set by PS_set_parameter(3).  PS_set_parameter(3) can be called  mul-
       tiple  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 im-
       ages. Templates and images are treated equally. A  resource  is	usally
       loaded or created and can be used repeatingly afterwards. Resource han-
       dling 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 Post-
       Script  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	parti-
       tion the	document into sections like a prolog and pages.	Programs eval-
       uating  those instructions can easily determine the page	size, the cre-
       ator, 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	every-
       thing  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 circum-
       stances 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 re-
       sources.

       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 re-
       usable 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 docu-
       ment 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.  Ev-
       erything	 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_tem-
       plate(3). This id is like an image id and can be	passed to PS_place_im-
       age(3). This makes a template identical to an image in  terms  of  han-
       dling. 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 *col-
       orspace,	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 parame-
       ters 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 in-
       cluded into the list of custom colors within the	document comments sec-
       tion at the beginning of	the file.

COLOR SEPARATION
       Printing	a document sometimes requires to separate colors because  cer-
       tain  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 'separation-
       color' 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  'separation-
       color'.

PATTERNS
       Filling an area can be done with	a single color or a self designed pat-
       tern. 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 re-
       peatingly placed	in horizontal and vertical direction with a given dis-
       tance. 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 docu-
       ment 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 pdf-
       marks. This features makes pslib	a viable alternative to	libraries cre-
       ating PDF directly.

       Some  functions	of  pslib will place a pdfmark silently	into the docu-
       ment. 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 rectan-
       gle 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  cre-
       ated  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 func-
       tions. In many cases the	calling	application has	its own	memory manage-
       ment and	error handling.	pslib can be told to use  those	 functions  by
       calling PS_new2(3) instead of PS_new(3).

       int  PS_new2 (PSDoc *psdoc, (errorhandler *) (PSDoc *p, int type, const
       char *msg, void *data), (allocproc *) (PSDoc  *p,  size_t  size,	 const
       char *caller), (reallocproc *) (PSDoc *p, void *mem, size_t size, const
       char *caller), (freeproc	*) (PSDoc *p, void *mem), void *opaque);

       The errorhandler	and the	last parameter opaque allow to pass  arbitrary
       data as the last	parameter to its own errorhandler. This	is quite often
       used if errors are being	output in a widget of a	graphical toolkit. The
       pointer	to  that widget	can be passed as opaque	and pslib will pass it
       forward to the error handler.

DOCUMENT INFORMATION
       PostScript documents usually contain a header made of comments with in-
       formation  about	 the document. The printer usually disregards this in-
       formation 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>.

				  23 May 2017			      PSLIB(3)

NAME | DESCRIPTION | GETTING STARTED | PAGE HANDLING | COORDINATE SYSTEM, SCOPE | DRAWING, PATH CONSTRUCTION | TEXT OUTPUT | HYPHENATION, KERNING, LIGATURES, PROTUSION | LOADING FILES | RESOURCE HANDLING | IMAGES | TEMPLATES | COLORS | COLOR SEPARATION | PATTERNS | HYPERLINKS, BOOKMARKS | TYPE3 FONTS | MEMORY MANAGEMENT, ERROR HANDLING | DOCUMENT INFORMATION | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pslib&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help