pslib.sgml

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

			in PDF. The PostScript interpreter itself will not care about the
			pdfmarks. This features makes pslib a viable alternative to libraries
			creating PDF directly.</para>
		<para>Some functions of pslib will place a pdfmark silently into the
		  document. The most prominent function is
			<function>PS_begin_page(3)</function> which stores the page size with
			the help of pdfmarks.</para>
		<para>pslib supports several types of hyperlinks, which are inserted
		  with the following function.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_add_weblink</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>llx</parameter></paramdef>
		    <paramdef>float <parameter>lly</parameter></paramdef>
		    <paramdef>float <parameter>urx</parameter></paramdef>
		    <paramdef>float <parameter>ury</parameter></paramdef>
		    <paramdef>const char *<parameter>url</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_add_pdflink</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>llx</parameter></paramdef>
		    <paramdef>float <parameter>lly</parameter></paramdef>
		    <paramdef>float <parameter>urx</parameter></paramdef>
		    <paramdef>float <parameter>ury</parameter></paramdef>
		    <paramdef>const char *<parameter>filename</parameter></paramdef>
		    <paramdef>int <parameter>page</parameter></paramdef>
		    <paramdef>const char *<parameter>dest</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_add_locallink</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>llx</parameter></paramdef>
		    <paramdef>float <parameter>lly</parameter></paramdef>
		    <paramdef>float <parameter>urx</parameter></paramdef>
		    <paramdef>float <parameter>ury</parameter></paramdef>
		    <paramdef>int <parameter>page</parameter></paramdef>
		    <paramdef>const char *<parameter>dest</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_add_launchlink</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>llx</parameter></paramdef>
		    <paramdef>float <parameter>lly</parameter></paramdef>
		    <paramdef>float <parameter>urx</parameter></paramdef>
		    <paramdef>float <parameter>ury</parameter></paramdef>
		    <paramdef>const char *<parameter>filename</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <para>Each of the above function requires a rectangle with its lower
		  left corner at <parameter>llx</parameter>, <parameter>lly</parameter>
			and its upper right corner at <parameter>urx</parameter>,
			<parameter>ury</parameter>. The rectangle will not be visible in the
			PostScript file and marks the sensitve area of the link. When the
			document is concerted to PDF, the rectangle will become visible.
			Its appearance can be set with the functions.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_set_border_style</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>style</parameter></paramdef>
		    <paramdef>float <parameter>width</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para><parameter>style</parameter> can be either 'solid' or 'dashed'.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_set_border_color</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>red</parameter></paramdef>
		    <paramdef>float <parameter>green</parameter></paramdef>
		    <paramdef>float <parameter>blue</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_set_border_dash</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>black</parameter></paramdef>
		    <paramdef>float <parameter>white</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <para>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</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_add_bookmark</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>text</parameter></paramdef>
		    <paramdef>int <parameter>parent</parameter></paramdef>
		    <paramdef>int <parameter>open</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>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
			<parameter>open</parameter> is greater 0.</para>

  </refsect1>
  <refsect1>
    <title>TYPO3 FONTS</title>

    <para>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</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_begin_font</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>fontname</parameter></paramdef>
		    <paramdef>int <parameter>reserved</parameter></paramdef>
		    <paramdef>double <parameter>a</parameter></paramdef>
		    <paramdef>double <parameter>b</parameter></paramdef>
		    <paramdef>double <parameter>c</parameter></paramdef>
		    <paramdef>double <parameter>d</parameter></paramdef>
		    <paramdef>double <parameter>e</parameter></paramdef>
		    <paramdef>double <parameter>f</parameter></paramdef>
		    <paramdef>const char *<parameter>optlist</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>and end finish it with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_end_font</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>Each font contains of a number of glyphs which are created
		  with a pair of</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_begin_glyph</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>glyphname</parameter></paramdef>
		    <paramdef>double <parameter>wx</parameter></paramdef>
		    <paramdef>double <parameter>llx</parameter></paramdef>
		    <paramdef>double <parameter>lly</parameter></paramdef>
		    <paramdef>double <parameter>urx</parameter></paramdef>
		    <paramdef>double <parameter>ury</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>and</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_end_glyph</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>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 <function>PS_setfont(3)</function>.</para>
		<para>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.</para>

  </refsect1>
  <refsect1>
    <title>MEMORY MANAGEMENT, ERROR HANDLING</title>

    <para>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 <function>PS_new2(3)</function> instead of
			<function>PS_new(3)</function>.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_new2</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>(errorhandler *) <parameter>(PSDoc *p, int type, const char *msg, void *data)</parameter></paramdef>
		    <paramdef>(allocproc *) <parameter>(PSDoc *p, size_t size, const char *caller)</parameter></paramdef>
		    <paramdef>(reallocproc *) <parameter>(PSDoc *p, void *mem, size_t size, const char *caller)</parameter></paramdef>
		    <paramdef>(freeproc *) <parameter>(PSDoc *p, void *mem)</parameter></paramdef>
		    <paramdef>void *<parameter>opaque</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>The errorhandler and the last parameter <parameter>opaque</parameter>
		  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 <parameter>opaque</parameter> and pslib will pass it
			forward to the error handler.</para>

  </refsect1>
  <refsect1>
    <title>DOCUMENT INFORMATION</title>

    <para>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 <function>PS_set_info(3)</function> to set those fields.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_set_info</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>key</parameter></paramdef>
		    <paramdef>const char *<parameter>value</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <para><function>PS_set_info(3)</function> 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.</para>

  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>

    <para>The detailed manual pages for each function of the library.</para>

  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

    <para>This manual page was written by &dhusername; &dhemail;.</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->