[gtk+] docs: Move documentation to inline comments: GtkPageSetup

[Javier Jardón <jjardon src gnome org>]

commit 692024940ceb9aab3ee0a4889ee888ca0cdb82c2
Author: Patrick Bernaud <patrickb chez com>
Date:   Mon Nov 8 18:36:38 2010 +0100

    docs: Move documentation to inline comments: GtkPageSetup
    
    Fixes https://bugzilla.gnome.org/show_bug.cgi?id=634340
    
    Signed-off-by: Javier Jardón <jjardon gnome org>

 docs/reference/gtk/tmpl/.gitignore        |    1 +
 docs/reference/gtk/tmpl/gtkpagesetup.sgml |  320 -----------------------------
 gtk/gtkpagesetup.c                        |   52 +++++
 3 files changed, 53 insertions(+), 320 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 5fa9fd4..5ac6dc1 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -30,6 +30,7 @@ gtkmessagedialog.sgml
 gtknotebook.sgml
 gtkobject.sgml
 gtkorientable.sgml
+gtkpagesetup.sgml
 gtkpagesetupunixdialog.sgml
 gtkpapersize.sgml
 gtkprinter.sgml
diff --git a/gtk/gtkpagesetup.c b/gtk/gtkpagesetup.c
index 8c56a69..a00177e 100644
--- a/gtk/gtkpagesetup.c
+++ b/gtk/gtkpagesetup.c
@@ -26,6 +26,58 @@
 #include "gtkintl.h"
 #include "gtktypebuiltins.h"
 
+/**
+ * SECTION:gtkpagesetup
+ * @Short_description: Stores page setup information
+ * @Title: GtkPageSetup
+ *
+ * A GtkPageSetup object stores the page size, orientation and margins.
+ * The idea is that you can get one of these from the page setup dialog
+ * and then pass it to the #GtkPrintOperation when printing.
+ * The benefit of splitting this out of the #GtkPrintSettings is that
+ * these affect the actual layout of the page, and thus need to be set
+ * long before user prints.
+ *
+ * <para id="print-margins">
+ * The margins specified in this object are the "print margins", i.e. the
+ * parts of the page that the printer cannot print on. These are different
+ * from the layout margins that a word processor uses; they are typically
+ * used to determine the <emphasis>minimal</emphasis> size for the layout
+ * margins.
+ * </para>
+ *
+ * To obtain a #GtkPageSetup use gtk_page_setup_new() to get the defaults,
+ * or use gtk_print_run_page_setup_dialog() to show the page setup dialog
+ * and receive the resulting page setup.
+ *
+ * <example>
+ * <title>A page setup dialog</title>
+ * <programlisting>
+ * static GtkPrintSettings *settings = NULL;
+ * static GtkPageSetup *page_setup = NULL;
+ *
+ * static void
+ * do_page_setup (void)
+ * {
+ *   GtkPageSetup *new_page_setup;
+ *
+ *   if (settings == NULL)
+ *     settings = gtk_print_settings_new (<!-- -->);
+ *
+ *   new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window),
+ *                                                     page_setup, settings);
+ *
+ *   if (page_setup)
+ *     g_object_unref (page_setup);
+ *
+ *   page_setup = new_page_setup;
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * Printing support was added in GTK+ 2.10.
+ */
+
 #define KEYFILE_GROUP_NAME "Page Setup"
 
 typedef struct _GtkPageSetupClass GtkPageSetupClass;