From f2ceb1c46a7b5dc9e2b6baa4bcf543601dc5d986 Mon Sep 17 00:00:00 2001
From: Havoc Pennington <hp@pobox.com>
Date: Sun, 4 Feb 2001 03:11:11 +0000
Subject: [PATCH] Add the intro docs section

2001-02-03  Havoc Pennington  <hp@pobox.com>

	* gtk/tmpl/gtkfixed.sgml: Add the intro docs section
---
 docs/reference/ChangeLog              |  4 +++
 docs/reference/gtk/tmpl/gtkfixed.sgml | 52 +++++++++++++++++++++++++--
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index e327fbb904..58904ccdb7 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+2001-02-03  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/tmpl/gtkfixed.sgml: Add the intro docs section
+
 2001-02-01  Havoc Pennington  <hp@redhat.com>
 
 	* gtk/gtk-sections.txt: updated
diff --git a/docs/reference/gtk/tmpl/gtkfixed.sgml b/docs/reference/gtk/tmpl/gtkfixed.sgml
index c72b4e743c..3e3b3d515d 100644
--- a/docs/reference/gtk/tmpl/gtkfixed.sgml
+++ b/docs/reference/gtk/tmpl/gtkfixed.sgml
@@ -2,13 +2,61 @@
 GtkFixed
 
 <!-- ##### SECTION Short_Description ##### -->
-a container which supports fixed sizes and positions of its children.
+a container which allows you to position widgets at fixed coordinates
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 The #GtkFixed widget is a container which can place child widgets at fixed
-positions and with fixed sizes, given in pixels.
+positions and with fixed sizes, given in pixels. #GtkFixed performs no
+automatic layout management.
+</para>
 
+<para>
+For most applications, you should not use this container! It keeps
+you from having to learn about the other GTK+ containers, but it
+results in broken applications.
+With #GtkFixed, the following things will result in truncated text, 
+overlapping widgets, and other display bugs:
+<itemizedlist>
+<listitem>
+<para>Themes, which may change widget sizes.
+</para>
+</listitem>
+<listitem>
+<para>Fonts other than the one you used to write the app will of
+course change the size of widgets containing text; keep in mind that
+users may use a larger font because of difficulty reading the default,
+or they may be using Windows or the framebuffer port of GTK+, where
+different fonts are available.
+</para>
+</listitem>
+<listitem>
+<para>
+Translation of text into other languages changes its size. Also,
+display of non-English text will use a different font in many cases.
+</para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>
+In addition, the fixed widget can't properly be mirrored in
+right-to-left languages such as Hebrew and Arabic. i.e. normally GTK+
+will flip the interface to put labels to the right of the thing they
+label, but it can't do that with #GtkFixed. So your application will 
+not be usable in right-to-left languages.
+</para>
+
+<para>
+Finally, fixed positioning makes it kind of annoying to add/remove GUI
+elements, since you have to reposition all the other elements. This is
+a long-term maintenance problem for your application.
+</para>
+
+<para>
+If you know none of these things are an issue for your application,
+and prefer the simplicity of #GtkFixed, by all means use the
+widget. But you should be aware of the tradeoffs.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->