[bpt/guile.git] / doc / guile.1

.\" Written by Robert Merkel (rgmerk@mira.net)
.\" augmented by Rob Browning <rlb@cs.utexas.edu>
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH GUILE 1
.SH NAME
guile \- a Scheme interpreter
.SH SYNOPSIS
.B guile [-q] [-ds] [--help] [--version] [--emacs] [--debug]
.B [-l FILE] [-e FUNCTION] [\]
.B [-c EXPR] [-s SCRIPT] [--]
.SH DESCRIPTION
GNU Guile is an interpreter for the Scheme programming language.  It
implements R5RS, providing additional features
necessary for real-world use.  It is extremely simple to embed guile
into a C program, calling C from Scheme and Scheme from C.  Guile's
design makes it very suitable for use as an "extension" or "glue"
language, but it also works well as a stand-alone scheme development
environment.

The
.B guile
executable itself provides a stand-alone interpreter for scheme
programs, for either interactive use or executing scripts.

This manpage provides only brief instruction in invoking
.B guile
from the command line.  Please consult the guile info documentation
(type 
.B info guile
at a command prompt) for more information.

.SH OPTIONS
.IP -l FILE
Load scheme source code from file.
.IP -e FUNCTION
After reading script, apply FUNCTION to command-line arguments
.IP -ds
do -s SCRIPT at this point (note that this argument must be used in
conjuction with -s)
.IP --help 
Describe command line options and exit
.IP --debug
Start guile with debugging evaluator and backtraces enabled 
(useful for debugging guile scripts)
.IP --version
Display guile version and exit.
.IP --emacs
Enable emacs protocol for use from within emacs (experimental)
.IP --
Stop argument processing, start guile in interactive mode.
.IP -c EXPR
Stop argument processing, evaluate EXPR as a scheme expression.
.IP -s SCRIPT-FILE
Load Scheme source from SCRIPT-FILE and execute as a script.
.IP -q
Suppress loading the user's ~/.guile file.

.SH ENVIRONMENT
.\".TP \w'MANROFFSEQ\ \ 'u
.TP
.B GUILE_LOAD_PATH
If
.RB $ GUILE_LOAD_PATH
is set, its value is used to agument the path to search for scheme
files when loading.  It should be a colon separated list of
directories which will be prepended to the default %load-path.

.SH FILES
.I ~/.guile
is a guile script that is executed before any other processing occurs.
For example, the following .guile activates guile's readline
interface:

.RS 4
(use-modules (ice-9 readline))
.RS 0
(activate-readline)

.SH "SEE ALSO"
The full documentation for guile is maintained as a Texinfo manual.  If
the info and guile programs are properly installed at your site, the
command
.IP
.B info guile
.PP
should give you access to the complete manual.

http://www.schemers.org provides a general introduction to the
Scheme language.

.SH "REPORTING BUGS"
There is a mailing list, bug-guile@gnu.org, for reporting Guile bugs and
fixes.  But before reporting something as a bug, please try to be sure
that it really is a bug, not a misunderstanding or a deliberate feature.
We ask you to read the section ``Reporting Bugs'' in the Guile reference
manual (or Info system) for hints on how and when to report bugs.  Also,
include the version number of the Guile you are running in every bug
report that you send in.  Bugs tend actually to be fixed if they can be
isolated, so it is in your interest to report them in such a way that
they can be easily reproduced.

.SH COPYING
Copyright (C) 2010 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
document provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
document under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this
document into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

.SH AUTHORS
Robert Merkel <rgmerk@mira.net> wrote this manpage.  
Rob Browning <rlb@cs.utexas.edu> has added to it.

.B guile 
is GNU software.  Guile is originally based on Aubrey Jaffer's
SCM interpreter, and is the work of many individuals.
Commit	Line	Data
4cd27226 MV	1	.\" Written by Robert Merkel (rgmerk@mira.net)
	2	.\" augmented by Rob Browning <rlb@cs.utexas.edu>
	3	.\" Process this file with
	4	.\" groff -man -Tascii foo.1
	5	.\"
1660414a	6	.TH GUILE 1
4cd27226 MV	7	.SH NAME
	8	guile \- a Scheme interpreter
	9	.SH SYNOPSIS
	10	.B guile [-q] [-ds] [--help] [--version] [--emacs] [--debug]
	11	.B [-l FILE] [-e FUNCTION] [\]
	12	.B [-c EXPR] [-s SCRIPT] [--]
	13	.SH DESCRIPTION
