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

[Mark Harig <idirectscm@aim.com>]

[-- 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 --]