Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"

[Mark Harig <idirectscm@aim.com>]

[-- Attachment #1.1: Type: text/plain, Size: 6838 bytes --]


On Sun, Apr 24, 2011 at 04:33:44PM +0200, Andy Wingo wrote:
> On Sat 23 Apr 2011 21:46, Mark Harig <idirectscm@aim.com> writes:
> 
> > Here is a set of patches to add the new section "Invoking Guile" to
> > the chapter "Programming in Scheme."
> 
> They look good in general, though I have some comments.  I would like
> Neil to look over them as well, or at least say he's OK with them.
> 
> First, your patches should be "atomic"; see
> http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#patch-series
> for some commentary.  In particular see point 3.  The manual should be
> working after each patch.


From that web page:


"3. No patch introduces a regression: after applying any
initial part of the series, the resulting project still
compiles and works, and has no bugs that it didn’t have
before."


I have generated both a guile.info and a guile.dvi file for
these changes and confirmed that there are no errors that
prevent these files from being generated.  Here are the versions of
the tools that I used:


$ makeinfo --version
makeinfo (GNU texinfo) 4.13


$ texi2dvi --version
texi2dvi (GNU Texinfo 4.13) 1.135


Patches 0004 and 0005 from my original message are atomic and may
*each* be reviewed, and rejected or committed independent of the other
patches.  They corrected errors in other parts of the manual that I
found while reviewing the changes I was making.


> 
> The commit logs are good.
> 
> > +@item -s @var{script} @var{arg...}
> > +@cindex script mode
> > +Read and evaluate Scheme source code from the file @var{script}, as the
> > +@code{load} function would.  After loading @var{script}, exit.  Any
> > +command-line arguments @var{arg...} following @var{script} become the
> > +script's arguments; the @code{command-line} function returns a list of
> > +strings of the form @code{(@var{script} @var{arg...})}.
> 
> The "-s" is actually optional, and only *needed* if your script starts
> with a dash.  So please document "guile foo.scm" as the default, and
> just mention "-s" in case of the script starting with a dash, or if you
> are writing some other shell script.


OK.  The description of "-s" was a copy of the original.  I
have written an updated description based on your comments.
Please review the new description.


> Use @itemx in this case, I think.


After reading the description of @itemx in the Texinfo
manual, I have left this unchanged.  @itemx is to be used
when there are more than a single table item for a given
description.  If you still think that this is needed, then I
need additional clarification.


> 
> > +strings, even those that are written as numerals.  (Note that here we
> > +are referring to names and values that are defined in the operating
> > +system shell from which Guile is invoked.  This is not the same as a
> > +Scheme environment that is defined within a running instance of guile.
> 
> "Guile", I think.


Corrected.


> 
> > +How to set environment variables before starting Guile depends on the
> > +operating system, and especially the shell that you are using.  For
> > +example, here's how to set the environment variable @env{ORGANIZATION}
> > +to @samp{not very much} using Bash:
> > +
> > +@example
> > +export ORGANIZATION="not very much"
> > +@end example
> > +
> > +@noindent
> > +and here's how to do it in csh or tcsh:
> > +
> > +@example
> > +setenv ORGANIZATION "not very much"
> > +@end example
> 
> Perhaps the tcsh example is superfluous.  Perhaps we should also mention
> the way to set env vars for one invocation: "GUILE_AUTO_COMPILE=0
> guile".
> 


Deleted the tcsh example, added a Bash example, and updated
the descriptive text.  Please review.


> > +If you wish to retrieve or change the value of the shell environment
> > +variables that effect the run-time behavior of Guile from within a
> > +running instance of guile, see @xref{Runtime Environment}.
> 
> "affect"
> 


Corrected.


> > +@item GUILE_HUSH
> > +@vindex GUILE_HUSH
> > +The @code{#/} notation for lists provokes a warning message from Guile.
> > +This syntax will be removed from Guile in the near future.
> > +
> > +To disable the warning message, set the @env{GUILE_HUSH} environment
> > +variable to any non-empty value.
> 
> This variable does not exist.
> 


Deleted.


> > +@item GUILE_INIT_MALLOC_LIMIT
> > +@vindex GUILE_INIT_MALLOC_LIMIT
> > +@item GUILE_MIN_YIELD_MALLOC
> > +@vindex GUILE_MIN_YIELD_MALLOC
> > +@cindex garbage collecting
> > +@item GUILE_MAX_SEGMENT_SIZE
> > +@vindex GUILE_MAX_SEGMENT_SIZE
> > +@item GUILE_INIT_SEGMENT_SIZE_2
> > +@vindex GUILE_INIT_SEGMENT_SIZE_2
> > +@item GUILE_INIT_SEGMENT_SIZE_1
> > +@vindex GUILE_INIT_SEGMENT_SIZE_1
> > +@item GUILE_MIN_YIELD_2
> > +@vindex GUILE_MIN_YIELD_2
> 
> Since switching to the BDW GC, these variables are not used any more.
> 
> GC_FREE_SPACE_DIVISOR is parsed by Guile though.  The GC itself does
> appear to do a number of getenv calls, but we can't really document
> those in Guile I don't think.
> 


Deleted.


> > +@item GUILE_SYSTEM_LOAD_COMPILED_PATH
> > +@item GUILE_SYSTEM_PATH
> > +@item GUILE_SYSTEM_LTDL_PATH
> 
> These are paths that Guile itself uses to look up .go, .scm, and .so
> files, respectively.  They have default values, relative to $prefix, but
> can be overridden if you really know what you're doing.  This is only
> really useful when building Guile itself.
> 


Deleted.  (From what you have written, it sounds as though someone
knowledgeable about the Guile construction and installation process
should document these elsewhere.)


> > +@item GUILE_INIT_SEGMENT_SIZE_1
> > +@item GUILE_MIN_YIELD_1
> > +@item GUILE_INIT_SEGMENT_SIZE_2
> > +@item GUILE_MIN_YIELD_2
> > +@item GUILE_MAX_SEGMENT_SIZE
> > +@item GUILE_INIT_HEAP_SIZE_1
> > +@item GUILE_INIT_HEAP_SIZE_2
> 
> Not used any more.
> 


Deleted.


> > +@item GUILE_WARN_DEPRECATED
> > +@vindex GUILE_WARN_DEPRECATED
> > +Please provide a description of me.
> 
> @ref to Deprecation.
> 


I wrote a description based on my understanding from the
'Deprecation' node.  Please review.


> 
> Otherwise, looking very good.  Thank you for this work, and looking
> forward to the revised patchset :-)
> 


Please find the three revised patches attached.  After
checking in the changes, I generated the new patches with:


   git format-patch origin


0001-doc-ref-guile.texi-node-Programming-in-Scheme-Added-.patch
0002-doc-ref-scheme-scripts.texi-node-Guile-Scripting-Del.patch
0003-doc-ref-guile-invoke.texi-node-Invoking-Guile-Initia.patch


Please also find attached an updated version of the plain
text generated for the new node.


--



[-- Attachment #1.2: Type: text/html, Size: 25359 bytes --]

[-- Attachment #2: 0001-doc-ref-guile.texi-node-Programming-in-Scheme-Added-.patch --]
[-- Type: text/x-patch, Size: 1870 bytes --]

From 60e39136b09863ac06229a4b00d39232e05055e5 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sun, 24 Apr 2011 15:47:48 -0400
Subject: [PATCH 1/3] * doc/ref/guile.texi (node Programming in Scheme): Added
 menu entry for   the new section "Invoking Guile" to
 the chapter "Programming in   Scheme".  Added
 '@include' to add the new file 'guile-invoke.texi',  
 which has the new section.

---
 doc/ref/guile.texi |   10 ++++++----
 1 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index dfadd13..30b6d14 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -217,20 +217,22 @@ Guile's core language is Scheme, and a lot can be achieved simply by using Guile
 to write and run Scheme programs --- as opposed to having to dive into C code.
 In this part of the manual, we explain how to use Guile in this mode, and
 describe the tools that Guile provides to help you with script writing,
-debugging and packaging your programs for distribution.
+debugging, and packaging your programs for distribution.
 
-For detailed reference information on the variables, functions
-etc. that make up Guile's application programming interface (API),
-@xref{API Reference}.
+For detailed reference information on the variables, functions, and so
+on that make up Guile's application programming interface (API), see
+@ref{API Reference}.
 
 @menu
 * Guile Scheme::                Guile's implementation of Scheme.
+* Invoking Guile::              Selecting optional features when starting Guile.
 * Guile Scripting::             How to write Guile scripts.
 * Using Guile Interactively::   Guile's REPL features.
 * Using Guile in Emacs::        Guile and Emacs.
 @end menu
 
 @include scheme-intro.texi
+@include guile-invoke.texi
 @include scheme-scripts.texi
 @include scheme-using.texi
 
-- 
1.7.4.4


[-- Attachment #3: 0002-doc-ref-scheme-scripts.texi-node-Guile-Scripting-Del.patch --]
[-- Type: text/x-patch, Size: 8224 bytes --]

From 4b1067f098e25cb1bd7a656edf7ac893c900aa7e Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sun, 24 Apr 2011 15:49:46 -0400
Subject: [PATCH 2/3] * doc/ref/scheme-scripts.texi (node Guile Scripting):
 Deleted the menu   entry for the section "Invoking
 Guile."  Deleted the node and   subsection "Invoking
 Guile."  This node has been moved to the new file  
 'doc/ref/guile-invoke.texi'.

---
 doc/ref/scheme-scripts.texi |  168 -------------------------------------------
 1 files changed, 0 insertions(+), 168 deletions(-)

diff --git a/doc/ref/scheme-scripts.texi b/doc/ref/scheme-scripts.texi
index 0ad1bec..7552dba 100644
--- a/doc/ref/scheme-scripts.texi
+++ b/doc/ref/scheme-scripts.texi
@@ -14,7 +14,6 @@ then tells Guile how to handle the Scheme code.
 
 @menu
 * The Top of a Script File::    How to start a Guile script.
-* Invoking Guile::              Command line options understood by Guile.
 * The Meta Switch::             Passing complex argument lists to Guile
                                 from shell scripts.
 * Command Line Handling::       Accessing the command line from a script.
@@ -76,173 +75,6 @@ The rest of the file should be a Scheme program.
 Guile reads the program, evaluating expressions in the order that they
 appear.  Upon reaching the end of the file, Guile exits.
 
-
-@node Invoking Guile
-@subsection Invoking Guile
-@cindex invocation
-
-Here we describe Guile's command-line processing in detail.  Guile
-processes its arguments from left to right, recognizing the switches
-described below.  For examples, see @ref{Scripting Examples}.
-
-@table @code
-
-@item -s @var{script} @var{arg...}
-Read and evaluate Scheme source code from the file @var{script}, as the
-@code{load} function would.  After loading @var{script}, exit.  Any
-command-line arguments @var{arg...} following @var{script} become the
-script's arguments; the @code{command-line} function returns a list of
-strings of the form @code{(@var{script} @var{arg...})}.
-
-@item -c @var{expr} @var{arg...}
-Evaluate @var{expr} as Scheme code, and then exit.  Any command-line
-arguments @var{arg...} following @var{expr} become command-line arguments; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -- @var{arg...}
-Run interactively, prompting the user for expressions and evaluating
-them.  Any command-line arguments @var{arg...} following the @code{--}
-become command-line arguments for the interactive session; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -L @var{directory}
-Add @var{directory} to the front of Guile's module load path.  The
-given directories are searched in the order given on the command line
-and before any directories in the GUILE_LOAD_PATH environment
-variable.  Paths added here are @emph{not} in effect during execution
-of the user's @file{.guile} file.
-
-@item -x @var{extension}
-Add @var{extension} to the front of Guile's load extension list
-(@pxref{Loading, @code{%load-extensions}}).  The specified extensions
-are tried in the order given on the command line, and before the default
-load extensions.  Extensions added here are @emph{not} in effect during
-execution of the user's @file{.guile} file.
-
-@item -l @var{file}
-Load Scheme source code from @var{file}, and continue processing the
-command line.
-
-@item -e @var{function}
-Make @var{function} the @dfn{entry point} of the script.  After loading
-the script file (with @code{-s}) or evaluating the expression (with
-@code{-c}), apply @var{function} to a list containing the program name
-and the command-line arguments --- the list provided by the
-@code{command-line} function.
-
-A @code{-e} switch can appear anywhere in the argument list, but Guile
-always invokes the @var{function} as the @emph{last} action it performs.
-This is weird, but because of the way script invocation works under
-POSIX, the @code{-s} option must always come last in the list.
-
-The @var{function} is most often a simple symbol that names a function
-that is defined in the script.  It can also be of the form @code{(@@
-@var{module-name} @var{symbol})} and in that case, the symbol is
-looked up in the module named @var{module-name}.
-
-For compatibility with some versions of Guile 1.4, you can also use the
-form @code{(symbol ...)} (that is, a list of only symbols that doesn't
-start with @code{@@}), which is equivalent to @code{(@@ (symbol ...)
-main)}, or @code{(symbol ...)  symbol} (that is, a list of only symbols
-followed by a symbol), which is equivalent to @code{(@@ (symbol ...)
-symbol)}.  We recommend to use the equivalent forms directly since they
-correspond to the @code{(@@ ...)}  read syntax that can be used in
-normal code, @xref{Using Guile Modules}.
-
-@xref{Scripting Examples}.
-
-@item -ds
-Treat a final @code{-s} option as if it occurred at this point in the
-command line; load the script here.
-
-This switch is necessary because, although the POSIX script invocation
-mechanism effectively requires the @code{-s} option to appear last, the
-programmer may well want to run the script before other actions
-requested on the command line.  For examples, see @ref{Scripting
-Examples}.
-
-@item \
-Read more command-line arguments, starting from the second line of the
-script file.  @xref{The Meta Switch}.
-
-@item --use-srfi=@var{list}
-The option @code{--use-srfi} expects a comma-separated list of numbers,
-each representing a SRFI number to be loaded into the interpreter
-before starting evaluating a script file or the REPL.  Additionally,
-the feature identifier for the loaded SRFIs is recognized by
-`cond-expand' when using this option.
-
-@example
-guile --use-srfi=8,13
-@end example
-
-@item --debug
-Start with the debugging virtual machine engine.  Using the debugging VM
-will enable support for VM hooks, which are needed for tracing,
-breakpoints, and accurate call counts when profiling.  The debugging VM
-is slower than the regular VM, though, by about 10 percent.  @xref{VM
-Hooks}, for more information.
-
-By default, the debugging VM engine is only used when entering an
-interactive session.  When executing a script with @code{-s} or
-@code{-c}, the normal, faster VM is used by default.
-
-@vnew{1.8}
-@item --no-debug
-Do not use the debugging VM engine, even when entering an interactive
-session.
-
-@item -q
-Do not the local initialization file, @code{.guile}.  This option only
-has an effect when running interactively; running scripts does not load
-the @code{.guile} file.  @xref{Init File}.
-
-@item --listen[=@var{p}]
-While this program runs, listen on a local port or a path for REPL
-clients.  If @var{p} starts with a number, it is assumed to be a local
-port on which to listen.  If it starts with a forward slash, it is
-assumed to be a path to a UNIX domain socket on which to listen.
-
-If @var{p} is not given, the default is local port 37146.  If you look
-at it upside down, it almost spells ``Guile''.  If you have netcat
-installed, you should be able to @kbd{nc localhost 37146} and get a
-Guile prompt.  Alternately you can fire up Emacs and connect to the
-process; see @ref{Using Guile in Emacs} for more details.
-
-Note that opening a port allows anyone who can connect to that port---in
-the TCP case, any local user---to do anything Guile can do, as the user
-that the Guile process is running as.  Don't use @option{--listen} on
-multi-user machines.  Of course, if you don't pass @option{--listen} to
-Guile, no port will be opened.
-
-That said, @code{--listen} is great for interactive debugging and
-development.
-
-@vnew{2.0}
-
-@item --auto-compile
-Compile source files automatically (default behavior).
-
-@vnew{2.0}
-
-@item --no-auto-compile
-Disable automatic source file compilation.
-
-@vnew{2.0}
-
-@item -h@r{, }--help
-Display help on invoking Guile, and then exit.
-
-@item -v@r{, }--version
-Display the current version of Guile, and then exit.
-
-@end table
-
-
 @node The Meta Switch
 @subsection The Meta Switch
 
-- 
1.7.4.4


[-- Attachment #4: 0003-doc-ref-guile-invoke.texi-node-Invoking-Guile-Initia.patch --]
[-- Type: text/x-patch, Size: 15308 bytes --]

From 03136ac2a64c13451932f6581656e34b9db06568 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sun, 24 Apr 2011 15:52:27 -0400
Subject: [PATCH 3/3] * doc/ref/guile-invoke.texi (node Invoking Guile):
 Initial revision.   This file contains the former
 section "Invoking Guile" that was   included in the
 chapter "Programming in Scheme" as a subsection   named
 "Command-line Options."  It also includes a new
 subsection   "Environment Variables," which describes
 those variables that can be   set in the operating
 system before Guile is started which affect   Guile's
 run-time behavior.

---
 doc/ref/guile-invoke.texi |  346 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 346 insertions(+), 0 deletions(-)
 create mode 100644 doc/ref/guile-invoke.texi

diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi
new file mode 100644
index 0000000..2674a71
--- /dev/null
+++ b/doc/ref/guile-invoke.texi
@@ -0,0 +1,346 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011
+@c   Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Invoking Guile
+@section Invoking Guile
+@cindex invocation
+
+Many features of Guile depend on and can be changed by information that
+the user provides either before or when Guile is started.  Below is a
+description of what information to provide and how to provide it.
+
+@menu
+* Command-line Options::        Command-line options understood by Guile.
+* Environment Variables::       Variables that affect Guile's behavior.
+@end menu
+
+@node Command-line Options
+@subsection Command-line Options
+@cindex Command-line Options
+@cindex command-line arguments
+@cindex arguments (command line)
+@cindex options (command line)
+@cindex switches (command line)
+@cindex startup (command-line arguments)
+@cindex invocation (command-line arguments)
+
+Here we describe Guile's command-line processing in detail.  Guile
+processes its arguments from left to right, recognizing the switches
+described below.  For examples, see @ref{Scripting Examples}.
+
+@table @code
+
+@item -s @var{script} @var{arg...}
+@cindex script mode
+By default, Guile will read a file named on the command line as a
+script.  However, it is possible to name a file using a leading hyphen,
+for example, @file{-myfile.scm}.  In this case, the file name must be
+preceded by @option{-s} to tell Guile that a (script) file is being
+named.  Any command-line arguments @var{arg...} following @var{script}
+become the script's arguments; the @code{command-line} function returns
+a list of strings of the form @code{(@var{script} @var{arg...})}.
+Scripts are read and evaluated as Scheme source code just as the
+@code{load} function would.  After loading @var{script}, Guile exits.
+
+@item -c @var{expr} @var{arg...}
+@cindex evaluate expression, command-line argument
+Evaluate @var{expr} as Scheme code, and then exit.  Any command-line
+arguments @var{arg...} following @var{expr} become command-line
+arguments; the @code{command-line} function returns a list of strings of
+the form @code{(@var{guile} @var{arg...})}, where @var{guile} is the
+path of the Guile executable.
+
+@item -- @var{arg...}
+Run interactively, prompting the user for expressions and evaluating
+them.  Any command-line arguments @var{arg...} following the @option{--}
+become command-line arguments for the interactive session; the
+@code{command-line} function returns a list of strings of the form
+@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
+Guile executable.
+
+@item -L @var{directory}
+Add @var{directory} to the front of Guile's module load path.  The given
+directories are searched in the order given on the command line and
+before any directories in the @env{GUILE_LOAD_PATH} environment
+variable.  Paths added here are @emph{not} in effect during execution of
+the user's @file{.guile} file.
+
+@item -x @var{extension}
+Add @var{extension} to the front of Guile's load extension list
+(@pxref{Loading, @code{%load-extensions}}).  The specified extensions
+are tried in the order given on the command line, and before the default
+load extensions.  Extensions added here are @emph{not} in effect during
+execution of the user's @file{.guile} file.
+
+@item -l @var{file}
+Load Scheme source code from @var{file}, and continue processing the
+command line.
+
+@item -e @var{function}
+Make @var{function} the @dfn{entry point} of the script.  After loading
+the script file (with @option{-s}) or evaluating the expression (with
+@option{-c}), apply @var{function} to a list containing the program name
+and the command-line arguments---the list provided by the
+@code{command-line} function.
+
+A @option{-e} switch can appear anywhere in the argument list, but Guile
+always invokes the @var{function} as the @emph{last} action it performs.
+This is weird, but because of the way script invocation works under
+POSIX, the @option{-s} option must always come last in the list.
+
+The @var{function} is most often a simple symbol that names a function
+that is defined in the script.  It can also be of the form @code{(@@
+@var{module-name} @var{symbol})}, and in that case, the symbol is
+looked up in the module named @var{module-name}.
+
+For compatibility with some versions of Guile 1.4, you can also use the
+form @code{(symbol ...)} (that is, a list of only symbols that doesn't
+start with @code{@@}), which is equivalent to @code{(@@ (symbol ...)
+main)}, or @code{(symbol ...)  symbol} (that is, a list of only symbols
+followed by a symbol), which is equivalent to @code{(@@ (symbol ...)
+symbol)}.  We recommend to use the equivalent forms directly since they
+correspond to the @code{(@@ ...)}  read syntax that can be used in
+normal code.  See @ref{Using Guile Modules} and @ref{Scripting
+Examples}.
+
+@item -ds
+Treat a final @option{-s} option as if it occurred at this point in the
+command line; load the script here.
+
+This switch is necessary because, although the POSIX script invocation
+mechanism effectively requires the @option{-s} option to appear last, the
+programmer may well want to run the script before other actions
+requested on the command line.  For examples, see @ref{Scripting
+Examples}.
+
+@item \
+Read more command-line arguments, starting from the second line of the
+script file.  @xref{The Meta Switch}.
+
+@item --use-srfi=@var{list}
+@cindex loading srfi modules (command line)
+The option @option{--use-srfi} expects a comma-separated list of numbers,
+each representing a SRFI module to be loaded into the interpreter
+before evaluating a script file or starting the REPL.  Additionally,
+the feature identifier for the loaded SRFIs is recognized by
+the procedure @code{cond-expand} when this option is used.
+
+Here is an example that loads the modules SRFI-8 ('receive') and SRFI-13
+('string library') before the GUILE interpreter is started:
+
+@example
+guile --use-srfi=8,13
+@end example
+
+@item --debug
+@cindex debugging virtual machine (command line)
+Start with the debugging virtual machine (VM) engine.  Using the
+debugging VM will enable support for VM hooks, which are needed for
+tracing, breakpoints, and accurate call counts when profiling.  The
+debugging VM is slower than the regular VM, though, by about ten
+percent.  @xref{VM Hooks}, for more information.
+
+By default, the debugging VM engine is only used when entering an
+interactive session.  When executing a script with @option{-s} or
+@option{-c}, the normal, faster VM is used by default.
+
+@vnew{1.8}
+@item --no-debug
+@cindex debugging virtual machine (command line)
+Do not use the debugging VM engine, even when entering an interactive
+session.
+
+@item -q
+@cindex init file, not loading
+@cindex @file{.guile} file, not loading
+Do not load the initialization file, @file{.guile}.  This option only
+has an effect when running interactively; running scripts does not load
+the @file{.guile} file.  @xref{Init File}.
+
+@item --listen[=@var{p}]
+While this program runs, listen on a local port or a path for REPL
+clients.  If @var{p} starts with a number, it is assumed to be a local
+port on which to listen.  If it starts with a forward slash, it is
+assumed to be a path to a UNIX domain socket on which to listen.
+
+If @var{p} is not given, the default is local port 37146.  If you look
+at it upside down, it almost spells ``Guile''.  If you have netcat
+installed, you should be able to @kbd{nc localhost 37146} and get a
+Guile prompt.  Alternately you can fire up Emacs and connect to the
+process; see @ref{Using Guile in Emacs} for more details.
+
+Note that opening a port allows anyone who can connect to that port---in
+the TCP case, any local user---to do anything Guile can do, as the user
+that the Guile process is running as.  Do not use @option{--listen} on
+multi-user machines.  Of course, if you do not pass @option{--listen} to
+Guile, no port will be opened.
+
+That said, @option{--listen} is great for interactive debugging and
+development.
+
+@vnew{2.0}
+
+@item --auto-compile
+Compile source files automatically (default behavior).
+
+@vnew{2.0}
+
+@item --no-auto-compile
+Disable automatic source file compilation.
+
+@vnew{2.0}
+
+@item -h@r{, }--help
+Display help on invoking Guile, and then exit.
+
+@item -v@r{, }--version
+Display the current version of Guile, and then exit.
+
+@end table
+
+@node Environment Variables
+@subsection Environment Variables
+@cindex environment variables
+@cindex shell
+@cindex initialization
+The @dfn{environment} is a feature of the operating system; it consists
+of a collection of variables with names and values.  Each variable is
+called an @dfn{environment variable} (or, sometimes, a ``shell
+variable''); environment variable names are case-sensitive, and it is
+conventional to use upper-case letters only.  The values are all text
+strings, even those that are written as numerals.  (Note that here we
+are referring to names and values that are defined in the operating
+system shell from which Guile is invoked.  This is not the same as a
+Scheme environment that is defined within a running instance of Guile.
+For a description of Scheme environments, @pxref{About Environments}.)
+   
+How to set environment variables before starting Guile depends on the
+operating system and, especially, the shell that you are using.  For
+example, here is how to tell Guile to provide detailed warning messages
+about deprecated features by setting @env{GUILE_WARN_DEPRECATED} using
+Bash:
+
+@example
+$ export GUILE_WARN_DEPRECATED="detailed"
+$ guile
+@end example
+
+@noindent
+Or, detailed warnings can be turned on for a single invocation using:
+
+@example
+$ env GUILE_WARN_DEPRECATED="detailed" guile
+@end example
+
+If you wish to retrieve or change the value of the shell environment
+variables that affect the run-time behavior of Guile from within a
+running instance of Guile, see @ref{Runtime Environment}.
+
+Here are the environment variables that affect the run-time behavior of
+Guile:
+
+@table @env
+@item GUILE_AUTO_COMPILE
+@vindex GUILE_AUTO_COMPILE
+This is a flag that can be used to tell Guile whether or not to compile
+Scheme source files automatically.  Starting with Guile 2.0, Scheme
+source files will be compiled automatically, by default.  If
+@env{GUILE_AUTO_COMPILE} is set to zero (0), then Scheme files are not
+compiled automatically.
+
+If a compiled @file{.go} file corresponding to a @file{.scm} file is not
+found or is not newer than the @file{.scm} file, the @file{.scm} file
+will be compiled on the fly, and the resulting @file{.go} file stored
+away.  An advisory note will be printed on the console.
+
+Note that this mechanism depends on the timestamp of the @file{.go} file
+being newer than that of the @file{.scm} file; if the @file{.scm} or
+@file{.go} files are moved after installation, care should be taken to
+preserve their original timestamps.
+
+Auto-compiled files will be stored in the directory
+@file{$XDG_CACHE_HOME/guile/ccache}, where @env{XDG_CACHE_HOME} defaults
+to the directory @file{$HOME/.cache}.  This directory will be created if
+it does not already exist.
+
+To inhibit automatic compilation, set the @env{GUILE_AUTO_COMPILE}
+environment variable to zero (0), or pass @option{--no-auto-compile} on
+the Guile command line.
+
+@item GUILE_HISTORY
+@vindex GUILE_HISTORY
+This variable names the file that holds the Guile REPL command history.
+You can specify a different history file by setting this environment
+variable.  By default, the history file is @file{$HOME/.guile_history}.
+
+@item GUILE_LOAD_COMPILED_PATH
+@vindex GUILE_LOAD_COMPILED_PATH
+This variable may be used to augment the path that is searched for
+compiled Scheme files (@file{.go} files) when loading.  Its value should
+be a colon-separated list of directories, which will be prefixed to the
+value of the default search path stored in @code{%load-compiled-path}.
+
+Here is an example using the Bash shell that adds the current directory,
+@file{.}, and the relative directory @file{../my-library} to
+@code{%load-compiled-path}:
+
+@example
+$ export GUILE_LOAD_COMPILED_PATH=".:../my-library"
+$ guile -c '(display %load-compiled-path) (newline)'
+(. ../my-library /usr/local/lib/guile/2.0/ccache)
+@end example
+
+@item GUILE_LOAD_PATH
+@vindex GUILE_LOAD_PATH
+This variable may be used to augment the path that is searched for
+Scheme files when loading.  Its value should be a colon-separated list
+of directories, which will be prefixed to the value of the default
+search path stored in @code{%load-path}.
+
+Here is an example using the Bash shell that adds the current directory
+and the parent of the current directory to @code{%load-path}:
+
+@example
+$ env GUILE_LOAD_PATH=".:.." \
+guile -c '(display %load-path) (newline)'
+(. .. /usr/local/share/guile/2.0 \
+/usr/local/share/guile/site/2.0 \
+/usr/local/share/guile/site /usr/local/share/guile)
+@end example
+
+(Note: The line breaks, above, are for documentation purposes only, and
+not required in the actual example.)
+
+@item GUILE_WARN_DEPRECATED
+@vindex GUILE_WARN_DEPRECATED
+As Guile evolves, some features will be eliminated or replaced by newer
+features.  To help users migrate their code as this evolution occurs,
+Guile will issue warning messages about code that uses features that
+have been marked for eventual elimination.  @env{GUILE_WARN_DEPRECATED}
+can be set to ``no'' to tell Guile not to display these warning
+messages, or set to ``detailed'' to tell Guile to display more lengthy
+messages describing the warning.  @xref{Deprecation}.
+
+@item HOME
+@vindex HOME
+Guile uses the environment variable @env{HOME}, the name of your home
+directory, to locate various files, such as @file{.guile} or
+@file{.guile_history}.
+
+@item LTDL_LIBRARY_PATH
+@vindex LTDL_LIBRARY_PATH
+Guile now adds its install prefix to the @env{LTDL_LIBRARY_PATH}.
+
+Users may now install Guile in non-standard directories and run
+`/path/to/bin/guile', without having also to set @env{LTDL_LIBRARY_PATH}
+to include `/path/to/lib'.
+
+@end table
+
+@c Local Variables: 
+@c mode: texinfo
+@c TeX-master: "guile"
+@c End: 
-- 
1.7.4.4


[-- Attachment #5: guile-section42.txt --]
[-- Type: text/plain, Size: 12660 bytes --]

4.2 Invoking Guile
==================

Many features of Guile depend on and can be changed by information that
the user provides either before or when Guile is started.  Below is a
description of what information to provide and how to provide it.

4.2.1 Command-line Options
--------------------------

Here we describe Guile's command-line processing in detail.  Guile
processes its arguments from left to right, recognizing the switches
described below.  For examples, see *note Scripting Examples::.

`-s SCRIPT ARG...'
     By default, Guile will read a file named on the command line as a
     script.  However, it is possible to name a file using a leading
     hyphen, for example, `-myfile.scm'.  In this case, the file name
     must be preceded by `-s' to tell Guile that a (script) file is
     being named.  Any command-line arguments ARG... following SCRIPT
     become the script's arguments; the `command-line' function returns
     a list of strings of the form `(SCRIPT ARG...)'.  Scripts are read
     and evaluated as Scheme source code just as the `load' function
     would.  After loading SCRIPT, Guile exits.

`-c EXPR ARG...'
     Evaluate EXPR as Scheme code, and then exit.  Any command-line
     arguments ARG... following EXPR become command-line arguments; the
     `command-line' function returns a list of strings of the form
     `(GUILE ARG...)', where GUILE is the path of the Guile executable.

`-- ARG...'
     Run interactively, prompting the user for expressions and
     evaluating them.  Any command-line arguments ARG... following the
     `--' become command-line arguments for the interactive session; the
     `command-line' function returns a list of strings of the form
     `(GUILE ARG...)', where GUILE is the path of the Guile executable.

`-L DIRECTORY'
     Add DIRECTORY to the front of Guile's module load path.  The given
     directories are searched in the order given on the command line and
     before any directories in the `GUILE_LOAD_PATH' environment
     variable.  Paths added here are _not_ in effect during execution of
     the user's `.guile' file.

`-x EXTENSION'
     Add EXTENSION to the front of Guile's load extension list (*note
     `%load-extensions': Loading.).  The specified extensions are tried
     in the order given on the command line, and before the default
     load extensions.  Extensions added here are _not_ in effect during
     execution of the user's `.guile' file.

`-l FILE'
     Load Scheme source code from FILE, and continue processing the
     command line.

`-e FUNCTION'
     Make FUNCTION the "entry point" of the script.  After loading the
     script file (with `-s') or evaluating the expression (with `-c'),
     apply FUNCTION to a list containing the program name and the
     command-line arguments--the list provided by the `command-line'
     function.

     A `-e' switch can appear anywhere in the argument list, but Guile
     always invokes the FUNCTION as the _last_ action it performs.
     This is weird, but because of the way script invocation works under
     POSIX, the `-s' option must always come last in the list.

     The FUNCTION is most often a simple symbol that names a function
     that is defined in the script.  It can also be of the form `(@
     MODULE-NAME SYMBOL)', and in that case, the symbol is looked up in
     the module named MODULE-NAME.

     For compatibility with some versions of Guile 1.4, you can also
     use the form `(symbol ...)' (that is, a list of only symbols that
     doesn't start with `@'), which is equivalent to `(@ (symbol ...)
     main)', or `(symbol ...)  symbol' (that is, a list of only symbols
     followed by a symbol), which is equivalent to `(@ (symbol ...)
     symbol)'.  We recommend to use the equivalent forms directly since
     they correspond to the `(@ ...)'  read syntax that can be used in
     normal code.  See *note Using Guile Modules:: and *note Scripting
     Examples::.

`-ds'
     Treat a final `-s' option as if it occurred at this point in the
     command line; load the script here.

     This switch is necessary because, although the POSIX script
     invocation mechanism effectively requires the `-s' option to
     appear last, the programmer may well want to run the script before
     other actions requested on the command line.  For examples, see
     *note Scripting Examples::.

`\'
     Read more command-line arguments, starting from the second line of
     the script file.  *Note The Meta Switch::.

`--use-srfi=LIST'
     The option `--use-srfi' expects a comma-separated list of numbers,
     each representing a SRFI module to be loaded into the interpreter
     before evaluating a script file or starting the REPL.
     Additionally, the feature identifier for the loaded SRFIs is
     recognized by the procedure `cond-expand' when this option is used.

     Here is an example that loads the modules SRFI-8 ('receive') and
     SRFI-13 ('string library') before the GUILE interpreter is started:

          guile --use-srfi=8,13

`--debug'
     Start with the debugging virtual machine (VM) engine.  Using the
     debugging VM will enable support for VM hooks, which are needed for
     tracing, breakpoints, and accurate call counts when profiling.  The
     debugging VM is slower than the regular VM, though, by about ten
     percent.  *Note VM Hooks::, for more information.

     By default, the debugging VM engine is only used when entering an
     interactive session.  When executing a script with `-s' or `-c',
     the normal, faster VM is used by default.

`--no-debug'
     Do not use the debugging VM engine, even when entering an
     interactive session.

`-q'
     Do not load the initialization file, `.guile'.  This option only
     has an effect when running interactively; running scripts does not
     load the `.guile' file.  *Note Init File::.

`--listen[=P]'
     While this program runs, listen on a local port or a path for REPL
     clients.  If P starts with a number, it is assumed to be a local
     port on which to listen.  If it starts with a forward slash, it is
     assumed to be a path to a UNIX domain socket on which to listen.

     If P is not given, the default is local port 37146.  If you look
     at it upside down, it almost spells "Guile".  If you have netcat
     installed, you should be able to `nc localhost 37146' and get a
     Guile prompt.  Alternately you can fire up Emacs and connect to the
     process; see *note Using Guile in Emacs:: for more details.

     Note that opening a port allows anyone who can connect to that
     port--in the TCP case, any local user--to do anything Guile can
     do, as the user that the Guile process is running as.  Do not use
     `--listen' on multi-user machines.  Of course, if you do not pass
     `--listen' to Guile, no port will be opened.

     That said, `--listen' is great for interactive debugging and
     development.

`--auto-compile'
     Compile source files automatically (default behavior).

`--no-auto-compile'
     Disable automatic source file compilation.

`-h, --help'
     Display help on invoking Guile, and then exit.

`-v, --version'
     Display the current version of Guile, and then exit.


4.2.2 Environment Variables
---------------------------

The "environment" is a feature of the operating system; it consists of
a collection of variables with names and values.  Each variable is
called an "environment variable" (or, sometimes, a "shell variable");
environment variable names are case-sensitive, and it is conventional
to use upper-case letters only.  The values are all text strings, even
those that are written as numerals.  (Note that here we are referring
to names and values that are defined in the operating system shell from
which Guile is invoked.  This is not the same as a Scheme environment
that is defined within a running instance of Guile.  For a description
of Scheme environments, *note About Environments::.)

   How to set environment variables before starting Guile depends on the
operating system and, especially, the shell that you are using.  For
example, here is how to tell Guile to provide detailed warning messages
about deprecated features by setting `GUILE_WARN_DEPRECATED' using Bash:

     $ export GUILE_WARN_DEPRECATED="detailed"
     $ guile

Or, detailed warnings can be turned on for a single invocation using:

     $ env GUILE_WARN_DEPRECATED="detailed" guile

   If you wish to retrieve or change the value of the shell environment
variables that affect the run-time behavior of Guile from within a
running instance of Guile, see *note Runtime Environment::.

   Here are the environment variables that affect the run-time behavior
of Guile:

`GUILE_AUTO_COMPILE'
     This is a flag that can be used to tell Guile whether or not to
     compile Scheme source files automatically.  Starting with Guile
     2.0, Scheme source files will be compiled automatically, by
     default.  If `GUILE_AUTO_COMPILE' is set to zero (0), then Scheme
     files are not compiled automatically.

     If a compiled `.go' file corresponding to a `.scm' file is not
     found or is not newer than the `.scm' file, the `.scm' file will
     be compiled on the fly, and the resulting `.go' file stored away.
     An advisory note will be printed on the console.

     Note that this mechanism depends on the timestamp of the `.go' file
     being newer than that of the `.scm' file; if the `.scm' or `.go'
     files are moved after installation, care should be taken to
     preserve their original timestamps.

     Auto-compiled files will be stored in the directory
     `$XDG_CACHE_HOME/guile/ccache', where `XDG_CACHE_HOME' defaults to
     the directory `$HOME/.cache'.  This directory will be created if
     it does not already exist.

     To inhibit automatic compilation, set the `GUILE_AUTO_COMPILE'
     environment variable to zero (0), or pass `--no-auto-compile' on
     the Guile command line.

`GUILE_HISTORY'
     This variable names the file that holds the Guile REPL command
     history.  You can specify a different history file by setting this
     environment variable.  By default, the history file is
     `$HOME/.guile_history'.

`GUILE_LOAD_COMPILED_PATH'
     This variable may be used to augment the path that is searched for
     compiled Scheme files (`.go' files) when loading.  Its value should
     be a colon-separated list of directories, which will be prefixed
     to the value of the default search path stored in
     `%load-compiled-path'.

     Here is an example using the Bash shell that adds the current
     directory, `.', and the relative directory `../my-library' to
     `%load-compiled-path':

          $ export GUILE_LOAD_COMPILED_PATH=".:../my-library"
          $ guile -c '(display %load-compiled-path) (newline)'
          (. ../my-library /usr/local/lib/guile/2.0/ccache)

`GUILE_LOAD_PATH'
     This variable may be used to augment the path that is searched for
     Scheme files when loading.  Its value should be a colon-separated
     list of directories, which will be prefixed to the value of the
     default search path stored in `%load-path'.

     Here is an example using the Bash shell that adds the current
     directory and the parent of the current directory to `%load-path':

          $ env GUILE_LOAD_PATH=".:.." \
          guile -c '(display %load-path) (newline)'
          (. .. /usr/local/share/guile/2.0 \
          /usr/local/share/guile/site/2.0 \
          /usr/local/share/guile/site /usr/local/share/guile)

     (Note: The line breaks, above, are for documentation purposes
     only, and not required in the actual example.)

`GUILE_WARN_DEPRECATED'
     As Guile evolves, some features will be eliminated or replaced by
     newer features.  To help users migrate their code as this
     evolution occurs, Guile will issue warning messages about code
     that uses features that have been marked for eventual elimination.
     `GUILE_WARN_DEPRECATED' can be set to "no" to tell Guile not to
     display these warning messages, or set to "detailed" to tell Guile
     to display more lengthy messages describing the warning.  *Note
     Deprecation::.

`HOME'
     Guile uses the environment variable `HOME', the name of your home
     directory, to locate various files, such as `.guile' or
     `.guile_history'.

`LTDL_LIBRARY_PATH'
     Guile now adds its install prefix to the `LTDL_LIBRARY_PATH'.

     Users may now install Guile in non-standard directories and run
     `/path/to/bin/guile', without having also to set
     `LTDL_LIBRARY_PATH' to include `/path/to/lib'.