On Sat 23 Apr 2011 21:46, Mark Harig <idirect...@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/