mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 11:50:28 +02:00
Code Activity

Move "Discouraged and Deprecated" from Introduction to API chapter

Browse source 
* 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.
This commit is contained in:
Neil Jerram 2009-12-19 01:05:43 +00:00
parent 2a7758fe23
commit 029fa8965d
4 changed files with 41 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

1
doc/ref/Makefile.am
View file

@ -56,6 +56,7 @@ guile_TEXINFOS = preface.texi \
tcltk.texi \ tcltk.texi \
scheme-scripts.texi \ scheme-scripts.texi \
api-overview.texi \ api-overview.texi \
api-discdepr.texi \
scheme-debugging.texi \ scheme-debugging.texi \
scheme-using.texi \ scheme-using.texi \
indices.texi \ indices.texi \

38
doc/ref/api-discdepr.texi Normal file
View file

@ -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.

2
doc/ref/guile.texi
View file

@ -291,6 +291,7 @@ available through both Scheme and C interfaces.
@menu @menu
* API Overview:: Overview of the Guile API. * API Overview:: Overview of the Guile API.
* Discouraged and Deprecated:: Obsolete back-compatible APIs.
* The SCM Type:: The fundamental data type for C code. * The SCM Type:: The fundamental data type for C code.
* Initialization:: Initializing Guile. * Initialization:: Initializing Guile.
* Snarfing Macros:: Macros for snarfing initialization actions. * Snarfing Macros:: Macros for snarfing initialization actions.
@ -314,6 +315,7 @@ available through both Scheme and C interfaces.
@end menu @end menu
@include api-overview.texi @include api-overview.texi
@include api-discdepr.texi
@include api-scm.texi @include api-scm.texi
@include api-init.texi @include api-init.texi
@include api-snarf.texi @include api-snarf.texi

34
doc/ref/intro.texi
View file

@ -11,7 +11,6 @@
* What is Guile?:: * What is Guile?::
* Obtaining and Installing Guile:: * Obtaining and Installing Guile::
* Whirlwind Tour:: * Whirlwind Tour::
* Discouraged and Deprecated::
* Manual Conventions:: * Manual Conventions::
* Reporting Bugs:: * Reporting Bugs::
@end menu @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 Scheme files can be autoloaded. Thus, we recommend that you define
your modules in Scheme. 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 @node Manual Conventions
@section Conventions used in this Manual @section Conventions used in this Manual