Commit | Line | Data |
---|---|---|
c6ae9c77 MV |
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 | ||
3229f68b MV |
7 | @node Preface |
8 | @chapter Preface | |
a0e07ba4 NJ |
9 | |
10 | This reference manual documents Guile, GNU's Ubiquitous Intelligent | |
11 | Language for Extensions. It describes how to use Guile in many useful | |
12 | and interesting ways. | |
13 | ||
3b48e114 | 14 | This is edition @value{MANUAL-EDITION} of the reference manual, and |
9401323e | 15 | corresponds to Guile version @value{VERSION}. |
a0e07ba4 | 16 | |
3229f68b | 17 | @menu |
3229f68b MV |
18 | * Manual Layout:: |
19 | * Manual Conventions:: | |
916542f1 MV |
20 | * Contributors:: |
21 | * Guile License:: | |
3229f68b | 22 | @end menu |
a0e07ba4 | 23 | |
e9b91f8e | 24 | |
a0e07ba4 | 25 | @node Manual Layout |
3229f68b | 26 | @section Layout of this Manual |
a0e07ba4 | 27 | |
3229f68b | 28 | The manual is divided into five chapters. |
a0e07ba4 | 29 | |
96e05382 | 30 | @table @strong |
3229f68b MV |
31 | @item Chapter 1: Introduction to Guile |
32 | This part provides an overview of what Guile is and how you can use | |
33 | it. A whirlwind tour shows how Guile can be used interactively and as | |
34 | a script interpreter, how to link Guile into your own applications, | |
35 | and how to write modules of interpreted and compiled code for use with | |
96e05382 MV |
36 | Guile. Everything introduced here is documented again and in full by |
37 | the later parts of the manual. This part also explains how to obtain | |
38 | and install new versions of Guile, and how to report bugs effectively. | |
39 | ||
3229f68b MV |
40 | @item Chapter 2: Programming in Scheme |
41 | This part provides an overview over programming in Scheme with Guile. | |
42 | It covers how to invoke the @code{guile} program from the command-line | |
43 | and how to write scripts in Scheme. It also gives an introduction | |
44 | into the basic ideas of Scheme itself and to the various extensions | |
45 | that Guile offers beyond standard Scheme. | |
46 | ||
47 | @item Chapter 3: Programming in C | |
48 | This part provides an overview of how to use Guile in a C program. It | |
49 | discusses the fundamental concepts that you need to understand to | |
50 | access the features of Guile, such as dynamic types and the garbage | |
51 | collector. It explains in a tutorial like manner how to define new | |
52 | data types and functions for the use by Scheme programs. | |
53 | ||
54 | @item Chapter 4: Guile API Reference | |
55 | This part of the manual documents the Guile @acronym{API} in | |
9401323e | 56 | functionality-based groups with the Scheme and C interfaces presented |
3229f68b MV |
57 | side by side. |
58 | ||
59 | @item Chapter 5: Guile Modules | |
96e05382 MV |
60 | Describes some important modules, distributed as part of the Guile |
61 | distribution, that extend the functionality provided by the Guile | |
3229f68b | 62 | Scheme core. |
a0e07ba4 | 63 | |
96e05382 | 64 | @end table |
a0e07ba4 | 65 | |
a0e07ba4 | 66 | |
a0e07ba4 | 67 | @node Manual Conventions |
3229f68b | 68 | @section Conventions used in this Manual |
a0e07ba4 NJ |
69 | |
70 | We use some conventions in this manual. | |
71 | ||
72 | @itemize @bullet | |
73 | ||
74 | @item | |
cef6deaf MV |
75 | For some procedures, notably type predicates, we use @dfn{iff} to mean |
76 | ``if and only if''. The construct is usually something like: `Return | |
77 | @var{val} iff @var{condition}', where @var{val} is usually | |
78 | ``@nicode{#t}'' or ``non-@nicode{#f}''. This typically means that | |
79 | @var{val} is returned if @var{condition} holds, and that @samp{#f} is | |
80 | returned otherwise. To clarify: @var{val} will @strong{only} be | |
81 | returned when @var{condition} is true. | |
a0e07ba4 NJ |
82 | @cindex iff |
83 | ||
84 | @item | |
85 | In examples and procedure descriptions and all other places where the | |
86 | evaluation of Scheme expression is shown, we use some notation for | |
87 | denoting the output and evaluation results of expressions. | |
88 | ||
cef6deaf | 89 | The symbol @samp{@result{}} is used to tell which value is returned by |
a0e07ba4 NJ |
90 | an evaluation: |
91 | ||
92 | @lisp | |
93 | (+ 1 2) | |
cef6deaf | 94 | @result{} 3 |
a0e07ba4 NJ |
95 | @end lisp |
96 | ||
97 | Some procedures produce some output besides returning a value. This | |
cef6deaf | 98 | is denoted by the symbol @samp{@print{}}. |
a0e07ba4 NJ |
99 | |
100 | @lisp | |
101 | (begin (display 1) (newline) 'hooray) | |
102 | @print{} 1 | |
cef6deaf | 103 | @result{} hooray |
a0e07ba4 NJ |
104 | @end lisp |
105 | ||
cef6deaf MV |
106 | As you can see, this code prints @samp{1} (denoted by |
107 | @samp{@print{}}), and returns @code{hooray} (denoted by | |
108 | @samp{@result{}}). Do not confuse the two. | |
109 | ||
a0e07ba4 NJ |
110 | @c Add other conventions here. |
111 | ||
112 | @end itemize | |
113 | ||
916542f1 MV |
114 | @node Contributors |
115 | @section Contributors to this Manual | |
116 | ||
117 | The Guile reference and tutorial manuals were written and edited | |
118 | largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the | |
119 | original tutorial on Guile's data representation and the C API for | |
120 | accessing Guile objects. | |
121 | ||
122 | Significant portions were contributed by Gary Houston (contributions | |
123 | to POSIX system calls and networking, expect, I/O internals and | |
124 | extensions, slib installation, error handling) and Tim Pierce | |
125 | (sections on script interpreter triggers, alists, function tracing). | |
126 | ||
127 | Tom Lord contributed a great deal of material with early Guile | |
128 | snapshots; although most of this text has been rewritten, all of it | |
129 | was important, and some of the structure remains. | |
130 | ||
131 | Aubrey Jaffer wrote the SCM Scheme implementation and manual upon | |
132 | which the Guile program and manual are based. Some portions of the | |
133 | SCM and SLIB manuals have been included here verbatim. | |
134 | ||
135 | Since Guile 1.4, Neil Jerram has been maintaining and improving the | |
136 | reference manual. Among other contributions, he wrote the Basic | |
137 | Ideas chapter, developed the tools for keeping the manual in sync | |
138 | with snarfed libguile docstrings, and reorganized the structure so as | |
139 | to accommodate docstrings for all Guile's primitives. | |
140 | ||
141 | Martin Grabmueller has made substantial contributions throughout the | |
142 | reference manual in preparation for the Guile 1.6 release, including | |
143 | filling out a lot of the documentation of Scheme data types, control | |
144 | mechanisms and procedures. In addition, he wrote the documentation | |
145 | for Guile's SRFI modules and modules associated with the Guile REPL. | |
146 | ||
147 | @node Guile License | |
148 | @section The Guile License | |
d10196fc | 149 | @cindex copying |
ed435f86 KR |
150 | @cindex GPL |
151 | @cindex LGPL | |
d10196fc | 152 | @cindex license |
916542f1 MV |
153 | |
154 | Guile is Free Software. Guile is copyrighted, not public domain, and | |
155 | there are restrictions on its distribution or redistribution, but | |
156 | these restrictions are designed to permit everything a cooperating | |
157 | person would want to do. | |
158 | ||
159 | @itemize @bullet | |
160 | @item | |
161 | The Guile library (libguile) and supporting files are published under | |
162 | the terms of the GNU Lesser General Public License version 2.1. See | |
163 | the file @file{COPYING.LIB}. | |
164 | ||
165 | @item | |
166 | The Guile readline module is published under the terms of the GNU | |
167 | General Public License version 2. See the file @file{COPYING}. | |
168 | ||
169 | @item | |
170 | The manual you're now reading is published under the terms of the GNU | |
171 | Free Documentation License (@pxref{GNU Free Documentation License}). | |
172 | @end itemize | |
173 | ||
174 | C code linking to the Guile library is subject to terms of that | |
175 | library. Basically such code may be published on any terms, provided | |
176 | users can re-link against a new or modified version of Guile. | |
177 | ||
178 | C code linking to the Guile readline module is subject to the terms of | |
179 | that module. Basically such code must be published on Free terms. | |
180 | ||
181 | Scheme level code written to be run by Guile (but not derived from | |
182 | Guile itself) is not resticted in any way, and may be published on any | |
183 | terms. We encourage authors to publish on Free terms. | |
184 | ||
185 | You must be aware there is no warranty whatsoever for Guile. This is | |
186 | described in full in the licenses. | |
187 | ||
a0e07ba4 NJ |
188 | |
189 | @c Local Variables: | |
190 | @c TeX-master: "guile.texi" | |
191 | @c End: |