From f17a09ba8d7af80760fc9156bf06e6b6c9014579 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <matthiasc@src.gnome.org>
Date: Fri, 14 Apr 2006 02:47:16 +0000
Subject: [PATCH] more docs

---
 docs/reference/gtk/gtk-docs.sgml              |  2 +-
 docs/reference/gtk/gtk-sections.txt           |  5 ++
 .../gtk/tmpl/gtkpagesetupunixdialog.sgml      | 11 +++-
 docs/reference/gtk/tmpl/gtkprinter.sgml       | 64 +++++++++++++++++--
 docs/reference/gtk/tmpl/gtkprintjob.sgml      | 57 +++++++++++++----
 .../gtk/tmpl/gtkprintunixdialog.sgml          | 24 +++++--
 6 files changed, 135 insertions(+), 28 deletions(-)

diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index c5dfa0cbf9..e94c3522ad 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -521,9 +521,9 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
       &GtkPrintSettings;
       &GtkPageSetup;
       &GtkPaperSize;
+      &GtkPrintUnixDialog;
       &GtkPrinter;
       &GtkPrintJob; 
-      &GtkPrintUnixDialog;
       &GtkPageSetupUnixDialog;
     </chapter>
 
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index bb48f3e3e9..7f30740930 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -5834,6 +5834,7 @@ GtkPrintOperationPrivate
 
 
 <SECTION>
+<INCLUDE>gtk/gtkprintunixdialog.h</INCLUDE>
 <FILE>gtkprintunixdialog</FILE>
 <TITLE>GtkPrintUnixDialog</TITLE>
 GtkPrintUnixDialog
@@ -5861,15 +5862,18 @@ gtk_print_unix_dialog_get_type
 <FILE>gtkprinter</FILE>
 <TITLE>GtkPrinter</TITLE>
 GtkPrinter
+GtkPrintBackend
 gtk_printer_new
 gtk_printer_get_backend
 gtk_printer_get_name
 gtk_printer_get_state_message
+gtk_printer_get_description
 gtk_printer_get_location
 gtk_printer_get_icon_name
 gtk_printer_get_job_count
 gtk_printer_is_active
 gtk_printer_is_virtual
+gtk_printer_is_default
 
 <SUBSECTION Standard>
 GTK_TYPE_PRINTER
@@ -6095,6 +6099,7 @@ gtk_print_job_get_type
 
 
 <SECTION>
+<INCLUDE>gtk/gtkpagesetupunixdialog.h</INCLUDE>
 <FILE>gtkpagesetupunixdialog</FILE>
 <TITLE>GtkPageSetupUnixDialog</TITLE>
 GtkPageSetupUnixDialog
diff --git a/docs/reference/gtk/tmpl/gtkpagesetupunixdialog.sgml b/docs/reference/gtk/tmpl/gtkpagesetupunixdialog.sgml
index a865352e2a..c98752ab1a 100644
--- a/docs/reference/gtk/tmpl/gtkpagesetupunixdialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkpagesetupunixdialog.sgml
@@ -2,13 +2,20 @@
 GtkPageSetupUnixDialog
 
 <!-- ##### SECTION Short_Description ##### -->
-
+A page setup dialog
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+GtkPageSetupUnixDialog implements a page setup dialog for platforms
+which don't provide a native page setup dialog, like Unix. It can
+be used very much like any other GTK+ dialog, at the cost of
+the portability offered by the <link
+linkend="gtk-High-level-Printing-API">high-level printing API</link>
 </para>
 
+<para>
+Printing support was added in GTK+ 2.10.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkprinter.sgml b/docs/reference/gtk/tmpl/gtkprinter.sgml
index 73ce83b52c..36f0da6970 100644
--- a/docs/reference/gtk/tmpl/gtkprinter.sgml
+++ b/docs/reference/gtk/tmpl/gtkprinter.sgml
@@ -2,20 +2,30 @@
 GtkPrinter
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Represents a printer
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+A #GtkPrinter object represents a printer. You only need to 
+deal directly with printers if you use the non-portable 
+#GtkPrintUnixDialog API. 
+</para>
+<para>
+A #GtkPrinter allows to get status information about the printer, 
+such as its description, its location, the number of queued jobs, 
+etc. Most importantly, a #GtkPrinter object can be used to create
+a #GtkPrintJob object, which lets you print to the printer.
 </para>
 
