pslib.sgml

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

		    <paramdef>float <parameter>width</parameter></paramdef>
		    <paramdef>float <parameter>height</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_circle</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
		    <paramdef>float <parameter>y</parameter></paramdef>
		    <paramdef>float <parameter>radius</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_arc</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
		    <paramdef>float <parameter>y</parameter></paramdef>
		    <paramdef>float <parameter>radius</parameter></paramdef>
		    <paramdef>float <parameter>alpha</parameter></paramdef>
		    <paramdef>float <parameter>beta</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_arcn</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
		    <paramdef>float <parameter>y</parameter></paramdef>
		    <paramdef>float <parameter>radius</parameter></paramdef>
		    <paramdef>float <parameter>alpha</parameter></paramdef>
		    <paramdef>float <parameter>beta</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_curveto</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>float <parameter>x1</parameter></paramdef>
		    <paramdef>float <parameter>y1</parameter></paramdef>
		    <paramdef>float <parameter>x2</parameter></paramdef>
		    <paramdef>float <parameter>y2</parameter></paramdef>
		    <paramdef>float <parameter>x3</parameter></paramdef>
		    <paramdef>float <parameter>y3</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>Once a path is constructed it can be optionally closed by</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_closepath</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>Closing a path means to add a segment from the last point to
		  the starting 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</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_stroke</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>In such a case you would not want to close the path. As already
		  mentioned a path can also be filled or even both with the
			functions.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_fill</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>void <function>PS_fill_stroke</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para><function>PS_fill_stroke(3)</function> does first fill and than
		  stroke a path. This is important to realize because the stroken line
			may cover parts of the filled area, depending on how wide it is.<para>
  </refsect1>
  <refsect1>
    <title>TEXT OUTPUT</title>

    <para>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 paragraph into acount.</para>
		<para>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
			available in the internet. If the font is to be embedded into
			the document, then the font outline (.pfb file) is also needed.</para>
    <para>Additional files are needed for more sophisticated text output.
		  It will be explained later in this documentation.
		  </para>
		<para>Before being able to output any text a font has to be loaded
		  with</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_findfont</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>fontname</parameter></paramdef>
		    <paramdef>const char *<parameter>encoding</parameter></paramdef>
		    <paramdef>int <parameter>embed</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>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
			<parameter>fontname</parameter>.pfb must be present.</para>
		<para>The <parameter>encoding</parameter> 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 provided by the font itself. It is usually
			AdobeStandardEncoding which is a smaller set of glyphs than TeXBase1.
			If unsure leave the encoding parameter empty.
			</para>
		<para>Calling <function>PS_findfont(3)</function> 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 limitation
			has to be enforced in order to be able to extract certain pages from
			the document without corruption. Programs like <command>psselect</command>
			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 resources will provoke errors.
			pslib will output a warning in case of
			potential problems.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_setfont</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>int <parameter>fontid</parameter></paramdef>
		    <paramdef>float <parameter>size</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
	  <para>sets the font which was loaded with
		  <function>PS_findfont(3)</function>	in a given size. After 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.</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_show</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>text</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>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</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_show_xy</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>text</parameter></paramdef>
		    <paramdef>float <parameter>x</parameter></paramdef>
		    <paramdef>float <parameter>y</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>can be used. Both functions also exist in a version which requires
		  the length of the string as the third parameter. The are called
			<function>PS_show2(3)</function> and <function>PS_show_xy2(3)</function>.
			</para>
		<para>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</para>
    <funcsynopsis>
      <funcprototype>
		    <funcdef>int <function>PS_show_boxed</function></funcdef>
		    <paramdef>PSDoc *<parameter>psdoc</parameter></paramdef>
		    <paramdef>const char *<parameter>text</parameter></paramdef>
		    <paramdef>float <parameter>left</parameter></paramdef>
		    <paramdef>float <parameter>bottom</parameter></paramdef>
		    <paramdef>float <parameter>width</parameter></paramdef>
		    <paramdef>float <parameter>height</parameter></paramdef>
		    <paramdef>const char *<parameter>hmode</parameter></paramdef>
		    <paramdef>const char *<parameter>feature</parameter></paramdef>
      </funcprototype>
	  </funcsynopsis>
		<para>should be usesd. It breaks the text into lines of length
		<parameter>width</parameter> 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 <parameter>hmode</parameter>.
			Hyphenation is turned off by default, because it needs to be set up
			before it can be used.
			</para>
    <para>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.</para>
  </refsect1>
  <refsect1>
    <title>HYPHENATION, KERNING, LIGATURES, PROTUSION</title>

    <para>pslib's advanced text output features cover hyphenation, kerning,
		  ligatures 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.</para>
		<para>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 position 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 encoding
			file is very similar to encoding files used by <command>dvips</command>
			and usually found in <filename>/usr/share/texmf/dvips/base</filename>.
			Adding a ligature requires a line like the following:</para>
		<programlisting>
% LIGKERN char1 char2 =: ligature ;
		</programlisting>
		<para>If 'char1' is followed by 'char2' they will be both replaced by the
		  glyph 'ligature'. This replacement may not be used exclusively for
			ligatures like 'fi' or 'ff' but for any combination of characters.
			Quite common is a hyphen followed by a hyphen, which is replaced by an
			endash.</para>
		<para>In order to set up hyphenation you will first need a hyphenation
		  dictionary for your language. Since pslib uses a well know hyphenation
			algorithmn used not just by TeX, but also by openoffice and scribus,
			one can take the dictionary from those programs. If you have scribus
			installed on your system, you will find the dictionaries for many
			languages in <filename>/usr/lib/scribus/dicts</filename>.</para>
		<para>Hyphenation is turned on when the parameter 'hyphenation' is set
		  to true and the parameter 'hyphendict' contains the file name of the
			hyphenation dictionary.</para>
		<para>Protusion is an advanced method to improve the appearance of text
		  margins. It is only used by the function
			<function>PS_show_boxed(3)</function> if the horizontal 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 whenever a font is