updated docs to cover simpler setup procedure.

2001-05-19  Damon Chaplin  <damon@ximian.com>

	* README:
	* doc/README:
	* doc/setting-up.txt:
	* doc/sections-file.txt:
	* doc/authors.txt: updated docs to cover simpler setup procedure.

	* doc/gtk_button.txt:
	* doc/manpage:
	* doc/manpage.man:
	* doc/notes.txt: removed out-of date stuff.

	* Makefile.am (dist-hook): updated so it doesn't try to remove old
	examples subdirectory stuff.

8 files changed, 35 insertions, 871 deletions

diff --git a/doc/README b/doc/README
index 9094665..eddb91d 100644
--- a/doc/README
+++ b/doc/README
@@ -3,14 +3,7 @@ FILES
 =====
 
 setting-up.txt
-    10-step guide to setting up a module to use gtk-doc.
-
-style-guide.txt
-    Initial draft of a style guide for writing GTK+ docs.
-
-authors.txt
-    notes for authors of the GTK documentation. The abbreviations to use,
-    a few useful DocBook tags etc.
+    5-step guide to setting up a module to use gtk-doc.
 
 gnome.txt
     information on the source code comments format which the Gnome project
@@ -20,20 +13,12 @@ sections-file.txt
     describes the MODULE-sections.txt file which is used to organise the
     documentation.
 
-Old stuff
----------
 
-notes.txt
-    my initial thoughts on the documentation - what should be included,
-    other documentation to look at etc.
 
-gtk_button.txt
-    the man page written by Shawn Amundson. I've tried to
-    copy the structure as much as possible.
-
-manpage
-    a man page in DocBook format which I found in the DocBook documentation. 
+style-guide.txt
+    Initial draft of a style guide for writing GTK+ docs.
 
-manpage.man
-    the above man page converted with docbook-to-man. View with 'man -l'.
+authors.txt
+    notes for authors of the GTK documentation. The abbreviations to use,
+    a few useful DocBook tags etc.
 
diff --git a/doc/authors.txt b/doc/authors.txt
index 883aa09..ef9eed9 100644
--- a/doc/authors.txt
+++ b/doc/authors.txt
@@ -1,47 +1,9 @@
-Tools
-=====
-
-* gtkdoc-scan
-
-  Scan a set of header files for declarations.
-
-  Usage: gtkdoc-scan --module=MODULE [--output-dir=DIR] FILES
-
-* gtkdoc-scanobj
-
-  Compile a C program to get information about GTK+ objects.
-
-  Usage: gtkdoc-scan --module=MODULE
-
-* gtkdoc-mktmpl
-
-  Make template files from declaration files
-
-  Usage: gtkdoc-mkhtml --module=MODULE [--output-dir=DIR] 
-
-* gtkdoc-mkdb
-
-  Make DocBook output from declaration files and template files.
-
-  Usage: gtkdoc-mkdb --module=MODULE
-
-* gtkdoc-mkhtml
-
-  Usage: gtkdoc-mkhtml MODULE DRIVER_FILE
-
-* gtkdoc-mkman
-
-  Usage: gtkdoc-mkman 
 
 General
 =======
 
 The files to edit manually are generated in the tmpl/ directory.
-
-You may find useful information in the GTK tutorial, or the info documentation.
-
-
-You must use &lt; or &gt; instead of '<' and '>'.
+Remember to use &lt; or &gt; instead of '<' and '>', in these files.
 
 The first part of each function/macro/struct etc. description should be
 a very short summary of what it is. This may be used at some point to
@@ -175,5 +137,3 @@ For filenames use:
 
     <filename>c:\windows</filename>
 
