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

[Andy Wingo <wingo@pobox.com>]

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/