1660414a LC	14	GNU Guile is an interpreter for the Scheme programming language. It
1660414a LC	15	implements R5RS, providing additional features
4cd27226 MV	16	necessary for real-world use. It is extremely simple to embed guile
	17	into a C program, calling C from Scheme and Scheme from C. Guile's
	18	design makes it very suitable for use as an "extension" or "glue"
	19	language, but it also works well as a stand-alone scheme development
	20	environment.
	21
	22	The
	23	.B guile
	24	executable itself provides a stand-alone interpreter for scheme
	25	programs, for either interactive use or executing scripts.
	26
	27	This manpage provides only brief instruction in invoking
	28	.B guile
	29	from the command line. Please consult the guile info documentation
	30	(type
	31	.B info guile
24d386ac	32	at a command prompt) for more information.
4cd27226 MV	33
	34	.SH OPTIONS
	35	.IP -l FILE
	36	Load scheme source code from file.
	37	.IP -e FUNCTION
	38	After reading script, apply FUNCTION to command-line arguments
	39	.IP -ds
	40	do -s SCRIPT at this point (note that this argument must be used in
	41	conjuction with -s)
	42	.IP --help
	43	Describe command line options and exit
	44	.IP --debug
	45	Start guile with debugging evaluator and backtraces enabled
	46	(useful for debugging guile scripts)
	47	.IP --version
	48	Display guile version and exit.
	49	.IP --emacs
	50	Enable emacs protocol for use from within emacs (experimental)
	51	.IP --
	52	Stop argument processing, start guile in interactive mode.
	53	.IP -c EXPR
	54	Stop argument processing, evaluate EXPR as a scheme expression.
	55	.IP -s SCRIPT-FILE
	56	Load Scheme source from SCRIPT-FILE and execute as a script.
24d386ac NJ	57	.IP -q
24d386ac NJ	58	Suppress loading the user's ~/.guile file.
4cd27226 MV	59
	60	.SH ENVIRONMENT
	61	.\".TP \w'MANROFFSEQ\ \ 'u
	62	.TP
	63	.B GUILE_LOAD_PATH
	64	If
	65	.RB $ GUILE_LOAD_PATH
	66	is set, its value is used to agument the path to search for scheme
	67	files when loading. It should be a colon separated list of
	68	directories which will be prepended to the default %load-path.
	69
	70	.SH FILES
	71	.I ~/.guile
	72	is a guile script that is executed before any other processing occurs.
	73	For example, the following .guile activates guile's readline
	74	interface:
	75
	76	.RS 4
	77	(use-modules (ice-9 readline))
	78	.RS 0
	79	(activate-readline)
	80
	81	.SH "SEE ALSO"
1660414a LC	82	The full documentation for guile is maintained as a Texinfo manual. If
	83	the info and guile programs are properly installed at your site, the
	84	command
	85	.IP
	86	.B info guile
	87	.PP
	88	should give you access to the complete manual.
4cd27226 MV	89
	90	http://www.schemers.org provides a general introduction to the
	91	Scheme language.
	92
a7d8a8a6 NJ	93	.SH "REPORTING BUGS"
	94	There is a mailing list, bug-guile@gnu.org, for reporting Guile bugs and
	95	fixes. But before reporting something as a bug, please try to be sure
	96	that it really is a bug, not a misunderstanding or a deliberate feature.
	97	We ask you to read the section ``Reporting Bugs'' in the Guile reference
	98	manual (or Info system) for hints on how and when to report bugs. Also,
	99	include the version number of the Guile you are running in every bug
	100	report that you send in. Bugs tend actually to be fixed if they can be
	101	isolated, so it is in your interest to report them in such a way that
	102	they can be easily reproduced.
	103
	104	.SH COPYING
	105	Copyright (C) 2010 Free Software Foundation, Inc.
	106
	107	Permission is granted to make and distribute verbatim copies of this
	108	document provided the copyright notice and this permission notice are
	109	preserved on all copies.
	110
	111	Permission is granted to copy and distribute modified versions of this
	112	document under the conditions for verbatim copying, provided that the
	113	entire resulting derived work is distributed under the terms of a
	114	permission notice identical to this one.
	115
	116	Permission is granted to copy and distribute translations of this
	117	document into another language, under the above conditions for modified
	118	versions, except that this permission notice may be stated in a
	119	translation approved by the Free Software Foundation.
	120
4cd27226 MV	121	.SH AUTHORS
	122	Robert Merkel <rgmerk@mira.net> wrote this manpage.
	123	Rob Browning <rlb@cs.utexas.edu> has added to it.
	124
	125	.B guile
	126	is GNU software. Guile is originally based on Aubrey Jaffer's
	127	SCM interpreter, and is the work of many individuals.