Re-enable the "find" dialog

2000-10-23  Havoc Pennington  <hp@redhat.com>

        * gtk/testtext.c: Re-enable the "find" dialog

	* gtk/testgtk.c: Add test for gdk_drawable_get_image

	* gdk/gdkwindow.c (gdk_window_begin_paint_region): Fix bug where
	the arguments to gdk_draw_drawable were in the wrong order
	(gdk_window_paint_init_bg): This function was ignoring the
	init_region, instead of clipping to it, so the entire backing
	pixmap was cleared on every begin_paint()
	(gdk_window_begin_paint_region): Hmm, the same list-walking bug
	was in here again, the loop kept using the same GtkWindowPaint
	over and over.
	(gdk_window_begin_paint_region): Fix a bug where we had two
	x_offset instead of x_offset and y_offset

	* gdk/gdkdraw.c (gdk_drawable_get_image): get composite drawable
	before we get the image.
	(gdk_draw_drawable): get the composite before we draw the drawable.
	(gdk_drawable_real_get_composite_drawable): default
	get_composite_drawable implementation that returns the drawable
	itself

	* gdk/gdkdrawable.h (struct _GdkDrawableClass ): Add
	get_composite_drawable virtual function

	* gdk/gdkwindow.c (gdk_window_begin_paint_region): Fix a cheesy
	list-walking bug

	* gdk/x11/gdkdrawable-x11.c (gdk_x11_draw_drawable): Add a hack to
	make this work if the source drawable is a GdkDrawableImplX11
	instead of a public drawable type. This is really broken; the
	problem is that GdkDrawable needs a virtual method get_xid(), but
	of course that doesn't work in practice. Enter RTTI.

	Also, improve mismatched depth message.

	* gdk/gdkpixmap.c (gdk_pixmap_get_image): Implement get_image for
	GdkPixmap

	* gdk/x11/gdkdrawable-x11.c (gdk_drawable_impl_x11_class_init):
	install _gdk_x11_get_image as our implementation of get_image

	* gdk/x11/gdkimage-x11.c (gdk_image_get): Rename to
	_gdk_x11_get_image and export for use in gdkdrawable-x11.c

	* gdk/gdkimage.c (gdk_image_get): Make this just a wrapper around
	gdk_drawable_get_image

	* gdk/gdkdraw.c (gdk_drawable_get_image): call virtual get_image

	* gdk/gdkdrawable.h (struct _GdkDrawableClass ): Virtualize
	get_image

	* gtk/gtktreestore.c (gtk_tree_store_get_node): remove weird
	trailing semicolon after for loop

12 files changed, 406 insertions, 118 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 8c50e48dd9..7fe274847a 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,18 @@
+2000-10-23  Havoc Pennington  <hp@redhat.com>
+
+	* gtk/gtk-sections.txt: remove GtkTextBTree
+
+	* gtk/text_widget.sgml: Overview of the text widget
+
+	* gtk/gtk-docs.sgml: Change to using categories for the toplevel 
+	organization of the reference entries. We'll add an alphabetical 
+	index eventually. The category way is a lot easier for people who
+	aren't familiar with the widgets. Removed objects_grouped.sgml 
+	from gtk-docs.sgml for now, it doesn't seem useful anymore.
+
+	* gtk/objects_grouped.sgml: Add a section for deprecated
+	objects; add a section for the TextView object collection
+
 Wed Oct 18 11:01:12 2000  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/Makefile.am gdk-pixbuf/Makefile.am: Fix typo
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index bc827b5587..c9052b21c6 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -62,7 +62,8 @@ GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
 GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
 
 content_files = 		\
-	objects_grouped.sgml
+	objects_grouped.sgml	\
+	text_widget.sgml
 
 ####################################
 # Everything below here is generic #
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 01f2a698a9..637531ddb5 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -120,6 +120,7 @@
 <!entity index-Object-Tree SYSTEM "sgml/tree_index.sgml">
 
 <!entity index-Objects-Grouped SYSTEM "objects_grouped.sgml">
