From 064f84ae563e34f480b22d8334c7f8e1d322d255 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 00:06:42 +0000 Subject: [PATCH 01/13] Streamline the manual's Preface material (The principle here is that Preface should only contain meta-information about the manual, such as how to use it and who wrote it; plus any political points that we want to draw attention to.) * doc/ref/preface.texi (Preface): Make unnumbered, for consistency with other GNU manuals (e.g. Emacs, GSL). Merge layout text into top level. Simplify first sentence. Move section on conventions away... * doc/ref/intro.texi (Introduction to Guile): ...to here. --- doc/ref/intro.texi | 48 ++++++++++++++++++++++++++++ doc/ref/preface.texi | 76 ++++++-------------------------------------- 2 files changed, 58 insertions(+), 66 deletions(-) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 55cb4a360..5bf11df3d 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -12,6 +12,7 @@ * Obtaining and Installing Guile:: * Whirlwind Tour:: * Discouraged and Deprecated:: +* Manual Conventions:: * Reporting Bugs:: @end menu @@ -417,6 +418,53 @@ 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 + +We use some conventions in this manual. + +@itemize @bullet + +@item +For some procedures, notably type predicates, we use ``iff'' to mean +``if and only if''. The construct is usually something like: `Return +@var{val} iff @var{condition}', where @var{val} is usually +``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that +@var{val} is returned if @var{condition} holds, and that @samp{#f} is +returned otherwise. To clarify: @var{val} will @strong{only} be +returned when @var{condition} is true. +@cindex iff + +@item +In examples and procedure descriptions and all other places where the +evaluation of Scheme expression is shown, we use some notation for +denoting the output and evaluation results of expressions. + +The symbol @samp{@result{}} is used to tell which value is returned by +an evaluation: + +@lisp +(+ 1 2) +@result{} 3 +@end lisp + +Some procedures produce some output besides returning a value. This +is denoted by the symbol @samp{@print{}}. + +@lisp +(begin (display 1) (newline) 'hooray) +@print{} 1 +@result{} hooray +@end lisp + +As you can see, this code prints @samp{1} (denoted by +@samp{@print{}}), and returns @code{hooray} (denoted by +@samp{@result{}}). Do not confuse the two. + +@c Add other conventions here. + +@end itemize + @node Reporting Bugs @section Reporting Bugs diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi index 8552d388b..d7c694a7f 100644 --- a/doc/ref/preface.texi +++ b/doc/ref/preface.texi @@ -5,24 +5,11 @@ @c See the file guile.texi for copying conditions. @node Preface -@chapter Preface +@unnumbered Preface -This manual documents version @value{VERSION} of Guile, GNU's -Ubiquitous Intelligent Language for Extensions. It describes how to -use Guile in many useful and interesting ways. - -@menu -* Manual Layout:: -* Manual Conventions:: -* Contributors:: -* Guile License:: -@end menu - - -@node Manual Layout -@section Layout of this Manual - -The manual is divided into the following chapters. +This manual describes how to use Guile, GNU's Ubiquitous Intelligent +Language for Extensions. It relates particularly to Guile version +@value{VERSION}. The manual is divided into the following chapters. @table @strong @item Chapter 1: Introduction to Guile @@ -64,56 +51,13 @@ classes, multiple inheritance and generic functions. @end table - -@node Manual Conventions -@section Conventions used in this Manual - -We use some conventions in this manual. - -@itemize @bullet - -@item -For some procedures, notably type predicates, we use ``iff'' to mean -``if and only if''. The construct is usually something like: `Return -@var{val} iff @var{condition}', where @var{val} is usually -``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that -@var{val} is returned if @var{condition} holds, and that @samp{#f} is -returned otherwise. To clarify: @var{val} will @strong{only} be -returned when @var{condition} is true. -@cindex iff - -@item -In examples and procedure descriptions and all other places where the -evaluation of Scheme expression is shown, we use some notation for -denoting the output and evaluation results of expressions. - -The symbol @samp{@result{}} is used to tell which value is returned by -an evaluation: - -@lisp -(+ 1 2) -@result{} 3 -@end lisp - -Some procedures produce some output besides returning a value. This -is denoted by the symbol @samp{@print{}}. - -@lisp -(begin (display 1) (newline) 'hooray) -@print{} 1 -@result{} hooray -@end lisp - -As you can see, this code prints @samp{1} (denoted by -@samp{@print{}}), and returns @code{hooray} (denoted by -@samp{@result{}}). Do not confuse the two. - -@c Add other conventions here. - -@end itemize +@menu +* Contributors:: +* Guile License:: +@end menu @node Contributors -@section Contributors to this Manual +@unnumberedsec Contributors to this Manual The Guile reference and tutorial manuals were written and edited largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the @@ -149,7 +93,7 @@ The chapter on GOOPS was written by Christian Lynbech, Mikael Djurfeldt and Neil Jerram. @node Guile License -@section The Guile License +@unnumberedsec The Guile License @cindex copying @cindex GPL @cindex LGPL From 0fc7099144fd3560e8c8ebdf38336bb5a533338c Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 00:35:35 +0000 Subject: [PATCH 02/13] Remove obsolete material about GH * doc/ref/extend.texi: Delete. --- doc/ref/extend.texi | 50 --------------------------------------------- 1 file changed, 50 deletions(-) delete mode 100644 doc/ref/extend.texi diff --git a/doc/ref/extend.texi b/doc/ref/extend.texi deleted file mode 100644 index 8e25ded2e..000000000 --- a/doc/ref/extend.texi +++ /dev/null @@ -1,50 +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. - -@page -@node Libguile Intro -@chapter Using Guile as an Extension Language - -The chapters in this part of the manual explain how to use Guile as a -powerful application extension language. - -An important change for the 1.6.x series of Guile releases is that the -GH interface is now deprecated. For the reasoning behind this decision, -see @xref{GH deprecation}. The GH interface will continue to be -supported for the 1.6.x and 1.8.x release series, but will be dropped -thereafter, so developers are encouraged to switch progressively to the -scm interface. The last chapter in this part of the manual (@pxref{GH}) -documents both how to use GH and how to switch from GH to scm. - -The Guile developers believe that clarification of the GH vs. scm -debate, and the consequent deprecation of the GH interface, are in the -long term interests of the project. However it does create an -unfortunate situation for developers who want to start a project using -Guile and so read the manual to find out how to proceed. They will -discover that the GH interface, although quite well documented, is -deprecated, but that there is almost no adequate documentation for its -theoretical replacement, the scm interface. Moreover, the scm interface -still has the odd few rough edges which need smoothing down. - -Therefore, although deprecated, it is quite OK to continue to use the GH -interface if you feel uncomfortable with the `scm_' interface as it -stands today. By the time that support for GH is dropped, we plan to -have thoroughly documented the `scm_' interface, and to have enhanced it -such that conversion from GH to the `scm_' interface will be very -straightforward, and probably mostly automated. - -As far as documentation of the scm interface is concerned, the current -position is that it is a bit confused, but that the situation should -improve rapidly once the 1.6.0 release is out. The plan is to refocus -the bulk of Part II, currently ``Guile Scheme'', as the ``Guile API -Reference'' so that it covers both Scheme and C interfaces. (This makes -sense because almost all of Guile's primitive procedures on the Scheme -level --- e.g. @code{memq} --- are also available as C level primitives -in the scm interface --- e.g. @code{scm_memq}.) There will then remain -a certain amount of Scheme-specific (such as the ``Basic Ideas'' -chapter) and C-specific documentation (such as SMOB usage and -interaction with the garbage collector) to collect into corresponding -chapters. From 2a7758fe2365e5ccf92b479a2c9961b2cfa5d373 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 00:57:59 +0000 Subject: [PATCH 03/13] Remove page breaks except before new chapters and indices * doc/ref/api-binding.texi, doc/ref/api-compound.texi, doc/ref/api-control.texi, doc/ref/api-data.texi, doc/ref/api-debug.texi, doc/ref/api-evaluation.texi, doc/ref/api-i18n.texi, doc/ref/api-io.texi, doc/ref/api-memory.texi, doc/ref/api-modules.texi, doc/ref/api-options.texi, doc/ref/api-overview.texi, doc/ref/api-procedures.texi, doc/ref/api-scheduling.texi, doc/ref/api-smobs.texi, doc/ref/api-translation.texi, doc/ref/api-utility.texi, doc/ref/expect.texi, doc/ref/libguile-concepts.texi, doc/ref/libguile-program.texi, doc/ref/misc-modules.texi, doc/ref/repl-modules.texi, doc/ref/scheme-debugging.texi, doc/ref/scheme-reading.texi, doc/ref/scheme-scripts.texi, doc/ref/script-getopt.texi, doc/ref/scsh.texi, doc/ref/srfi-modules.texi: Remove @page before @section. --- doc/ref/api-binding.texi | 1 - doc/ref/api-compound.texi | 1 - doc/ref/api-control.texi | 1 - doc/ref/api-data.texi | 1 - doc/ref/api-debug.texi | 1 - doc/ref/api-evaluation.texi | 1 - doc/ref/api-i18n.texi | 1 - doc/ref/api-io.texi | 1 - doc/ref/api-memory.texi | 2 -- doc/ref/api-modules.texi | 1 - doc/ref/api-options.texi | 1 - doc/ref/api-overview.texi | 1 - doc/ref/api-procedures.texi | 1 - doc/ref/api-scheduling.texi | 1 - doc/ref/api-smobs.texi | 1 - doc/ref/api-translation.texi | 1 - doc/ref/api-utility.texi | 1 - doc/ref/expect.texi | 1 - doc/ref/libguile-concepts.texi | 1 - doc/ref/libguile-program.texi | 1 - doc/ref/misc-modules.texi | 2 -- doc/ref/repl-modules.texi | 2 -- doc/ref/scheme-debugging.texi | 1 - doc/ref/scheme-reading.texi | 1 - doc/ref/scheme-scripts.texi | 1 - doc/ref/script-getopt.texi | 1 - doc/ref/scsh.texi | 1 - doc/ref/srfi-modules.texi | 1 - 28 files changed, 31 deletions(-) diff --git a/doc/ref/api-binding.texi b/doc/ref/api-binding.texi index e53c48040..c5d5659f4 100644 --- a/doc/ref/api-binding.texi +++ b/doc/ref/api-binding.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Binding Constructs @section Definitions and Variable Bindings diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index 5c1bd888b..770918454 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Compound Data Types @section Compound Data Types diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index b220355ce..a8296c9c7 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Control Mechanisms @section Controlling the Flow of Program Execution diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 81f44de39..c6022e918 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Simple Data Types @section Simple Generic Data Types diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index c29bfdf12..916453a91 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Debugging @section Debugging Infrastructure diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index fda029127..457015e0d 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Read/Load/Eval/Compile @section Reading and Evaluating Scheme Code diff --git a/doc/ref/api-i18n.texi b/doc/ref/api-i18n.texi index ee76544eb..fba8f32cf 100644 --- a/doc/ref/api-i18n.texi +++ b/doc/ref/api-i18n.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Internationalization @section Support for Internationalization diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index eb5338c0d..a483f1904 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Input and Output @section Input and Output diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index 15cef6438..ec58470a5 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Memory Management @section Memory Management and Garbage Collection @@ -479,7 +478,6 @@ to the value, it is eligible to be returned from a guardian. @end deffn -@page @node Objects @section Objects diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index 1c9ab23ab..054f87fb5 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Modules @section Modules @cindex modules diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi index 1b526a873..464c7f0b5 100644 --- a/doc/ref/api-options.texi +++ b/doc/ref/api-options.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Options and Config @section Configuration, Features and Runtime Options diff --git a/doc/ref/api-overview.texi b/doc/ref/api-overview.texi index 48378895e..583d009f5 100644 --- a/doc/ref/api-overview.texi +++ b/doc/ref/api-overview.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node API Overview @section Overview of the Guile API diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi index 0f89612a9..0644556f3 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Procedures and Macros @section Procedures and Macros diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index 8382ba3f1..ce6e9521f 100644 --- a/doc/ref/api-scheduling.texi +++ b/doc/ref/api-scheduling.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Scheduling @section Threads, Mutexes, Asyncs and Dynamic Roots diff --git a/doc/ref/api-smobs.texi b/doc/ref/api-smobs.texi index 82ca4b203..db8161cdd 100644 --- a/doc/ref/api-smobs.texi +++ b/doc/ref/api-smobs.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Smobs @section Smobs diff --git a/doc/ref/api-translation.texi b/doc/ref/api-translation.texi index 8782a6fbd..c46f3409b 100644 --- a/doc/ref/api-translation.texi +++ b/doc/ref/api-translation.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Translation @section Support for Translating Other Languages diff --git a/doc/ref/api-utility.texi b/doc/ref/api-utility.texi index edc002bd9..8fdfb2240 100644 --- a/doc/ref/api-utility.texi +++ b/doc/ref/api-utility.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Utility Functions @section General Utility Functions diff --git a/doc/ref/expect.texi b/doc/ref/expect.texi index 71e9a385b..140fd477e 100644 --- a/doc/ref/expect.texi +++ b/doc/ref/expect.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Expect @section Expect diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi index ffdc5f0ec..f0471c2e9 100644 --- a/doc/ref/libguile-concepts.texi +++ b/doc/ref/libguile-concepts.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node General Libguile Concepts @section General concepts for using libguile diff --git a/doc/ref/libguile-program.texi b/doc/ref/libguile-program.texi index b3102f21f..92901c781 100644 --- a/doc/ref/libguile-program.texi +++ b/doc/ref/libguile-program.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Programming Overview @section An Overview of Guile Programming diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi index 28a636f26..b56bcffca 100644 --- a/doc/ref/misc-modules.texi +++ b/doc/ref/misc-modules.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Pretty Printing @section Pretty Printing @@ -60,7 +59,6 @@ Print within the given @var{columns}. The default is 79. @end deffn -@page @node Formatted Output @section Formatted Output @cindex formatted output diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi index 5f274e253..385ba496d 100644 --- a/doc/ref/repl-modules.texi +++ b/doc/ref/repl-modules.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Readline Support @section Readline Support @@ -255,7 +254,6 @@ possibilities in @var{string-list}. Matching is case-sensitive. @end defun -@page @node Value History @section Value History diff --git a/doc/ref/scheme-debugging.texi b/doc/ref/scheme-debugging.texi index bcd9f2df3..dd49dd3a3 100644 --- a/doc/ref/scheme-debugging.texi +++ b/doc/ref/scheme-debugging.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Tracing @section Tracing diff --git a/doc/ref/scheme-reading.texi b/doc/ref/scheme-reading.texi index 8b0e434db..6ec80a57c 100644 --- a/doc/ref/scheme-reading.texi +++ b/doc/ref/scheme-reading.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Further Reading @section Further Reading diff --git a/doc/ref/scheme-scripts.texi b/doc/ref/scheme-scripts.texi index 5e9f16aaf..f43d360f3 100644 --- a/doc/ref/scheme-scripts.texi +++ b/doc/ref/scheme-scripts.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Guile Scripting @section Guile Scripting diff --git a/doc/ref/script-getopt.texi b/doc/ref/script-getopt.texi index af1eb7d9c..c7bb0d439 100644 --- a/doc/ref/script-getopt.texi +++ b/doc/ref/script-getopt.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Command Line Handling @section Handling Command Line Options and Arguments diff --git a/doc/ref/scsh.texi b/doc/ref/scsh.texi index b1af1a443..073bb7fe0 100644 --- a/doc/ref/scsh.texi +++ b/doc/ref/scsh.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node The Scheme shell (scsh) @section The Scheme shell (scsh) @cindex SCSH diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 043490ddb..8f8889c8a 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -4,7 +4,6 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node SRFI Support @section SRFI Support Modules @cindex SRFI From 029fa8965d31424e474c42352a121e3fca693609 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 01:05:43 +0000 Subject: [PATCH 04/13] 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. --- doc/ref/Makefile.am | 1 + doc/ref/api-discdepr.texi | 38 ++++++++++++++++++++++++++++++++++++++ doc/ref/guile.texi | 2 ++ doc/ref/intro.texi | 34 ---------------------------------- 4 files changed, 41 insertions(+), 34 deletions(-) create mode 100644 doc/ref/api-discdepr.texi diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index d58b3705a..8039a4ed6 100644 --- 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 \ + api-discdepr.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 index 000000000..ae6a6853f --- /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 332be361b..de16f2f5a 100644 --- 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. +* 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. @@ -314,6 +315,7 @@ available through both Scheme and C interfaces. @end menu @include api-overview.texi +@include api-discdepr.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 5bf11df3d..25dbaea7c 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -11,7 +11,6 @@ * What is Guile?:: * Obtaining and Installing Guile:: * Whirlwind Tour:: -* Discouraged and Deprecated:: * 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. -@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 From 65de74947772312ed6f116c2c78092acd9f4204d Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 01:28:27 +0000 Subject: [PATCH 05/13] Move Conventions section to after `Reporting Bugs' (Reporting Bugs fits better immediately after the tour of how to use Guile) * doc/ref/intro.texi: Move `Manual Conventions' to after `Reporting Bugs', and rename to `Typographical Conventions'. --- doc/ref/intro.texi | 96 +++++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 25dbaea7c..7feba6136 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -11,8 +11,8 @@ * What is Guile?:: * Obtaining and Installing Guile:: * Whirlwind Tour:: -* Manual Conventions:: * Reporting Bugs:: +* Typographical Conventions:: @end menu @node What is Guile? @@ -384,53 +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. -@node Manual Conventions -@section Conventions used in this Manual - -We use some conventions in this manual. - -@itemize @bullet - -@item -For some procedures, notably type predicates, we use ``iff'' to mean -``if and only if''. The construct is usually something like: `Return -@var{val} iff @var{condition}', where @var{val} is usually -``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that -@var{val} is returned if @var{condition} holds, and that @samp{#f} is -returned otherwise. To clarify: @var{val} will @strong{only} be -returned when @var{condition} is true. -@cindex iff - -@item -In examples and procedure descriptions and all other places where the -evaluation of Scheme expression is shown, we use some notation for -denoting the output and evaluation results of expressions. - -The symbol @samp{@result{}} is used to tell which value is returned by -an evaluation: - -@lisp -(+ 1 2) -@result{} 3 -@end lisp - -Some procedures produce some output besides returning a value. This -is denoted by the symbol @samp{@print{}}. - -@lisp -(begin (display 1) (newline) 'hooray) -@print{} 1 -@result{} hooray -@end lisp - -As you can see, this code prints @samp{1} (denoted by -@samp{@print{}}), and returns @code{hooray} (denoted by -@samp{@result{}}). Do not confuse the two. - -@c Add other conventions here. - -@end itemize - @node Reporting Bugs @section Reporting Bugs @@ -599,6 +552,53 @@ contents are themselves pointers). @end itemize +@node Typographical Conventions +@section Typographical Conventions + +We use some conventions in this manual. + +@itemize @bullet + +@item +For some procedures, notably type predicates, we use ``iff'' to mean +``if and only if''. The construct is usually something like: `Return +@var{val} iff @var{condition}', where @var{val} is usually +``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that +@var{val} is returned if @var{condition} holds, and that @samp{#f} is +returned otherwise. To clarify: @var{val} will @strong{only} be +returned when @var{condition} is true. +@cindex iff + +@item +In examples and procedure descriptions and all other places where the +evaluation of Scheme expression is shown, we use some notation for +denoting the output and evaluation results of expressions. + +The symbol @samp{@result{}} is used to tell which value is returned by +an evaluation: + +@lisp +(+ 1 2) +@result{} 3 +@end lisp + +Some procedures produce some output besides returning a value. This +is denoted by the symbol @samp{@print{}}. + +@lisp +(begin (display 1) (newline) 'hooray) +@print{} 1 +@result{} hooray +@end lisp + +As you can see, this code prints @samp{1} (denoted by +@samp{@print{}}), and returns @code{hooray} (denoted by +@samp{@result{}}). Do not confuse the two. + +@c Add other conventions here. + +@end itemize + @c Local Variables: @c TeX-master: "guile.texi" From 3d9af0c96644022bfa0a6ca2a10c50e0c70c141c Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 01:31:03 +0000 Subject: [PATCH 06/13] New introductory text about Guile * doc/ref/guile.texi (Top): Rename `Introduction to Guile' as just `Introduction'. * doc/ref/intro.texi: Add new introductory text. [Not yet complete] * doc/ref/preface.texi (Preface): Update for chapter renaming. --- doc/ref/guile.texi | 2 +- doc/ref/intro.texi | 32 ++++++++++++++++++++++++++++++-- doc/ref/preface.texi | 2 +- 3 files changed, 32 insertions(+), 4 deletions(-) diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index de16f2f5a..0438e2468 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -167,7 +167,7 @@ x @menu * Preface:: -* Introduction to Guile:: +* Introduction:: * Programming in Scheme:: * Programming in C:: diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 7feba6136..4fabb4880 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -4,8 +4,36 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@node Introduction to Guile -@chapter Introduction to Guile +@node Introduction +@chapter Introduction + +Guile is an implementation of the Scheme programming language. Scheme +(@url{schemers.org}) is an elegant and conceptually simple dialect of +Lisp, originated by Guy Steele and Gerald Sussman, and since evolved +mainly by the series of reports known as RnRS (the Revised^n Reports +on Scheme). + +Unlike -- for example -- Python or Perl, Scheme has no benevolent +dictator. There are many Scheme implementations, with different +characteristics and with communities and academic activities around +them, and the language develops as a result of the interplay between +these. Guile's particular characteristics are that +@itemize +@item +it is easy to combine with other code written in C +@item +it has a historical and continuing connection with the GNU Project +@item +it emphasizes interactive and incremental programming +@item +it actually supports several languages, not just Scheme. +@end itemize +@noindent +The next section explains what we mean by these points. The sections +after that cover how you can obtain and install Guile, a tour of the +ways that you can use it, how to report any problems that you +encounter, and some typographical conventions that we use in this +manual. @menu * What is Guile?:: diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi index d7c694a7f..f2d59cc53 100644 --- a/doc/ref/preface.texi +++ b/doc/ref/preface.texi @@ -12,7 +12,7 @@ Language for Extensions. It relates particularly to Guile version @value{VERSION}. The manual is divided into the following chapters. @table @strong -@item Chapter 1: Introduction to Guile +@item Chapter 1: Introduction This part provides an overview of what Guile is and how you can use it. A whirlwind tour shows how Guile can be used interactively and as a script interpreter, how to link Guile into your own applications, From 95c2df5c60abbb5fcc217bde6efe47bff8e0ac3b Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 23:26:29 +0000 Subject: [PATCH 07/13] Format `Revised^n' more nicely in TeX * doc/ref/intro.texi (Introduction): Format Revised^n differently for TeX. --- doc/ref/intro.texi | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 4fabb4880..fc4e4d6eb 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -10,8 +10,14 @@ Guile is an implementation of the Scheme programming language. Scheme (@url{schemers.org}) is an elegant and conceptually simple dialect of Lisp, originated by Guy Steele and Gerald Sussman, and since evolved -mainly by the series of reports known as RnRS (the Revised^n Reports -on Scheme). +by the series of reports known as RnRS (the +@tex +Revised$^n$ +@end tex +@ifnottex +Revised^n +@end ifnottex +Reports onScheme). Unlike -- for example -- Python or Perl, Scheme has no benevolent dictator. There are many Scheme implementations, with different From ebb6158f2377c16285551e87d453cd5d93c90d46 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 23:32:22 +0000 Subject: [PATCH 08/13] More about Guile's relationship to Scheme standards Also continue adding a bit more structure to the introductory "what is Guile" material. * doc/ref/intro.texi (Introduction): Split `What is Guile?' (which is a bad heading, since we've already answered that...) into `Guile and Scheme' and `Combining with C'. Further splits will follow, to cover the other toplevel bullet points. (Guile and Scheme): Remove `packaged for use in a wide variety of environments', as I don't see what this can mean to the reader at this point. Add text about R6RS and SRFIs. --- doc/ref/intro.texi | 54 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index fc4e4d6eb..50cf1f85c 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -35,39 +35,61 @@ it emphasizes interactive and incremental programming it actually supports several languages, not just Scheme. @end itemize @noindent -The next section explains what we mean by these points. The sections -after that cover how you can obtain and install Guile, a tour of the -ways that you can use it, how to report any problems that you +The next few sections explain what we mean by these points. The +sections after that cover how you can obtain and install Guile, a tour +of the ways that you can use it, how to report any problems that you encounter, and some typographical conventions that we use in this manual. @menu -* What is Guile?:: +* Guile and Scheme:: +* Combining with C:: * Obtaining and Installing Guile:: * Whirlwind Tour:: * Reporting Bugs:: * Typographical Conventions:: @end menu -@node What is Guile? -@section What is Guile? +@node Guile and Scheme +@section Guile and Scheme -Guile is an interpreter for the Scheme programming language, packaged -for use in a wide variety of environments. Guile implements Scheme as -described in the +Guile implements Scheme as described in the @tex Revised$^5$ @end tex @ifnottex Revised^5 @end ifnottex -Report on the Algorithmic Language Scheme (usually known as @acronym{R5RS}), -providing clean and general data and control structures. Guile goes -beyond the rather austere language presented in @acronym{R5RS}, extending it with -a module system, full access to @acronym{POSIX} system calls, networking support, -multiple threads, dynamic linking, a foreign function call interface, -powerful string processing, and many other features needed for -programming in the real world. +Report on the Algorithmic Language Scheme (usually known as +@acronym{R5RS}), providing clean and general data and control +structures. Guile goes beyond the rather austere language presented +in @acronym{R5RS}, extending it with a module system, full access to +@acronym{POSIX} system calls, networking support, multiple threads, +dynamic linking, a foreign function call interface, powerful string +processing, and many other features needed for programming in the real +world. + +The Scheme community has recently agreed and published R6RS, the +latest installment in the RnRS series. R6RS significantly expands the +core Scheme language, and standardises many non-core functions that +implementations -- including Guile -- have previously done in +different ways. Guile has been updated to incorporate some of the +features of R6RS, and to adjust some existing features to conform to +the R6RS specification, but it is by no means a complete R6RS +implementation. + +Between R5RS and R6RS, the SRFI process +(@url{http://srfi.schemers.org/}) standardised interfaces for many +practical needs, such as multithreading programming and +multidimensional arrays. Guile supports many SRFIs, as documented in +detail in @ref{SRFI Support}. + +In summary, so far as relationship to the Scheme standards is +concerned, Guile is an R5RS implementation with many extensions, some +of which conform to SRFIs or to the relevant parts of R6RS. + +@node Combining with C +@section Combining with Other C Code Like a shell, Guile can run interactively, reading expressions from the user, evaluating them, and displaying the results, or as a script From cdda4e0a3d15e19074f288b2443374835c78277d Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 23:37:28 +0000 Subject: [PATCH 09/13] Remove obsolete and empty Tcl/Tk file * doc/ref/Makefile.am (guile_TEXINFOS): Remove tcltk.texi. * doc/ref/tcltk.texi: Deleted. --- doc/ref/Makefile.am | 1 - doc/ref/tcltk.texi | 9 --------- 2 files changed, 10 deletions(-) delete mode 100644 doc/ref/tcltk.texi diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index 8039a4ed6..e201198dd 100644 --- a/doc/ref/Makefile.am +++ b/doc/ref/Makefile.am @@ -53,7 +53,6 @@ guile_TEXINFOS = preface.texi \ posix.texi \ expect.texi \ scsh.texi \ - tcltk.texi \ scheme-scripts.texi \ api-overview.texi \ api-discdepr.texi \ diff --git a/doc/ref/tcltk.texi b/doc/ref/tcltk.texi deleted file mode 100644 index da3091946..000000000 --- a/doc/ref/tcltk.texi +++ /dev/null @@ -1,9 +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. - -@page -@node Tcl/Tk Interface -@chapter Tcl/Tk Interface From 84d86e74531bbfd292696eb578910f6c7be51eda Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sat, 19 Dec 2009 23:49:23 +0000 Subject: [PATCH 10/13] Typo and formatting * doc/ref/intro.texi (Introduction): "onScheme" -> "on Scheme". Add blank lines around @itemize block - looks better in Info. --- doc/ref/intro.texi | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 50cf1f85c..78199a7cd 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -17,13 +17,14 @@ Revised$^n$ @ifnottex Revised^n @end ifnottex -Reports onScheme). +Reports on Scheme). Unlike -- for example -- Python or Perl, Scheme has no benevolent dictator. There are many Scheme implementations, with different characteristics and with communities and academic activities around them, and the language develops as a result of the interplay between these. Guile's particular characteristics are that + @itemize @item it is easy to combine with other code written in C @@ -34,6 +35,7 @@ it emphasizes interactive and incremental programming @item it actually supports several languages, not just Scheme. @end itemize + @noindent The next few sections explain what we mean by these points. The sections after that cover how you can obtain and install Guile, a tour From c6c8e7e06d3a9b04ea5be2f0ac2a1029498e3a06 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Mon, 21 Dec 2009 01:02:56 +0000 Subject: [PATCH 11/13] More intro text on combining with C code * doc/ref/intro.texi (Combining with C): New paragraph. --- doc/ref/intro.texi | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 78199a7cd..4821479fe 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -107,6 +107,18 @@ control structures, and even syntax to Guile, creating a domain-specific language tailored to the task at hand, but based on a robust language design. +This kind of combination is helped by four aspects of Guile's design +and history. First is that Guile has always been targeted as an +extension language. Hence its C API has always been of great +importance, and has been developed accordingly. Second and third are +rather technical points -- that Guile uses conservative garbage +collection, and that it implements the Scheme concept of continuations +by copying and reinstating the C stack -- but whose practical +consequence is that most existing C code can be glued into Guile as +is, without needing modifications to cope with strange Scheme +execution flows. Last is the module system, which helps extensions to +coexist without stepping on each others' toes. + Guile's module system allows one to break up a large program into manageable sections with well-defined interfaces between them. Modules may contain a mixture of interpreted and compiled code; Guile From 3ce5e1304bd77eb167f856a2a163038f01f452c8 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Mon, 21 Dec 2009 01:09:43 +0000 Subject: [PATCH 12/13] Placeholders for expected remaining Intro sections * doc/ref/intro.texi (Introduction): Add menu entries and sections for `Guile and the GNU Project', `Interactive Programming' and `Supporting Multiple Languages'. --- doc/ref/intro.texi | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 4821479fe..c91aacb60 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -46,6 +46,9 @@ manual. @menu * Guile and Scheme:: * Combining with C:: +* Guile and the GNU Project:: +* Interactive Programming:: +* Supporting Multiple Languages:: * Obtaining and Installing Guile:: * Whirlwind Tour:: * Reporting Bugs:: @@ -128,6 +131,15 @@ routines for general distribution; as of this writing, one can find Emacs interfaces, database access routines, compilers, @acronym{GUI} toolkit interfaces, and @acronym{HTTP} client functions, among others. +@node Guile and the GNU Project +@section Guile and the GNU Project + +@node Interactive Programming +@section Interactive Programming + +@node Supporting Multiple Languages +@section Supporting Multiple Languages + In the future, we hope to expand Guile to support other languages like Tcl and Perl by translating them to Scheme code. This means that users can program applications which use Guile in the language of their From 0a864beb3170ab4e293a10f9a4b5c11a1aeaf722 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sun, 27 Dec 2009 13:20:05 +0000 Subject: [PATCH 13/13] Improvements to Introduction chapter * doc/ref/intro.texi (Introduction): Change "some" to "the". (Guile and Scheme): "multithreading" -> "multithreaded". (Combining with C): Mention "libguile" as library name. (Guile and the GNU Project): New text. (Interactive Programming): New text. (Supporting Multiple Languages): New text, reflecting currently supported languages. (Obtaining and Installing Guile): Use @var for version placeholder. Remove mention of separate tutorial. --- doc/ref/intro.texi | 91 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 63 insertions(+), 28 deletions(-) diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 3301ded81..86e52a573 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -40,7 +40,7 @@ it actually supports several languages, not just Scheme. The next few sections explain what we mean by these points. The sections after that cover how you can obtain and install Guile, a tour of the ways that you can use it, how to report any problems that you -encounter, and some typographical conventions that we use in this +encounter, and the typographical conventions that we use in this manual. @menu @@ -83,32 +83,30 @@ features of R6RS, and to adjust some existing features to conform to the R6RS specification, but it is by no means a complete R6RS implementation. -Between R5RS and R6RS, the SRFI process -(@url{http://srfi.schemers.org/}) standardised interfaces for many -practical needs, such as multithreading programming and -multidimensional arrays. Guile supports many SRFIs, as documented in -detail in @ref{SRFI Support}. +Between R5RS and R6RS, the SRFI process (@url{http://srfi.schemers.org/}) +standardised interfaces for many practical needs, such as multithreaded +programming and multidimensional arrays. Guile supports many SRFIs, as +documented in detail in @ref{SRFI Support}. In summary, so far as relationship to the Scheme standards is concerned, Guile is an R5RS implementation with many extensions, some of which conform to SRFIs or to the relevant parts of R6RS. @node Combining with C -@section Combining with Other C Code +@section Combining with C Code -Like a shell, Guile can run interactively, reading expressions from the -user, evaluating them, and displaying the results, or as a script -interpreter, reading and executing Scheme code from a file. However, -Guile is also packaged as an object library, allowing other applications -to easily incorporate a complete Scheme interpreter. An application can -then use Guile as an extension language, a clean and powerful configuration -language, or as multi-purpose ``glue'', connecting primitives provided -by the application. It is easy to call Scheme code from C code and vice -versa, giving the application designer full control of how and when to -invoke the interpreter. Applications can add new functions, data types, -control structures, and even syntax to Guile, creating a domain-specific -language tailored to the task at hand, but based on a robust language -design. +Like a shell, Guile can run interactively --- reading expressions from the user, +evaluating them, and displaying the results --- or as a script interpreter, +reading and executing Scheme code from a file. Guile also provides an object +library, @dfn{libguile}, that allows other applications to easily incorporate a +complete Scheme interpreter. An application can then use Guile as an extension +language, a clean and powerful configuration language, or as multi-purpose +``glue'', connecting primitives provided by the application. It is easy to call +Scheme code from C code and vice versa, giving the application designer full +control of how and when to invoke the interpreter. Applications can add new +functions, data types, control structures, and even syntax to Guile, creating a +domain-specific language tailored to the task at hand, but based on a robust +language design. This kind of combination is helped by four aspects of Guile's design and history. First is that Guile has always been targeted as an @@ -134,16 +132,54 @@ toolkit interfaces, and @acronym{HTTP} client functions, among others. @node Guile and the GNU Project @section Guile and the GNU Project +Guile was conceived by the GNU Project following the fantastic success +of Emacs Lisp as an extension language within Emacs. Just as Emacs +Lisp allowed complete and unanticipated applications to be written +within the Emacs environment, the idea was that Guile should do the +same for other GNU Project applications. This remains true today. + +Guile is now used by GNU project applications such as AutoGen, Lilypond, Denemo, +Mailutils, TeXmacs and Gnucash, and we hope that there will be many more in +future. + @node Interactive Programming @section Interactive Programming +Non-free software has no interest in its users being able to see how it works. +They are supposed to just accept it, or to report problems and hope that the +source code owners will choose to work on them. + +Free software aims to work reliably just as much as non-free software does, but +it should also empower its users by making its workings available. This is +useful for many reasons, including education, auditing and enhancements, as well +as for debugging problems. + +The ideal free software system achieves this by making it easy for interested +users to see the source code for a feature that they are using, and to follow +through that source code step-by-step, as it runs. In Emacs, good examples of +this are the source code hyperlinks in the help system, and @code{edebug}. +Then, for bonus points and maximising the ability for the user to experiment +quickly with code changes, the system should allow parts of the source code to +be modified and reloaded into the running program, to take immediate effect. + +Guile allows this kind of interactive programming, and this distinguishes it +from many Scheme implementations that instead prioritise running a fixed Scheme +program as fast as possible --- because there are tradeoffs between performance +and the ability to modify parts of an already running program. There are faster +Schemes than Guile, but Guile is a GNU project and so prioritises the GNU vision +of programming freedom and experimentation. + @node Supporting Multiple Languages @section Supporting Multiple Languages -In the future, we hope to expand Guile to support other languages like -Tcl and Perl by translating them to Scheme code. This means that users -can program applications which use Guile in the language of their -choice, rather than having the tastes of the application's author +Since the 2.0 release, Guile's architecture supports compiling any language to +its core virtual machine bytecode, and Scheme is just one of the supported +languages. Other supported languages are Emacs Lisp, ECMAScript (commonly known +as Javascript) and Brainfuck, and work is under discussion for Lua, Ruby and +Python. + +This means that users can program applications which use Guile in the language +of their choice, rather than having the tastes of the application's author imposed on them. @node Obtaining and Installing Guile @@ -151,7 +187,7 @@ imposed on them. Guile can be obtained from the main GNU archive site @url{ftp://ftp.gnu.org} or any of its mirrors. The file will be named -guile-version.tar.gz. The current version is @value{VERSION}, so the +guile-@var{version}.tar.gz. The current version is @value{VERSION}, so the file you should grab is: @url{ftp://ftp.gnu.org/pub/gnu/guile/guile-@value{VERSION}.tar.gz} @@ -176,9 +212,8 @@ make install @end example This will install the Guile executable @file{guile}, the Guile library -@file{libguile} and various associated header files and support -libraries. It will also install the Guile tutorial and reference -manual. +@file{libguile} and various associated header files and support libraries. It +will also install the Guile reference manual. @c [[include instructions for getting R5RS]]