From 1435c7dcf8a520daba1d221d4da7ff81119e649c Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Sun, 8 Aug 2010 14:26:26 +0200 Subject: [PATCH 1/1] 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. --- README | 17 +++-------------- configure.ac | 1 - doc/ref/Makefile.am | 2 +- doc/ref/api-deprecated.texi | 31 ++++++++++++++++++++++++++++++ doc/ref/api-discdepr.texi | 38 ------------------------------------- doc/ref/guile.texi | 4 ++-- 6 files changed, 37 insertions(+), 56 deletions(-) create mode 100644 doc/ref/api-deprecated.texi delete mode 100644 doc/ref/api-discdepr.texi 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 -- 2.20.1