+<!entity gtk-TextWidget SYSTEM "text_widget.sgml">
 ]>
 <book id="index">
   <bookinfo>
@@ -173,6 +174,7 @@ An advanced widget set.
 </varlistentry>
 </variablelist>
     </para>
+
     &gtk-General;
     &gtk-Feature-Test-Macros;
     &gtk-Graphics-Contexts;
@@ -188,120 +190,176 @@ An advanced widget set.
     &gtk-Types;
     &gtk-Bindings;
     &gtk-Standard-Enumerations;
+
   </chapter>
 
-  <chapter id="gtkobjects" role="no-toc">
+  <chapter  id="gtkobjects" role="no-toc">
     <title>GTK+ Widgets and Objects</title>
-    &index-Objects-Grouped;
 
-    &GtkAccelLabel;
-    &GtkAdjustment;
-    &GtkAlignment;
-    &GtkArrow;
-    &GtkAspectFrame;
-    &GtkButtonBox;
-    &GtkBin;
-    &GtkBox;
-    &GtkButton;
-    &GtkCalendar;
-    &GtkCheckButton;
-    &GtkCheckMenuItem;
-    &GtkCList;
-    &GtkColorSelection;
-    &GtkColorSelectionDialog;
-    &GtkCombo;
-    &GtkContainer;
-    &GtkCTree;
-    &GtkCurve;
-    &GtkData;
-    &GtkDialog;
-    &GtkDrawingArea;
-    &GtkEditable;
-    &GtkEntry;
-    &GtkEventBox;
-    &GtkFileSelection;
-    &GtkFixed;
-    &GtkFontSelection;
-    &GtkFontSelectionDialog;
-    &GtkFrame;
-    &GtkGammaCurve;
-    &GtkHandleBox;
-    &GtkHButtonBox;
-    &GtkHBox;
-    &GtkHPaned;
-    &GtkHRuler;
-    &GtkHScale;
-    &GtkHScrollbar;
-    &GtkHSeparator;
-    &GtkImage;
-    &GtkIMContext;
-    &GtkIMMulticontext;
-    &GtkInputDialog;
-    &GtkInvisible;
-    &GtkItem;
-    &GtkItemFactory;
-    &GtkLabel;
-    &GtkLayout;
-    &GtkList;
-    &GtkListItem;
-    &GtkMenu;
-    &GtkMenuBar;
-    &GtkMenuItem;
-    &GtkMenuShell;
-    &GtkMisc;
-    &GtkNotebook;
-    &GtkObject;
-    &GtkOptionMenu;
-    &GtkPacker;
-    &GtkPaned;
-    &GtkPixmap;
-    &GtkPlug;
-    &GtkPreview;
-    &GtkProgress;
-    &GtkProgressBar;
-    &GtkRadioButton;
-    &GtkRadioMenuItem;
-    &GtkRange;
-    &GtkRuler;
-    &GtkScale;
-    &GtkScrollbar;
-    &GtkScrolledWindow;
-    &GtkSeparator;
-    &GtkSocket;
-    &GtkSpinButton;
-    &GtkStatusbar;
-    &GtkTable;
-    &GtkTearoffMenuItem;
-    &GtkText;
-    &GtkTextBuffer;
-    &gtk-GtkTextIter;
-    &gtk-GtkTextMark;
-    &GtkTextTag;
-    &GtkTextTagTable;
-    &GtkTextView;
-    &GtkTipsQuery;
-    &GtkToggleButton;
-    &GtkToolbar;
-    &GtkTooltips;
-    &GtkTree;
-    &GtkTreeItem;
-    &GtkVButtonBox;
-    &GtkVBox;
-    &GtkViewport;
-    &GtkVPaned;
-    &GtkVRuler;
-    &GtkVScale;
-    &GtkVScrollbar;
-    &GtkVSeparator;
-    &GtkWidget;
-    &GtkWindow;
-  </chapter>
-
-  <chapter id="gtk-index">
-    <title>Index</title>
     <sect1>
       <title>Object Hierarchy</title>
     &index-Object-Tree;
     </sect1>
