Update documentation of cairo_paginated_surface

2 files changed, 14 insertions, 27 deletions

diff --git a/src/cairo-paginated-surface-private.h b/src/cairo-paginated-surface-private.h
index c18cb3c14..247ed7262 100644
--- a/src/cairo-paginated-surface-private.h
+++ b/src/cairo-paginated-surface-private.h
@@ -71,6 +71,18 @@ typedef struct _cairo_paginated_surface_backend {
  * have paginated output, (that is, things directed at printers, or
  * for saving content in files such as PostScript or PDF files).
  *
+ * To use the paginated surface, you'll first need to create your
+ * 'real' surface using _cairo_surface_init and the standard
+ * cairo_surface_backend_t. Then you also call
+ * _cairo_paginated_surface_create which takes its own, much simpler,
+ * cairo_paginated_surface_backend. You are free to return the result
+ * of _cairo_paginated_surface_create from your public
+ * cairo_<foo>_surface_create. The paginated backend will be careful
+ * to not let the user see that they really got a "wrapped"
+ * surface. See test-paginated-surface.c for a fairly minimal example
+ * of a paginated-using surface. That should be a reasonable example
+ * to follow.
+ *
  * What the paginated surface does is first save all drawing
  * operations for a page into a meta-surface. Then when the user calls
  * cairo_show_page, the paginated surface performs the following
diff --git a/src/cairo-paginated-surface.c b/src/cairo-paginated-surface.c
index 475db3e54..01b6ed83f 100644
--- a/src/cairo-paginated-surface.c
+++ b/src/cairo-paginated-surface.c
@@ -36,33 +36,8 @@
 
 /* The paginated surface layer exists to provide as much code sharing
  * as possible for the various paginated surface backends in cairo
- * (PostScript, PDF, etc.).
- *
- * The concept is that a surface which uses a paginated surface merely
- * needs to implement backend operations which it can accurately
- * provide, (and return CAIRO_INT_STATUS_UNSUPPORTED or leave backend
- * function pointers NULL otherwise). The paginated surface is the
- * responsible for collecting operations that aren't supported,
- * replaying them against the image surface, and then supplying the
- * resulting images to the target surface.
- *
- * When created, a paginated surface accepts the target surface to
- * which the final drawing will eventually be performed. The paginated
- * surface then uses cairo_meta_surface_t to record all drawing
- * operations up until each show_page operation.
- *
- * At the time of show_page, the paginated surface replays the meta
- * surface against the target surface and maintains regions of the
- * result that will come from the nativ surface and regions that will
- * need to come from image fallbacks. It then replays the necessary
- * portions against image surface and provides those results to the
- * target surface through existing interfaces.
- *
- * This way the target surface is never even aware of any distinction
- * between native drawing operations vs. results that are supplied by
- * image fallbacks. Instead the surface need only implement as much of
- * the surface backend interface as it can do correctly, and let the
- * paginated surface take care of all the messy details.
+ * (PostScript, PDF, etc.). See cairo-paginated-surface-private.h for
+ * more details on how it works and how to use it.
  */
 
 #include "cairoint.h"