RubyGems - cairo - Versions diffs - 1.8.3-x86-mingw32 → 1.8.4-x86-mingw32 - Mend

cairo 1.8.3-x86-mingw32 → 1.8.4-x86-mingw32

Potentially problematic release.

This version of cairo might be problematic. Click here for more details.

Files changed (126) hide show

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/cairo-ps-surface.html ADDED Viewed

@@ -0,0 +1,622 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>PostScript Surfaces</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
+<link rel="up" href="cairo-surfaces.html" title="Surfaces">
+<link rel="prev" href="cairo-png-functions.html" title="PNG Support">
+<link rel="next" href="cairo-win32-surface.html" title="Win32 Surfaces">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
+<tr valign="middle">
+<td><a accesskey="p" href="cairo-png-functions.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="cairo-surfaces.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="cairo-win32-surface.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr>
+<tr><td colspan="5" class="shortcuts">
+<a href="#cairo-ps-surface.synopsis" class="shortcut">Top</a>
+                 |
+                <a href="#cairo-ps-surface.description" class="shortcut">Description</a>
+</td></tr>
+</table>
+<div class="refentry" title="PostScript Surfaces">
+<a name="cairo-ps-surface"></a><div class="titlepage"></div>
+<div class="refnamediv"><table width="100%"><tr>
+<td valign="top">
+<h2><span class="refentrytitle"><a name="cairo-ps-surface.top_of_page"></a>PostScript Surfaces</span></h2>
+<p>PostScript Surfaces — Rendering PostScript documents</p>
+</td>
+<td valign="top" align="right"></td>
+</tr></table></div>
+<div class="refsynopsisdiv" title="Synopsis">
+<a name="cairo-ps-surface.synopsis"></a><h2>Synopsis</h2>
+<pre class="synopsis">
+#define             <a class="link" href="cairo-ps-surface.html#CAIRO-HAS-PS-SURFACE--CAPS" title="CAIRO_HAS_PS_SURFACE">CAIRO_HAS_PS_SURFACE</a>
+<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *   <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-create" title="cairo_ps_surface_create ()">cairo_ps_surface_create</a>             (const char *filename,
+                                                         double width_in_points,
+                                                         double height_in_points);
+<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *   <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-create-for-stream" title="cairo_ps_surface_create_for_stream ()">cairo_ps_surface_create_for_stream</a>  (<a class="link" href="cairo-png-functions.html#cairo-write-func-t" title="cairo_write_func_t ()">cairo_write_func_t</a> write_func,
+                                                         void *closure,
+                                                         double width_in_points,
+                                                         double height_in_points);
+void                <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-restrict-to-level" title="cairo_ps_surface_restrict_to_level ()">cairo_ps_surface_restrict_to_level</a>  (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         <a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a> level);
+enum                <a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a>;
+void                <a class="link" href="cairo-ps-surface.html#cairo-ps-get-levels" title="cairo_ps_get_levels ()">cairo_ps_get_levels</a>                 (<a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a> const **levels,
+                                                         int *num_levels);
+const char *        <a class="link" href="cairo-ps-surface.html#cairo-ps-level-to-string" title="cairo_ps_level_to_string ()">cairo_ps_level_to_string</a>            (<a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a> level);
+void                <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-set-eps" title="cairo_ps_surface_set_eps ()">cairo_ps_surface_set_eps</a>            (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         <a class="link" href="cairo-types.html#cairo-bool-t" title="cairo_bool_t">cairo_bool_t</a> eps);
+<a class="link" href="cairo-types.html#cairo-bool-t" title="cairo_bool_t">cairo_bool_t</a>        <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-get-eps" title="cairo_ps_surface_get_eps ()">cairo_ps_surface_get_eps</a>            (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface);
+void                <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-set-size" title="cairo_ps_surface_set_size ()">cairo_ps_surface_set_size</a>           (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         double width_in_points,
+                                                         double height_in_points);
+void                <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-begin-setup" title="cairo_ps_surface_dsc_begin_setup ()">cairo_ps_surface_dsc_begin_setup</a>    (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface);
+void                <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-begin-page-setup" title="cairo_ps_surface_dsc_begin_page_setup ()">cairo_ps_surface_dsc_begin_page_setup</a>
+                                                        (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface);
+void                <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()">cairo_ps_surface_dsc_comment</a>        (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         const char *comment);
+</pre>
+</div>
+<div class="refsect1" title="Description">
+<a name="cairo-ps-surface.description"></a><h2>Description</h2>
+<p>
+The PostScript surface is used to render cairo graphics to Adobe
+PostScript files and is a multi-page vector surface backend.
+</p>
+</div>
+<div class="refsect1" title="Details">
+<a name="cairo-ps-surface.details"></a><h2>Details</h2>
+<div class="refsect2" title="CAIRO_HAS_PS_SURFACE">
+<a name="CAIRO-HAS-PS-SURFACE--CAPS"></a><h3>CAIRO_HAS_PS_SURFACE</h3>
+<pre class="programlisting">#define CAIRO_HAS_PS_SURFACE 1
+</pre>
+<p>
+Defined if the PostScript surface backend is available.
+This macro can be used to conditionally compile backend-specific code.
+</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_create ()">
+<a name="cairo-ps-surface-create"></a><h3>cairo_ps_surface_create ()</h3>
+<pre class="programlisting"><a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *   cairo_ps_surface_create             (const char *filename,
+                                                         double width_in_points,
+                                                         double height_in_points);</pre>
+<p>
+Creates a PostScript surface of the specified size in points to be
+written to <em class="parameter"><code>filename</code></em>. See <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-create-for-stream" title="cairo_ps_surface_create_for_stream ()"><code class="function">cairo_ps_surface_create_for_stream()</code></a> for
+a more flexible mechanism for handling the PostScript output than
+simply writing it to a named file.
+</p>
+<p>
+Note that the size of individual pages of the PostScript output can
+vary. See <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-set-size" title="cairo_ps_surface_set_size ()"><code class="function">cairo_ps_surface_set_size()</code></a>.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>filename</code></em> :</span></p></td>
+<td> a filename for the PS output (must be writable), <code class="literal">NULL</code> may be
+           used to specify no output. This will generate a PS surface that
+           may be queried and used as a source, without generating a
+           temporary file.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>width_in_points</code></em> :</span></p></td>
+<td> width of the surface, in points (1 point == 1/72.0 inch)
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>height_in_points</code></em> :</span></p></td>
+<td> height of the surface, in points (1 point == 1/72.0 inch)
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> a pointer to the newly created surface. The caller
+owns the surface and should call <a class="link" href="cairo-surface.html#cairo-surface-destroy" title="cairo_surface_destroy ()"><code class="function">cairo_surface_destroy()</code></a> when done
+with it.
+This function always returns a valid pointer, but it will return a
+pointer to a "nil" surface if an error such as out of memory
+occurs. You can use <a class="link" href="cairo-surface.html#cairo-surface-status" title="cairo_surface_status ()"><code class="function">cairo_surface_status()</code></a> to check for this.
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.2</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_create_for_stream ()">
+<a name="cairo-ps-surface-create-for-stream"></a><h3>cairo_ps_surface_create_for_stream ()</h3>
+<pre class="programlisting"><a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *   cairo_ps_surface_create_for_stream  (<a class="link" href="cairo-png-functions.html#cairo-write-func-t" title="cairo_write_func_t ()">cairo_write_func_t</a> write_func,
+                                                         void *closure,
+                                                         double width_in_points,
+                                                         double height_in_points);</pre>
+<p>
+Creates a PostScript surface of the specified size in points to be
+written incrementally to the stream represented by <em class="parameter"><code>write_func</code></em> and
+<em class="parameter"><code>closure</code></em>. See <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-create" title="cairo_ps_surface_create ()"><code class="function">cairo_ps_surface_create()</code></a> for a more convenient way
+to simply direct the PostScript output to a named file.
+</p>
+<p>
+Note that the size of individual pages of the PostScript
+output can vary. See <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-set-size" title="cairo_ps_surface_set_size ()"><code class="function">cairo_ps_surface_set_size()</code></a>.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>write_func</code></em> :</span></p></td>
+<td> a <a class="link" href="cairo-png-functions.html#cairo-write-func-t" title="cairo_write_func_t ()"><span class="type">cairo_write_func_t</span></a> to accept the output data, may be <code class="literal">NULL</code>
+             to indicate a no-op <em class="parameter"><code>write_func</code></em>. With a no-op <em class="parameter"><code>write_func</code></em>,
+             the surface may be queried or used as a source without
+             generating any temporary files.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>closure</code></em> :</span></p></td>
+<td> the closure argument for <em class="parameter"><code>write_func</code></em>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>width_in_points</code></em> :</span></p></td>
+<td> width of the surface, in points (1 point == 1/72.0 inch)
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>height_in_points</code></em> :</span></p></td>
+<td> height of the surface, in points (1 point == 1/72.0 inch)
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> a pointer to the newly created surface. The caller
+owns the surface and should call <a class="link" href="cairo-surface.html#cairo-surface-destroy" title="cairo_surface_destroy ()"><code class="function">cairo_surface_destroy()</code></a> when done
+with it.
+This function always returns a valid pointer, but it will return a
+pointer to a "nil" surface if an error such as out of memory
+occurs. You can use <a class="link" href="cairo-surface.html#cairo-surface-status" title="cairo_surface_status ()"><code class="function">cairo_surface_status()</code></a> to check for this.
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.2</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_restrict_to_level ()">
+<a name="cairo-ps-surface-restrict-to-level"></a><h3>cairo_ps_surface_restrict_to_level ()</h3>
+<pre class="programlisting">void                cairo_ps_surface_restrict_to_level  (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         <a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a> level);</pre>
+<p>
+Restricts the generated PostSript file to <em class="parameter"><code>level</code></em>. See
+<a class="link" href="cairo-ps-surface.html#cairo-ps-get-levels" title="cairo_ps_get_levels ()"><code class="function">cairo_ps_get_levels()</code></a> for a list of available level values that
+can be used here.
+</p>
+<p>
+This function should only be called before any drawing operations
+have been performed on the given surface. The simplest way to do
+this is to call this function immediately after creating the
+surface.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>surface</code></em> :</span></p></td>
+<td> a PostScript <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>level</code></em> :</span></p></td>
+<td> PostScript level
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.6</p>
+</div>
+<hr>
+<div class="refsect2" title="enum cairo_ps_level_t">
+<a name="cairo-ps-level-t"></a><h3>enum cairo_ps_level_t</h3>
+<pre class="programlisting">typedef enum _cairo_ps_level {
+    CAIRO_PS_LEVEL_2,
+    CAIRO_PS_LEVEL_3
+} cairo_ps_level_t;
+</pre>
+<p>
+<a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t"><span class="type">cairo_ps_level_t</span></a> is used to describe the language level of the
+PostScript Language Reference that a generated PostScript file will
+conform to.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><a name="CAIRO-PS-LEVEL-2--CAPS"></a><span class="term"><code class="literal">CAIRO_PS_LEVEL_2</code></span></p></td>
+<td> The language level 2 of the PostScript specification.
+</td>
+</tr>
+<tr>
+<td><p><a name="CAIRO-PS-LEVEL-3--CAPS"></a><span class="term"><code class="literal">CAIRO_PS_LEVEL_3</code></span></p></td>
+<td> The language level 3 of the PostScript specification.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_get_levels ()">
+<a name="cairo-ps-get-levels"></a><h3>cairo_ps_get_levels ()</h3>
+<pre class="programlisting">void                cairo_ps_get_levels                 (<a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a> const **levels,
+                                                         int *num_levels);</pre>
+<p>
+Used to retrieve the list of supported levels. See
+<a class="link" href="cairo-ps-surface.html#cairo-ps-surface-restrict-to-level" title="cairo_ps_surface_restrict_to_level ()"><code class="function">cairo_ps_surface_restrict_to_level()</code></a>.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>levels</code></em> :</span></p></td>
+<td> supported level list
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>num_levels</code></em> :</span></p></td>
+<td> list length
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.6</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_level_to_string ()">
+<a name="cairo-ps-level-to-string"></a><h3>cairo_ps_level_to_string ()</h3>
+<pre class="programlisting">const char *        cairo_ps_level_to_string            (<a class="link" href="cairo-ps-surface.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a> level);</pre>
+<p>
+Get the string representation of the given <em class="parameter"><code>level</code></em> id. This function
+will return <code class="literal">NULL</code> if <em class="parameter"><code>level</code></em> id isn't valid. See <a class="link" href="cairo-ps-surface.html#cairo-ps-get-levels" title="cairo_ps_get_levels ()"><code class="function">cairo_ps_get_levels()</code></a>
+for a way to get the list of valid level ids.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>level</code></em> :</span></p></td>
+<td> a level id
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> the string associated to given level.
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.6</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_set_eps ()">
+<a name="cairo-ps-surface-set-eps"></a><h3>cairo_ps_surface_set_eps ()</h3>
+<pre class="programlisting">void                cairo_ps_surface_set_eps            (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         <a class="link" href="cairo-types.html#cairo-bool-t" title="cairo_bool_t">cairo_bool_t</a> eps);</pre>
+<p>
+If <em class="parameter"><code>eps</code></em> is <code class="literal">TRUE</code>, the PostScript surface will output Encapsulated
+PostScript.
+</p>
+<p>
+This function should only be called before any drawing operations
+have been performed on the current page. The simplest way to do
+this is to call this function immediately after creating the
+surface. An Encapsulated PostScript file should never contain more
+than one page.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>surface</code></em> :</span></p></td>
+<td> a PostScript <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>eps</code></em> :</span></p></td>
+<td> <code class="literal">TRUE</code> to output EPS format PostScript
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.6</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_get_eps ()">
+<a name="cairo-ps-surface-get-eps"></a><h3>cairo_ps_surface_get_eps ()</h3>
+<pre class="programlisting"><a class="link" href="cairo-types.html#cairo-bool-t" title="cairo_bool_t">cairo_bool_t</a>        cairo_ps_surface_get_eps            (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface);</pre>
+<p>
+Check whether the PostScript surface will output Encapsulated PostScript.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>surface</code></em> :</span></p></td>
+<td> a PostScript <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> <code class="literal">TRUE</code> if the surface will output Encapsulated PostScript.
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.6</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_set_size ()">
+<a name="cairo-ps-surface-set-size"></a><h3>cairo_ps_surface_set_size ()</h3>
+<pre class="programlisting">void                cairo_ps_surface_set_size           (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         double width_in_points,
+                                                         double height_in_points);</pre>
+<p>
+Changes the size of a PostScript surface for the current (and
+subsequent) pages.
+</p>
+<p>
+This function should only be called before any drawing operations
+have been performed on the current page. The simplest way to do
+this is to call this function immediately after creating the
+surface or immediately after completing a page with either
+<a class="link" href="cairo-context.html#cairo-show-page" title="cairo_show_page ()"><code class="function">cairo_show_page()</code></a> or <a class="link" href="cairo-context.html#cairo-copy-page" title="cairo_copy_page ()"><code class="function">cairo_copy_page()</code></a>.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>surface</code></em> :</span></p></td>
+<td> a PostScript <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>width_in_points</code></em> :</span></p></td>
+<td> new surface width, in points (1 point == 1/72.0 inch)
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>height_in_points</code></em> :</span></p></td>
+<td> new surface height, in points (1 point == 1/72.0 inch)
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.2</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_dsc_begin_setup ()">
+<a name="cairo-ps-surface-dsc-begin-setup"></a><h3>cairo_ps_surface_dsc_begin_setup ()</h3>
+<pre class="programlisting">void                cairo_ps_surface_dsc_begin_setup    (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface);</pre>
+<p>
+This function indicates that subsequent calls to
+<a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> should direct comments to the Setup
+section of the PostScript output.
+</p>
+<p>
+This function should be called at most once per surface, and must
+be called before any call to <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-begin-page-setup" title="cairo_ps_surface_dsc_begin_page_setup ()"><code class="function">cairo_ps_surface_dsc_begin_page_setup()</code></a>
+and before any drawing is performed to the surface.
+</p>
+<p>
+See <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> for more details.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody><tr>
+<td><p><span class="term"><em class="parameter"><code>surface</code></em> :</span></p></td>
+<td> a PostScript <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+</td>
+</tr></tbody>
+</table></div>
+<p class="since">Since 1.2</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_dsc_begin_page_setup ()">
+<a name="cairo-ps-surface-dsc-begin-page-setup"></a><h3>cairo_ps_surface_dsc_begin_page_setup ()</h3>
+<pre class="programlisting">void                cairo_ps_surface_dsc_begin_page_setup
+                                                        (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface);</pre>
+<p>
+This function indicates that subsequent calls to
+<a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> should direct comments to the
+PageSetup section of the PostScript output.
+</p>
+<p>
+This function call is only needed for the first page of a
+surface. It should be called after any call to
+<a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-begin-setup" title="cairo_ps_surface_dsc_begin_setup ()"><code class="function">cairo_ps_surface_dsc_begin_setup()</code></a> and before any drawing is
+performed to the surface.
+</p>
+<p>
+See <a class="link" href="cairo-ps-surface.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> for more details.</p>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody><tr>
+<td><p><span class="term"><em class="parameter"><code>surface</code></em> :</span></p></td>
+<td> a PostScript <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+</td>
+</tr></tbody>
+</table></div>
+<p class="since">Since 1.2</p>
+</div>
+<hr>
+<div class="refsect2" title="cairo_ps_surface_dsc_comment ()">
+<a name="cairo-ps-surface-dsc-comment"></a><h3>cairo_ps_surface_dsc_comment ()</h3>
+<pre class="programlisting">void                cairo_ps_surface_dsc_comment        (<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface,
+                                                         const char *comment);</pre>
+<p>
+Emit a comment into the PostScript output for the given surface.
+</p>
+<p>
+The comment is expected to conform to the PostScript Language
+Document Structuring Conventions (DSC). Please see that manual for
+details on the available comments and their meanings. In
+particular, the %<code class="literal">IncludeFeature</code> comment allows a
+device-independent means of controlling printer device features. So
+the PostScript Printer Description Files Specification will also be
+a useful reference.
+</p>
+<p>
+The comment string must begin with a percent character (%) and the
+total length of the string (including any initial percent
+characters) must not exceed 255 characters. Violating either of
+these conditions will place <em class="parameter"><code>surface</code></em> into an error state. But
+beyond these two conditions, this function will not enforce
+conformance of the comment with any particular specification.
+</p>
+<p>
+The comment string should not have a trailing newline.
+</p>
+<p>
+The DSC specifies different sections in which particular comments
+can appear. This function provides for comments to be emitted
+within three sections: the header, the Setup section, and the
+PageSetup section.  Comments appearing in the first two sections
+apply to the entire document while comments in the BeginPageSetup
+section apply only to a single page.
+</p>
+<p>
+For comments to appear in the header section, this function should
+be called after the surface is created, but before a call to
+<code class="function">cairo_ps_surface_begin_setup()</code>.
+</p>
+<p>
+For comments to appear in the Setup section, this function should
+be called after a call to <code class="function">cairo_ps_surface_begin_setup()</code> but before
+a call to <code class="function">cairo_ps_surface_begin_page_setup()</code>.
+</p>
+<p>
+For comments to appear in the PageSetup section, this function
+should be called after a call to <code class="function">cairo_ps_surface_begin_page_setup()</code>.
+</p>
+<p>
+Note that it is only necessary to call <code class="function">cairo_ps_surface_begin_page_setup()</code>
+for the first page of any surface. After a call to
+<a class="link" href="cairo-context.html#cairo-show-page" title="cairo_show_page ()"><code class="function">cairo_show_page()</code></a> or <a class="link" href="cairo-context.html#cairo-copy-page" title="cairo_copy_page ()"><code class="function">cairo_copy_page()</code></a> comments are unambiguously
+directed to the PageSetup section of the current page. But it
+doesn't hurt to call this function at the beginning of every page
+as that consistency may make the calling code simpler.
+</p>
+<p>
+As a final note, cairo automatically generates several comments on
+its own. As such, applications must not manually generate any of
+the following comments:
+</p>
+<p>
+Header section: %!PS-Adobe-3.0, %<code class="literal">Creator</code>, %<code class="literal">CreationDate</code>, %<code class="literal">Pages</code>,
+%<code class="literal">BoundingBox</code>, %<code class="literal">DocumentData</code>, %<code class="literal">LanguageLevel</code>, %<code class="literal">EndComments</code>.
+</p>
+<p>
+Setup section: %<code class="literal">BeginSetup</code>, %<code class="literal">EndSetup</code>
+</p>
+<p>
+PageSetup section: %<code class="literal">BeginPageSetup</code>, %<code class="literal">PageBoundingBox</code>,
+%<code class="literal">EndPageSetup</code>.
+</p>
+<p>
+Other sections: %<code class="literal">BeginProlog</code>, %<code class="literal">EndProlog</code>, %<code class="literal">Page</code>, %<code class="literal">Trailer</code>, %<code class="literal">EOF</code>
+</p>
+<p>
+Here is an example sequence showing how this function might be used:
+</p>
+<p>
+</p>
+<div class="informalexample"><pre class="programlisting">
+<a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t">cairo_surface_t</a> *surface = cairo_ps_surface_create (filename, width, height);
+...
+cairo_ps_surface_dsc_comment (surface, "%%Title: My excellent document");
+cairo_ps_surface_dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover")
+...
+cairo_ps_surface_dsc_begin_setup (surface);
+cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor White");
+...
+cairo_ps_surface_dsc_begin_page_setup (surface);
+cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A3");
+cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity");
+cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy");
+cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue");
+... draw to first page here ..
+cairo_show_page (cr);
+...
+cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A5");
+...
+</pre></div>
+<p>
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>surface</code></em> :</span></p></td>
+<td> a PostScript <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>comment</code></em> :</span></p></td>
+<td> a comment string to be emitted into the PostScript output
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 1.2</p>
+</div>
+</div>
+<div class="refsect1" title="See Also">
+<a name="cairo-ps-surface.see-also"></a><h2>See Also</h2>
+<p>
+</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></li></ul></div>
+<p>
+</p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>