+<para>
+Printing support was added in GTK+ 2.10.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### SECTION Stability_Level ##### -->
 
 
@@ -24,14 +34,58 @@ GtkPrinter
 
 </para>
 
-@parent_instance: 
-@priv: 
+
+<!-- ##### SIGNAL GtkPrinter::details-acquired ##### -->
+<para>
+
+</para>
+
+@printer: the object which received the signal.
+@arg1: 
+
+<!-- ##### ARG GtkPrinter:backend ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrinter:icon-name ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrinter:is-virtual ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrinter:job-count ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrinter:location ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrinter:name ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrinter:state-message ##### -->
+<para>
+
+</para>
 
 <!-- ##### FUNCTION gtk_printer_new ##### -->
 <para>
 
 </para>
 
+@name: 
+@backend: 
+@virtual: 
 @Returns: 
 
 
diff --git a/docs/reference/gtk/tmpl/gtkprintjob.sgml b/docs/reference/gtk/tmpl/gtkprintjob.sgml
index 837ca3683d..91b46b3855 100644
--- a/docs/reference/gtk/tmpl/gtkprintjob.sgml
+++ b/docs/reference/gtk/tmpl/gtkprintjob.sgml
@@ -2,20 +2,33 @@
 GtkPrintJob
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Represents a print job
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+A #GtkPrintJob object represents a job that is sent to a
+printer. You only need to deal directly with print jobs if 
+you use the non-portable #GtkPrintUnixDialog API. 
 </para>
+<para>
+Use gtk_print_job_get_surface() to obtain the cairo surface
+onto which the pages must be drawn. Use gtk_print_job_send()
+to send the finished job to the printer. #GtkPrintJob also 
+supports printing of preexisting PDF documents, via the 
+gtk_print_job_set_source_file(). 
+<!-- FIXME more details needed here -->
+</para>
+<!-- FIXME examples ? -->
 
+<para>
+Printing support was added in GTK+ 2.10.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### SECTION Stability_Level ##### -->
 
 
@@ -24,17 +37,33 @@ GtkPrintJob
 
 </para>
 
-@parent_instance: 
-@priv: 
-@print_pages: 
-@page_ranges: 
-@num_page_ranges: 
-@page_set: 
-@num_copies: 
-@collate: 
-@reverse: 
-@scale: 
-@rotate_to_orientation: 
+
+<!-- ##### SIGNAL GtkPrintJob::status-changed ##### -->
+<para>
+
+</para>
+
+@printjob: the object which received the signal.
+
+<!-- ##### ARG GtkPrintJob:page-setup ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrintJob:printer ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrintJob:settings ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPrintJob:title ##### -->
+<para>
+
+</para>
 
 <!-- ##### USER_FUNCTION GtkPrintJobCompleteFunc ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkprintunixdialog.sgml b/docs/reference/gtk/tmpl/gtkprintunixdialog.sgml
index 23090a35fb..f27d5da92a 100644
--- a/docs/reference/gtk/tmpl/gtkprintunixdialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkprintunixdialog.sgml
@@ -2,20 +2,34 @@
 GtkPrintUnixDialog
 
 <!-- ##### SECTION Short_Description ##### -->
-
+A print dialog 
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+GtkPrintUnixDialog implements a print dialog for platforms
+which don't provide a native print dialog, like Unix. It can 
+be used very much like any other GTK+ dialog, at the cost of 
+the portability offered by the <link 
+linkend="gtk-High-level-Printing-API">high-level printing API</link>
+</para>
+<para>
+In order to print something with #GtkPrintUnixDialog, you need
+to use gtk_print_unix_dialog_get_selected_printer() to obtain
+a #GtkPrinter object and use it to construct a #GtkPrintJob using
+gtk_print_job_new().
 </para>
 
+<!-- FIXME example here -->
+
+<para>
+Printing support was added in GTK+ 2.10.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkPageSetupUnixDialog, #GtkPrinter, #GtkPrintJob
 </para>
 
-
 <!-- ##### SECTION Stability_Level ##### -->
 
 
@@ -24,8 +38,6 @@ GtkPrintUnixDialog
 
 </para>
 
-@parent_instance: 
-@priv: 
 
 <!-- ##### FUNCTION gtk_print_unix_dialog_set_page_setup ##### -->
 <para>