-
-Also, <screenshot>, <option>, 
\ No newline at end of file
diff --git a/doc/gtk_button.txt b/doc/gtk_button.txt
deleted file mode 100644
index 24a2b3e..0000000
--- a/doc/gtk_button.txt
+++ /dev/null
@@ -1,235 +0,0 @@
-NAME
-    gtk_button - GTK+ push button widget
-
-SYNOPSIS
-     #include <gtk/gtkbutton.h>
-
-     GtkType        gtk_button_get_type       (void);
-     GtkWidget*     gtk_button_new            (void);
-     GtkWidget*     gtk_button_new_with_label (const gchar *label);
-     void           gtk_button_pressed        (GtkButton *button);
-     void           gtk_button_released       (GtkButton *button);
-     void           gtk_button_clicked        (GtkButton *button);
-     void           gtk_button_enter          (GtkButton *button);
-     void           gtk_button_leave          (GtkButton *button);
-     void           gtk_button_set_relief     (GtkButton *button,
-                                               GtkReliefStyle style);
-     GtkReliefStyle gtk_button_get_relief     (GtkButton *button);
-
-DESCRIPTION
-    This widget is a standard push button widget. Push button
-    widgets are generally used for allowing the user to click on
-    them to initiate a command.
-
-    This widget is a container widget which contains one child.
-
-OBJECT HIERARCHY
-     gtk_object
-     gtk_widget
-     gtk_container 
-     gtk_button
-
-SIGNAL PROTOTYPES
-     "clicked"      void user_function (GtkWidget *widget, gpointer data);
-     "pressed"      void user_function (GtkWidget *widget, gpointer data);
-     "released"     void user_function (GtkWidget *widget, gpointer data);
-     "enter"        void user_function (GtkWidget *widget, gpointer data);
-     "leave"        void user_function (GtkWidget *widget, gpointer data);
-
-USAGE
-  Creation
-
-    The most common way to create a button is with a label in it,
-    which contains text for the user to read. The child of the
-    button will then be a the gtk_label(3) manpage widget with the
-    text you passwd in. You can do this in one command:
-
-            GtkWidget *button;
-            button = gtk_button_new_with_label ("This is a button");
-
-    To create a gtk_button widget which does not already have a
-    child, use gtk_button_new():
-
-            GtkWidget *button;
-            button = gtk_button_new ();
-
-    After you have created a button you can then add a widget to the
-    button (such as a label or pixmap) using gtk_container_add().
-    See the gtk_container(3) manpage for more information on adding
-    widgets to containers.
-
-  Creating a pixmap in a button in a window
-
-    After we have an empty gtk_button, such as above, and we have a
-    gtk_pixmap, we can simply add the gtk_pixmap to the gtk_button
-    with gtk_container_add().
-
-    The following code will open the file "gimp.xpm" and place it in
-    a button.
-
-            #include <gtk/gtk.h>
-
-            int main (int argc, char *argv[])
-            {
-                GtkWidget *window;
-                GtkWidget *button;
-                GtkWidget *pixmap;
-                GtkStyle *style;
-                GdkPixmap *gdkpixmap;
-                GdkBitmap *mask;
-                char *filename = "gimp.xpm";
-
-                gtk_init (&argc, &argv);
-
-                window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
-
-                button = gtk_button_new ();
-                gtk_container_add (GTK_CONTAINER (window), button);
-
-                /* The button is realized now, which creates button->window
-                   used below to create the pixmap. */
-                gtk_widget_realize (button);
-
-                style = gtk_widget_get_style (button);
-                gdkpixmap = gdk_pixmap_create_from_xpm (button->window, &mask,
-                                               &style->bg[GTK_STATE_NORMAL],
-                                               filename);
-                pixmap = gtk_pixmap_new (gdkpixmap, mask);
-
-                gtk_container_add (GTK_CONTAINER (button), pixmap);
-
-                gtk_widget_show (pixmap);
-                gtk_widget_show (button);
-                gtk_widget_show (window);
-
-                gtk_main ();
-                return 0;
-            }
-
-  Different reliefs
-
-    Reliefs affect how the shadowing of the button is drawn. The
-    different types of relief styles are:
-
-            GTK_RELIEF_NORMAL
-            GTK_RELIEF_HALF
-            GTK_RELIEF_NONE
-
-    When set to a normal relief, the widget looks and acts like a
-    normal button. When half or none relief is used, shadowing is
-    only drawn when the mouse cursor is over the widget.
-
-    To set the relief, use gtk_button_set_relief(), like:
-
-            gtk_button_set_relief (button, GTK_RELIEF_HALF);
-
-    To get the current relief of a button, use
-    gtk_button_get_relief():
-
-            GtkReliefStyle relief;
-            relief = gtk_button_get_relief (GTK_BUTTON (button));
-
-  Executing a command when the button is pressed
-
-    To execute a function when a button is pressed, use
-    gtk_signal_connect() to connect to the "clicked" signal.
-
-            gtk_signal_connect (GTK_OBJECT (button), "clicked",
-                                GTK_SIGNAL_FUNC (user_function),
-                                NULL);
-
-    user_function is a user defined function, like the following:
-
-            void user_function (GtkWidget *button, gpointer data)
-            {
-                printf("clicked\n");
-            }
-
-FUNCTIONS
-    GtkType gtk_button_get_type (void);
-
-            This function returns the GtkType which is assigned to the
-            object class for gtk_button.
-
-    GtkWidget* gtk_button_new (void);
-
-            This functions returns a new button widget which can then be
-            used as a container for another widget.
-
-    GtkWidget* gtk_button_new_with_label (const gchar *label);
-
-            This function returns a new button widget with a label widget
-            as a child.   The label widget will have the text passed into
-            the commant.
-
-    void gtk_button_pressed (GtkButton *button);
-
-            This function sends a "pressed" signal to the button.
-
-    void gtk_button_released (GtkButton *button);
-
-            This function sends a "released" signal to the button.
-
-    void gtk_button_clicked (GtkButton *button);
-
-            This function sends a "clicked" signal to the button.
-
-    void gtk_button_enter (GtkButton *button);
-
-            This function sends a "enter" signal to the button.
-
-    void gtk_button_leave (GtkButton *button);
-
-            This function sends a "leave" signal to the button.
-
-    void gtk_button_set_relief (GtkButton *button, GtkReliefStyle
-    style);
-
-            This function is sets the GtkReliefStyle of the button.  The
-            relief style is one of: GTK_RELIEF_NORMAL, GTK_RELIEF_HALF,
-            or GTK_RELIEF_NONE.  The relief determines when the shadow of
-            the button is drawn.
-
-    GtkReliefStyle gtk_button_get_relief (GtkButton *button);
-
-            This function returns the current relief of the button.
-
-SIGNALS
-    "clicked"
-
-            void user_function (GtkWidget *widget, gpointer data);
-
-            Gets emitted when the button is clicked. A click is 
-            a press and release of the button when the cursor is
-            inside the button on release.  
-
-    "pressed"
-
-            void user_function (GtkWidget *widget, gpointer data);
-
-            Gets emitted when the left mouse button is pressed.
-
-    "released"
-
-            void user_function (GtkWidget *widget, gpointer data);
-
-            Gets emitted when the left mouse button is released and
-            the widget was previously pressed.
-
-    "enter"
-
-            void user_function (GtkWidget *widget, gpointer data);
-
-            Emitted when the mouse cursor enters the button.
-
-    "leave"
-
-            void user_function (GtkWidget *widget, gpointer data);
-
-            Emitted when the mouse cursor leaves the button.
-
-AUTHORS
-    The author of this man page is Shawn T. Amundson
-    <amundson@gtk.org>. For the authors of GTK+, see the AUTHORS
-    file in the GTK+ distribution.
-
diff --git a/doc/manpage b/doc/manpage
deleted file mode 100644
index 6cd98a6..0000000
--- a/doc/manpage
+++ /dev/null
@@ -1,170 +0,0 @@
-<!doctype refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
-<REFENTRY ID="RE-1007-UNMANAGECHILDREN-1">
-
-<REFMETA>
-<REFENTRYTITLE>XtUnmanageChildren</REFENTRYTITLE>
-<MANVOLNUM>3
-<REFMISCINFO>Xt - Geometry Management</REFMISCINFO>
-</REFMETA>
-
-
-<REFNAMEDIV>
-<REFNAME>XtUnmanageChildren
-</REFNAME>
-<REFPURPOSE>remove a list of children from a parent widget's managed list.
-</REFPURPOSE>
-<INDEXTERM ID="IX-1007-UNMANAGECHILDREN-1"><PRIMARY>widgets</PRIMARY><SECONDARY>removing</SECONDARY></INDEXTERM>
-<INDEXTERM ID="IX-1007-UNMANAGECHILDREN-2"><PRIMARY>XtUnmanageChildren</PRIMARY></INDEXTERM>
-</REFNAMEDIV>
-
-
-<REFSYNOPSISDIV>
-<REFSYNOPSISDIVINFO>
-<DATE>4 March 1996</DATE>
-</REFSYNOPSISDIVINFO>
-<SYNOPSIS>
-void XtUnmanageChildren(<REPLACEABLE CLASS="PARAMETER">children</REPLACEABLE>, <REPLACEABLE CLASS="PARAMETER">num_children</REPLACEABLE>)
-    WidgetList <REPLACEABLE CLASS="PARAMETER">children</REPLACEABLE>;
-    Cardinal <REPLACEABLE CLASS="PARAMETER">num_children</REPLACEABLE>;</SYNOPSIS>
-
-<REFSECT2 ID="R2-1007-UNMANAGECHILDREN-1">
-<REFSECT2INFO>
-<DATE>6 March 1996</DATE>
-</REFSECT2INFO>
-<TITLE>Inputs
-</TITLE>
-<VARIABLELIST>
-<VARLISTENTRY>
-<TERM><REPLACEABLE CLASS="PARAMETER">children</REPLACEABLE>
-</TERM>
-<LISTITEM>
-<PARA>Specifies an array of child widgets.  Each child must be of
-class RectObj or any subclass thereof.
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-<VARLISTENTRY>
-<TERM><REPLACEABLE CLASS="PARAMETER">num_children</REPLACEABLE>
-</TERM>
-<LISTITEM>
-<PARA>Specifies the number of elements in <REPLACEABLE CLASS="PARAMETER">children</REPLACEABLE>.
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-</VARIABLELIST>
-<REFSECT3>
-<TITLE>Subsidiary Inputs</TITLE>
-<PARA>Inputs into unmanageable children may also include
-food, drink, and discipline.
-</PARA>
-</REFSECT3>
-</REFSECT2></REFSYNOPSISDIV>
-
-
-<REFSECT1 ID="R1-1007-UNMANAGECHILDREN-1">
-<REFSECT1INFO>
-<DATE>5 March 1996</DATE>
-</REFSECT1INFO>
-<TITLE>Description
-</TITLE>
-<PARA><FUNCTION>XtUnmanageChildren()</FUNCTION> unmaps the specified widgets
-and removes them from their parent's geometry management.
-The widgets will disappear from the screen, and (depending
-on its parent) may no longer have screen space allocated for
-them.
-</PARA>
-<PARA>Each of the widgets in the <REPLACEABLE CLASS="PARAMETER">children</REPLACEABLE> array must have
-the same parent.
-</PARA>
-<PARA>See the &ldquo;Algorithm&rdquo; section below for full details of the
-widget unmanagement procedure.
-</PARA>
-</REFSECT1>
-<REFSECT1 ID="R1-1007-UNMANAGECHILDREN-2">
-<TITLE>Usage
-</TITLE>
-<PARA>Unmanaging widgets is the usual method for temporarily
-making them invisible.  They can be re-managed with
-<FUNCTION>XtManageChildren()</FUNCTION>.
-</PARA>
-<PARA>You can unmap a widget, but leave it under geometry
-management by calling <FUNCTION>XtUnmapWidget()</FUNCTION>.  You can
-destroy a widget's window without destroying the widget by
-calling <FUNCTION>XtUnrealizeWidget()</FUNCTION>.  You can destroy a
-widget completely with <FUNCTION>XtDestroyWidget()</FUNCTION>.
-</PARA>
-<PARA>If you are only going to unmanage a single widget, it is
-more convenient to call <FUNCTION>XtUnmanageChild()</FUNCTION>.  It is
-often more convenient to call <FUNCTION>XtUnmanageChild()</FUNCTION>
-several times than it is to declare and initialize an array
-of widgets to pass to <FUNCTION>XtUnmanageChildren()</FUNCTION>.  Calling
-<FUNCTION>XtUnmanageChildren()</FUNCTION> is more efficient, however,
-because it only calls the parent's <FUNCTION>change_managed()</FUNCTION>
-method once.
-</PARA>
-</REFSECT1>
-<REFSECT1 ID="R1-1007-UNMANAGECHILDREN-3">
-<TITLE>Algorithm
-</TITLE>
-<PARA><FUNCTION>XtUnmanageChildren()</FUNCTION> performs the following:
-</PARA>
-<VARIABLELIST>
-<VARLISTENTRY>
-<TERM>&bull;
-</TERM>
-<LISTITEM>
-<PARA>Issues an error if the children do not all have the same
-parent or if the parent is not a subclass of
-<CLASSNAME>compositeWidgetClass</CLASSNAME>.
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-<VARLISTENTRY>
-<TERM>&bull;
-</TERM>
-<LISTITEM>
-<PARA>Returns immediately if the common parent is being destroyed;
-otherwise, for each unique child on the list,
-<FUNCTION>XtUnmanageChildren()</FUNCTION> performs the following:
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-<VARLISTENTRY>
-<TERM>-
-</TERM>
-<LISTITEM>
-<PARA>Ignores the child if it already is unmanaged or is being
-destroyed.
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-<VARLISTENTRY>
-<TERM>-
-</TERM>
-<LISTITEM>
-<PARA>Otherwise, if the child is realized, it makes it nonvisible
-by unmapping it.
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-<VARLISTENTRY>
-<TERM>&bull;
-</TERM>
-<LISTITEM>
-<PARA>Calls the <FUNCTION>change_managed()</FUNCTION> method of the widgets'
-parent if the parent is realized.
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-</VARIABLELIST>
-<PARA>
-</PARA>
-</REFSECT1>
-<REFSECT1 ID="R1-1007-UNMANAGECHILDREN-4">
-<TITLE>Structures
-</TITLE>
-<PARA>The <TYPE>WidgetList</TYPE> type is simply an array of widgets:
-</PARA>
-<SCREEN ID="SC-1007-UNMANAGECHILDREN-1">typedef Widget *WidgetList;
-</SCREEN>
-</REFSECT1></REFENTRY>
\ No newline at end of file
diff --git a/doc/manpage.man b/doc/manpage.man
deleted file mode 100644
index 438bcca..0000000
--- a/doc/manpage.man
+++ /dev/null
@@ -1,140 +0,0 @@
-...\" $Header$
-...\"
-...\"	transcript compatibility for postscript use.
-...\"
-...\"	synopsis:  .P! <file.ps>
-...\"
-.de P!
-.fl
-\!!1 setgray
-.fl
-\\&.\"
-.fl
-\!!0 setgray
-.fl			\" force out current output buffer
-\!!save /psv exch def currentpoint translate 0 0 moveto
-\!!/showpage{}def
-.fl			\" prolog
-.sy sed -e 's/^/!/' \\$1\" bring in postscript file
-\!!psv restore
-.
-.de pF
-.ie     \\*(f1 .ds f1 \\n(.f
-.el .ie \\*(f2 .ds f2 \\n(.f
-.el .ie \\*(f3 .ds f3 \\n(.f
-.el .ie \\*(f4 .ds f4 \\n(.f
-.el .tm ? font overflow
-.ft \\$1
-..
-.de fP
-.ie     !\\*(f4 \{\
-.	ft \\*(f4
-.	ds f4\"
-'	br \}
-.el .ie !\\*(f3 \{\
-.	ft \\*(f3
-.	ds f3\"
-'	br \}
-.el .ie !\\*(f2 \{\
-.	ft \\*(f2
-.	ds f2\"
-'	br \}
-.el .ie !\\*(f1 \{\
-.	ft \\*(f1
-.	ds f1\"
-'	br \}
-.el .tm ? font underflow
-..
-.ds f1\"
-.ds f2\"
-.ds f3\"
-.ds f4\"
-.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
-.TH "XtUnmanageChildren" "3
-"
-.SH "NAME"
-XtUnmanageChildren \(em remove a list of children from a parent widget\&'s managed list\&.
-.iX "widgets" "removing"
-.iX "XtUnmanageChildren"
-.SH "SYNOPSIS"
-4 March 1996; 
-.PP
-.nf
-void XtUnmanageChildren(\fIchildren\fP, \fInum_children\fP)
-    WidgetList \fIchildren\fP;
-    Cardinal \fInum_children\fP;
-.fi
-.SS "Inputs"
-6 March 1996; 
-.IP "\fIchildren\fP" 10
-Specifies an array of child widgets\&.  Each child must be of
-class RectObj or any subclass thereof\&.
-.IP "\fInum_children\fP" 10
-Specifies the number of elements in \fIchildren\fP\&.
-.SS "Subsidiary Inputs"
-.PP
-Inputs into unmanageable children may also include
-food, drink, and discipline\&.
-.SH "Description"
-5 March 1996; 
-.PP
-\fBXtUnmanageChildren()\fP unmaps the specified widgets
-and removes them from their parent\&'s geometry management\&.
-The widgets will disappear from the screen, and (depending
-on its parent) may no longer have screen space allocated for
-them\&.
-.PP
-Each of the widgets in the \fIchildren\fP array must have
-the same parent\&.
-.PP
-See the Algorithm section below for full details of the
-widget unmanagement procedure\&.
-.SH "Usage"
-.PP
-Unmanaging widgets is the usual method for temporarily
-making them invisible\&.  They can be re-managed with
-\fBXtManageChildren()\fP\&.
-.PP
-You can unmap a widget, but leave it under geometry
-management by calling \fBXtUnmapWidget()\fP\&.  You can
-destroy a widget\&'s window without destroying the widget by
-calling \fBXtUnrealizeWidget()\fP\&.  You can destroy a
-widget completely with \fBXtDestroyWidget()\fP\&.
-.PP
-If you are only going to unmanage a single widget, it is
-more convenient to call \fBXtUnmanageChild()\fP\&.  It is
-often more convenient to call \fBXtUnmanageChild()\fP
-several times than it is to declare and initialize an array
-of widgets to pass to \fBXtUnmanageChildren()\fP\&.  Calling
-\fBXtUnmanageChildren()\fP is more efficient, however,
-because it only calls the parent\&'s \fBchange_managed()\fP
-method once\&.
-.SH "Algorithm"
-.PP
-\fBXtUnmanageChildren()\fP performs the following:
-.IP "" 10
-Issues an error if the children do not all have the same
-parent or if the parent is not a subclass of
-\fBcompositeWidgetClass\fP\&.
-.IP "" 10
-Returns immediately if the common parent is being destroyed;
-otherwise, for each unique child on the list,
-\fBXtUnmanageChildren()\fP performs the following:
-.IP "-" 10
-Ignores the child if it already is unmanaged or is being
-destroyed\&.
-.IP "-" 10
-Otherwise, if the child is realized, it makes it nonvisible
-by unmapping it\&.
-.IP "" 10
-Calls the \fBchange_managed()\fP method of the widgets\&'
-parent if the parent is realized\&.
-.PP
-.SH "Structures"
-.PP
-The \fBWidgetList\fP type is simply an array of widgets:
-.PP
-.nf
-typedef Widget *WidgetList;
-.fi
-...\" created by instant / docbook-to-man, Mon 31 Aug 1998, 22:15
diff --git a/doc/notes.txt b/doc/notes.txt
deleted file mode 100644
index 7fd9041..0000000
--- a/doc/notes.txt
+++ /dev/null
@@ -1,180 +0,0 @@
-
-GTK Reference Documentation Notes
-===============================
-
-Things to include:
-    Compiling with GTK - gtk-config, gtk.m4, debugging options.
-    g_warning, g_return_if_fail etc. - though these are in glib.
-    Initialising the GTK library and entering the main loop.
-    Widgets (see below)
-    Object data hash (& GINT_TO_POINTER-type macros)
-    Type functions
-    Ref counting
-    Widget Layout - size_request/size_allocate, coordinate system, X windows.
-    Styles
-    Accelerators - major changes for GTK 1.1
-    Signals - signal emission procedure, connecting to signals, stopping,
-	adding new signals for new widgets, marshaller functions.
-    X Events - signals ending in "_event" have extra param, event masks
-    Keyboard input - focus, CAN_FOCUS, GRAB_FOCUS
-    Default widgets - CAN_DEFAULT, HAS_DEFAULT
-    Args - not complete yet.
-    Drag-and-drop
-    Selections
-    Timers
-    AddInput
-    RC files
-    Factories - major changes for GTK 1.1
-
-    Indices - functions, signals,	
-	      widget hierarchy/alphabetical list/grouped - annotated
-
-
-For each widget:
-
-    (We include a brief summary of the widget and its functions/signals at the
-    top of the page, since a lot of the time people know how it works but
-    have just forgotten a prototype or variable name.)
-
- *  Name
- *  Ancestors in widget hierarchy, with hyperlinks and set out like Java docs.
-    Short description.
- ?  '#Include <gtk/gtkbutton.h>' line?
- *  Index of functions, with prototypes, hyperlinks to descriptions below.
- ?  Index of useful members of widget struct, hyperlinks to descriptions below.
- *  Index of signals, with prototypes of signal handlers, and hyperlinks to
-        descriptions below.
- *  Standard widget functions and macros, with hyperlinks.
-    Usage - example code covering common use of the widget, which may also use
-        ancestor's properties, e.g. gtk_misc_set_alignment (GTK_MISC (label)...
- +  Full description of functions. Show parameters listed like Java docs?
-        A lot of the time there will just be one param - the widget itself.
- +  Full description of struct members. Show how to access using macro?
- +  Full description of signals.
- +  Full description of standard functions and macros.
-    See Also section showing related widgets, mainly for the man pages.
-    
-    Could also be some structs or enums which are used by the widget, e.g.
-    the GtkTableChild/GtkPackerChild structs. Do we keep the enums separate?
-    Or put them with the widget if they are only relevant to that widget?
-
-    Include screenshots?
-
- +  Include Args? - These still aren't fully supported, and they duplicate
-       the functionality already available, but should probably be included.
-
-
-Issues:
-
-    Some things have/will change between different GTK versions so we have to
-    show the changes somehow - a 'deprecated' icon/entity/label or possibly
-    show the version of GTK which each item was added to, e.g. a GTK 1.1 icon.
-    'Added in GTK 1.1', 'Deprecated in GTK 1.1', 'Not in GTK 1.1' ...
-
-    Cross-references - any time a widget class/type/enum appears there should
-        be a cross-reference (which will turn into a hyperlink for html).
-	But for man pages/printed docs we don't want 'See Also's everywhere.
-	Need to use an easy-to-remember naming scheme for ids - use
-	widget names, function names, enum names as much as possible.
-
-    Glib & GDK documentation - want this to be very similar, and we also need
-        to add cross-references to glib/gdk types and functions. But glib
-	documentation should also be separate?
-
-    For man page output we should include keywords or something to make it
-        easy to find the page with 'man -k' or similar.
-    For printed output we should also index all widgets, functions etc.,
-        so the pages can be found easily.
-    For the HTML version, we should create a database of entry points -
-        widgets, functions, declarations, so that an IDE can easily open up
-	the GTK documentation at a relevant page. e.g. If you move the mouse
-	over a widget in the palette and press F1 it shows the page about
-	the widget.
-
-
-GLib Reference
-==============
-
-Sections:
-    Intro - glib_major_version.
-    Types - gint, gchar, TRUE, FALSE.
-    Type conversion macros - GPOINTER_TO_INT.
-    Limits - G_MINFLOAT etc.
-    Macros - MIN, MAX, ABS, CLAMP, G_ENUM, G_STMT_START, G_GNUC_PRINTF,
-	     G_GNUC_FUNCTION, ATEXIT.
-    Memory allocation - g_new, g_new0, g_malloc, g_mem_chunk_create,
-		        g_chunk_new.
-    Warnings/assertions - g_assert, g_return_if_fail, g_error, g_warning.
-    Timers.
-    String utility functions.
-    Utility functions - g_get_user_name, g_get_home_dir, g_snprintf.
-    Scanner.
-    Modules.
-    Completion.
-
-  Data structures:
-    Doubly-linked lists.
-    Singly-linked lists.
-    Hash tables & hash functions - beware of adding pointers to
-        dynamically-allocated memory! - it may never be freed.
-    Caches.
-    Trees.
-    Strings.
-    String chunks.
-    Resizable arrays.
-    Resizable pointer arrays.
-    Byte arrays.
-    Quarks ??
-    Datasets.
-    Relation & Tuples.
-
-
-
-Reference Material
-==================
-
-GTK Specific Stuff:
-
-    GTK info pages
-	- a number of widgets & functions are documented, as well as some more
-	  general GTK programming topics, e.g. signals, object data.
-
-    GTK tutorial
-	- has descriptions of many widgets.
-
-    Shawn Admundson's example man page
-        - nice structure, includes brief reference material at top and more
-	  detailed descriptions below which is good (like Java docs). Also
-	  has a 'Usage' section which describes common usage.
-	  Doesn't include GTK Args, or useful members of the widget struct.
-
-    gtk+/gtk/testgtk gtk+/examples
-	- lots of example code.
-
-
-Documentation of other languages/toolkits:
-
-    Gnome's DocBook documentation.
-        - gnome-libs/gnome-hello has a basic DocBook document.
-	- perl script in gnome-libs/devel-docs/gdoc - what does it do??
-	- gnome-libs/devel-docs/gnome-dev-info.sgml has lots of stuff:
-	    uses '<!entity libgnome SYSTEM ...' to include other docs.
-	    pinch the bookinfo & license stuff.
-	    has tags: 'screenshot', 'graphic', 'ulink', 'email'
-	    '<programlisting role="C">', 'literal', 'prompt', 'userinput'
-	    'function', 'funcsynopsis', 'funcdef' 'paramdef', 'parameter'
-
-    Java documentation
-        - has a very nice structure and nice graphics to make it more
-	  attractive, cross-references, describes every function param.
-
-    QT documentation
-        - nice structure, screenshots, cross-references.
-
-    man manual page
-        - we want to output man pages, so we should try to keep close to
-	  the standard parts etc. (Use section 3 - library functions)
-	  From man man page:
-	  'They may be labelled NAME, SYNOPSIS, DESCRIPTION, OPTIONS,
-          FILES, SEE ALSO, BUGS, and AUTHOR.'
-	  see man (7) for the troff macros available (on Linux anyway).
diff --git a/doc/sections-file.txt b/doc/sections-file.txt
index 6f3f3fa..9e8e1f9 100644
--- a/doc/sections-file.txt
+++ b/doc/sections-file.txt
@@ -16,8 +16,7 @@ or for widgets it is based on the widget name converted to lower case).
 
 The <TITLE> ... </TITLE> tag is used to specify the title of the section.
 It is only useful before the templates are initially created, since the title
-set in the template file overrides this. (Note that if you change the titles
-anywhere you will have to update the main SGML file.)
+set in the template file overrides this.
 
 You can group items in the section by using the <SUBSECTION> tag. Currently
 it outputs a blank line between subsections in the synopsis section.
diff --git a/doc/setting-up.txt b/doc/setting-up.txt
index 5b0ea1b..30d7708 100644
--- a/doc/setting-up.txt
+++ b/doc/setting-up.txt
@@ -1,70 +1,31 @@
 
-How to set up a module to use gtk-doc
-=====================================
+How to Set Up an Application or Library to use GTK-Doc
+======================================================
 
+This assumes that you are using autoconf & automake to build your package.
 
-1. Get the latest gtk-doc from CVS, install it, and read the README so you
-   have an idea of how it works. Also look at the examples directory to see
-   an example of how gnome-libs docs could be set up.
 
+1. Insert the code from examples/configure.in into your configure.in.
+   (somewhere before the call to AC_OUTPUT.)
 
-2. Decide if you want your documentation in a subdirectory of your main
-   application directory/module or as a separate directory/module.
-   If you put the docs inside the application module you can use relative paths
-   to point to the source code. If you put it in a separate module you may want
-   to add a configure option to point to the source code directory (as the
-   gnome example does).
+2. Create a directory in which you want the docs to be built,
+   e.g. 'myproject/docs/reference'.
 
+3. Copy examples/Makefile.am to this directory and edit the variables at
+   the top of the file.
 
-3. Create a directory to put the documentation.
-   Decide if your docs need to be split into separate pieces (as gnome-libs is
-   split into gnome and gnomeui), or there will be just one document.
-   If it is split into pieces, you need to create subdirectories for each
-   piece and the toplevel Makefile.am in the root directory (look at examples/)
+4. Add the new Makefile to your configure.in's AC_OUTPUT call, and make sure
+   all the SUBDIRS variables are set properly so the docs directory is built.
 
+5. If your library or application includes GtkObjects/GObjects, and you want
+   their signals, arguments/parameters and position in the hierarchy to be
+   documented:
 
-4. Set up your configure.in so that it accepts a --with-html-dir option
-   and substitutes HTML_DIR (like in the examples).
-
-
-5. Copy gnome/Makefile.am to each document directory (or if your module
-   contains widgets copy gnomeui/Makefile.am).
-
-   Change DOC_MODULE to the name of your module.
-   Change DOC_MAIN_SGML_FILE to the name of the file you want to use as the
-     main SGML file - it will use entity references to include all of the
-     generated SGML files (MODULE-docs.sgml is fine).
-   Change DOC_SOURCE_DIR to the directory containing the source code. If the
-     documentation is within the application's directory then you can simply
-     use a relative path. If not, you need to use a configure option as used
-     in the examples directory. If you are scanning installed headers only
-     and don't have comment blocks in the source code you don't need this.
-
-   If you have widgets in your module, change the CFLAGS and LDFLAGS so that
-   gtkdoc-scanobj can compile and link a program with your library.
-
-   Change the options for gtkdoc-scan:
-     gtkdoc-scan scans header files. If you pass it a --source-dir option it
-     will recursively scan all the header files found in the directory tree.
-     You can use --ignore-headers to ignore particular header files
-     (just use the basenames and separate them with spaces, e.g.
-     --ignore-headers="libgnomeP.h gnome-i18nP.h gnome-triggersP.h" ).
-     Alternatively you can simply specify the headers which you do want
-     scanned as standard arguments. GLib uses this to scan installed headers:
-
-scan:
-        gtkdoc-scan --module=$(DOC_MODULE) `glib-config --prefix`/include/glib.h `glib-config --prefix`/include/gmodule.h `glib-config --prefix`/lib/glib/include/glibconfig.h 
-
-   Change the options for gtkdoc-mkdb:
-     If you have comment blocks in your source code, use the option
-        --source-dir=$(DOC_SOURCE_DIR)
-     If not, take it out.
-
-
-6. If your module contains widgets you need to create a MODULE.types file.
-   This contains any '#include' directives needed to compile a program with
-   your module, and a list of functions to initialize all of the widgets in
-   the library. For example, the gtk.types file starts like this:
+   Create a MODULE.types file in the docs directory, e.g. "myproject.types".
+   This should contain any '#include' directives needed to compile a program
+   with your module, and a list of functions to initialize all of the widgets
+   and objects in the library. For example, the gtk.types file starts like
+   this:
 
 	#include <gtk/gtk.h>
 
@@ -74,35 +35,19 @@ scan:
 	gtk_arrow_get_type
 
 
-
-7. Create the Makefile and 'make scan'. This will scan all the headers and
-   produce a list of declarations found in the MODULE-decl-list.txt file.
-   Copy this file to MODULE-sections.txt and rearrange it if necessary.
-   (See sections-file.txt for a description of the format).
-
-
-8. Do a 'make templates' to create the template files in tmpl/
-
-
-9. Do a 'make sgml' to create the DocBook SGML output in sgml/
-
-
-10.Create your main SGML file (with the name you used in Makefile.am),
-   using entity references to include all the generated SGML files.
-   In sgml/MODULE-doc.top and sgml/MODULE-doc.bottom you will find a generated
-   list of entities and references which you can use to include in your
-   main SGML file. (Look at the gnome/gnome-docs.sgml and
-   gnomeui/gnomeui-docs.sgml files in the examples directory).
-
-   Note: if you add or remove 'sections' in the documentation, you will need
-   to update this main SGML file. It's very easy to forget.
+That's it! If you now build the application or library you should get a
+complete set of documentation.
 
 
-11. Do a 'make html' to make the final HTML.
+You can tweak the output in several ways:
 
+ o modify the main SGML file to add introductory sections or to split the
+   documentation into several chapters.
 
+ o modify the MODULE-sections.txt file to rearrange the documentation into
+   different sections or a different order (see sections-file.txt for info).
 
-11a. Email me and tell me where it went wrong :)
+ o add a MODULE-overrides.txt to override particular declarations.
 
 
 Damon