* 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.
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.
'warn-deprecated) to enable and disable the detailed messaged at run
time.
---disable-discouraged
-
- In addition to deprecated features, Guile can also contain things
- 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.
+ Additionally, if your toolchain is new enough, you will receive
+ warnings at link time if you have a Guile extension that uses
+ deprecated functions provided by Guile.
--disable-shared --- Do not build shared libraries.
--disable-static --- Do not build static libraries.
# 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])
sxml-match.texi \
scheme-scripts.texi \
api-overview.texi \
- api-discdepr.texi \
+ api-deprecated.texi \
scheme-debugging.texi \
scheme-using.texi \
indices.texi \
--- /dev/null
+@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.
+++ /dev/null
-@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.
@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.
@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
HCoop / bpt / guile.git / commitdiff