[cairo-commit] pycairo/doc/reference surfaces.rst,1.6,1.7

[Steve Chaplin]

Committed by: stevech1097

Update of /cvs/cairo/pycairo/doc/reference
In directory kemper:/tmp/cvs-serv4439/doc/reference

Modified Files:
	surfaces.rst 
Log Message:
'SC'

Index: surfaces.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/surfaces.rst,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- surfaces.rst	19 Mar 2009 08:26:52 -0000	1.6
+++ surfaces.rst	25 Mar 2009 07:12:09 -0000	1.7
@@ -285,55 +285,141 @@
 
    .. method:: get_format()
 
+      :returns: the :ref:`format <mattributes_format>` of the surface.
+
+      .. versionadded:: 1.2
+
    .. method:: get_height()
 
+      :returns: the height of the surface in pixels.
+
    .. method:: get_stride()
 
+      :returns: the stride of the *ImageSurface* in bytes. The stride is the distance in bytes from the beginning of one row of the image data to the beginning of the next row.
+
    .. method:: get_width()
 
+      :returns: the width of the surface in pixels.
+
 
 class PDFSurface(:class:`Surface`)
 ==================================
 
-.. class:: PDFSurface
+The PDFSurface is used to render cairo graphics to Adobe PDF files and is a
+multi-page vector surface backend.
 
-.. comment
- C:  surface = cairo_pdf_surface_create (filename, width_in_points,
- 				        height_in_points);
- Py: surface = cairo.PDFSurface (f, width_in_points, height_in_points)
-     where 'f' is a filename, a file object, or a file-like object
+.. class:: PDFSurface(fobj, width_in_points, height_in_points)
+
+   :param fobj: a filename or writable file object
+   :type fobj: str, file or file-like object
+   :param width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
+   :type  width_in_points: float
+   :param height_in_points: height of the surface, in points (1 point == 1/72.0 inch)
+   :type  height_in_points: float
+   :returns: a new *PDFSurface*
+   :raises: *MemoryError* in case of no memory
 
+   Creates a *PDFSurface* of the specified size in points to be written to *fobj*.
+
+   .. versionadded:: 1.2
 
    .. method:: set_size()
 
+      :param width_in_points: new surface width, in points (1 point == 1/72.0 inch)
+      :type  width_in_points: float
+      :param height_in_points: new surface height, in points (1 point == 1/72.0 inch)
+      :type  height_in_points: float
+
+      Changes the size of a *PDFSurface* for the current (and subsequent) pages.
+
+      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 :meth:`Context.show_page` or
+      :meth:`Context.copy_page`.
+
+      .. versionadded:: 1.2
+
 
 class PSSurface(:class:`Surface`)
 =================================
 
-.. class:: PSSurface
+The *PSSurface* is used to render cairo graphics to Adobe PostScript files and
+is a multi-page vector surface backend.
 
-.. comment
- C:  surface = cairo_ps_surface_create (filename, width_in_points,
- 			               height_in_points);
- Py: surface = cairo.PSSurface  (f, width_in_points, height_in_points)
-     where 'f' is a filename, a file object, or a file-like object
+.. class:: PSSurface(fobj, width_in_points, height_in_points)
+
+   :param fobj:  a filename or writable file object
+   :type fobj: str, file or file-like object
+   :param width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
+   :type  width_in_points: float
+   :param height_in_points: height of the surface, in points (1 point == 1/72.0 inch)
+   :type  height_in_points: float
+   :returns: a new *PDFSurface*
+   :raises: *MemoryError* in case of no memory
+
+   Creates a *PSSurface* of the specified size in points to be written to
+   *fobj*.
+
+   Note that the size of individual pages of the PostScript output can
+   vary. See :meth:`PSSurface.set_size`.
 
    .. method:: dsc_begin_page_setup()
 
+      This method indicates that subsequent calls to
+      :meth:`PSSurface.dsc_comment` should direct comments to the PageSetup
+      section of the PostScript output.
+
+      This method call is only needed for the first page of a surface. It should
+      be called after any call to :meth:`PSSurface.dsc_begin_setup` and before
+      any drawing is performed to the surface.
+
+      See :meth:`PSSurface.dsc_comment` for more details.
+
+      .. versionadded:: 1.2
+
    .. method:: dsc_begin_setup()
 
+      This function indicates that subsequent calls to
+      :meth:`PSSurface.dsc_comment` should direct comments to the Setup
+      section of the PostScript output.
+
+      This function should be called at most once per surface, and must be
+      called before any call to :meth:`PSSurface.dsc_begin_page_setup` and
+      before any drawing is performed to the surface.
+
+      See :meth:`PSSurface.dsc_comment` for more details.
+
+      .. versionadded:: 1.2
+
    .. method:: dsc_comment()
 
+
+      .. versionadded:: 1.2
+
    .. method:: get_eps()
 
+
+      .. versionadded:: 1.6
+
    .. method:: ps_level_to_string()
 
+
+      .. versionadded:: 1.6
+
    .. method:: restrict_to_level()
 
+
+      .. versionadded:: 1.6
+
    .. method:: set_eps()
 
+      .. versionadded:: 1.6
+
    .. method:: set_size()
 
+      .. versionadded:: 1.2
+
 
 class SVGSurface(:class:`Surface`)
 ==================================
@@ -366,6 +452,8 @@
 
    .. method:: get_depth()
 
+
    .. method:: get_height()
 
+
    .. method:: get_width()