summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-08-08 14:26:26 +0200
committerAndy Wingo <wingo@pobox.com>2010-08-08 14:26:26 +0200
commit1435c7dcf8a520daba1d221d4da7ff81119e649c (patch)
treef55096dfc9cfd7fc5975975e8e35c5fe24e566c5
parent8a4ed2dd34c86eb451c5555a85f64f3fbdf9cef6 (diff)
downloadguile-1435c7dcf8a520daba1d221d4da7ff81119e649c.tar.gz
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.
-rw-r--r--README17
-rw-r--r--configure.ac1
-rw-r--r--doc/ref/Makefile.am2
-rw-r--r--doc/ref/api-deprecated.texi31
-rw-r--r--doc/ref/api-discdepr.texi38
-rw-r--r--doc/ref/guile.texi4
6 files changed, 37 insertions, 56 deletions
diff --git a/README b/README
index 90914e1c2..f216d7d4a 100644
--- a/README
+++ b/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
-
- 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.
diff --git a/configure.ac b/configure.ac
index aac492e37..f3afec341 100644
--- a/configure.ac
+++ b/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])
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index f415eeb88..beeba0fdd 100644
--- a/doc/ref/Makefile.am
+++ b/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 \
diff --git a/doc/ref/api-deprecated.texi b/doc/ref/api-deprecated.texi
new file mode 100644
index 000000000..ea18e4a6e
--- /dev/null
+++ b/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.
diff --git a/doc/ref/api-discdepr.texi b/doc/ref/api-discdepr.texi
deleted file mode 100644
index ae6a6853f..000000000
--- a/doc/ref/api-discdepr.texi
+++ /dev/null
@@ -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.
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 35361046a..c47dfc5c2 100644
--- a/doc/ref/guile.texi
+++ b/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