pslib.sgml

PSlib是一个用来生成PostScript文件的类库。提供了一个生成PostScript文件的简单方法。

<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@

    
	The docbook-to-man binary is found in the docbook-to-man package.
	Please remember that if you create the nroff version in one of the
	debian/rules file targets (such as build), you will need to include
	docbook-to-man in your Build-Depends control field.

  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>UWE</firstname>">
  <!ENTITY dhsurname   "<surname>STEINMANN</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>Jul 2, 2007</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>3</manvolnum>">
  <!ENTITY dhemail     "<email>[e-mail]</email>">
  <!ENTITY dhusername  "Uwe Steinmann">
  <!ENTITY dhucpackage "<refentrytitle>PSLIB</refentrytitle>">
  <!ENTITY funcname    "pslib">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright> <year>2004</year> <holder>&dhusername;</holder> </copyright> &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&funcname;</refname>

    <refpurpose>Library to create PostScript files</refpurpose>
  </refnamediv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>pslib is a library to create PostScript files with a set of
		  about 50 functions for line drawing, text output, page handling, etc.
			It is very similar to other libraries like panda, cpdf or pdflib which
			produce PDF. pslib can to a certain degree replace those libraries if
			the PostScript file is converted to PDF with ghostscripts excellent
			pdf writer. The results achieved with pslib can be even better when
			it comes to text output, because it supports kerning, ligatures and
			hyphenation.
			</para>
		<para>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.</para>

  </refsect1>
  <refsect1>
    <title>GETTING STARTED</title>

    <para>Programs which want to use pslib will have to include the
		  header file <literal>libps/pslib.h</literal> and link against libps.
			Before doing any document
			creation the library should be initialized with
			<function>PS_boot(3)</function>. 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
			<function>isalpha(3)</function> and <function>tolower(3)</function>
			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 <function>PS_shutdown(3)</function>.</para>
		<para>A PostScript document is
			represented by a pointer to <literal>PSDoc</literal>. Such a document
			can be created with <function>PS_new(3)</function> and destroyed
			with <function>PS_delete(3)</function>. <function>PS_new(3)</function> 
			returns a pointer to <literal>PSDoc</literal>. You can handle several
			documents at the same time. The following example will do the basic
			preparation without creating a document on the disk.</para>
	  <programlisting>
...
#include &lt;libps/pslib.h&gt;

main(int argc, char *argv[]) {
	PSDoc *psdoc;

	PS_boot();
	psdoc = PS_new();
	PS_delete(psdoc);
	PS_shutdown();
}
	  </programlisting>
		<para>In order to actually create a PostScript document on disk you will
		  have to call</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_open_file</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>filename</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>or</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_open_fp</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>FILE *<parameter>fp</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para><function>PS_open_file(3)</function> will create a new file
		  with the given file name, while <function>PS_open_fp(3)</function>
			will use an already open file. Both require a pointer to
			<literal>PSDoc</literal>.</para>
		<para>If the document shall not be created on disk but in memory,
		  which can be very handy in web application, one can use</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_open_mem</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>(*writeproc) <parameter>(PSDoc *p, void *data, size_t size)</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>The second parameter is a function which is called instead of pslib's
		  own output function.</para>
		<para>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 <function>PS_close(3)</function>.
			<function>PS_close(3)</function> will only close the file if it
			was opened by <function>PS_open_file(3)</function>.
			</para>
	  <programlisting>
...
#include &lt;libps/pslib.h&gt;

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();
}
	  </programlisting>
		<para>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
			<function>PS_new2(3)</function> and <function>PS_new3(3)</function> for
			a detailed description or read the section about memory management
			and error handler below..</para>
  </refsect1>
  <refsect1>
    <title>PAGE HANDLING</title>

    <para>A PostScript document contains one or more pages. pslib provides
		  the function</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_begin_page</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>width</parameter></paramdef>
		    <paramdef>float <parameter>height</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>and</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_end_page</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>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.</para>
		<para>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.</para>
  </refsect1>
  <refsect1>
    <title>COORDINATE SYSTEM, SCOPE</title>

    <para>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.</para>
		<para>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.</para>
  </refsect1>
  <refsect1>
    <title>DRAWING, PATH CONSTRUCTION</title>

    <para>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.</para>
		<para>Each path is started with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_moveto</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
		    <paramdef>float <parameter>y</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>If this function is called within a path, it will just start
		  a new subpath. The path can be constructed with one of the following
			functions.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_lineto</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
		    <paramdef>float <parameter>y</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_rect</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
		    <paramdef>float <parameter>y</parameter></paramdef>