+
+    <sect1 id="WindowWidgets">
+      <title>Windows</title>
+        &GtkDialog;
+        &GtkInvisible;
+        &GtkPlug;
+        &GtkWindow;
+    </sect1>
+
+    <sect1 id="DisplayWidgets">
+      <title>Display Widgets</title>
+        &GtkAccelLabel;
+        &GtkImage;
+        &GtkLabel;
+        &GtkProgressBar;
+        &GtkStatusbar;
+    </sect1>
+
+    <sect1 id="ButtonWidgets">
+      <title>Buttons and Toggles</title>
+        &GtkButton;
+        &GtkCheckButton;
+        &GtkRadioButton;
+        &GtkToggleButton;
+    </sect1>
+
+    <sect1 id="NumericEntry">
+      <title>Numeric/Text Data Entry</title>
+        &GtkEntry;
+        &GtkHScale;      
+        &GtkSpinButton;
+        &GtkVScale;
+    </sect1>
+
+    <sect1 id="TextWidgetObjects">
+      <title>Multiline Text Editor</title>
+        &gtk-TextWidget;
+        &gtk-GtkTextIter;
+        &gtk-GtkTextMark;
+        &GtkText;
+        &GtkTextBuffer;
+        &GtkTextTag;
+        &GtkTextTagTable;
+        &GtkTextView;
+    </sect1>
+
+
+    <sect1 id="MenusAndCombos">
+      <title>Menus, Combo Box, Toolbar</title>
+        &GtkCheckMenuItem;      
+        &GtkCombo;
+        &GtkItemFactory;
+        &GtkMenu;
+        &GtkMenuBar;
+        &GtkMenuItem;
+        &GtkMenuShell;
+        &GtkOptionMenu;
+        &GtkRadioMenuItem;
+        &GtkTearoffMenuItem;
+        &GtkToolbar;
+    </sect1>
+
+    <sect1 id="SelectorWidgets">
+      <title>Selectors (File/Font/Color/Input Devices)</title>
+        &GtkColorSelection;
+        &GtkColorSelectionDialog;
+        &GtkFileSelection;
+        &GtkFontSelection;
+        &GtkFontSelectionDialog;
+        &GtkInputDialog;
+    </sect1>
+    
+    <sect1 id="LayoutContainers">
+      <title>Layout Containers</title>
+        &GtkAlignment;
+        &GtkAspectFrame;
+        &GtkHBox;
+        &GtkHButtonBox;
+        &GtkFixed;
+        &GtkHPaned;
+        &GtkLayout;
+        &GtkNotebook;
+        &GtkTable;
+        &GtkVButtonBox;
+        &GtkVBox;
+        &GtkVPaned;
+    </sect1>
+
+    <sect1 id="Ornaments">
+      <title>Ornaments</title>
+        &GtkFrame;
+        &GtkHSeparator;
+        &GtkVSeparator;
+    </sect1>
+
+    <sect1 id="ScrollingWidgets">
+      <title>Scrolling</title>
+        &GtkHScrollbar;
+        &GtkScrolledWindow;
+        &GtkVScrollbar;
+    </sect1>
+
+    <sect1 id="MiscObjects">
+      <title>Miscellaneous</title>
+        &GtkAdjustment;
+        &GtkArrow;
+        &GtkCalendar;
+        &GtkDrawingArea;
+        &GtkEventBox;
+        &GtkHandleBox;
+        &GtkIMContext;
+        &GtkIMMulticontext;
+        &GtkTooltips;
+        &GtkViewport;
+    </sect1>
+
+    <sect1 id="AbstractObjects">
+      <title>Abstract Base Classes</title>
+        &GtkBin;
+        &GtkBox;
+        &GtkContainer;
+        &GtkEditable;
+        &GtkButtonBox;
+        &GtkMisc;
+        &GtkObject;
+        &GtkPaned;
+        &GtkRange;
+        &GtkScale;
+        &GtkScrollbar;
+        &GtkSeparator;
+        &GtkWidget;
+    </sect1>    
+
+    <sect1 id="PlugSocket">
+      <title>Cross-process Embedding</title>
+        &GtkSocket;
+    </sect1>
+
+    <sect1 id="DeprecatedObjects">
+      <title>Deprecated</title>
+        &GtkCList;      
+        &GtkCTree;
+        &GtkCurve;
+        &GtkData;
+        &GtkGammaCurve;
+        &GtkHRuler;
+        &GtkItem;
+        &GtkList;
+        &GtkListItem;
+        &GtkPacker;
+        &GtkPixmap;
+        &GtkPreview;
+        &GtkProgress;
+        &GtkRuler;
+        &GtkTipsQuery;
+        &GtkTree;
+        &GtkTreeItem;
+        &GtkVRuler;
+    </sect1>
+
   </chapter>
