X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/dd13bcf6ca346d7b80b772d1665bf92814f464a9..0e18163366c2f2a0caecde18241dbd7987b4db7c:/doc/ref/preface.texi diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi dissimilarity index 95% index 062797b58..3545836c3 100644 --- a/doc/ref/preface.texi +++ b/doc/ref/preface.texi @@ -1,157 +1,114 @@ -@iftex -@page -@unnumbered Preface - -This reference manual documents Guile, GNU's Ubiquitous Intelligent -Language for Extensions. It describes how to use Guile in many useful -and interesting ways. - -This is edition @value{MANUAL-EDITION} of the reference manual, and -corresponds to Guile version @value{VERSION}. -@end iftex - - -@iftex -@section The Guile License -@end iftex - -@ifnottex -@node Guile License -@chapter The Guile License -@end ifnottex - -The license of Guile is the GNU Lesser General Public License. - -@iftex -@section Layout of this Manual -@end iftex - -@ifnottex -@node Manual Layout -@chapter Layout of this Manual -@end ifnottex - -The manual is divided into five parts. - -@strong{Part I: Introduction to Guile} 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, and how to write modules of interpreted and -compiled code for use with Guile. Everything introduced here is -documented again and in full by the later parts of the manual. This -part also explains how to obtain and install new versions of Guile, and -how to report bugs effectively. - -@strong{Part II: Writing and Running Guile Scheme} and @strong{Part III: -Programming with Guile} document all aspects of practical programming -using Guile. This covers both the Scheme level --- where we provide an -introduction to the key ideas of the Scheme language --- and use of -Guile's @code{scm} interface to write new primitives and objects in C, -and to incorporate Guile into a C application. It also covers the use -of Guile as a POSIX compliant script interpreter, and how to use the -Guile debugger. - -@c @strong{Part V: Extending Applications Using Guile} explains the options -@c available for using Guile as a application extension language. At the -@c simpler end of the scale, an application might use Guile to define some -@c application-specific primitives in C and then load an application Scheme -@c file. In this case most of the application code is written on the -@c Scheme level, and uses the application-specific primitives as an -@c extension to standard Scheme. At the other end of the scale, an -@c application might be predominantly written in C --- with its main -@c control loop implemented in C --- but make occasional forays into Scheme -@c to, say, read configuration data or run user-defined customization code. -@c This part of the manual covers the complete range of application -@c extension options. - -@strong{Part IV: Guile API Reference} documents Guile's core API. Most -of the variables and procedures in Guile's core programming interface -are available in both Scheme and C, and are related systematically such -that the C interface can be inferred from the Scheme interface and vice -versa. Therefore this part of the manual documents the Guile API in -functionality-based groups with the Scheme and C interfaces presented -side by side. Where the Scheme and C interfaces for a particular -functional area do differ --- which is sometimes inevitable, given the -differences in the structure of the two languages --- this is pointed -out and explained. In all cases the overriding principle is that all -the reference documentation for a given functional area is grouped -together. - -@c the core Scheme language and features that Guile implements. Although -@c the basis for this is the Scheme language described in R5RS, this part -@c of the manual does not assume any prior familiarity with R5RS in -@c particular, or with Scheme in general. Basic Scheme concepts, standard -@c aspects of the Scheme language and Guile extensions on top of R5RS are -@c all documented from scratch, and organized by functionality rather than -@c by the defining standards. - -@strong{Part V: Guile Modules} describes some important modules, -distributed as part of the Guile distribution, that extend the -functionality provided by the Guile Scheme core. Two important examples -are: - -@itemize @bullet -@item -the POSIX module, which provides Scheme level procedures for system and -network programming that conform to the POSIX standard - -@item -the SLIB module, which makes Aubrey Jaffer's portable Scheme library -available for use in Guile. -@end itemize - - -@iftex -@section Manual Conventions -@end iftex - -@ifnottex -@node Manual Conventions -@chapter Conventions used in this Manual -@end ifnottex - -We use some conventions in this manual. - -@itemize @bullet - -@item -For some procedures, notably type predicates, we use @dfn{iff} to -mean `if and only if'. The construct is usually something like: -`Return @var{val} iff @var{condition}', where @var{val} is usually -`@code{#t}' or `non-@code{#f}'. This typically means that @var{val} -is returned if @var{condition} holds, and that @samp{#f} is returned -otherwise. -@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 @code{@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 @code{@print{}}. - -@lisp -(begin (display 1) (newline) 'hooray) -@print{} 1 -@result{} -hooray -@end lisp - -@c Add other conventions here. - -@end itemize - - -@c Local Variables: -@c TeX-master: "guile.texi" -@c End: +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010, 2011 +@c Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + +@node Preface +@unnumbered Preface + +This manual describes how to use Guile, GNU's Ubiquitous Intelligent +Language for Extensions. It relates particularly to Guile version +@value{VERSION}. + +@menu +* Contributors:: +* Guile License:: +@end menu + +@node Contributors +@unnumberedsec Contributors to this Manual + +Like Guile itself, the Guile reference manual is a living entity, cared +for by many people over a long period of time. As such, it is hard to +identify individuals of whom to say ``yes, this person, she wrote the +manual.'' + +Still, among the many contributions, some caretakers stand out. First +among them is Neil Jerram, who has been working on this document for ten +years now. Neil's attention both to detail and to the big picture have +made a real difference in the understanding of a generation of Guile +hackers. + +Next we should note Marius Vollmer's effect on this document. Marius +maintained Guile during a period in which Guile's API was +clarified---put to the fire, so to speak---and he had the good sense to +effect the same change on the manual. + +Martin Grabmueller made substantial contributions throughout the manual +in preparation for the Guile 1.6 release, including filling out a lot of +the documentation of Scheme data types, control mechanisms and +procedures. In addition, he wrote the documentation for Guile's SRFI +modules and modules associated with the Guile REPL. + +Ludovic Court@`es and Andy Wingo, the Guile maintainers at the time of +this writing (late 2010), have also made their dent in the manual, +writing documentation for new modules and subsystems in Guile 2.0. They +are also responsible for ensuring that the existing text retains its +relevance as Guile evolves. @xref{Reporting Bugs}, for more information +on reporting problems in this manual. + +The content for the first versions of this manual incorporated and was +inspired by documents from Aubrey Jaffer, author of the SCM system on +which Guile was based, and from Tom Lord, Guile's first maintainer. +Although most of this text has been rewritten, all of it was important, +and some of the structure remains. + +The manual for the first versions of Guile were largely written, edited, +and compiled by Mark Galassi and Jim Blandy. In particular, Jim wrote +the original tutorial on Guile's data representation and the C API for +accessing Guile objects. + +Significant portions were also contributed by Thien-Thi Nguyen, Kevin +Ryde, Mikael Djurfeldt, Christian Lynbech, Julian Graham, Gary Houston, +Tim Pierce, and a few dozen more. You, reader, are most welcome to join +their esteemed ranks. Visit Guile's web site at +@uref{http://www.gnu.org/software/guile/} to find out how to get +involved. + + +@node Guile License +@unnumberedsec The Guile License +@cindex copying +@cindex GPL +@cindex LGPL +@cindex license + +Guile is Free Software. Guile is copyrighted, not public domain, and +there are restrictions on its distribution or redistribution, but +these restrictions are designed to permit everything a cooperating +person would want to do. + +@itemize @bullet +@item +The Guile library (libguile) and supporting files are published under +the terms of the GNU Lesser General Public License version 3 or later. +See the files @file{COPYING.LESSER} and @file{COPYING}. + +@item +The Guile readline module is published under the terms of the GNU +General Public License version 3 or later. See the file @file{COPYING}. + +@item +The manual you're now reading is published under the terms of the GNU +Free Documentation License (@pxref{GNU Free Documentation License}). +@end itemize + +C code linking to the Guile library is subject to terms of that +library. Basically such code may be published on any terms, provided +users can re-link against a new or modified version of Guile. + +C code linking to the Guile readline module is subject to the terms of +that module. Basically such code must be published on Free terms. + +Scheme level code written to be run by Guile (but not derived from +Guile itself) is not restricted in any way, and may be published on any +terms. We encourage authors to publish on Free terms. + +You must be aware there is no warranty whatsoever for Guile. This is +described in full in the licenses. + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: