doc/ref/api-discdepr.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Discouraged and Deprecated
   8 @section Discouraged and Deprecated
   9
  10 From time to time functions and other features of Guile become
  11 obsolete.  Guile has some mechanisms in place that can help you cope
  12 with this.
  13
  14 Guile has two levels of obsoleteness: things can be @emph{deprecated},
  15 meaning that their use is considered harmful and should be avoided,
  16 even in old code; or they can be merely @emph{discouraged}, meaning
  17 that they are fine in and of themselves, but that there are better
  18 alternatives that should be used in new code.
  19
  20 When you use a feature that is deprecated, you will likely get a
  21 warning message at run-time.  Also, deprecated features are not ready
  22 for production use: they might be very slow.  When something is merely
  23 discouraged, it performs normally and you wont get any messages at
  24 run-time.
  25
  26 The primary source for information about just what things are
  27 discouraged or deprecated in a given release is the file
  28 @file{NEWS}.  That file also documents what you should use instead
  29 of the obsoleted things.
  30
  31 The file @file{README} contains instructions on how to control the
  32 inclusion or removal of the deprecated and/or discouraged features
  33 from the public API of Guile, and how to control the warning messages
  34 for deprecated features.
  35
  36 The idea behind those mechanisms is that normally all deprecated and
  37 discouraged features are available, but that you can omit them on
  38 purpose to check whether your code still relies on them.