* Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
@ 2011-04-23 19:46 Mark Harig
2011-04-24 14:33 ` Andy Wingo
0 siblings, 1 reply; 20+ messages in thread
From: Mark Harig @ 2011-04-23 19:46 UTC (permalink / raw)
To: guile-devel
[-- Attachment #1.1: Type: text/plain, Size: 1047 bytes --]
Here is a set of patches to add the new section "Invoking Guile" to the chapter "Programming in Scheme."
CAVEAT: Please review the subsection "Environment Variables" thoroughly before committing this change.
This subsection is "incorekt and incomplet." The list of variables is my *guess* based on looking through the
NEWS file. Some variables might need to be deleted from the list and some missing ones might need to be
added. The descriptions of the variables are also my guess (when I could make a guess) based on
descriptions I could find. Please change or delete these variables or their descriptions as needed.
Please find attached five (git format-patch) patch files (one for each changed file). I am also including the
plain-text version of the new section "Invoking Guile" so that the content can be more easily reviewed
without having to navigate the texinfo macros.
I have attempted to check the .texinfo files by reviewing both the .info and .dvi (TeX) files that can be
generated from the .texinfo files.
[-- Attachment #1.2: Type: text/html, Size: 1330 bytes --]
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Signed-off-by-Mark-Harig-idirectscm-aim.com.patch --]
[-- Type: text/x-patch; name="0001-Signed-off-by-Mark-Harig-idirectscm-aim.com.patch", Size: 1839 bytes --]
From dd63bd48cf3db53c20fb1e9e8d85e91fe29dc1a2 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sat, 23 Apr 2011 13:01:39 -0400
* 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..26d32b7 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:: Command-line options understood by 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
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-Signed-off-by-Mark-Harig-idirectscm-aim.com.patch --]
[-- Type: text/x-patch; name="0002-Signed-off-by-Mark-Harig-idirectscm-aim.com.patch", Size: 8200 bytes --]
From 8c4301321bbe23de70d8e7c5ec4bd6567840851b Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sat, 23 Apr 2011 13:07:48 -0400
* 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
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #4: 0003-doc-ref-guile-invoke.texi-node-Invoking-Guile-Initia.patch --]
[-- Type: text/x-patch; name="0003-doc-ref-guile-invoke.texi-node-Invoking-Guile-Initia.patch", Size: 17571 bytes --]
From f4ac15f540e22fc83d13005efaaebb75d4603fc3 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sat, 23 Apr 2011 13:23:58 -0400
* 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 and which affect
Guile's run-time behavior.
---
doc/ref/guile-invoke.texi | 421 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 421 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..4d11c95
--- /dev/null
+++ b/doc/ref/guile-invoke.texi
@@ -0,0 +1,421 @@
+@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
+
+@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
+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...}
+@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}
+The option @option{--use-srfi} expects a comma-separated list of numbers,
+each representing a SRFI number 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 using this option.
+
+@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. 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, @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, see @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'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
+
+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}.
+
+Here are the environment variables that effect 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_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.
+
+@item GUILE_INIT_MALLOC_LIMIT
+@vindex GUILE_INIT_MALLOC_LIMIT
+@item GUILE_MIN_YIELD_MALLOC
+@vindex GUILE_MIN_YIELD_MALLOC
+@cindex garbage collecting
+The garbage collector uses lazy sweeping. This is reflected in the
+output of the procedure @code{gc-stats}; since cells are being freed
+when they are allocated, the cells-allocated field stays roughly
+constant.
+
+For malloc-related triggers, the garbage collector uses the same
+heuristic as the cell-triggered collections. It may be tuned with the
+environment variable @env{GUILE_MIN_YIELD_MALLOC}. This is the
+percentage for minimum yield of malloc-related triggers. The default is
+forty (40) percent.
+
+@env{GUILE_INIT_MALLOC_LIMIT} sets the size in kilobytes of the initial
+trigger for garbage collection. The default is two hundred (200)
+kilobytes.
+
+@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
+Debugging operations for the freelist have been deprecated, along with
+the C variables that control garbage collection. The environment
+variables @env{GUILE_MAX_SEGMENT_SIZE}, @env{GUILE_INIT_SEGMENT_SIZE_2},
+@env{GUILE_INIT_SEGMENT_SIZE_1}, and @env{GUILE_MIN_YIELD_2} should be
+used (units: bytes? kilobytes?)
+
+@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_SYSTEM_LOAD_COMPILED_PATH
+@vindex GUILE_SYSTEM_LOAD_COMPILED_PATH
+Please provide a description of me, or delete me if I am obsolete.
+
+@item GUILE_SYSTEM_PATH
+@vindex GUILE_SYSTEM_PATH
+Please provide a description of me, or delete me if I am obsolete.
+
+@item GUILE_SYSTEM_LTDL_PATH
+@vindex GUILE_SYSTEM_LTDL_PATH
+Please provide a description of me, or delete me if I am obsolete.
+
+@item GUILE_INIT_SEGMENT_SIZE_1
+@vindex GUILE_INIT_SEGMENT_SIZE_1
+@cindex memory allocation, heap
+The application can set up other default values for the
+garbage-collection heap allocation parameters. Allocation of two-word
+cell heaps is controlled by the environment variables
+@env{GUILE_INIT_SEGMENT_SIZE_1} and @env{GUILE_MIN_YIELD_1}.
+@env{GUILE_INIT_SEGMENT_SIZE_1} is the size of initial heap segment in
+bytes (default is 360000).
+
+@item GUILE_MIN_YIELD_1
+@vindex GUILE_MIN_YIELD_1
+Minimum number of freed cells at each garbage collection in percent of
+total heap size (default is forty (40) percent).
+
+@item GUILE_INIT_SEGMENT_SIZE_2
+@vindex GUILE_INIT_SEGMENT_SIZE_2
+Allocation of four-word cell heaps is controlled by the environment
+variables @env{GUILE_INIT_SEGMENT_SIZE_2} and @env{GUILE_MIN_YIELD_2}.
+Four-word cell heaps are used for real numbers and miscellaneous other
+objects.
+
+Please provide a description of @env{GUILE_INIT_SEGMENT_SIZE_2}.
+
+@item GUILE_MIN_YIELD_2
+@vindex GUILE_MIN_YIELD_2
+Please provide a description of @env{GUILE_MIN_YIELD_2}.
+
+@item GUILE_MAX_SEGMENT_SIZE
+@vindex GUILE_MAX_SEGMENT_SIZE
+Maximal segment size in bytes? kilobytes? (default is 2097000)
+
+@item GUILE_INIT_HEAP_SIZE_1
+@vindex GUILE_INIT_HEAP_SIZE_1
+Please provide a description of me.
+
+@item GUILE_INIT_HEAP_SIZE_2
+@vindex GUILE_INIT_HEAP_SIZE_2
+Please provide a description of me.
+
+@item GUILE_WARN_DEPRECATED
+@vindex GUILE_WARN_DEPRECATED
+Please provide a description of me.
+
+@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
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #5: 0004-doc-ref-indices.texi-Minor-corrections-to-the-text-a.patch --]
[-- Type: text/x-patch; name="0004-doc-ref-indices.texi-Minor-corrections-to-the-text-a.patch", Size: 2138 bytes --]
From df3a3a01f243dbdb19b1409ead3adf1fd7582b13 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sat, 23 Apr 2011 14:20:58 -0400
* doc/ref/indices.texi: Minor corrections to the text and cross
references.
---
doc/ref/indices.texi | 14 +++++++-------
1 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/doc/ref/indices.texi b/doc/ref/indices.texi
index afe571f..b114450 100644
--- a/doc/ref/indices.texi
+++ b/doc/ref/indices.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -8,8 +8,8 @@
@node Concept Index
@unnumbered Concept Index
-This index contains concepts, keywords and non-Schemey names for several
-features, to make it easier to locate the desired sections.
+This index contains concepts, keywords, and non-Schemey names for
+several features to make it easier to locate the desired sections.
@printindex cp
@@ -25,8 +25,8 @@ It also includes Guile's Autoconf macros.
When looking for a particular procedure, please look under its Scheme
name as well as under its C name. The C name can be constructed from
-the Scheme names by a simple transformation described in the section
-@xref{API Overview}.
+the Scheme names by a simple transformation described in the API
+Reference (@pxref{API Overview}).
@printindex fn
@@ -43,7 +43,7 @@ constants in Guile.
When looking for a particular variable or constant, please look under
its Scheme name as well as under its C name. The C name can be
constructed from the Scheme names by a simple transformation described
-in the section @xref{API Overview}.
+in the API Reference (@pxref{API Overview}).
@printindex vr
@@ -53,7 +53,7 @@ in the section @xref{API Overview}.
@unnumbered Type Index
This is an alphabetical list of all the important data types defined in
-the Guile Programmers Manual.
+the Guile Reference Manual.
@printindex tp
--
1.7.4.4
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #6: 0005-Corrected-some-cross-references-that-had-parentheses.patch --]
[-- Type: text/x-patch; name="0005-Corrected-some-cross-references-that-had-parentheses.patch", Size: 1985 bytes --]
From b4c4533eaf8d3994f24cddfb529dadff9187d877 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Sat, 23 Apr 2011 14:53:03 -0400
* Corrected some cross references that had parentheses around the node
name, which made the cross references invalid.
---
doc/ref/r6rs.texi | 10 +++++-----
1 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index bc569ed..5f31ef9 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -8,8 +8,8 @@
@section R6RS Support
@cindex R6RS
-@xref{R6RS Libraries}, for more information on how to define R6RS libraries, and
-their integration with Guile modules.
+@xref{R6RS Libraries}, for more information on how to define R6RS
+libraries, and their integration with Guile modules.
@menu
* R6RS Incompatibilities:: Guile mostly implements R6RS.
@@ -1584,7 +1584,7 @@ fixnum.
@deffnx {Scheme Procedure} fxdiv0 fx1 fx2
@deffnx {Scheme Procedure} fxmod0 fx1 fx2
These procedures implement number-theoretic division on fixnums;
-@xref{(rnrs base)}, for a description of their semantics.
+@xref{rnrs base}, for a description of their semantics.
@end deffn
@deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
@@ -1770,7 +1770,7 @@ Returns the absolute value of @var{fl}.
@deffnx {Scheme Procedure} fldiv0 fl1 fl2
@deffnx {Scheme Procedure} flmod0 fl1 fl2
These procedures implement number-theoretic division on flonums;
-@xref{(rnrs base)}, for a description for their semantics.
+@xref{rnrs base}, for a description for their semantics.
@end deffn
@deffn {Scheme Procedure} flnumerator fl
@@ -1800,7 +1800,7 @@ library. @xref{Arithmetic}, for documentation.
@deffnx {Scheme Procedure} flatan fl1 fl2
These procedures, which compute the usual transcendental functions, are
the flonum variants of the procedures provided by the R6RS base library
-(@pxref{(rnrs base)}).
+(@pxref{rnrs base}).
@end deffn
@deffn {Scheme Procedure} flsqrt fl
--
1.7.4.4
[-- Attachment #7: invoking-guile.txt --]
[-- Type: text/plain, Size: 14351 bytes --]
4.2 Invoking Guile
==================
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...'
Read and evaluate Scheme source code from the file SCRIPT, as the
`load' function would. After loading SCRIPT, exit. 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...)'.
`-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 number 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 using this option.
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. Don't use
`--listen' on multi-user machines. Of course, if you don't 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, see *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's how to set the environment variable `ORGANIZATION' to
`not very much' using Bash:
export ORGANIZATION="not very much"
and here's how to do it in csh or tcsh:
setenv ORGANIZATION "not very much"
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 *Note Runtime Environment::.
Here are the environment variables that effect 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_HUSH'
The `#/' 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 `GUILE_HUSH' environment
variable to any non-empty value.
`GUILE_INIT_MALLOC_LIMIT'
`GUILE_MIN_YIELD_MALLOC'
The garbage collector uses lazy sweeping. This is reflected in the
output of the procedure `gc-stats'; since cells are being freed
when they are allocated, the cells-allocated field stays roughly
constant.
For malloc-related triggers, the garbage collector uses the same
heuristic as the cell-triggered collections. It may be tuned with
the environment variable `GUILE_MIN_YIELD_MALLOC'. This is the
percentage for minimum yield of malloc-related triggers. The
default is forty (40) percent.
`GUILE_INIT_MALLOC_LIMIT' sets the size in kilobytes of the initial
trigger for garbage collection. The default is two hundred (200)
kilobytes.
`GUILE_MAX_SEGMENT_SIZE'
`GUILE_INIT_SEGMENT_SIZE_2'
`GUILE_INIT_SEGMENT_SIZE_1'
`GUILE_MIN_YIELD_2'
Debugging operations for the freelist have been deprecated, along
with the C variables that control garbage collection. The
environment variables `GUILE_MAX_SEGMENT_SIZE',
`GUILE_INIT_SEGMENT_SIZE_2', `GUILE_INIT_SEGMENT_SIZE_1', and
`GUILE_MIN_YIELD_2' should be used (units: bytes? kilobytes?)
`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_SYSTEM_LOAD_COMPILED_PATH'
Please provide a description of me, or delete me if I am obsolete.
`GUILE_SYSTEM_PATH'
Please provide a description of me, or delete me if I am obsolete.
`GUILE_SYSTEM_LTDL_PATH'
Please provide a description of me, or delete me if I am obsolete.
`GUILE_INIT_SEGMENT_SIZE_1'
The application can set up other default values for the
garbage-collection heap allocation parameters. Allocation of
two-word cell heaps is controlled by the environment variables
`GUILE_INIT_SEGMENT_SIZE_1' and `GUILE_MIN_YIELD_1'.
`GUILE_INIT_SEGMENT_SIZE_1' is the size of initial heap segment in
bytes (default is 360000).
`GUILE_MIN_YIELD_1'
Minimum number of freed cells at each garbage collection in
percent of total heap size (default is forty (40) percent).
`GUILE_INIT_SEGMENT_SIZE_2'
Allocation of four-word cell heaps is controlled by the environment
variables `GUILE_INIT_SEGMENT_SIZE_2' and `GUILE_MIN_YIELD_2'.
Four-word cell heaps are used for real numbers and miscellaneous
other objects.
Please provide a description of `GUILE_INIT_SEGMENT_SIZE_2'.
`GUILE_MIN_YIELD_2'
Please provide a description of `GUILE_MIN_YIELD_2'.
`GUILE_MAX_SEGMENT_SIZE'
Maximal segment size in bytes? kilobytes? (default is 2097000)
`GUILE_INIT_HEAP_SIZE_1'
Please provide a description of me.
`GUILE_INIT_HEAP_SIZE_2'
Please provide a description of me.
`GUILE_WARN_DEPRECATED'
Please provide a description of me.
`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'.
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-23 19:46 Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Mark Harig
@ 2011-04-24 14:33 ` Andy Wingo
2011-04-24 20:36 ` Mark Harig
0 siblings, 1 reply; 20+ messages in thread
From: Andy Wingo @ 2011-04-24 14:33 UTC (permalink / raw)
To: Mark Harig; +Cc: guile-devel
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.
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. Use @itemx in this case, I think.
> +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.
> +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".
> +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"
> +@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.
> +@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.
> +@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.
> +@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.
> +@item GUILE_WARN_DEPRECATED
> +@vindex GUILE_WARN_DEPRECATED
> +Please provide a description of me.
@ref to Deprecation.
wingo@unquote:~/src/guile$ meta/guile
GNU Guile 2.0.0.202-514ff6
Copyright (C) 1995-2011 Free Software Foundation, Inc.
Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
This program is free software, and you are welcome to redistribute it
under certain conditions; type `,show c' for details.
Enter `,help' for help.
scheme@(guile-user)> (feature? 'foo)
$1 = #f
scheme@(guile-user)>
Some deprecated features have been used. Set the environment
variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
program to get more information. Set it to "no" to suppress
this message.
wingo@unquote:~/src/guile$ GUILE_WARN_DEPRECATED=detailed meta/guile
GNU Guile 2.0.0.202-514ff6
Copyright (C) 1995-2011 Free Software Foundation, Inc.
Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
This program is free software, and you are welcome to redistribute it
under certain conditions; type `,show c' for details.
Enter `,help' for help.
scheme@(guile-user)> (feature? 'foo)
`feature?' is deprecated. Use `provided?' instead.
$1 = #f
scheme@(guile-user)>
wingo@unquote:~/src/guile$
Otherwise, looking very good. Thank you for this work, and looking
forward to the revised patchset :-)
Cheers,
Andy
--
http://wingolog.org/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-24 14:33 ` Andy Wingo
@ 2011-04-24 20:36 ` Mark Harig
2011-04-24 21:00 ` Andy Wingo
0 siblings, 1 reply; 20+ messages in thread
From: Mark Harig @ 2011-04-24 20:36 UTC (permalink / raw)
To: wingo; +Cc: guile-devel
[-- 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'.
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-24 20:36 ` Mark Harig
@ 2011-04-24 21:00 ` Andy Wingo
2011-04-24 21:58 ` Mark Harig
` (2 more replies)
0 siblings, 3 replies; 20+ messages in thread
From: Andy Wingo @ 2011-04-24 21:00 UTC (permalink / raw)
To: Mark Harig; +Cc: guile-devel
Hi Mark,
Thanks for the revisions.
On Sun 24 Apr 2011 22:36, Mark Harig <idirectscm@aim.com> writes:
> On Sun, Apr 24, 2011 at 04:33:44PM +0200, Andy Wingo wrote:
>> your patches should be "atomic"
>
> "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."
Right, at the end of applying all of your patches, I'm sure that's the
case; however the first patch adds an @include without adding the
appropriate file, so applying just the first patch without the following
two would yield a project that doesn't compile. I just meant that you
need to squish the first two or three of them together. I can do that
when I apply them, though.
By @itemx I just meant to do instead of:
> +@item -s @var{script} @var{arg...}
you would
@item @var{script} @var{arg...}
@itemx -s @var{script} @var{arg}
The other option would be
@item [-s] @var{script} @var{arg}
which is not as clear IMO. I feel that it's important to have a good
example up there, and making it clear that it's OK to just invoke Guile
as "guile foo.scm" is important. But your description is good too.
> +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}.
Again, probably worth eliding the deprecated 1.4 stuff...
> +@item --auto-compile
> +Compile source files automatically (default behavior).
> +
> +@vnew{2.0}
> +
> +@item --no-auto-compile
> +Disable automatic source file compilation.
> +
> +@vnew{2.0}
Need --fresh-auto-compile here too
> +@item GUILE_AUTO_COMPILE
> +@vindex GUILE_AUTO_COMPILE
Need to note GUILE_AUTO_COMPILE=fresh, and @ref to Compilation
Best regards,
Andy
--
http://wingolog.org/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-24 21:00 ` Andy Wingo
@ 2011-04-24 21:58 ` Mark Harig
2011-04-25 8:01 ` Andy Wingo
2011-04-24 22:09 ` David Pirotte
2011-04-25 19:49 ` Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Mark Harig
2 siblings, 1 reply; 20+ messages in thread
From: Mark Harig @ 2011-04-24 21:58 UTC (permalink / raw)
To: wingo; +Cc: guile-devel
[-- Attachment #1: Type: text/plain, Size: 4216 bytes --]
On Sun, Apr 24, 2011 at 11:00:16PM +0200, Andy Wingo wrote:
> Hi Mark,
>
> Thanks for the revisions.
>
> On Sun 24 Apr 2011 22:36, Mark Harig <idirectscm@aim.com> writes:
>
> > On Sun, Apr 24, 2011 at 04:33:44PM +0200, Andy Wingo wrote:
> >> your patches should be "atomic"
> >
> > "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."
>
> Right, at the end of applying all of your patches, I'm sure that's the
> case; however the first patch adds an @include without adding the
> appropriate file, so applying just the first patch without the following
> two would yield a project that doesn't compile. I just meant that you
> need to squish the first two or three of them together. I can do that
> when I apply them, though.
>
What do guile developers normally do when generating the
patches? ('git format-patch origin' is generating three
separate files. Do you concatenate the patch files that
'git' emits?) Please let me know if there is a documented
recipe that guile-devel uses that I can follow for future
changes.
> By @itemx I just meant to do instead of:
>
> > +@item -s @var{script} @var{arg...}
>
> you would
>
> @item @var{script} @var{arg...}
> @itemx -s @var{script} @var{arg}
>
> The other option would be
>
> @item [-s] @var{script} @var{arg}
>
> which is not as clear IMO. I feel that it's important to have a good
> example up there, and making it clear that it's OK to just invoke Guile
> as "guile foo.scm" is important. But your description is good too.
Thanks for the clarification. I will add the two-line @item/@itemx pair.
>
> > +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}.
>
> Again, probably worth eliding the deprecated 1.4 stuff...
>
It's not clear to me what you mean here. Please provide the
text that you would like. (I did not review the
"command-line options" section for content because my
original proposal was to keep that section and add a missing
"environment variables" section.)
> > +@item --auto-compile
> > +Compile source files automatically (default behavior).
> > +
> > +@vnew{2.0}
> > +
> > +@item --no-auto-compile
> > +Disable automatic source file compilation.
> > +
> > +@vnew{2.0}
>
> Need --fresh-auto-compile here too
>
> > +@item GUILE_AUTO_COMPILE
> > +@vindex GUILE_AUTO_COMPILE
>
> Need to note GUILE_AUTO_COMPILE=fresh, and @ref to Compilation
>
I do not know what that option does (other than a guess).
There has been no update to the Guile manual page or the
reference manual mentioning it.
It appears that this "fresh" feature (no pun intended) has
been added since Guile 2.0.0. 'guile --help' does not
mention it for Guile 2.0.0. I will add the text to update
my patches, if wanted, but I need for someone to provide me
with the text that they would like (i.e., the specification
for what the user should know). Alternatively, they could
be added independently by a separate patch.
Once the "environment variables" section has been added to
the Guile Reference Manual, developers should be able to add
updates about them as part of an "atomic" patch that
describes the new feature and implements it. Depending on
the change, this might involve updating:
1) The text of the Guile Reference Manual
2) The text provided by Guile's "--help" option
3) The text of the Guile manual page
4) The NEWS file: to describe new features and mark
features as deprecated or obsolete.
--
[-- Attachment #2: Type: text/html, Size: 5055 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-24 21:00 ` Andy Wingo
2011-04-24 21:58 ` Mark Harig
@ 2011-04-24 22:09 ` David Pirotte
2011-04-24 22:43 ` Indexing Scheme and C identifiers separately Mark Harig
2011-04-25 19:49 ` Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Mark Harig
2 siblings, 1 reply; 20+ messages in thread
From: David Pirotte @ 2011-04-24 22:09 UTC (permalink / raw)
To: Andy Wingo; +Cc: Mark Harig, guile-devel
Le Sun, 24 Apr 2011 23:00:16 +0200,
Andy Wingo <wingo@pobox.com> a écrit :
> Hi Mark,
>
> Thanks for the revisions.
> ..
Hello Mark,
Andy,
While you are at the manual, may I point to some suggestion I made about the
structure and contents of the indexes which still is, IMHO, valid today. [wanted to
actually really point the email in guile-devel archive but but it didn't let me parse
before october 2009 ...]
I didn't and still don't have [yet] the skill to fluently and bug freely manipulate
large doc written in texinfo, otherwise I would have done it.
Cheers,
David
;;;
;;; here below, the 'most appropriate' email from the thread, I think
;;;
From: "Neil Jerram" <neiljerram@googlemail.com>
To: "David Séverin" <david@altosw.be>
Cc: guile-devel <guile-devel@gnu.org>
Subject: Re: Plan for 2.0
Date: Mon, 5 Jan 2009 13:47:00 +0000
2009/1/4 Neil Jerram <neiljerram@googlemail.com>:
> 2009/1/4 David Séverin <david@altosw.be>:
>> Hi Guilers,
>>
>> It might be a small thing [and of course not a priority at all], but I'd love to
>> see a small evolution of the manual index structure in order to separate scheme
>> procedures from others, scheme variables from others...:
>>
>> * Concept Index
>> * Scheme Prodedure Index * C Procedure Index
>> * Scheme Variable Index * C Variable Index
>> * Scheme Type Index * C Type Index
>> * R5RS Index
>>
>> Being a scheme 'only' programmer, I'd love not to have to scroll through
>> gh_* and scm_* ... when I am looking for something in an index.
>
> Thanks for this idea!
>
> I'm not persuaded by the procedure/variable/type separation
I'm sorry, that's complete nonsense, as we already have the
procedure/variable/type separation.
So in fact now I completely agree with what you've suggested.
Regards,
Neil
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Indexing Scheme and C identifiers separately
2011-04-24 22:09 ` David Pirotte
@ 2011-04-24 22:43 ` Mark Harig
2011-04-25 1:18 ` Noah Lavine
2011-04-25 16:16 ` David Pirotte
0 siblings, 2 replies; 20+ messages in thread
From: Mark Harig @ 2011-04-24 22:43 UTC (permalink / raw)
To: david, wingo; +Cc: guile-devel
[-- Attachment #1: Type: text/plain, Size: 2669 bytes --]
On Sun, Apr 24, 2011 at 07:09:07PM -0300, David Pirotte wrote:
> While you are at the manual, may I point to some
> suggestion I made about the structure and contents of the
> indexes which still is, IMHO, valid today. [wanted to
> actually really point the email in guile-devel archive but
> but it didn't let me parse before october 2009 ...]
>
> I didn't and still don't have [yet] the skill to fluently
> and bug freely manipulate large doc written in texinfo,
> otherwise I would have done it.
>
> Cheers,
> David
>
> >> Hi Guilers,
> >>
> >> It might be a small thing [and of course not a priority
> >> at all], but I'd love to see a small evolution of the
> >> manual index structure in order to separate scheme
> >> procedures from others, scheme variables from
> >> others...:
> >>
> >> * Concept Index
> >> * Scheme Prodedure Index * C Procedure Index
> >> * Scheme Variable Index * C Variable Index
> >> * Scheme Type Index * C Type Index
> >> * R5RS Index
> >>
> >> Being a scheme 'only' programmer, I'd love not to have
> >> to scroll through gh_* and scm_* ... when I am looking
> >> for something in an index.
I do not know how you are reading the Guile Reference
Manual, but the printed version is about 809 pages long. At
present, the indices run from page 755 to 809, so the
revision that is suggested, above, would not be small.
What would be of some help to get this project started is a
list of the identifiers:
1) A list of all Scheme procedure names
2) A list of all C procedure names
3) A list of all Scheme variable names
4) A list of all C variable names
5) A list of all Scheme type names
6) A list of all C type names
(By "all names", I mean "all names included in the Guile
Reference Manual", not, for example, "all C function names
in Standard C".)
To make the project more manageable, it could be done in
"atomic" sets.
1) Set 1 would be all Scheme and C procedure names
2) Set 2 would be all Scheme and C variable names
3) Set 3 would be all Scheme and C type names
Each of these sets could be added to the manual
independently over a period of time.
Also useful would be more suggestions for the Concept Index.
If you are using the reference manual and attempt to look
something up via the `Info-index' or `Info-virtual-index'
commands and are not able to locate what you are looking
for, then that is a good candidate for a report to the
bug-guile mailing list. A `@cindex' entry can then be added
to the appropriate locations in the manual, making it more
useful and easier to use.
--
[-- Attachment #2: Type: text/html, Size: 3302 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Indexing Scheme and C identifiers separately
2011-04-24 22:43 ` Indexing Scheme and C identifiers separately Mark Harig
@ 2011-04-25 1:18 ` Noah Lavine
2011-04-25 16:16 ` David Pirotte
1 sibling, 0 replies; 20+ messages in thread
From: Noah Lavine @ 2011-04-25 1:18 UTC (permalink / raw)
To: Mark Harig; +Cc: wingo, guile-devel, david
Hello,
> I do not know how you are reading the Guile Reference
> Manual, but the printed version is about 809 pages long. At
> present, the indices run from page 755 to 809, so the
> revision that is suggested, above, would not be small.
>
> What would be of some help to get this project started is a
> list of the identifiers:
>
> 1) A list of all Scheme procedure names
> 2) A list of all C procedure names
> 3) A list of all Scheme variable names
> 4) A list of all C variable names
> 5) A list of all Scheme type names
> 6) A list of all C type names
>
> (By "all names", I mean "all names included in the Guile
> Reference Manual", not, for example, "all C function names
> in Standard C".)
Perhaps I am misunderstanding you, but I am afraid that you are not
aware that the indices are generated automatically. The relevant file
is "<guile-source>/doc/ref/indices.texi. It contains three
"@printindex" commands, which I suspect generate the indices.
Therefore the way to do this is not to remake the indices ourselves,
but to change the texinfo code that generates them for us.
Unfortunately, I do not know enough about texinfo to know what is
involved in this.
So the good news is that it will be much less work than it might seem
to re-do this. The bad news is that someone has to learn texinfo,
unless one of us already knows it.
Noah
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-24 21:58 ` Mark Harig
@ 2011-04-25 8:01 ` Andy Wingo
0 siblings, 0 replies; 20+ messages in thread
From: Andy Wingo @ 2011-04-25 8:01 UTC (permalink / raw)
To: Mark Harig; +Cc: guile-devel
Hi Mark,
On Sun 24 Apr 2011 23:58, Mark Harig <idirectscm@aim.com> writes:
> On Sun, Apr 24, 2011 at 11:00:16PM +0200, Andy Wingo wrote:
>>
>> Right, at the end of applying all of your patches, I'm sure that's the
>> case; however the first patch adds an @include without adding the
>> appropriate file, so applying just the first patch without the following
>> two would yield a project that doesn't compile. I just meant that you
>> need to squish the first two or three of them together. I can do that
>> when I apply them, though.
>>
>
> What do guile developers normally do when generating the
> patches? ('git format-patch origin' is generating three
> separate files. Do you concatenate the patch files that
> 'git' emits?) Please let me know if there is a documented
> recipe that guile-devel uses that I can follow for future
> changes.
We use git-format-patch, yes. The separate files that it generates
correspond to the separate git commits that you made. In order to
generate an atomic commit, you will need to squash your patches
together. To do this, do an interactive rebase in git.
Interactive rebase is described here:
http://book.git-scm.com/4_interactive_rebasing.html
You would "pick" the first patch, then "squash" the next two. That
would yield one atomic commit, which would then be written by
git-format-patch into one atomic patch.
I highly recommend reading more, experimenting, making backups, etc;
rebase is wonderful once you get the hang of it, but it is a sharp
tool. Good luck!
>> > +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}.
>>
>> Again, probably worth eliding the deprecated 1.4 stuff...
>>
>
> It's not clear to me what you mean here. Please provide the
> text that you would like. (I did not review the
> "command-line options" section for content because my
> original proposal was to keep that section and add a missing
> "environment variables" section.)
I recommend removing this paragraph, or removing mentions of Guile 1.4.
But as you note, that could be a separate atomic commit, and you don't
have to take care of that now.
>> > +@item --auto-compile
>> > +Compile source files automatically (default behavior).
>> > +
>> > +@vnew{2.0}
>> > +
>> > +@item --no-auto-compile
>> > +Disable automatic source file compilation.
>> > +
>> > +@vnew{2.0}
>>
>> Need --fresh-auto-compile here too
>>
>> > +@item GUILE_AUTO_COMPILE
>> > +@vindex GUILE_AUTO_COMPILE
>>
>> Need to note GUILE_AUTO_COMPILE=fresh, and @ref to Compilation
>>
>
> I do not know what that option does (other than a guess).
> There has been no update to the Guile manual page or the
> reference manual mentioning it.
Are you working off of the "stable-2.0" branch? There are updates there
for --fresh-auto-compile and GUILE_AUTO_COMPILE=fresh.
To rebase your work onto that branch, you would do a "git rebase
origin/stable-2.0".
Regards,
Andy
--
http://wingolog.org/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Indexing Scheme and C identifiers separately
2011-04-24 22:43 ` Indexing Scheme and C identifiers separately Mark Harig
2011-04-25 1:18 ` Noah Lavine
@ 2011-04-25 16:16 ` David Pirotte
2011-05-20 22:53 ` Neil Jerram
1 sibling, 1 reply; 20+ messages in thread
From: David Pirotte @ 2011-04-25 16:16 UTC (permalink / raw)
To: Mark Harig; +Cc: guile-devel
Hello Mark,
Le Sun, 24 Apr 2011 18:43:54 -0400,
Mark Harig <idirectscm@aim.com> a écrit :
> On Sun, Apr 24, 2011 at 07:09:07PM -0300, David Pirotte wrote:
[...]
> What would be of some help to get this project started is a
> list of the identifiers:
>
> 1) A list of all Scheme procedure names
> 2) A list of all C procedure names
> 3) A list of all Scheme variable names
> 4) A list of all C variable names
> 5) A list of all Scheme type names
> 6) A list of all C type names
Yes, that's what I meant. What you get, looking at
http://www.gnu.org/software/guile/docs/docs-2.0/guile-ref/index.html, is ...
Looking at 'Procedure Index', for example not really knowing what your looking for
but presumably starting with letter 's', as a 'pure' scheme programmer, reaching
scm-xxx, you'll have to hit more or less 33 times page down [depending on your
display and browser size obviously] to 'continue' with other 'scheme' indice entries
[they may be other entries, at the beginning they are *scm_]. If you realize you
probably have passed and missed the item you're looking for, you'll have to hit 33
times page-up ... not a big deal but it would be really nice to have 'per language'
indices.
If [and only if :-)] it can be easily done [which I assumed, but ...], i would
suggest the following [assuming a 'grouping' by language but i don't have a problem
if it is by 'proc' 'var' and 'type'
Indices
. Concept Index
. Scheme Procedure Index
. Scheme Variable Index
. Scheme Type Index
. C Procedure Index
. C Variable Index
. C Type index
. R5RS Index
> (By "all names", I mean "all names included in the Guile
> Reference Manual", not, for example, "all C function names
> in Standard C".)
Thanks God :-)
> Also useful would be more suggestions for the Concept Index.
> ...
I will if and when I have a useful comment to make but so far I think it really is
good.
Many thanks for your work on the manual.
Cheers,
David
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-24 21:00 ` Andy Wingo
2011-04-24 21:58 ` Mark Harig
2011-04-24 22:09 ` David Pirotte
@ 2011-04-25 19:49 ` Mark Harig
2011-04-26 18:07 ` Neil Jerram
2011-06-30 11:23 ` Andy Wingo
2 siblings, 2 replies; 20+ messages in thread
From: Mark Harig @ 2011-04-25 19:49 UTC (permalink / raw)
To: wingo; +Cc: guile-devel
[-- Attachment #1.1: Type: text/plain, Size: 2948 bytes --]
>
> > On Sun, Apr 24, 2011 at 04:33:44PM +0200, Andy Wingo wrote:
> >> your patches should be "atomic"
> >
> > "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."
>
> Right, at the end of applying all of your patches, I'm sure that's the
> case; however the first patch adds an @include without adding the
> appropriate file, so applying just the first patch without the following
> two would yield a project that doesn't compile. I just meant that you
> need to squish the first two or three of them together. I can do that
> when I apply them, though.
>
> By @itemx I just meant to do instead of:
>
> > +@item -s @var{script} @var{arg...}
>
> you would
>
> @item @var{script} @var{arg...}
> @itemx -s @var{script} @var{arg}
>
> The other option would be
>
> @item [-s] @var{script} @var{arg}
>
> which is not as clear IMO. I feel that it's important to have a good
> example up there, and making it clear that it's OK to just invoke Guile
> as "guile foo.scm" is important. But your description is good too.
OK. I have added an '@itemx' entry to distinguish between the usual
case and the special case.
>
> > +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}.
>
> Again, probably worth eliding the deprecated 1.4 stuff...
>
OK. I'm not going to change anything here (not that I disagree).
I'll leave that for someone to make a separate change.
> > +@item --auto-compile
> > +Compile source files automatically (default behavior).
> > +
> > +@vnew{2.0}
> > +
> > +@item --no-auto-compile
> > +Disable automatic source file compilation.
> > +
> > +@vnew{2.0}
>
> Need --fresh-auto-compile here too
>
> > +@item GUILE_AUTO_COMPILE
> > +@vindex GUILE_AUTO_COMPILE
>
> Need to note GUILE_AUTO_COMPILE=fresh, and @ref to Compilation
>
OK. Added an entry to the command-line options section and updated
the description in GUILE_AUTO_COMPILE.
In order to expedite this change, I am attaching the three updated patches.
---
P.S., My original patch set contained two additional patches that can be
applied separately and independently. They correct errors that I found
in unrelated files while checking the changes in this patch set.
[-- Attachment #1.2: Type: text/html, Size: 4138 bytes --]
[-- Attachment #2: 0001-doc-ref-guile.texi-node-Programming-in-Scheme-Added-.patch --]
[-- Type: text/x-patch, Size: 1867 bytes --]
From 4f69c9dc751408bb89a28f17c289e87de075aca8 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Mon, 25 Apr 2011 11:33:22 -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: 8339 bytes --]
From 6a09439e3e87191de1fa8bd93fd825d46f32160c Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Mon, 25 Apr 2011 13:56:26 -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 | 173 -------------------------------------------
1 files changed, 0 insertions(+), 173 deletions(-)
diff --git a/doc/ref/scheme-scripts.texi b/doc/ref/scheme-scripts.texi
index c7d22a4..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,178 +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.1}
-
-@item --fresh-auto-compile
-Treat the auto-compilation cache as invalid, forcing recompilation.
-
-@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: 15442 bytes --]
From 80c6fd67b228ea8685def8ca4305bec9cdd98cd9 Mon Sep 17 00:00:00 2001
From: Mark Harig <idirectscm@aim.com>
Date: Mon, 25 Apr 2011 13:58:56 -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 and which affect
Guile's run-time behavior.
---
doc/ref/guile-invoke.texi | 355 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 355 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..9379a8b
--- /dev/null
+++ b/doc/ref/guile-invoke.texi
@@ -0,0 +1,355 @@
+@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 @var{script} @var{arg...}
+@itemx -s @var{script} @var{arg...}
+@cindex script mode
+By default, Guile will read a file named on the command line as a
+script. 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...})}.
+
+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.
+
+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.1}
+
+@item --fresh-auto-compile
+Treat the auto-compilation cache as invalid, forcing recompilation.
+
+@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 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.
+
+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.
+
+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.
+
+Set @env{GUILE_AUTO_COMPILE} to zero (0), to prevent Scheme files from
+being compiled automatically. Set this variable to ``fresh'' to tell
+Guile to compile Scheme files whether they are newer than the compiled
+files or not.
+
+@xref{Compilation}.
+
+@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
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-25 19:49 ` Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Mark Harig
@ 2011-04-26 18:07 ` Neil Jerram
2011-04-26 21:01 ` Ludovic Courtès
2011-04-27 16:54 ` Mark Harig
2011-06-30 11:23 ` Andy Wingo
1 sibling, 2 replies; 20+ messages in thread
From: Neil Jerram @ 2011-04-26 18:07 UTC (permalink / raw)
To: Mark Harig; +Cc: wingo, guile-devel
Hi Mark,
FWIW, these patches look great to me; I just have two minor comments,
inline below. It's great to have someone looking at the manual material
with such a careful eye for detail.
Just one meta-thing that occurred to me: can we all agree on a value for
fill-column, so as to avoid spurious M-q diffs? And, if we can
agree on that, is there a neat way of helping people to use it? - some
kind of local variables setup, I suppose.
Mark Harig <idirectscm@aim.com> writes:
> From 80c6fd67b228ea8685def8ca4305bec9cdd98cd9 Mon Sep 17 00:00:00 2001
[...]
> +@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}.
You inserted a comma here before "@var{symbol})}, and in that case". I
agree that a comma was needed, but would have put it as "@var{symbol})}
and, in that case, the ...". What do you think?
> +@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.
Is it useful to say "Starting with Guile 2.0" in a post-2.0.0 version of
the manual? I think that expression could be deleted now.
Regards,
Neil
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-26 18:07 ` Neil Jerram
@ 2011-04-26 21:01 ` Ludovic Courtès
2011-04-27 9:40 ` Andy Wingo
2011-04-27 16:54 ` Mark Harig
1 sibling, 1 reply; 20+ messages in thread
From: Ludovic Courtès @ 2011-04-26 21:01 UTC (permalink / raw)
To: guile-devel
Hi Neil,
Neil Jerram <neil@ossau.uklinux.net> writes:
> Just one meta-thing that occurred to me: can we all agree on a value for
> fill-column, so as to avoid spurious M-q diffs? And, if we can
> agree on that, is there a neat way of helping people to use it? - some
> kind of local variables setup, I suppose.
It can be put in .dir-locals.el (info "(emacs) Directory Variables").
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-26 21:01 ` Ludovic Courtès
@ 2011-04-27 9:40 ` Andy Wingo
2011-04-27 10:23 ` Ludovic Courtès
0 siblings, 1 reply; 20+ messages in thread
From: Andy Wingo @ 2011-04-27 9:40 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: guile-devel
On Tue 26 Apr 2011 23:01, ludo@gnu.org (Ludovic Courtès) writes:
> Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> Just one meta-thing that occurred to me: can we all agree on a value for
>> fill-column, so as to avoid spurious M-q diffs? And, if we can
>> agree on that, is there a neat way of helping people to use it? - some
>> kind of local variables setup, I suppose.
>
> It can be put in .dir-locals.el (info "(emacs) Directory Variables").
Yeah. In fact it is there, in the root .dir-locals.el, as 72. Is that
sufficient?
Andy
--
http://wingolog.org/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-27 9:40 ` Andy Wingo
@ 2011-04-27 10:23 ` Ludovic Courtès
2011-04-27 19:29 ` Neil Jerram
0 siblings, 1 reply; 20+ messages in thread
From: Ludovic Courtès @ 2011-04-27 10:23 UTC (permalink / raw)
To: Andy Wingo; +Cc: guile-devel
Hi!
Andy Wingo <wingo@pobox.com> writes:
> On Tue 26 Apr 2011 23:01, ludo@gnu.org (Ludovic Courtès) writes:
>
>> Neil Jerram <neil@ossau.uklinux.net> writes:
>>
>>> Just one meta-thing that occurred to me: can we all agree on a value for
>>> fill-column, so as to avoid spurious M-q diffs? And, if we can
>>> agree on that, is there a neat way of helping people to use it? - some
>>> kind of local variables setup, I suppose.
>>
>> It can be put in .dir-locals.el (info "(emacs) Directory Variables").
>
> Yeah. In fact it is there, in the root .dir-locals.el, as 72. Is that
> sufficient?
Oh right, should be enough, yes.
Ludo’.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-26 18:07 ` Neil Jerram
2011-04-26 21:01 ` Ludovic Courtès
@ 2011-04-27 16:54 ` Mark Harig
2011-04-27 19:40 ` Neil Jerram
1 sibling, 1 reply; 20+ messages in thread
From: Mark Harig @ 2011-04-27 16:54 UTC (permalink / raw)
To: neil; +Cc: wingo, guile-devel
[-- Attachment #1: Type: text/plain, Size: 2787 bytes --]
>
> > From 80c6fd67b228ea8685def8ca4305bec9cdd98cd9 Mon Sep 17 00:00:00 2001
> [...]
> > +@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}.
>
> You inserted a comma here before "@var{symbol})}, and in that case". I
> agree that a comma was needed, but would have put it as "@var{symbol})}
> and, in that case, the ...". What do you think?
>
Is the sentence of the form 1) "A and B" or of the form 2) "A, and some
supplemental information about A"? I think it is 2). Then, you are
left with the choice of how many commas:
1) "A, and, in that case, B"
2) "A, and in that case, B"
3) "A and, in that case, B"
Either choice 1) or 2) gets my vote. Choice 3) is, I think, an error.
Another perspective: Re-write the sentence, replacing "and in that
case" with "in which case." This should make it clearer that the
sentence consists of a main clause and a sub-clause (preceded by a
comma), not two main clauses.
> > +@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.
>
> Is it useful to say "Starting with Guile 2.0" in a post-2.0.0 version of
> the manual? I think that expression could be deleted now.
>
That's a consequence of the fact that I looked up what information I
could find from the NEWS file, and then used that text as an initial
version.
I agree that it's not the best solution to the problem, but the
problem is "how does the manual convey to long-time Guile users this
change in behavior?" I do not have a good solution to that in this
brief patch. For now, experienced users will and should rely on the
NEWS file to inform them about changes in behavior.
---
[-- Attachment #2: Type: text/html, Size: 3411 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-27 10:23 ` Ludovic Courtès
@ 2011-04-27 19:29 ` Neil Jerram
0 siblings, 0 replies; 20+ messages in thread
From: Neil Jerram @ 2011-04-27 19:29 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: Andy Wingo, guile-devel
ludo@gnu.org (Ludovic Courtès) writes:
>>> It can be put in .dir-locals.el (info "(emacs) Directory Variables").
>>
>> Yeah. In fact it is there, in the root .dir-locals.el, as 72. Is that
>> sufficient?
>
> Oh right, should be enough, yes.
OK, that's fine then; that means we'll naturally asymptote towards a
situation where there aren't any more reflowing diffs.
Thanks!
Neil
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-27 16:54 ` Mark Harig
@ 2011-04-27 19:40 ` Neil Jerram
0 siblings, 0 replies; 20+ messages in thread
From: Neil Jerram @ 2011-04-27 19:40 UTC (permalink / raw)
To: Mark Harig; +Cc: wingo, guile-devel
Mark Harig <idirectscm@aim.com> writes:
>> > +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}.
>>
>> You inserted a comma here before "@var{symbol})}, and in that case". I
>> agree that a comma was needed, but would have put it as "@var{symbol})}
>> and, in that case, the ...". What do you think?
>>
>
> Is the sentence of the form 1) "A and B" or of the form 2) "A, and some
> supplemental information about A"? I think it is 2). Then, you are
> left with the choice of how many commas:
>
> 1) "A, and, in that case, B"
> 2) "A, and in that case, B"
> 3) "A and, in that case, B"
>
> Either choice 1) or 2) gets my vote. Choice 3) is, I think, an error.
I'm not sure it's completely clearcut but yes, I see your point. In
that case I might technically favour 1), but then that's a lot of
commas. But, in any case, ...
> Another perspective: Re-write the sentence, replacing "and in that
> case" with "in which case." This should make it clearer that the
> sentence consists of a main clause and a sub-clause (preceded by a
> comma), not two main clauses.
... this is a much nicer idea than any of the above!
>> > +@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.
>>
>> Is it useful to say "Starting with Guile 2.0" in a post-2.0.0 version of
>> the manual? I think that expression could be deleted now.
>>
>
> That's a consequence of the fact that I looked up what information I
> could find from the NEWS file, and then used that text as an initial
> version.
>
> I agree that it's not the best solution to the problem, but the
> problem is "how does the manual convey to long-time Guile users this
> change in behavior?" I do not have a good solution to that in this
> brief patch. For now, experienced users will and should rely on the
> NEWS file to inform them about changes in behavior.
Agreed. I think it makes sense overall for the manual to describe the
status quo (plus the history section, for fun) and for NEWS to cover
changes.
(Notwithstanding that there are some occurrences in the manual source of
`@vnew{...}', which I guess was/is an attempt to codify such things
(when features changed, or were introduced) in the manual source. As
far as I know this usage has never been sufficiently widespread to be
reliable.)
Regards,
Neil
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Indexing Scheme and C identifiers separately
2011-04-25 16:16 ` David Pirotte
@ 2011-05-20 22:53 ` Neil Jerram
0 siblings, 0 replies; 20+ messages in thread
From: Neil Jerram @ 2011-05-20 22:53 UTC (permalink / raw)
To: David Pirotte; +Cc: Mark Harig, guile-devel
David Pirotte <david@altosw.be> writes:
> Looking at 'Procedure Index', for example not really knowing what your looking for
> but presumably starting with letter 's', as a 'pure' scheme programmer, reaching
> scm-xxx, you'll have to hit more or less 33 times page down [depending on your
> display and browser size obviously] to 'continue' with other 'scheme' indice entries
> [they may be other entries, at the beginning they are *scm_]. If you realize you
> probably have passed and missed the item you're looking for, you'll have to hit 33
> times page-up ... not a big deal but it would be really nice to have 'per language'
> indices.
>
> If [and only if :-)] it can be easily done [which I assumed, but ...], i would
> suggest the following [assuming a 'grouping' by language but i don't have a problem
> if it is by 'proc' 'var' and 'type'
>
> Indices
>
> . Concept Index
> . Scheme Procedure Index
> . Scheme Variable Index
> . Scheme Type Index
> . C Procedure Index
> . C Variable Index
> . C Type index
> . R5RS Index
I have supported this idea in the past, and I've recently taken a look
at how it might be implemented.
Unfortunately, I don't currently see a way of doing it. Unless the
@deffns in the manual are restructured in some big way, it means that
we'd need a @deffn command and one or more following @deffnx commands to
generate entries in different indices. That appears to be not currently
possible, and I've not managed to find any indication that it's even on
Texinfo's radar.
I'm happy to keep looking at this if people have other ideas about it;
but at the moment I'm stuck.
Regards,
Neil
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"
2011-04-25 19:49 ` Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Mark Harig
2011-04-26 18:07 ` Neil Jerram
@ 2011-06-30 11:23 ` Andy Wingo
1 sibling, 0 replies; 20+ messages in thread
From: Andy Wingo @ 2011-06-30 11:23 UTC (permalink / raw)
To: Mark Harig; +Cc: guile-devel
Hi Mark,
On Mon 25 Apr 2011 21:49, Mark Harig <idirectscm@aim.com> writes:
>>
>> > On Sun, Apr 24, 2011 at 04:33:44PM +0200, Andy Wingo wrote:
>> >> your patches should be "atomic"
>> >
>> > "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."
>>
>> Right, at the end of applying all of your patches, I'm sure that's the
>> case; however the first patch adds an @include without adding the
>> appropriate file, so applying just the first patch without the following
>> two would yield a project that doesn't compile. I just meant that you
>> need to squish the first two or three of them together. I can do that
>> when I apply them, though.
I went ahead and did this. Your commit logs were good but in the future
please provide an initial description line, and wrap the change
descriptions to 72 characters. See any of the Guile commit messages for
examples.
> In order to expedite this change, I am attaching the three updated patches.
I'm sorry that our back-and-forth distracted us from actually making
forward progress. I have applied your patches, and the changes should
be in 2.0.2's manual.
Thanks again,
Andy
--
http://wingolog.org/
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2011-06-30 11:23 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-04-23 19:46 Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Mark Harig
2011-04-24 14:33 ` Andy Wingo
2011-04-24 20:36 ` Mark Harig
2011-04-24 21:00 ` Andy Wingo
2011-04-24 21:58 ` Mark Harig
2011-04-25 8:01 ` Andy Wingo
2011-04-24 22:09 ` David Pirotte
2011-04-24 22:43 ` Indexing Scheme and C identifiers separately Mark Harig
2011-04-25 1:18 ` Noah Lavine
2011-04-25 16:16 ` David Pirotte
2011-05-20 22:53 ` Neil Jerram
2011-04-25 19:49 ` Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Mark Harig
2011-04-26 18:07 ` Neil Jerram
2011-04-26 21:01 ` Ludovic Courtès
2011-04-27 9:40 ` Andy Wingo
2011-04-27 10:23 ` Ludovic Courtès
2011-04-27 19:29 ` Neil Jerram
2011-04-27 16:54 ` Mark Harig
2011-04-27 19:40 ` Neil Jerram
2011-06-30 11:23 ` Andy Wingo
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).