1<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ 2 3<!-- Process this file with docbook-to-man to generate an nroff manual 4 page: `docbook-to-man manpage.sgml > manpage.1'. You may view 5 the manual page with: `docbook-to-man manpage.sgml | nroff -man | 6 less'. A typical entry in a Makefile or Makefile.am is: 7 8manpage.1: manpage.sgml 9 docbook-to-man $< > $@ 10 11 12 The docbook-to-man binary is found in the docbook-to-man package. 13 Please remember that if you create the nroff version in one of the 14 debian/rules file targets (such as build), you will need to include 15 docbook-to-man in your Build-Depends control field. 16 17 --> 18 19 <!-- Fill in your name for FIRSTNAME and SURNAME. --> 20 <!ENTITY dhfirstname "<firstname>UWE</firstname>"> 21 <!ENTITY dhsurname "<surname>STEINMANN</surname>"> 22 <!-- Please adjust the date whenever revising the manpage. --> 23 <!ENTITY dhdate "<date>March 28, 2011</date>"> 24 <!-- SECTION should be 1-8, maybe w/ subsection other parameters are 25 allowed: see man(7), man(1). --> 26 <!ENTITY dhsection "<manvolnum>3</manvolnum>"> 27 <!ENTITY dhemail "<email>uwe@steinmann.cx</email>"> 28 <!ENTITY dhusername "Uwe Steinmann"> 29 <!ENTITY dhucpackage "<refentrytitle>PSLIB</refentrytitle>"> 30 <!ENTITY funcname "pslib"> 31 32 <!ENTITY debian "<productname>Debian</productname>"> 33 <!ENTITY gnu "<acronym>GNU</acronym>"> 34 <!ENTITY gpl "&gnu; <acronym>GPL</acronym>"> 35]> 36 37<refentry> 38 <refentryinfo> 39 <address> 40 &dhemail; 41 </address> 42 <author> 43 &dhfirstname; 44 &dhsurname; 45 </author> 46 <copyright> 47 <year>2004-2011</year> 48 <holder>&dhusername;</holder> 49 </copyright> 50 &dhdate; 51 </refentryinfo> 52 <refmeta> 53 &dhucpackage; 54 55 &dhsection; 56 </refmeta> 57 <refnamediv> 58 <refname>&funcname;</refname> 59 60 <refpurpose>Library to create PostScript files</refpurpose> 61 </refnamediv> 62 <refsect1> 63 <title>DESCRIPTION</title> 64 65 <para>pslib is a library to create PostScript files with a set of 66 about 50 functions for line drawing, text output, page handling, etc. 67 It is very similar to other libraries like panda, cpdf or pdflib which 68 produce PDF. pslib can to a certain degree replace those libraries if 69 the PostScript file is converted to PDF with ghostscripts excellent 70 pdf writer. The results achieved with pslib can be even better when 71 it comes to text output, because it supports kerning, ligatures and 72 hyphenation. 73 </para> 74 <para>pslib is a C-library but there are bindings for Perl, Python, Tcl 75 and PHP. 76 This documentation will only describe the functions of the C-library, 77 though most of what is said here can be applied to the other language 78 bindings. 79 The PHP extension of pslib is documented in PEAR. The extension is 80 called ps.</para> 81 82 </refsect1> 83 <refsect1> 84 <title>GETTING STARTED</title> 85 86 <para>Programs which want to use pslib will have to include the 87 header file <literal>libps/pslib.h</literal> and link against libps. 88 Before doing any document 89 creation the library should be initialized with 90 <function>PS_boot(3)</function>. It will set the locale and selects 91 the messages in your language as defined by the environment variable 92 LC_ALL. Your locale settings will affect hyphenation which uses 93 <function>isalpha(3)</function> and <function>tolower(3)</function> 94 to prepare the word for hyphenation. German umlauts will 95 be filtered out if the locale is not set properly. The library should 96 be finalized by <function>PS_shutdown(3)</function>.</para> 97 <para>A PostScript document is 98 represented by a pointer to <literal>PSDoc</literal>. Such a document 99 can be created with <function>PS_new(3)</function> and destroyed 100 with <function>PS_delete(3)</function>. <function>PS_new(3)</function> 101 returns a pointer to <literal>PSDoc</literal>. You can handle several 102 documents at the same time. The following example will do the basic 103 preparation without creating a document on the disk.</para> 104 <programlisting> 105... 106#include <libps/pslib.h> 107 108main(int argc, char *argv[]) { 109 PSDoc *psdoc; 110 111 PS_boot(); 112 psdoc = PS_new(); 113 PS_delete(psdoc); 114 PS_shutdown(); 115} 116 </programlisting> 117 <para>In order to actually create a PostScript document on disk you will 118 have to call</para> 119 <funcsynopsis> 120 <funcprototype> 121 <funcdef>int <function>PS_open_file</function></funcdef> 122 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 123 <paramdef>const char *<parameter>filename</parameter></paramdef> 124 </funcprototype> 125 </funcsynopsis> 126 <para>or</para> 127 <funcsynopsis> 128 <funcprototype> 129 <funcdef>int <function>PS_open_fp</function></funcdef> 130 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 131 <paramdef>FILE *<parameter>fp</parameter></paramdef> 132 </funcprototype> 133 </funcsynopsis> 134 <para><function>PS_open_file(3)</function> will create a new file 135 with the given file name, while <function>PS_open_fp(3)</function> 136 will use an already open file. Both require a pointer to 137 <literal>PSDoc</literal>.</para> 138 <para>If the document shall not be created on disk but in memory, 139 which can be very handy in web application, one can use</para> 140 <funcsynopsis> 141 <funcprototype> 142 <funcdef>int <function>PS_open_mem</function></funcdef> 143 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 144 <paramdef>(*writeproc) <parameter>(PSDoc *p, void *data, size_t size)</parameter></paramdef> 145 </funcprototype> 146 </funcsynopsis> 147 <para>The second parameter is a function which is called instead of pslib's 148 own output function.</para> 149 <para>Extending the previous example with one of the former three functions 150 to open a document will at least create an initial empty PostScript 151 document. It has to be closed with <function>PS_close(3)</function>. 152 <function>PS_close(3)</function> will only close the file if it 153 was opened by <function>PS_open_file(3)</function>. 154 </para> 155 <programlisting> 156... 157#include <libps/pslib.h> 158 159main(int argc, char *argv[]) { 160 PSDoc *psdoc; 161 162 PS_boot(); 163 psdoc = PS_new(); 164 PS_open_file(psdoc, "test.ps"); 165 PS_close(psdoc); 166 PS_delete(psdoc); 167 PS_shutdown(); 168} 169 </programlisting> 170 <para>There are more sophisticated funktions to start a new PostScript 171 document. They are used when error handling and memory management 172 shall be controlled by the calling application. Check the manual pages 173 <function>PS_new2(3)</function> and <function>PS_new3(3)</function> for 174 a detailed description or read the section about memory management 175 and error handler below..</para> 176 </refsect1> 177 <refsect1> 178 <title>PAGE HANDLING</title> 179 180 <para>A PostScript document contains one or more pages. pslib provides 181 the function</para> 182 <funcsynopsis> 183 <funcprototype> 184 <funcdef>int <function>PS_begin_page</function></funcdef> 185 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 186 <paramdef>float <parameter>width</parameter></paramdef> 187 <paramdef>float <parameter>height</parameter></paramdef> 188 </funcprototype> 189 </funcsynopsis> 190 <para>and</para> 191 <funcsynopsis> 192 <funcprototype> 193 <funcdef>int <function>PS_end_page</function></funcdef> 194 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 195 </funcprototype> 196 </funcsynopsis> 197 <para>to start a new page with the given size in points and to end 198 a page. All functions that draw any visible output will 199 only work within a page. The page size has no meaning for the PostScript 200 interpreter but will be used by ghostscript or Acrobat Distiller 201 to set 202 the page size in the PDF document. Some PostScript viewer also use 203 the size to resize the output window.</para> 204 <para>Starting the first page of a document will internally end the 205 PostScript header. This may have impact on resource handling. For 206 more information see the section about resource handling.</para> 207 </refsect1> 208 <refsect1> 209 <title>COORDINATE SYSTEM, SCOPE</title> 210 211 <para>PostScript defines a coordinate system with its origin in the 212 lower left corner of a page. Its base unit is point which is 1/72 of an 213 inch. Unless the coordinate system is scaled all values will be expected 214 in point.</para> 215 <para>pslib provides many functions which may not be called at any time. 216 For example, drawing and text output functions may only be called within 217 a page, path constrution functions may only be called within a path. 218 pslib defines so called scopes which are checked before executing a 219 function. Those scopes are prolog, document, page, pattern, template, 220 path and object. If for example, one tries 221 to output text outside of a page or within a path, then an error 222 will be issued.</para> 223 </refsect1> 224 <refsect1> 225 <title>DRAWING, PATH CONSTRUCTION</title> 226 227 <para>PostScript does not have any functions to draw a line directly but 228 uses a two pass mechanism. First a path is constructed which is then 229 drawn (stroken). The path can also be used for filling an area or 230 to clip further drawing. A path must not be a continues line, it 231 may consist of several subpaths.</para> 232 <para>Each path is started with</para> 233 <funcsynopsis> 234 <funcprototype> 235 <funcdef>void <function>PS_moveto</function></funcdef> 236 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 237 <paramdef>float <parameter>x</parameter></paramdef> 238 <paramdef>float <parameter>y</parameter></paramdef> 239 </funcprototype> 240 </funcsynopsis> 241 <para>If this function is called within a path, it will just start 242 a new subpath. The path can be constructed with one of the following 243 functions.</para> 244 <funcsynopsis> 245 <funcprototype> 246 <funcdef>void <function>PS_lineto</function></funcdef> 247 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 248 <paramdef>float <parameter>x</parameter></paramdef> 249 <paramdef>float <parameter>y</parameter></paramdef> 250 </funcprototype> 251 </funcsynopsis> 252 <funcsynopsis> 253 <funcprototype> 254 <funcdef>void <function>PS_rect</function></funcdef> 255 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 256 <paramdef>float <parameter>x</parameter></paramdef> 257 <paramdef>float <parameter>y</parameter></paramdef> 258 <paramdef>float <parameter>width</parameter></paramdef> 259 <paramdef>float <parameter>height</parameter></paramdef> 260 </funcprototype> 261 </funcsynopsis> 262 <funcsynopsis> 263 <funcprototype> 264 <funcdef>void <function>PS_circle</function></funcdef> 265 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 266 <paramdef>float <parameter>x</parameter></paramdef> 267 <paramdef>float <parameter>y</parameter></paramdef> 268 <paramdef>float <parameter>radius</parameter></paramdef> 269 </funcprototype> 270 </funcsynopsis> 271 <funcsynopsis> 272 <funcprototype> 273 <funcdef>void <function>PS_arc</function></funcdef> 274 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 275 <paramdef>float <parameter>x</parameter></paramdef> 276 <paramdef>float <parameter>y</parameter></paramdef> 277 <paramdef>float <parameter>radius</parameter></paramdef> 278 <paramdef>float <parameter>alpha</parameter></paramdef> 279 <paramdef>float <parameter>beta</parameter></paramdef> 280 </funcprototype> 281 </funcsynopsis> 282 <funcsynopsis> 283 <funcprototype> 284 <funcdef>void <function>PS_arcn</function></funcdef> 285 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 286 <paramdef>float <parameter>x</parameter></paramdef> 287 <paramdef>float <parameter>y</parameter></paramdef> 288 <paramdef>float <parameter>radius</parameter></paramdef> 289 <paramdef>float <parameter>alpha</parameter></paramdef> 290 <paramdef>float <parameter>beta</parameter></paramdef> 291 </funcprototype> 292 </funcsynopsis> 293 <funcsynopsis> 294 <funcprototype> 295 <funcdef>void <function>PS_curveto</function></funcdef> 296 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 297 <paramdef>float <parameter>x1</parameter></paramdef> 298 <paramdef>float <parameter>y1</parameter></paramdef> 299 <paramdef>float <parameter>x2</parameter></paramdef> 300 <paramdef>float <parameter>y2</parameter></paramdef> 301 <paramdef>float <parameter>x3</parameter></paramdef> 302 <paramdef>float <parameter>y3</parameter></paramdef> 303 </funcprototype> 304 </funcsynopsis> 305 <para>Once a path is constructed it can be optionally closed by</para> 306 <funcsynopsis> 307 <funcprototype> 308 <funcdef>void <function>PS_closepath</function></funcdef> 309 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 310 </funcprototype> 311 </funcsynopsis> 312 <para>Closing a path means to add a segment from the last point to 313 the starting point of the path. It is helpful if an area is to be 314 filled. In most cases 315 the path is used for drawing which is done with</para> 316 <funcsynopsis> 317 <funcprototype> 318 <funcdef>void <function>PS_stroke</function></funcdef> 319 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 320 </funcprototype> 321 </funcsynopsis> 322 <para>In such a case you would not want to close the path. As already 323 mentioned a path can also be filled or even both with the 324 functions.</para> 325 <funcsynopsis> 326 <funcprototype> 327 <funcdef>void <function>PS_fill</function></funcdef> 328 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 329 </funcprototype> 330 </funcsynopsis> 331 <funcsynopsis> 332 <funcprototype> 333 <funcdef>void <function>PS_fill_stroke</function></funcdef> 334 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 335 </funcprototype> 336 </funcsynopsis> 337 <para><function>PS_fill_stroke(3)</function> does first fill and than 338 stroke a path. This is important to realize because the stroken line 339 may cover parts of the filled area, depending on how wide it is.<para> 340 </refsect1> 341 <refsect1> 342 <title>TEXT OUTPUT</title> 343 344 <para>Text output is definetly one of the strongest parts of pslib. 345 pslib supports kerning, protusion, ligatures and hyphenation. All of 346 it is in a wide range customizeable by parameters. The hyphenation 347 algorithmn is based on the one used by TeX without the ability to take a 348 whole paragraph into acount.</para> 349 <para>Text output requires at least the Adobe font metric files, even 350 for the standard PostScript fonts. pslib has not, like other libraries, 351 the font metrics for the standard fonts compiled in. They are freely 352 available in the internet. If the font is to be embedded into 353 the document, then the font outline (.pfb file) is also needed.</para> 354 <para>Additional files are needed for more sophisticated text output. 355 It will be explained later in this documentation. 356 </para> 357 <para>Before being able to output any text a font has to be loaded 358 with</para> 359 <funcsynopsis> 360 <funcprototype> 361 <funcdef>int <function>PS_findfont</function></funcdef> 362 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 363 <paramdef>const char *<parameter>fontname</parameter></paramdef> 364 <paramdef>const char *<parameter>encoding</parameter></paramdef> 365 <paramdef>int <parameter>embed</parameter></paramdef> 366 </funcprototype> 367 </funcsynopsis> 368 <para>It returns a unique id for the font. 369 The fontname is the filename of the Adobe font metrics file 370 without the extension .afm. If the font shall be embedded into the 371 document, then the last parameter must be set to 1 and the file 372 <parameter>fontname</parameter>.pfb must be present.</para> 373 <para>The <parameter>encoding</parameter> specifies the font encoding 374 to be used in the PostScript document. It defaults to TeXBase1, which 375 is a reasonable set of glyphs covering most western languages, when 376 the empty string or NULL is passed. The special encoding 'builtin' 377 stands for the encoding as provided by the font itself. It is usually 378 AdobeStandardEncoding which is a smaller set of glyphs than TeXBase1. 379 If unsure leave the encoding parameter empty. 380 </para> 381 <para>Calling <function>PS_findfont(3)</function> is a sensitive matter. 382 Thought it may be called in almost every scope it is highly recommended 383 to call it either within a page or before the first page (within the 384 prolog). Especially when 385 the font is to be embedded or uses a non default encoding. This limitation 386 has to be enforced in order to be able to extract certain pages from 387 the document without corruption. Programs like <command>psselect</command> 388 extract a page by taking the prolog of the PostScript document and the 389 selected page. Resources, like fonts, not being part of the 390 page or the prolog will not be included into the resulting document and 391 using those resources will provoke errors. 392 pslib will output a warning in case of 393 potential problems.</para> 394 <funcsynopsis> 395 <funcprototype> 396 <funcdef>int <function>PS_setfont</function></funcdef> 397 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 398 <paramdef>int <parameter>fontid</parameter></paramdef> 399 <paramdef>float <parameter>size</parameter></paramdef> 400 </funcprototype> 401 </funcsynopsis> 402 <para>sets the font which was loaded with 403 <function>PS_findfont(3)</function> in a given size. After calling this 404 function everything is prepared to output text with one of the following 405 functions. Each text output function uses kerning pairs and ligatures 406 if available.</para> 407 <funcsynopsis> 408 <funcprototype> 409 <funcdef>int <function>PS_show</function></funcdef> 410 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 411 <paramdef>const char *<parameter>text</parameter></paramdef> 412 </funcprototype> 413 </funcsynopsis> 414 <para>outputs text at the current text position and moves the x position 415 to the end of the text. If text is to be output at a certain position on 416 the page the function</para> 417 <funcsynopsis> 418 <funcprototype> 419 <funcdef>int <function>PS_show_xy</function></funcdef> 420 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 421 <paramdef>const char *<parameter>text</parameter></paramdef> 422 <paramdef>float <parameter>x</parameter></paramdef> 423 <paramdef>float <parameter>y</parameter></paramdef> 424 </funcprototype> 425 </funcsynopsis> 426 <para>can be used. Both functions also exist in a version which requires 427 the length of the string as the third parameter. The are called 428 <function>PS_show2(3)</function> and <function>PS_show_xy2(3)</function>. 429 </para> 430 <para>The functions mentioned so far will print all text into one line. 431 If one would like to wrap a longer text into a box, the function</para> 432 <funcsynopsis> 433 <funcprototype> 434 <funcdef>int <function>PS_show_boxed</function></funcdef> 435 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 436 <paramdef>const char *<parameter>text</parameter></paramdef> 437 <paramdef>float <parameter>left</parameter></paramdef> 438 <paramdef>float <parameter>bottom</parameter></paramdef> 439 <paramdef>float <parameter>width</parameter></paramdef> 440 <paramdef>float <parameter>height</parameter></paramdef> 441 <paramdef>const char *<parameter>hmode</parameter></paramdef> 442 <paramdef>const char *<parameter>feature</parameter></paramdef> 443 </funcprototype> 444 </funcsynopsis> 445 <para>should be usesd. It breaks the text into lines of length 446 <parameter>width</parameter> and fills the box until there is no space 447 left. 448 The function returns the number of remaining chars which did not fit 449 into the box. This number can be used to create a second, third, ... 450 box for the remaining text. Text can be left and/or right justified 451 or centered depending on the parameter <parameter>hmode</parameter>. 452 Hyphenation is turned off by default, because it needs to be set up 453 before it can be used. 454 </para> 455 <para>Once again, working with fonts is an error prune issue, because 456 it is important 457 at what position in the document the fonts are loaded. At a rule of 458 thumb you should load fonts which are used on several pages of 459 the document before the first page, and fonts only used on a 460 single page within that page. For a more detailed discussion see the 461 section on resource handling.</para> 462 </refsect1> 463 <refsect1> 464 <title>HYPHENATION, KERNING, LIGATURES, PROTUSION</title> 465 466 <para>pslib's advanced text output features cover hyphenation, kerning, 467 ligatures and protusion. Kerning and ligatures are turned on by default 468 and will be used if the current font supports it. Some ligatures are 469 built into pslib, just in case the font has the glyphs but misses the 470 command to build the ligature. Those ligatures are fi, fl, ff, ffi, 471 and ffl. Both ligatures and kerning can be turned off by setting the 472 parameter 'ligature' respectively 'kerning' to false. pslib automatically 473 inserts a ligature if the character sequence of that ligature is found. 474 If a ligature is not to be used then its character sequence must be 475 broken up with a broken bar character. Ligatures will never be used if 476 charspacing has a value unequal to zero.</para> 477 <para>If a font 478 provides more ligatures as those mentioned before, they are usually 479 at places not conform to the Adobe Standard Encoding. There glyph name 480 is often the name of the glyph supposed to be at that position in the 481 Adobe Standard Encoding. pslib can utilize those ligatures when a so 482 called encoding file is supplied. The encoding file contains an 483 font encoding vector and definitions for extra ligatures. An encoding 484 file is very similar to encoding files used by <command>dvips</command> 485 and usually found in <filename>/usr/share/texmf/dvips/base</filename>. 486 Adding a ligature requires a line like the following:</para> 487 <programlisting> 488% LIGKERN char1 char2 =: ligature ; 489 </programlisting> 490 <para>If 'char1' is followed by 'char2' they will be both replaced by the 491 glyph 'ligature'. This replacement may not be used exclusively for 492 ligatures like 'fi' or 'ff' but for any combination of characters. 493 Quite common is a hyphen followed by a hyphen, which is replaced by an 494 endash.</para> 495 <para>In order to set up hyphenation you will first need a hyphenation 496 dictionary for your language. Since pslib uses a well know hyphenation 497 algorithmn used not just by TeX, but also by openoffice and scribus, 498 one can take the dictionary from those programs. If you have scribus 499 installed on your system, you will find the dictionaries for many 500 languages in <filename>/usr/lib/scribus/dicts</filename>.</para> 501 <para>Hyphenation is turned on when the parameter 'hyphenation' is set 502 to true and the parameter 'hyphendict' contains the file name of the 503 hyphenation dictionary.</para> 504 <para>Protusion is an advanced method to improve the appearance of text 505 margins. It is only used by the function 506 <function>PS_show_boxed(3)</function> if the horizontal mode is set 507 to 'justify'. A margin may not look straight if lines end or begin 508 with characters with a 'light' appearance like a period, hyphen or comma. 509 Those characters should reach into the margin to make it look straight. 510 pslib tries to read a so called protusion file whenever a font is 511 loaded with <function>PS_findfont(3)</function>. If it cannot be found 512 a warning is issued. The file must be named 'fontname.pro' and contains 513 a line for each character with protusion information. Finding reasonable 514 protusion values can be a tedious work.</para> 515 <programlisting> 516N hyphen ; M 0 650 ; 517N comma ; M 0 650 ; 518N period ; M 0 650 ; 519N semicolon ; M 0 500 ; 520 </programlisting> 521 <para>The syntax is similar to an .afm file. The protusion values for the 522 left and right margin are the last two numbers.</para> 523 </refsect1> 524 <refsect1> 525 <title>LOADING FILES</title> 526 527 <para>All files which are being loaded by pslib are searched 528 for in the current directory and the 'SearchPath'. 'SearchPath' is 529 a parameter which is set by <function>PS_set_parameter(3)</function>. 530 <function>PS_set_parameter(3)</function> can be called multiple 531 times to add several directories to the search path. Function which 532 are affected by the search path are <function>PS_findfont(3)</function> 533 for loading .afm, .pfb, and .enc files, 534 <function>PS_include_file(3)</function>.</para> 535 </refsect1> 536 <refsect1> 537 <title>RESOURCE HANDLING</title> 538 539 <para>Resources in pslib are fonts, patterns, templates, spot colors, and 540 images. Templates and images are treated equally. A resource is usally 541 loaded or created and can be used repeatingly afterwards. Resource 542 handling is 543 somewhat sensitve, in terms of the position in the document where they 544 are loaded or created. Plain PostScript does not care about where a 545 resource is defined as long as it is known before it is used. PostScript 546 documents are not always printed but quite often displayed on the screen 547 or processed by software. Most software which reads PostScript documents 548 does not just interpret the PostScript code but also so called Document 549 Structuring Conventions (DSC). Such instructions are helpful to provide 550 further information about the document and to partition the document 551 into sections like a prolog and pages. Programs evaluating those 552 instructions can easily determine the page size, the creator, title or 553 author, the number of pages and can jump straight to a certain page 554 without interpreting the PostScript code before that page. Especially 555 isolating certain pages requires the document to be created stringly 556 following the DSC. This means that all resource which are used through 557 out the document must be either created on each page where they are 558 used (not very sensible if the resource is used more than once) 559 or within the prolog right before the first 560 page. pslib will put everything before the first page into the prolog. 561 On the other side the prolog may not contain any PostScript code that 562 does output something. pslib makes sure this rule is not violated. 563 </para> 564 <para>In practice the above rules do not apply equally to all resource 565 but can be seen as a general rule of thumb. Fonts can under certain 566 circumstances be loaded at any time (see the section on 'Text output'). 567 </para> 568 <para>Please note, that starting from 0.4.5 of pslib images are treated as 569 resources as well, though this behaviour can be turned of by setting 570 `imagereuse' to `false' if existing code shows unexpected side effects. 571 </para> 572 </refsect1> 573 <refsect1> 574 <title>IMAGES</title> 575 576 <para>Placing images on a page in the PostScript document is similar 577 to font handling. First the image has to be loaded with</para> 578 <funcsynopsis> 579 <funcprototype> 580 <funcdef>int <function>PS_open_image_file</function></funcdef> 581 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 582 <paramdef>const char *<parameter>type</parameter></paramdef> 583 <paramdef>const char *<parameter>filename</parameter></paramdef> 584 <paramdef>const char *<parameter>stringparam</parameter></paramdef> 585 <paramdef>int <parameter>intparam</parameter></paramdef> 586 </funcprototype> 587 </funcsynopsis> 588 <para>or</para> 589 <funcsynopsis> 590 <funcprototype> 591 <funcdef>int <function>PS_open_image</function></funcdef> 592 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 593 <paramdef>const char *<parameter>type</parameter></paramdef> 594 <paramdef>const char *<parameter>source</parameter></paramdef> 595 <paramdef>const char *<parameter>data</parameter></paramdef> 596 <paramdef>long <parameter>length</parameter></paramdef> 597 <paramdef>int <parameter>width</parameter></paramdef> 598 <paramdef>int <parameter>height</parameter></paramdef> 599 <paramdef>int <parameter>components</parameter></paramdef> 600 <paramdef>int <parameter>bpc</parameter></paramdef> 601 <paramdef>const char *<parameter>params</parameter></paramdef> 602 </funcprototype> 603 </funcsynopsis> 604 <para>and than it can be placed on the page with the function</para> 605 <funcsynopsis> 606 <funcprototype> 607 <funcdef>int <function>PS_place_image</function></funcdef> 608 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 609 <paramdef>int <parameter>imageid</parameter></paramdef> 610 <paramdef>float <parameter>x</parameter></paramdef> 611 <paramdef>float <parameter>y</parameter></paramdef> 612 <paramdef>float <parameter>scale</parameter></paramdef> 613 </funcprototype> 614 </funcsynopsis> 615 <para>Once an image is not needed anymore it should be closed to free 616 the resources.</para> 617 <funcsynopsis> 618 <funcprototype> 619 <funcdef>int <function>PS_close_image</function></funcdef> 620 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 621 <paramdef>int <parameter>imageid</parameter></paramdef> 622 </funcprototype> 623 </funcsynopsis> 624 <para>Until version 0.4.4 of pslib images are not real resources. Each 625 call of 626 <function>PS_place_image(3)</function> wrote the complete image 627 into the PostScript file. Starting with version 0.4.5 images are 628 by default reusable objects which are saved once into the PostScript 629 file (with <function>PS_open_image(3)</function> or 630 <function>PS_open_image_file(3)</function>) and replayed as often as 631 desired with <function>PS_place_image(3)</function>. This behaviour 632 can be turned off if `imagereuse' is set to `false'. Reusing images 633 usually has the advantages of smaller file size, faster processing 634 of the PostScript file and the possibility to place images into 635 templates which was not allowed till version 0.4.4. If an image is 636 placed into a template and is not needed anymore, it can be closed 637 right after ending the template.</para> 638 <para>Please note, that everything sayed about resources becomes true 639 for reusable images, too.</para> 640 641 </refsect1> 642 <refsect1> 643 <title>TEMPLATES</title> 644 645 <para>Templates are a bit like images created within the document 646 itself. Their big advantage is its reusability on any page thoughout 647 the document by simply referencing them. This saves a lot of disk space 648 if the template is placed many times. They are often used for logos or 649 headers which are to 650 be placed on each page. A template is started with the function</para> 651 <funcsynopsis> 652 <funcprototype> 653 <funcdef>int <function>PS_begin_template</function></funcdef> 654 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 655 <paramdef>float <parameter>width</parameter></paramdef> 656 <paramdef>float <parameter>height</parameter></paramdef> 657 </funcprototype> 658 </funcsynopsis> 659 <para>Like a page or an image a template has a boundig box. Within that 660 box almost any operation for drawing, text output, etc. can be called. 661 Everything beyond the bounding box is clipped. 662 A template is ended and ready for use with</para> 663 <funcsynopsis> 664 <funcprototype> 665 <funcdef>int <function>PS_end_template</function></funcdef> 666 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 667 </funcprototype> 668 </funcsynopsis> 669 <para>Each template has its own id which was returned by 670 <function>PS_begin_template(3)</function>. This id is like an image id and 671 can be passed to <function>PS_place_image(3)</function>. This makes a 672 template identical to an image in terms of handling. Any call of 673 <function>PS_place_image(3)</function> will only place a reference to 674 the template into the document which results in a small document 675 size.</para> 676 </refsect1> 677 <refsect1> 678 <title>COLORS</title> 679 680 <para>pslib supports all colorspaces available in PostScript including 681 spot colors. Opposed to the PostScript color modell which knows just 682 one current color, pslib distinguishes between a stroke and fill color. 683 Colors are set with</para> 684 <funcsynopsis> 685 <funcprototype> 686 <funcdef>int <function>PS_setcolor</function></funcdef> 687 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 688 <paramdef>const char *<parameter>type</parameter></paramdef> 689 <paramdef>const char *<parameter>colorspace</parameter></paramdef> 690 <paramdef>float <parameter>c1</parameter></paramdef> 691 <paramdef>float <parameter>c2</parameter></paramdef> 692 <paramdef>float <parameter>c3</parameter></paramdef> 693 <paramdef>float <parameter>c4</parameter></paramdef> 694 </funcprototype> 695 </funcsynopsis> 696 <para><parameter>type</parameter> determines if the fill, stroke or 697 both (fillstroke) colors are set by the function. The colorspace 698 can be any of 'gray', 'rgb', 'cmyk', 'spot', or 'pattern'. The colorspace 699 'pattern' is somewhat special and will be discussed in the next section. 700 The float parameters contain the actual values of the color. Depending 701 on the colorspace not all parameters will be evaluated. Spot colors 702 need to be created before with</para> 703 <funcsynopsis> 704 <funcprototype> 705 <funcdef>int <function>PS_makespotcolor</function></funcdef> 706 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 707 <paramdef>const char *<parameter>name</parameter></paramdef> 708 <paramdef>float<parameter>reserved</parameter></paramdef> 709 </funcprototype> 710 </funcsynopsis> 711 <para>The name of the spot color can be any string value, thought one will 712 usually take the official name of the spot color, e.g. PANTONE 114 C. 713 Each spot color has a color in an alternative colorspace which is used 714 when the spot color itself cannot be used. This is always the case when 715 the PostScript file is viewed on a computer screen or printed by an ink 716 printer. If the PostScript document is separated for professional 717 printing, the alternative color has no meaning. The alternative color is 718 taken from the current fill color. This means, that you have to call 719 <function>PS_setcolor(3)</function> and set the current fill color before 720 calling <function>PS_makespotcolor(3)</function>. 721 <function>PS_makespotcolor(3)</function> can only handle fill colors in 722 the colorspace 'gray', 'rgb', or 'cmyk'.</para> 723 <para><function>PS_makespotcolor(3)</function> returns the id of the spot 724 color which is passed as parameter <parameter>c1</parameter> to 725 <function>PS_setcolor(3)</function>. All spot colors used in the document 726 should be defined before the first page, otherwise they will not be 727 included into the list of custom colors within the document comments 728 section at the beginning of the file.</para> 729 730 </refsect1> 731 <refsect1> 732 <title>COLOR SEPARATION</title> 733 734 <para>Printing a document sometimes requires to separate colors 735 because certain printers print each color separately. 736 Color separation is often done on the 737 multi color document by the printing company. However, pslib can 738 separate colors very easily by setting the value 'separationcolor' on 739 a value from 1 to 4, depending on the color you would like to separate 740 (1=cyan, 2=magenta, 3=yellow, 4=black). This has to be done before 741 creating a page. The resulting document will 742 contain only those parts in the separated color. Consequently, one 743 has to create four identical pages, each called with a different value 744 for 'separationcolor'. 745 </para> 746 </refsect1> 747 <refsect1> 748 <title>PATTERNS</title> 749 750 <para>Filling an area can be done with a single color or a self designed 751 pattern. Such a pattern can be any drawing. Actually, it can be everything 752 which can be put on a page. If a pattern is used for filling it is 753 repeatingly placed in horizontal and vertical direction with a given 754 distance. Pattern are started with</para> 755 <funcsynopsis> 756 <funcprototype> 757 <funcdef>int <function>PS_begin_pattern</function></funcdef> 758 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 759 <paramdef>float <parameter>width</parameter></paramdef> 760 <paramdef>float <parameter>height</parameter></paramdef> 761 <paramdef>float <parameter>xstep</parameter></paramdef> 762 <paramdef>float <parameter>ystep</parameter></paramdef> 763 <paramdef>int <parameter>painttype</parameter></paramdef> 764 </funcprototype> 765 </funcsynopsis> 766 <para>and ended with</para> 767 <funcsynopsis> 768 <funcprototype> 769 <funcdef>int <function>PS_end_pattern</function></funcdef> 770 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 771 </funcprototype> 772 </funcsynopsis> 773 <para>Within those two functions almost any output operation can be 774 used for creating the pattern. Once a pattern is created, it 775 can be used like a color for filling. Just pass the string "pattern" 776 and the pattern id (returned by <function>PS_begin_pattern(3)</function>) 777 to <function>PS_setcolor(3)</function>. Any following drawing and/or 778 filling operation will now use the pattern.</para> 779 </refsect1> 780 <refsect1> 781 <title>HYPERLINKS, BOOKMARKS</title> 782 783 <para>PostScript itself does not support any hyperlink functions like 784 PDF does. Nervertheless, one can embed hyperlinks into a PostScript 785 document which will be used if the document is later converted to PDF. 786 Such commands for embedding hyperlinks are called pdfmarks. pdfmarks 787 allow to store any feature in a PostScript document which is available 788 in PDF. The PostScript interpreter itself will not care about the 789 pdfmarks. This features makes pslib a viable alternative to libraries 790 creating PDF directly.</para> 791 <para>Some functions of pslib will place a pdfmark silently into the 792 document. The most prominent function is 793 <function>PS_begin_page(3)</function> which stores the page size with 794 the help of pdfmarks.</para> 795 <para>pslib supports several types of hyperlinks, which are inserted 796 with the following function.</para> 797 <funcsynopsis> 798 <funcprototype> 799 <funcdef>int <function>PS_add_weblink</function></funcdef> 800 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 801 <paramdef>float <parameter>llx</parameter></paramdef> 802 <paramdef>float <parameter>lly</parameter></paramdef> 803 <paramdef>float <parameter>urx</parameter></paramdef> 804 <paramdef>float <parameter>ury</parameter></paramdef> 805 <paramdef>const char *<parameter>url</parameter></paramdef> 806 </funcprototype> 807 </funcsynopsis> 808 <funcsynopsis> 809 <funcprototype> 810 <funcdef>int <function>PS_add_pdflink</function></funcdef> 811 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 812 <paramdef>float <parameter>llx</parameter></paramdef> 813 <paramdef>float <parameter>lly</parameter></paramdef> 814 <paramdef>float <parameter>urx</parameter></paramdef> 815 <paramdef>float <parameter>ury</parameter></paramdef> 816 <paramdef>const char *<parameter>filename</parameter></paramdef> 817 <paramdef>int <parameter>page</parameter></paramdef> 818 <paramdef>const char *<parameter>dest</parameter></paramdef> 819 </funcprototype> 820 </funcsynopsis> 821 <funcsynopsis> 822 <funcprototype> 823 <funcdef>int <function>PS_add_locallink</function></funcdef> 824 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 825 <paramdef>float <parameter>llx</parameter></paramdef> 826 <paramdef>float <parameter>lly</parameter></paramdef> 827 <paramdef>float <parameter>urx</parameter></paramdef> 828 <paramdef>float <parameter>ury</parameter></paramdef> 829 <paramdef>int <parameter>page</parameter></paramdef> 830 <paramdef>const char *<parameter>dest</parameter></paramdef> 831 </funcprototype> 832 </funcsynopsis> 833 <funcsynopsis> 834 <funcprototype> 835 <funcdef>int <function>PS_add_launchlink</function></funcdef> 836 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 837 <paramdef>float <parameter>llx</parameter></paramdef> 838 <paramdef>float <parameter>lly</parameter></paramdef> 839 <paramdef>float <parameter>urx</parameter></paramdef> 840 <paramdef>float <parameter>ury</parameter></paramdef> 841 <paramdef>const char *<parameter>filename</parameter></paramdef> 842 </funcprototype> 843 </funcsynopsis> 844 <para>Each of the above function requires a rectangle with its lower 845 left corner at <parameter>llx</parameter>, <parameter>lly</parameter> 846 and its upper right corner at <parameter>urx</parameter>, 847 <parameter>ury</parameter>. The rectangle will not be visible in the 848 PostScript file and marks the sensitve area of the link. When the 849 document is concerted to PDF, the rectangle will become visible. 850 Its appearance can be set with the functions.</para> 851 <funcsynopsis> 852 <funcprototype> 853 <funcdef>int <function>PS_set_border_style</function></funcdef> 854 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 855 <paramdef>const char *<parameter>style</parameter></paramdef> 856 <paramdef>float <parameter>width</parameter></paramdef> 857 </funcprototype> 858 </funcsynopsis> 859 <para><parameter>style</parameter> can be either 'solid' or 'dashed'.</para> 860 <funcsynopsis> 861 <funcprototype> 862 <funcdef>int <function>PS_set_border_color</function></funcdef> 863 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 864 <paramdef>float <parameter>red</parameter></paramdef> 865 <paramdef>float <parameter>green</parameter></paramdef> 866 <paramdef>float <parameter>blue</parameter></paramdef> 867 </funcprototype> 868 </funcsynopsis> 869 <funcsynopsis> 870 <funcprototype> 871 <funcdef>int <function>PS_set_border_dash</function></funcdef> 872 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 873 <paramdef>float <parameter>black</parameter></paramdef> 874 <paramdef>float <parameter>white</parameter></paramdef> 875 </funcprototype> 876 </funcsynopsis> 877 <para>pslib also supports to add bookmarks which will be displayed 878 by PDF viewers as a table of contents next to the document. Bookmarks have 879 a title and point to a page in the document. The can be added with</para> 880 <funcsynopsis> 881 <funcprototype> 882 <funcdef>int <function>PS_add_bookmark</function></funcdef> 883 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 884 <paramdef>const char *<parameter>text</parameter></paramdef> 885 <paramdef>int <parameter>parent</parameter></paramdef> 886 <paramdef>int <parameter>open</parameter></paramdef> 887 </funcprototype> 888 </funcsynopsis> 889 <para>To build up a hierachical tree of bookmarks, one can pass a 890 parent bookmark when creating a new one. The parent bookmark is referenced 891 by its id as it is returned by the function itself. A bookmark is 892 always added for the current page. It is shown open if the parameter 893 <parameter>open</parameter> is greater 0.</para> 894 895 </refsect1> 896 <refsect1> 897 <title>TYPE3 FONTS</title> 898 899 <para>PostScript knows several types of fonts. The most common is 900 called Type1 which are usally supplied by many font manufactures 901 as .pfb files. pslib can read those fonts and use them right away. 902 Another type of font is called Type3. Type3 fonts distinguish from 903 Type1 fonts by the way its glyphs are constructed. Glyphs in Type3 904 fonts are created with regular PostScript commands and can easily 905 be created with pslib. All you need to do is start a new font with</para> 906 <funcsynopsis> 907 <funcprototype> 908 <funcdef>int <function>PS_begin_font</function></funcdef> 909 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 910 <paramdef>const char *<parameter>fontname</parameter></paramdef> 911 <paramdef>int <parameter>reserved</parameter></paramdef> 912 <paramdef>double <parameter>a</parameter></paramdef> 913 <paramdef>double <parameter>b</parameter></paramdef> 914 <paramdef>double <parameter>c</parameter></paramdef> 915 <paramdef>double <parameter>d</parameter></paramdef> 916 <paramdef>double <parameter>e</parameter></paramdef> 917 <paramdef>double <parameter>f</parameter></paramdef> 918 <paramdef>const char *<parameter>optlist</parameter></paramdef> 919 </funcprototype> 920 </funcsynopsis> 921 <para>and end finish it with</para> 922 <funcsynopsis> 923 <funcprototype> 924 <funcdef>int <function>PS_end_font</function></funcdef> 925 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 926 </funcprototype> 927 </funcsynopsis> 928 <para>Each font contains of a number of glyphs which are created 929 with a pair of</para> 930 <funcsynopsis> 931 <funcprototype> 932 <funcdef>int <function>PS_begin_glyph</function></funcdef> 933 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 934 <paramdef>const char *<parameter>glyphname</parameter></paramdef> 935 <paramdef>double <parameter>wx</parameter></paramdef> 936 <paramdef>double <parameter>llx</parameter></paramdef> 937 <paramdef>double <parameter>lly</parameter></paramdef> 938 <paramdef>double <parameter>urx</parameter></paramdef> 939 <paramdef>double <parameter>ury</parameter></paramdef> 940 </funcprototype> 941 </funcsynopsis> 942 <para>and</para> 943 <funcsynopsis> 944 <funcprototype> 945 <funcdef>int <function>PS_end_glyph</function></funcdef> 946 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 947 </funcprototype> 948 </funcsynopsis> 949 <para>Within a glyph each command is allowed to create a path and to 950 stroke or fill it. Once a font is created it can be used like any 951 other font by calling <function>PS_setfont(3)</function>.</para> 952 <para>The font cannot be saved to a file and used by other applications 953 but it can used within the pslib document which has several advantages 954 when certain symbols, e.g. logos are used through out a document.</para> 955 956 </refsect1> 957 <refsect1> 958 <title>MEMORY MANAGEMENT, ERROR HANDLING</title> 959 960 <para>pslib uses by default its on memory management and error handling 961 functions. In many cases the calling application has its own memory 962 management and error handling. pslib can be told to use those 963 functions by calling <function>PS_new2(3)</function> instead of 964 <function>PS_new(3)</function>.</para> 965 <funcsynopsis> 966 <funcprototype> 967 <funcdef>int <function>PS_new2</function></funcdef> 968 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 969 <paramdef>(errorhandler *) <parameter>(PSDoc *p, int type, const char *msg, void *data)</parameter></paramdef> 970 <paramdef>(allocproc *) <parameter>(PSDoc *p, size_t size, const char *caller)</parameter></paramdef> 971 <paramdef>(reallocproc *) <parameter>(PSDoc *p, void *mem, size_t size, const char *caller)</parameter></paramdef> 972 <paramdef>(freeproc *) <parameter>(PSDoc *p, void *mem)</parameter></paramdef> 973 <paramdef>void *<parameter>opaque</parameter></paramdef> 974 </funcprototype> 975 </funcsynopsis> 976 <para>The errorhandler and the last parameter <parameter>opaque</parameter> 977 allow to pass arbitrary data as the last parameter to its own 978 errorhandler. This is quite often used if errors are being output 979 in a widget of a graphical toolkit. The pointer to that widget can 980 be passed as <parameter>opaque</parameter> and pslib will pass it 981 forward to the error handler.</para> 982 983 </refsect1> 984 <refsect1> 985 <title>DOCUMENT INFORMATION</title> 986 987 <para>PostScript documents usually contain a header made of comments 988 with information about the document. The printer usually disregards 989 this information but many PostScript viewer use it. Besides that, 990 one can also place pdfmarks into the PostScript document which contain 991 the title, keywords, author and other information. pslib provides the 992 function <function>PS_set_info(3)</function> to set those fields.</para> 993 <funcsynopsis> 994 <funcprototype> 995 <funcdef>int <function>PS_set_info</function></funcdef> 996 <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef> 997 <paramdef>const char *<parameter>key</parameter></paramdef> 998 <paramdef>const char *<parameter>value</parameter></paramdef> 999 </funcprototype> 1000 </funcsynopsis> 1001 <para><function>PS_set_info(3)</function> must be called before the 1002 first page. Calling it later will have no effect and produces a warning. 1003 The function may also be used to set the bounding box of the document. 1004 Usually there is no need for it, because the dimension of the first 1005 page will be used for the bounding box.</para> 1006 1007 </refsect1> 1008 <refsect1> 1009 <title>SEE ALSO</title> 1010 1011 <para>The detailed manual pages for each function of the library.</para> 1012 1013 </refsect1> 1014 <refsect1> 1015 <title>AUTHOR</title> 1016 1017 <para>This manual page was written by &dhusername; &dhemail;.</para> 1018 1019 </refsect1> 1020</refentry> 1021 1022<!-- Keep this comment at the end of the file 1023Local variables: 1024mode: sgml 1025sgml-omittag:t 1026sgml-shorttag:t 1027sgml-minimize-attributes:nil 1028sgml-always-quote-attributes:t 1029sgml-indent-step:2 1030sgml-indent-data:t 1031sgml-parent-document:nil 1032sgml-default-dtd-file:nil 1033sgml-exposed-tags:nil 1034sgml-local-catalogs:nil 1035sgml-local-ecat-files:nil 1036End: 1037--> 1038 1039 1040