summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ref/api-deprecated.texi0
-rw-r--r--doc/ref/guile.texi4
-rw-r--r--doc/ref/intro.texi30
3 files changed, 31 insertions, 3 deletions
diff --git a/doc/ref/api-deprecated.texi b/doc/ref/api-deprecated.texi
deleted file mode 100644
index e69de29bb..000000000
--- a/doc/ref/api-deprecated.texi
+++ /dev/null
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 134ba7c29..16ba3d880 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -137,7 +137,7 @@ x
@comment The title is printed in a large font.
@title Guile Reference Manual
@subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
-@c @subtitle $Id: guile.texi,v 1.35 2004-08-02 12:29:00 mvo Exp $
+@c @subtitle $Id: guile.texi,v 1.36 2004-08-02 15:15:31 mvo Exp $
@c See preface.texi for the list of authors
@author The Guile Developers
@@ -302,7 +302,6 @@ available through both Scheme and C interfaces.
* Options and Config:: Configuration, features and runtime options.
* Translation:: Support for translating other languages.
* Debugging:: Internal debugging interface.
-* Deprecated:: Features that are planned to disappear.
* GH:: The deprecated GH interface.
@end menu
@@ -326,7 +325,6 @@ available through both Scheme and C interfaces.
@include api-options.texi
@include api-translation.texi
@include api-debug.texi
-@include api-deprecated.texi
@include gh.texi
@node Guile Modules
diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index e09a797c5..f002547c1 100644
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -11,6 +11,7 @@
* What is Guile?::
* Obtaining and Installing Guile::
* Whirlwind Tour::
+* Discouraged and Deprecated::
* Reporting Bugs::
@end menu
@@ -378,6 +379,35 @@ There is also a way to manipulate the module system from C but only
Scheme files can be autoloaded. Thus, we recommend that you define
your modules in Scheme.
+@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 the how to control the warning
+messages for deprecated features.
+
@node Reporting Bugs
@section Reporting Bugs