move README.linux-fb in here

2002-01-01  Havoc Pennington  <hp@pobox.com>

	* gtk/framebuffer.sgml: move README.linux-fb in here

	* gtk/tmpl/gtkpreview.sgml: explain what to use instead

	* gtk/tmpl/gtkseparator.sgml: typo fix

	* gtk/tmpl/gtkstock.sgml: add some overview docs

	* gtk/Makefile.am (content_files): add new files

	* gtk/changes-1.2.sgml: move Changes-1.2.txt in here

	* gtk/changes-2.0.sgml: move Changes-2.0.txt in here

	* gdk/tmpl/threads.sgml: mention gdk_threads_init() in the
	overview docs, copy in the examples from the FAQ

	* gtk/gtk-docs.sgml: change DTD to 3.1, and add
	question_index.sgml and changes-1.2, changes-2.0

	* gtk/tmpl/gtkdrawingarea.sgml: fixups to reflect 2.0 changes

	* gtk/question_index.sgml: new section with question-based
	index of the manual

	* gtk/text_widget.sgml: fix some cross-references

2002-01-01  Havoc Pennington  <hp@pobox.com>

	* docs/README.linux-fb: note that this file is obsolete

	* docs/Changes-2.0.txt, docs/Changes-1.2.txt: Add notes to these
	files that they should not be edited and look in the reference
	manual instead. Probably these files should just be replaced by
	the note, and their main contents deleted.

	* gtk/gtktextview.c: docs

	* gtk/gtktextmark.c: docs

	* gtk/gtktextchild.c: docs

	* gtk/gtktextbuffer.c: docs stuff

	* gtk/gtkclipboard.c (gtk_clipboard_get): fool with docs to maybe
	give people more leads in sorting out PRIMARY vs. CLIPBOARD

1 files changed, 25 insertions, 6 deletions

diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index ae4357f96f..4a3f20fd65 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -88,18 +88,37 @@ static GQuark clipboards_owned_key_id = 0;
 /**
  * gtk_clipboard_get:
  * @selection: a #GdkAtom which identifies the clipboard
- *             to use. A value of %GDK_NONE here is the
- *             same as <literal>gdk_atom_intern ("CLIPBOARD", FALSE)</literal>,
- *             and provides the default clipboard. Another
- *             common value is %GDK_SELECTION_PRIMARY, which
- *             identifies the primary X selection. 
+ *             to use.
  * 
  * Returns the clipboard object for the given selection.
+ * Cut/copy/paste menu items and keyboard shortcuts should use
+ * the default clipboard, returned by passing #GDK_NONE for @selection.
+ * The currently-selected object or text should be provided on the clipboard
+ * identified by #GDK_SELECTION_PRIMARY. Cut/copy/paste menu items
+ * conceptually copy the contents of the #GDK_SELECTION_PRIMARY clipboard
+ * to the default clipboard, i.e. they copy the selection to what the
+ * user sees as the clipboard.
+ *
+ * (Passing #GDK_NONE is the same as using <literal>gdk_atom_intern
+ * ("CLIPBOARD", FALSE)</literal>. See
+ * <ulink url="http://www.freedesktop.org/standards/clipboards.txt">
+ * http://www.freedesktop.org/standards/clipboards.txt</ulink>
+ * for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections
+ * under the X window system. On Win32 the #GDK_SELECTION_PRIMARY
+ * clipboard is essentially ignored.)
+ *
+ * It's possible to have arbitrary named clipboards; if you do invent
+ * new clipboards, you should prefix the selection name with an
+ * underscore (because the ICCCM requires that nonstandard atoms are
+ * underscore-prefixed), and namespace it as well. For example,
+ * if your application called "Foo" has a special-purpose
+ * clipboard, you might call it "_FOO_SPECIAL_CLIPBOARD".
  * 
  * Return value: the appropriate clipboard object. If no
  *             clipboard already exists, a new one will
  *             be created. Once a clipboard object has
- *             been created, it is persistent for all time.
+ *             been created, it is persistent for all time and
+ *             cannot be freed.
  **/
 GtkClipboard *
 gtk_clipboard_get (GdkAtom selection)