pslib.sgml

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

			loaded with <function>PS_findfont(3)</function>. 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.</para>
		<programlisting>
N hyphen ; M 0 650 ;
N comma ; M 0 650 ;
N period ; M 0 650 ;
N semicolon ; M 0 500 ;
		</programlisting>
		<para>The syntax is similar to an .afm file. The protusion values for the
		  left and right margin are the last two numbers.</para>
  </refsect1>
  <refsect1>
    <title>LOADING FILES</title>

    <para>All files which are being loaded by pslib are searched
		  for in the current directory and the 'SearchPath'. 'SearchPath' is
			a parameter which is set by <function>PS_set_parameter(3)</function>.
			<function>PS_set_parameter(3)</function> can be called multiple
			times to add several directories to the search path. Function which
			are affected by the search path are <function>PS_findfont(3)</function>
			for loading .afm, .pfb, and .enc files,
			<function>PS_include_file(3)</function>.</para>
  </refsect1>
  <refsect1>
    <title>RESOURCE HANDLING</title>

    <para>Resources in pslib are fonts, patterns, templates, spot colors, and
		  images. Templates and images are treated equally. A resource is usally
			loaded or created and can be used repeatingly afterwards. Resource
			handling is
			somewhat sensitve, in terms of the position in the document where they
			are loaded or created. Plain PostScript does not care about where a
			resource is defined as long as it is known before it is used. PostScript
			documents are not always printed but quite often displayed on the screen
			or processed by software. Most software which reads PostScript documents
			does not just interpret the PostScript code but also so called Document
			Structuring Conventions (DSC). Such instructions are helpful to provide
			further information about the document and to partion the document
			into sections like a prolog and pages. Programs evaluating those
			instructions can easy determine the page size, the creator, title or
			author, the number of pages and can jump straight to a certain page
			without interpreting the PostScript code before that page. Especially
			isolating certain pages requires the document to be created stringly
			following the DSC. This means that all resource which are used through
			out the document must be either created on each page where they are
			used (not very sensible if the resource is used more than once)
			or within the prolog right before the first
			page. pslib will put everything before the first page into the prolog.
			On the other side the prolog may not contain any PostScript code that
			does output something. pslib makes sure this rule is not violated.
			</para>
		<para>In practice the above rules do not apply equally to all resource
		  but can be seen as a general rule of thumb. Fonts can under certain
			circumstances be loaded at any time (see the section on 'Text output').
			The same is currently true for images, which is likely to be changed
			in the future.
			</para>
  </refsect1>
  <refsect1>
    <title>IMAGES</title>

    <para>Placing images on a page in the PostScript document is similar
		  to font handling. First the image has to be loaded with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_open_image_file</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>type</parameter></paramdef>
		    <paramdef>const char *<parameter>filename</parameter></paramdef>
		    <paramdef>const char *<parameter>stringparam</parameter></paramdef>
		    <paramdef>int <parameter>intparam</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>or</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_open_image</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>type</parameter></paramdef>
		    <paramdef>const char *<parameter>source</parameter></paramdef>
		    <paramdef>const char *<parameter>data</parameter></paramdef>
		    <paramdef>long <parameter>length</parameter></paramdef>
		    <paramdef>int <parameter>width</parameter></paramdef>
		    <paramdef>int <parameter>height</parameter></paramdef>
		    <paramdef>int <parameter>components</parameter></paramdef>
		    <paramdef>int <parameter>bpc</parameter></paramdef>
		    <paramdef>const char *<parameter>params</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
	  <para>and than it can be placed on the page with the function</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_place_image</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>int <parameter>imageid</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
				<paramdef>float <parameter>y</parameter></paramdef>
		    <paramdef>float <parameter>scale</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>Images are currently not real resources. Each call of
			<function>PS_place_image(3)</function> will write the complete images
			into the PostScript file.</para>

  </refsect1>
  <refsect1>
    <title>TEMPLATES</title>

    <para>Templates are a bit like images created within the document
		  itself. Their big advantage is its reusability on any page thoughout
			the document by simply referencing them. This saves a lot of disk space
			if the template is placed many times. They are often used for logos or
			headers which are to
			be placed on each page. A template is started with the function</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_begin_template</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>width</parameter></paramdef>
				<paramdef>float <parameter>height</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <para>Like a page or an image a template has a boundig box. Within that
		  box almost any operation for drawing, text output, etc. can be called.
			Everything beyond the bounding box is clipped.
			A template is ended and ready for use with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_end_template</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>Each template has its own id which was returned by
			<function>PS_begin_template(3)</function>. This id is like an image id and
			can be passed to <function>PS_place_image(3)</function>. This makes a
			template identical to an image in terms of handling. Any call of
			<function>PS_place_image(3)</function> will only place a reference to
			the template into the document which results in a small document
			size.</para>
  </refsect1>
  <refsect1>
    <title>COLORS</title>

    <para>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</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_setcolor</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>type</parameter></paramdef>
		    <paramdef>const char *<parameter>colorspace</parameter></paramdef>
		    <paramdef>float <parameter>c1</parameter></paramdef>
		    <paramdef>float <parameter>c2</parameter></paramdef>
		    <paramdef>float <parameter>c3</parameter></paramdef>
		    <paramdef>float <parameter>c4</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para><parameter>type</parameter> determines if the fill, stroke or
		  both (fillstroke) colors are set by the function. The colorspace
			can be any of 'gray', 'rgb', 'cmyk', 'spot', or 'pattern'. The colorspace
			'pattern' is somewhat special and will be discussed in the next section.
			The float parameters contain the actual values of the color. Depending
			on the colorspace not all parameters will be evaluated. Spot colors
			need to be created before with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_makespotcolor</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>name</parameter></paramdef>
		    <paramdef>float<parameter>reserved</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>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
			<function>PS_setcolor(3)</function> and set the current fill color before
			calling <function>PS_makespotcolor(3)</function>.
			<function>PS_makespotcolor(3)</function> can only handle fill colors in
			the colorspace 'gray', 'rgb', or 'cmyk'.</para>
		<para><function>PS_makespotcolor(3)</function> returns the id of the spot
		  color which is passed as parameter <parameter>c1</parameter> to
			<function>PS_setcolor(3)</function>. All spot colors used in the document
			should be defined before the first page, otherwise they will not be
			included into the list of custom colors within the document comments
			section at the beginning of the file.</para>

  </refsect1>
  <refsect1>
    <title>COLOR SEPARATION</title>

    <para>Printing a document sometimes requires to separate colors
		  because certain printers print each color separately.
			Color separation is often done on the
			multi color document by the printing company. However, pslib can 
			separate colors very easily by setting the value 'separationcolor' on
			a value from 1 to 4, depending on the color you would like to separate
			(1=cyan, 2=magenta, 3=yellow, 4=black). This has to be done before
			creating a page. The resulting document will
			contain only those parts in the separated color. Consequently, one
			has to create four identical pages, each called with a different value
			for 'separationcolor'.
			</para>
  </refsect1>
  <refsect1>
    <title>PATTERNS</title>

    <para>Filling an area can be done with a single color or a self designed
		  pattern. Such a pattern can be any drawing. Actually, it can be everything
			which can be put on a page. If a pattern is used for filling it is
			repeatingly placed in horizontal and vertical direction with a given
			distance. Pattern are started with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_begin_pattern</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>width</parameter></paramdef>
				<paramdef>float <parameter>height</parameter></paramdef>
				<paramdef>float <parameter>xstep</parameter></paramdef>
				<paramdef>float <parameter>ystep</parameter></paramdef>
				<paramdef>int <parameter>painttype</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>and ended with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_end_pattern</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>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 <function>PS_begin_pattern(3)</function>)
			to <function>PS_setcolor(3)</function>. Any following drawing and/or
			filling operation will now use the pattern.</para>
  </refsect1>
  <refsect1>
    <title>HYPERLINKS, BOOKMARKS</title>

    <para>PostScript itself does not support any hyperlink functions like
		  PDF does. Nervertheless, one can embed hyperlinks into a PostScript
			document which will be used if the document is later converted to PDF.
			Such commands for embedding hyperlinks are called pdfmarks. pdfmarks
			allow to store any feature in a PostScript document which is available