1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-12 06:41:13 +02:00

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.
This commit is contained in:
Neil Jerram 2009-12-19 00:06:42 +00:00
parent 3733df073f
commit 064f84ae56
2 changed files with 58 additions and 66 deletions

View file

@ -12,6 +12,7 @@
* Obtaining and Installing Guile:: * Obtaining and Installing Guile::
* Whirlwind Tour:: * Whirlwind Tour::
* Discouraged and Deprecated:: * Discouraged and Deprecated::
* Manual Conventions::
* Reporting Bugs:: * Reporting Bugs::
@end menu @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 discouraged features are available, but that you can omit them on
purpose to check whether your code still relies on them. 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 @node Reporting Bugs
@section Reporting Bugs @section Reporting Bugs

View file

@ -5,24 +5,11 @@
@c See the file guile.texi for copying conditions. @c See the file guile.texi for copying conditions.
@node Preface @node Preface
@chapter Preface @unnumbered Preface
This manual documents version @value{VERSION} of Guile, GNU's This manual describes how to use Guile, GNU's Ubiquitous Intelligent
Ubiquitous Intelligent Language for Extensions. It describes how to Language for Extensions. It relates particularly to Guile version
use Guile in many useful and interesting ways. @value{VERSION}. The manual is divided into the following chapters.
@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.
@table @strong @table @strong
@item Chapter 1: Introduction to Guile @item Chapter 1: Introduction to Guile
@ -64,56 +51,13 @@ classes, multiple inheritance and generic functions.
@end table @end table
@menu
@node Manual Conventions * Contributors::
@section Conventions used in this Manual * Guile License::
@end menu
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 Contributors @node Contributors
@section Contributors to this Manual @unnumberedsec Contributors to this Manual
The Guile reference and tutorial manuals were written and edited The Guile reference and tutorial manuals were written and edited
largely by Mark Galassi and Jim Blandy. In particular, Jim wrote the 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. Djurfeldt and Neil Jerram.
@node Guile License @node Guile License
@section The Guile License @unnumberedsec The Guile License
@cindex copying @cindex copying
@cindex GPL @cindex GPL
@cindex LGPL @cindex LGPL