+
 </book>
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index 44d27b38d3..7f419e6b7a 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -1951,7 +1951,6 @@ GTK_IS_TEXT_CLASS
 
 <SECTION>
 <FILE>gtktextbuffer</FILE>
-GtkTextBTree
 <TITLE>GtkTextBuffer</TITLE>
 gtk_text_buffer_new
 gtk_text_buffer_get_line_count
diff --git a/docs/reference/gtk/objects_grouped.sgml b/docs/reference/gtk/objects_grouped.sgml
index 3b546dc9c3..db8f91d9b4 100644
--- a/docs/reference/gtk/objects_grouped.sgml
+++ b/docs/reference/gtk/objects_grouped.sgml
@@ -46,25 +46,31 @@
 
 <emphasis>Data Entry Widgets</emphasis>
     <link linkend="GtkEntry">GtkEntry</link>
-    <link linkend="GtkText">GtkText</link>
     <link linkend="GtkSpinButton">GtkSpinButton</link>
+    <link linkend="GtkTextView">GtkTextView</link>
     <link linkend="GtkOptionMenu">GtkOptionMenu</link>
     <link linkend="GtkCombo">GtkCombo</link>
     <link linkend="GtkHScale">GtkHScale</link>
     <link linkend="GtkVScale">GtkVScale</link>
+                    
 
 <emphasis>Lists &amp; Trees</emphasis>
     <link linkend="GtkCList">GtkCList</link>
     <link linkend="GtkCTree">GtkCTree</link>
     <link linkend="GtkList">GtkList</link>
     <link linkend="GtkListItem">GtkListItem</link>
-    <link linkend="GtkTree">GtkTree</link>
-    <link linkend="GtkTreeItem">GtkTreeItem</link>
+
+<emphasis>Text Widget Objects</emphasis>
+    <link linkend="GtkTextBuffer">GtkTextBuffer</link>
+    <link linkend="GtkTextTag">GtkTextTag</link>
+    <link linkend="GtkTextTagTable">GtkTextTagTable</link>
+    <link linkend="GtkTextView">GtkTextView</link>
 
 <emphasis>Tooltips</emphasis>
     <link linkend="GtkTooltips">GtkTooltips</link>
     <link linkend="GtkTipsQuery">GtkTipsQuery</link>
 </literallayout></entry>
+
 <entry><literallayout>
 <emphasis>Menus &amp; Menu Bars</emphasis>
     <link linkend="GtkMenuBar">GtkMenuBar</link>
@@ -96,6 +102,7 @@
     <link linkend="GtkColorSelection">GtkColorSelection</link>
     <link linkend="GtkFontSelection">GtkFontSelection</link>
 </literallayout></entry>
+
 <entry><literallayout>
 <emphasis>Abstract Base Classes</emphasis>
     <link linkend="GtkWidget">GtkWidget</link>
@@ -126,5 +133,12 @@
     <link linkend="GtkItemFactory">GtkItemFactory</link>
     <link linkend="GtkInvisible">GtkInvisible</link>
 </literallayout></entry>
+
+<entry><literallayout>
+<emphasis>Deprecated Objects</emphasis>
+    <link linkend="GtkText">GtkText</link>
+    <link linkend="GtkTree">GtkTree</link>
+    <link linkend="GtkTreeItem">GtkTreeItem</link>
+</literallayout></entry>
 </row>
 </tbody></tgroup></informaltable>
diff --git a/docs/reference/gtk/text_widget.sgml b/docs/reference/gtk/text_widget.sgml
new file mode 100644
index 0000000000..776f079533
--- /dev/null
+++ b/docs/reference/gtk/text_widget.sgml
@@ -0,0 +1,127 @@
+<refentry id="TextWidget" revision="18 Oct 2000">
+<refmeta>
+<refentrytitle>Text Widget Overview</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Text Widget Overview</refname><refpurpose>Overview of <link linkend="GtkTextBuffer">GtkTextBuffer</link>, <link linkend="GtkTextView">GtkTextView</link>, and friends</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Conceptual Overview</title>
+
+<para>
+GTK+ has an extremely powerful framework for multiline text editing.  The
+primary objects involved in the process are <link
+linkend="GtkTextBuffer">GtkTextBuffer</link>, which represents the text being
+edited, and <link linkend="GtkTextView">GtkTextView</link>, a widget which can
+display a <link linkend="GtkTextBuffer">GtkTextBuffer</link>. Each buffer can be
+displayed by any number of views.
+</para>
+
+<para>
+Text in a buffer can be marked with <firstterm>tags</firstterm>. A tag is an
+attribute that can be applied to some range of text. For example, a tag might be
+called "bold" and make the text inside the tag bold. However, the tag concept is
+more general than that; tags don't have to affect appearance. They can instead
+affect change the behavior of mouse and key presses, "lock" a range of text so
+the user can't edit it, or countless other things. A tag is represented by a
+<link linkend="GtkTextTag">GtkTextTag</link> object. One <link
+linkend="GtkTextTag">GtkTextTag</link> can be applied to any number of text
+ranges in any number of buffers.
+</para>
+
+<para>
+Each tag is stored in a <link
+linkend="GtkTextTagTable">GtkTextTagTable</link>. A tag table defines a set of
+tags that can be used together. Each buffer has one tag table associated with
+it; only tags from that tag table can be used with the buffer. A single tag
+table can be shared between multiple buffers, however.
+</para>
+
+<para>
+Tags can have names, which is convenient sometimes (for example, you can name
+your tag that makes things bold "bold"), but they can also be anonymous (which
+is convenient if you're creating tags on-the-fly).
+</para>
+
+<para>
+Most text manipulation is accomplished with <firstterm>iterators</firstterm>,
+represented by a <link linkend="GtkTextIter">GtkTextIter</link>. An iterator
+represents a position in the text buffer. <link
+linkend="GtkTextIter">GtkTextIter</link> is a struct designed to be allocated on
+the stack; it's guaranteed to be copiable by value and never contain any
+heap-allocated data. Iterators are not valid indefinitely; whenever the buffer
+is modified in a way that affects the number of characters in the buffer, all
+outstanding iterators become invalid. (Note that deleting 5 characters and then
+reinserting 5 still invalidates iterators, though you end up with the same
+number of characters).
+</para>
+
+<para>
+Because of this, iterators can't be used to preserve positions across buffer
+modifications. To preserve a position, the <link
+linkend="GtkTextMark">GtkTextMark</link> object is ideal. You can think of a
+mark as an invisible cursor or insertion point; it floats in the buffer, saving
+a position. If the text surrounding the mark is deleted, the mark remains in the
+position the text once occupied; if text is inserted at the mark, the mark ends
+up either to the left or to the right of the new text, depending on its
+<firstterm>gravity</firstterm>. The standard text cursor in left-to-right
+languages is a mark with right gravity, because it stays to the right of
+inserted text.
+</para>
+
+<para>
+Like tags, marks can be either named or anonymous. There are two marks built-in
+to <link linkend="GtkTextBuffer">GtkTextBuffer</link>; these are named
+<literal>"insert"</literal> and <literal>"selection_bound"</literal> and refer
+to the insertion point and the boundary of the selection which is not the
+insertion point, respectively. If no text is selected, these two marks will be
+in the same position. You can manipulate what is selected and where the cursor
+appears by moving these marks around.
+
+<footnote>
+<para>
+If you want to place the cursor in response to a user action, be sure to use
+gtk_text_buffer_place_cursor(), which moves both at once without causing a
+temporary selection (moving one then the other temporarily selects the range in
+between the old and new positions).
+</para>
+</footnote>
+</para>
+
+</refsect1>
+
+
+<refsect1>
+<title>Simple Example</title>
+
+<para>
+The simplest usage of <link linkend="GtkTextView">GtkTextView</link> 
+might look like this:
+<programlisting>
+
+  /* Get a buffer (it's a GObject, not a GtkObject, so we own a reference
+   * after this). Passing NULL as argument causes an empty tag table to be
+   * automatically created.  
+   */
+
+  buffer = gtk_text_buffer_new (NULL);
+
+  view = gtk_text_view_new_with_buffer (buffer);
+
+  /* view holds a reference now */
+  g_object_unref (G_OBJECT (buffer));
+
+  /* Now you might put the view in a container and display it on the
+   * screen; when the user edits the text, signals on the buffer
+   * will be emitted, such as "changed", "insert_text", and so on.
+   */
+</programlisting>
+</para>
+
+</refsect1>
+
+</refentry>
diff --git a/docs/reference/gtk/tmpl/gtktextbuffer.sgml b/docs/reference/gtk/tmpl/gtktextbuffer.sgml
index cd8a16a348..102d2f22cb 100644
--- a/docs/reference/gtk/tmpl/gtktextbuffer.sgml
+++ b/docs/reference/gtk/tmpl/gtktextbuffer.sgml
@@ -3,15 +3,24 @@ GtkTextBuffer
 
 <!-- ##### SECTION Short_Description ##### -->
 
+Stores attributed text for display in a <link
+linkend="GtkTextView">GtkTextView</link>
 
 <!-- ##### SECTION Long_Description ##### -->
+
+<para>
+You may wish to begin by reading the <link linkend="TextWidget">text widget
+conceptual overview</link> which gives an overview of all the objects and data
+types related to the text widget and how they work together.
+</para>
+
 <para>
 
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkTextView, #GtkTextIter, #GtkTextMark
 </para>
 
 <!-- ##### STRUCT GtkTextBTree ##### -->
diff --git a/docs/reference/gtk/tmpl/gtktextiter.sgml b/docs/reference/gtk/tmpl/gtktextiter.sgml
index bee274eb6e..eac93cacc8 100644
--- a/docs/reference/gtk/tmpl/gtktextiter.sgml
+++ b/docs/reference/gtk/tmpl/gtktextiter.sgml
@@ -1,11 +1,17 @@
 <!-- ##### SECTION Title ##### -->
-gtktextiter
+GtkTextIter
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Text buffer iterator
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+You may wish to begin by reading the <link linkend="TextWidget">text widget
+conceptual overview</link> which gives an overview of all the objects and data
+types related to the text widget and how they work together.
+</para>
+
+<para>
 
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtktextmark.sgml b/docs/reference/gtk/tmpl/gtktextmark.sgml
index 1e7d2681a3..dccd4e46fe 100644
--- a/docs/reference/gtk/tmpl/gtktextmark.sgml
+++ b/docs/reference/gtk/tmpl/gtktextmark.sgml
@@ -1,12 +1,51 @@
 <!-- ##### SECTION Title ##### -->
-gtktextmark
+GtkTextMark
 
 <!-- ##### SECTION Short_Description ##### -->
 
+A position in the buffer preserved across buffer modifications
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+You may wish to begin by reading the <link linkend="TextWidget">text widget
+conceptual overview</link> which gives an overview of all the objects and data
+types related to the text widget and how they work together.
+</para>
 
+<para>
+A #GtkTextMark is like a bookmark in a text buffer; it preserves a position in
+the text. You can convert the mark to an iterator using
+gtk_text_buffer_get_iter_at_mark(). Unlike iterators, marks remain valid across
+buffer mutations, because their behavior is defined when text is inserted or
+deleted. When text containing a mark is deleted, the mark remains in the
+position originally occupied by the deleted text. When text is inserted at a
+mark, a mark with <firstterm>left gravity</firstterm> will be moved to the
+beginning of the newly-inserted text, and a mark with <firstterm>right
+gravity</firstterm> will be moved to the end. 
+
+<footnote>
+<para>
+"left" and "right" here refer to logical direction (left is the toward the start
+of the buffer); in some languages such as Hebrew the logically-leftmost text is
+not actually on the left when displayed.
+</para>
+</footnote>
+</para>
+
+<para>
+Marks are reference counted, but the reference count only controls the validity
+of the memory; marks can be deleted from the buffer at any time with
+gtk_text_buffer_delete_mark(). Once deleted from the buffer, a mark is
+essentially useless.
+</para>
+
+<para>
+Marks optionally have names; these can be convenient to avoid passing the 
+#GtkTextMark object around.
+</para>
+
+<para>
+Marks are typically created using the gtk_text_buffer_create_mark() function.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/reference/gtk/tmpl/gtktexttag.sgml b/docs/reference/gtk/tmpl/gtktexttag.sgml
index 6bf264242e..41e0a1b502 100644
--- a/docs/reference/gtk/tmpl/gtktexttag.sgml
+++ b/docs/reference/gtk/tmpl/gtktexttag.sgml
@@ -3,9 +3,16 @@ GtkTextTag
 
 <!-- ##### SECTION Short_Description ##### -->
 
+A tag that can be applied to text in a <link linkend="GtkTextBuffer">GtkTextBuffer</link>
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+You may wish to begin by reading the <link linkend="TextWidget">text widget
+conceptual overview</link> which gives an overview of all the objects and data
+types related to the text widget and how they work together.
+</para>
+
+<para>
 
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtktexttagtable.sgml b/docs/reference/gtk/tmpl/gtktexttagtable.sgml
index 26f7ce2e39..be207363f4 100644
--- a/docs/reference/gtk/tmpl/gtktexttagtable.sgml
+++ b/docs/reference/gtk/tmpl/gtktexttagtable.sgml
@@ -3,9 +3,16 @@ GtkTextTagTable
 
 <!-- ##### SECTION Short_Description ##### -->
 
+Collection of tags that can be used together
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+You may wish to begin by reading the <link linkend="TextWidget">text widget
+conceptual overview</link> which gives an overview of all the objects and data
+types related to the text widget and how they work together.
+</para>
+
+<para>
 
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtktextview.sgml b/docs/reference/gtk/tmpl/gtktextview.sgml
index 9f36a4eaec..e26818c40a 100644
--- a/docs/reference/gtk/tmpl/gtktextview.sgml
+++ b/docs/reference/gtk/tmpl/gtktextview.sgml
@@ -2,16 +2,22 @@
 GtkTextView
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Widget that displays a <link linkend="GtkTextBuffer">GtkTextBuffer</link>
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+You may wish to begin by reading the <link linkend="TextWidget">text widget
+conceptual overview</link> which gives an overview of all the objects and data
+types related to the text widget and how they work together.
+</para>
+
+<para>
 
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkTextBuffer, #GtkTextIter
 </para>
 
 <!-- ##### STRUCT GtkTextView ##### -->