Move "Discouraged and Deprecated" from Introduction to API chapter

* doc/ref/intro.texi (Discouraged and Deprecated): Move from here...

* doc/ref/api-discdepr.texi: ...to new file here.

* doc/ref/guile.texi: Include api-discdepr.texi, and include
 `Discouraged and Deprecated' in API chapter menu.

* doc/ref/Makefile.am (guile_TEXINFOS): Add api-discdepr.texi.

diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index d58b370..8039a4e 100644 (file)
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -56,6 +56,7 @@ guile_TEXINFOS = preface.texi                 \
                 tcltk.texi                     \
                 scheme-scripts.texi            \
                 api-overview.texi              \
+                api-discdepr.texi              \
                 scheme-debugging.texi          \
                 scheme-using.texi              \
                 indices.texi                   \

diff --git a/doc/ref/api-discdepr.texi b/doc/ref/api-discdepr.texi
new file mode 100644 (file)
index 0000000..ae6a685
--- /dev/null
+++ b/doc/ref/api-discdepr.texi
@@ -0,0 +1,38 @@
+@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 332be36..de16f2f 100644 (file)
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -291,6 +291,7 @@ available through both Scheme and C interfaces.
 
 @menu
 * API Overview::                Overview of the Guile API.
+* Discouraged and Deprecated::  Obsolete back-compatible APIs.
 * The SCM Type::                The fundamental data type for C code.
 * Initialization::              Initializing Guile.
 * Snarfing Macros::             Macros for snarfing initialization actions.
@@ -314,6 +315,7 @@ available through both Scheme and C interfaces.
 @end menu
 
 @include api-overview.texi
+@include api-discdepr.texi
 @include api-scm.texi
 @include api-init.texi
 @include api-snarf.texi

diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi
index 5bf11df..25dbaea 100644 (file)
--- a/doc/ref/intro.texi
+++ b/doc/ref/intro.texi
@@ -11,7 +11,6 @@
 * What is Guile?::              
 * Obtaining and Installing Guile::  
 * Whirlwind Tour::              
-* Discouraged and Deprecated::
 * Manual Conventions::          
 * Reporting Bugs::              
 @end menu
@@ -385,39 +384,6 @@ 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 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.
-
 @node Manual Conventions
 @section Conventions used in this Manual