mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-29 19:30:36 +02:00
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.
This commit is contained in:
Andy Wingo
parent
8a4ed2dd34
commit
1435c7dcf8
6 changed files with 37 additions and 56 deletions
17
README
17
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.
|
||||
|
|
|
|||
|
|
@ -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])
|
||||
|
|
|
|||
|
|
@ -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 \
|
||||
|
|
|
|||
31
doc/ref/api-deprecated.texi
Normal file
31
doc/ref/api-deprecated.texi
Normal file
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue