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              \
                 tcltk.texi                     \
                 scheme-scripts.texi            \
                 api-overview.texi              \

+                api-discdepr.texi              \

                 scheme-debugging.texi          \
                 scheme-using.texi              \
                 indices.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.
 
 @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.
 * 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
 @end menu
 
 @include api-overview.texi

+@include api-discdepr.texi

 @include api-scm.texi
 @include api-init.texi
 @include api-snarf.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::              
 * What is Guile?::              
 * Obtaining and Installing Guile::  
 * Whirlwind Tour::              

-* Discouraged and Deprecated::

 * Manual Conventions::          
 * Reporting Bugs::              
 @end menu
 * 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.
 
 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
 
 @node Manual Conventions
 @section Conventions used in this Manual