loose ends from "discouraged" removal

* README: Remove docs on "discouraged".

* configure.ac: Remove one more "discouraged" thing.

* doc/ref/api-deprecated.texi: Rename from api-discdepr.texi, and remove
  sections on "discouraged".

* doc/ref/Makefile.am:
* doc/ref/guile.texi: Update referrers.

README

@@ -145,10 +145,6 @@ switches specific to Guile you may find useful in some circumstances.
   implementation and helps to keep Guile reasonably clean of historic
   baggage.
 
-  Deprecated features are considered harmful; using them is likely a
-  bug.  See below for the related notion of `discouraged' features,
-  which are OK but have fallen out of favor.
-
   See the file NEWS for a list of features that are currently
   deprecated.  Each entry will also tell you what you should replace
   your code with.
@@ -198,16 +194,9 @@ switches specific to Guile you may find useful in some circumstances.
   'warn-deprecated) to enable and disable the detailed messaged at run
   time.
 
---disable-discouraged
+  Additionally, if your toolchain is new enough, you will receive
-
+  warnings at link time if you have a Guile extension that uses
-  In addition to deprecated features, Guile can also contain things
+  deprecated functions provided by Guile.
-  that are merely `discouraged'.  It is OK to continue to use these
-  features in old code, but new code should avoid them since there are
-  better alternatives.
-
-  There is nothing wrong with a discouraged feature per se, but they
-  might have strange names, or be non-standard, for example.  Avoiding
-  them will make your code better.
 
 --disable-shared  ---  Do not build shared libraries.
 --disable-static  ---  Do not build static libraries.

configure.ac

@@ -1604,7 +1604,6 @@ AC_SUBST([sitedir])
 
 # Additional SCM_I_GSC definitions are above.
 AC_SUBST([SCM_I_GSC_GUILE_DEBUG])
-AC_SUBST([SCM_I_GSC_ENABLE_DISCOURAGED])
 AC_SUBST([SCM_I_GSC_ENABLE_DEPRECATED])
 AC_SUBST([SCM_I_GSC_STACK_GROWS_UP])
 AC_SUBST([SCM_I_GSC_C_INLINE])

doc/ref/Makefile.am

@@ -61,7 +61,7 @@ guile_TEXINFOS = preface.texi			\
 		 sxml-match.texi		\
 		 scheme-scripts.texi		\
 		 api-overview.texi		\
-		 api-discdepr.texi		\
+		 api-deprecated.texi		\
 		 scheme-debugging.texi		\
 		 scheme-using.texi		\
 		 indices.texi			\

doc/ref/api-deprecated.texi

@@ -0,0 +1,31 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010
+@c   Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Deprecation
+@section Deprecation
+
+From time to time functions and other features of Guile become obsolete.
+Guile's @dfn{deprecation} is a mechanism that can help you cope with
+this.
+
+When you use a feature that is deprecated, you will likely get a
+warning message at run-time.  Also, deprecated features are not ready
+for production use: they might be very slow.
+
+Additionally, if you have a new enough toolchain, using a deprecated
+function from @code{libguile} will cause a link-time warning.
+
+The primary source for information about just what things are deprecated
+in a given release is the file @file{NEWS}.  That file also documents
+what you should use instead of the obsoleted things.
+
+The file @file{README} contains instructions on how to control the
+inclusion or removal of the deprecated features from the public API of
+Guile, and how to control the deprecation warning messages.
+
+The idea behind those mechanisms is that normally all deprecated are
+available, but you get feedback when compiling and running code that
+uses them, so that you can migrate to the newer APIs at your leisure.

doc/ref/api-discdepr.texi

@@ -1,38 +0,0 @@
-@c -*-texinfo-*-
-@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
-@c   Free Software Foundation, Inc.
-@c See the file guile.texi for copying conditions.
-
-@node Discouraged and Deprecated
-@section Discouraged and Deprecated
-
-From time to time functions and other features of Guile become
-obsolete.  Guile has some mechanisms in place that can help you cope
-with this.
-
-Guile has two levels of obsoleteness: things can be @emph{deprecated},
-meaning that their use is considered harmful and should be avoided,
-even in old code; or they can be merely @emph{discouraged}, meaning
-that they are fine in and of themselves, but that there are better
-alternatives that should be used in new code.
-
-When you use a feature that is deprecated, you will likely get a
-warning message at run-time.  Also, deprecated features are not ready
-for production use: they might be very slow.  When something is merely
-discouraged, it performs normally and you wont get any messages at
-run-time.
-
-The primary source for information about just what things are
-discouraged or deprecated in a given release is the file
-@file{NEWS}.  That file also documents what you should use instead
-of the obsoleted things.
-
-The file @file{README} contains instructions on how to control the
-inclusion or removal of the deprecated and/or discouraged features
-from the public API of Guile, and how to control the warning messages
-for deprecated features.
-
-The idea behind those mechanisms is that normally all deprecated and
-discouraged features are available, but that you can omit them on
-purpose to check whether your code still relies on them.

doc/ref/guile.texi

@@ -288,7 +288,7 @@ available through both Scheme and C interfaces.
 
 @menu
 * API Overview::                Overview of the Guile API.
-* Discouraged and Deprecated::  Obsolete back-compatible APIs.
+* Deprecation::                 Obsolete back-compatible APIs.
 * The SCM Type::                The fundamental data type for C code.
 * Initialization::              Initializing Guile.
 * Snarfing Macros::             Macros for snarfing initialization actions.
@@ -316,7 +316,7 @@ available through both Scheme and C interfaces.
 @end menu
 
 @include api-overview.texi
-@include api-discdepr.texi
+@include api-deprecated.texi
 @include api-scm.texi
 @include api-init.texi
 @include api-snarf.texi