[gtk+] Update documentation around deprecations.

[Matthias Clasen <matthiasc src gnome org>]

commit 2298c51d93c65ecb22080448213cdbc32d2e90ee
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Nov 9 22:08:43 2011 -0500

    Update documentation around deprecations.

 docs/reference/gtk/compiling.sgml |   17 ++++++++++++++---
 1 files changed, 14 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/gtk/compiling.sgml b/docs/reference/gtk/compiling.sgml
index b8a080d..f4021c6 100644
--- a/docs/reference/gtk/compiling.sgml
+++ b/docs/reference/gtk/compiling.sgml
@@ -47,9 +47,20 @@ $ cc `pkg-config --cflags --libs gtk+-3.0` hello.c -o hello
 </para>
 
 <para>
-If you want to make sure that your program doesn't use any deprecated
-functions, you can define the preprocessor symbol GTK_DISABLE_DEPRECATED
-by using the command line option <literal>-DGTK_DISABLE_DEPRECATED=1</literal>.
+Deprecated GTK+ functions are annotated to make the compiler
+emit warnings when they are used (e.g. with gcc, you need to use
+the -Wdeprecated-declarations option). If these warnings are
+problematic, they can be turned off by defining the preprocessor
+symbol GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
+option <literal>-DGDK_DISABLE_DEPRECATION_WARNINGS</literal>
+</para>
+
+<para>
+The older deprecation mechanism of hiding deprecated interfaces
+entirely from the compiler by using the preprocessor symbol
+GTK_DISABLE_DEPRECATED is still used for deprecated macros,
+enumeration values, etc. To detect uses of these in your code,
+use the commandline option <literal>-DGTK_DISABLE_DEPRECATED</literal>.
 There are similar symbols GDK_DISABLE_DEPRECATED,
 GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and
 GLib.