[Guile-commits] 02/02: Minor additional manual updates

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit 94e66d2384108675241ec6857d20390aa5230fc1
Author: Andy Wingo <address@hidden>
Date:   Sun Oct 7 12:28:51 2018 +0200

    Minor additional manual updates
    
    * doc/ref/api-debug.texi (VM Hooks): Update for changes in VM hook API.
    * doc/ref/guile.texi: Update copyright years.
    * doc/ref/preface.texi (Contributors): Update.
---
 doc/ref/api-debug.texi | 74 ++++++++++++++++++++++++--------------------------
 doc/ref/guile.texi     |  5 ++--
 doc/ref/preface.texi   | 21 +++++++-------
 3 files changed, 47 insertions(+), 53 deletions(-)

diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index a6cfd7b..4fc295d 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 
2010, 2011, 2012, 2013, 2014
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 
2010, 2011, 2012, 2013, 2014, 2018
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -938,15 +938,15 @@ when running your program, or otherwise use the 
@code{call-with-vm} and
 @code{set-vm-engine!}  procedures to ensure that you are running in a VM
 with the @code{debug} engine.
 
-To digress, Guile's VM has 6 different hooks (@pxref{Hooks}) that can be
-fired at different times, which may be accessed with the following
-procedures.
+To digress, Guile's VM has 4 different hooks that can be fired at
+different times.  For implementation reasons, these hooks are not
+actually implemented with first-class Scheme hooks (@pxref{Hooks}); they
+are managed using an ad-hoc interface.
 
-The first argument of calls to these hooks is the frame in question.
address@hidden  Some hooks may call their procedures with more
-arguments.  Since these hooks may be fired very frequently, Guile does a
-terrible thing: it allocates the frames on the C stack instead of the
-garbage-collected heap.
+VM hooks are called with one argument: the current frame.
address@hidden  Since these hooks may be fired very frequently, Guile
+does a terrible thing: it allocates the frames on the C stack instead of
+the garbage-collected heap.
 
 The upshot here is that the frames are only valid within the dynamic
 extent of the call to the hook. If a hook procedure keeps a reference to
@@ -962,48 +962,44 @@ The interface to hooks is provided by the @code{(system 
vm vm)} module:
 All of these functions implicitly act on the VM for the current thread
 only.
 
address@hidden {Scheme Procedure} vm-next-hook
-The hook that will be fired before an instruction is retired (and
address@hidden {Scheme Procedure} vm-add-next-hook! f
+Arrange to call @var{f} when before an instruction is retired (and
 executed).
 @end deffn
 
address@hidden {Scheme Procedure} vm-push-continuation-hook
-The hook that will be fired after preparing a new frame. Fires just
-before applying a procedure in a non-tail context, just before the
-corresponding apply-hook.
address@hidden deffn
-
address@hidden {Scheme Procedure} vm-pop-continuation-hook
-The hook that will be fired before returning from a frame.
address@hidden {Scheme Procedure} vm-add-apply-hook! f
+Arrange to call @var{f} whenever a procedure is applied.  The frame
+locals will be the callee, followed by the arguments to the call.
 
-This hook fires with a variable number of arguments, corresponding to
-the values that the frame returns to its continuation.
+Note that procedure application is somewhat orthogonal to continuation
+pushes and pops.  To know whether a call is a tail call or not, with
+respect to the frame previously in place, check the value of the frame
+pointer compared the previous frame pointer.
 @end deffn
 
address@hidden {Scheme Procedure} vm-apply-hook
-The hook that will be fired before a procedure is applied. The frame's
-procedure will have already been set to the new procedure.
address@hidden {Scheme Procedure} vm-add-return-hook! f
+Arrange to call @var{f} before returning from a frame.  The values in
+the frame will be the frame's return values.
 
-Note that procedure application is somewhat orthogonal to continuation
-pushes and pops. A non-tail call to a procedure will result first in a
-firing of the push-continuation hook, then this application hook,
-whereas a tail call will run without having fired a push-continuation
-hook.
+Note that it's possible to return from an ``inner'' frame: one that was
+not immediately proceeded by a call with that frame pointer.  In that
+case, it corresponds to a non-local control flow jump, either because of
+applying a composable continuation or because of restoring a saved
+undelimited continuation.
 @end deffn
 
address@hidden {Scheme Procedure} vm-abort-continuation-hook
-The hook that will be called after aborting to a
-prompt.  @xref{Prompts}.
address@hidden {Scheme Procedure} vm-add-abort-hook!
+Arrange to call @var{f} after aborting to a prompt.  @xref{Prompts}.
 
-Like the pop-continuation hook, this hook fires with a variable number
-of arguments, corresponding to the values that returned to the
-continuation.
+Unfortunately, the values passed to the prompt handler are not easily
+available to @var{f}.
 @end deffn
 
address@hidden {Scheme Procedure} vm-restore-continuation-hook
-The hook that will be called after restoring an undelimited
-continuation. Unfortunately it's not currently possible to introspect on
-the values that were given to the continuation.
address@hidden {Scheme Procedure} vm-remove-next-hook! f
address@hidden {Scheme Procedure} vm-remove-apply-hook! f
address@hidden {Scheme Procedure} vm-remove-return-hook! f
address@hidden {Scheme Procedure} vm-remove-abort-hook! f
+Remove @var{f} from the corresponding VM hook for the current thread.
 @end deffn
 
 @cindex VM trace level
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 8cc4fe6..488416a 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -13,9 +13,8 @@
 @copying
 This manual documents Guile version @value{VERSION}.
 
-Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009,
-2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 Free Software
-Foundation, Inc.
+Copyright (C) 1996-1997, 2000-2005, 2009-2018 Free Software Foundation,
+Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
diff --git a/doc/ref/preface.texi b/doc/ref/preface.texi
index 3545836..87f4810 100644
--- a/doc/ref/preface.texi
+++ b/doc/ref/preface.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010, 
2011
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010, 
2011, 2018
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -25,10 +25,9 @@ identify individuals of whom to say ``yes, this person, she 
wrote the
 manual.''
 
 Still, among the many contributions, some caretakers stand out.  First
-among them is Neil Jerram, who has been working on this document for ten
-years now.  Neil's attention both to detail and to the big picture have
-made a real difference in the understanding of a generation of Guile
-hackers.
+among them is Neil Jerram, who has worked on this document for over ten
+years.  Neil's attention both to detail and to the big picture have made
+a real difference in the understanding of a generation of Guile hackers.
 
 Next we should note Marius Vollmer's effect on this document.  Marius
 maintained Guile during a period in which Guile's API was
@@ -41,12 +40,12 @@ the documentation of Scheme data types, control mechanisms 
and
 procedures.  In addition, he wrote the documentation for Guile's SRFI
 modules and modules associated with the Guile REPL.
 
-Ludovic address@hidden and Andy Wingo, the Guile maintainers at the time of
-this writing (late 2010), have also made their dent in the manual,
-writing documentation for new modules and subsystems in Guile 2.0.  They
-are also responsible for ensuring that the existing text retains its
-relevance as Guile evolves.  @xref{Reporting Bugs}, for more information
-on reporting problems in this manual.
+Ludovic address@hidden and Andy Wingo, who co-maintain Guile since 2010,
+along with Mark Weaver, have also made their dent in the manual, writing
+documentation for new modules and subsystems that arrived with Guile
+2.0.  Ludovic, Andy, and Mark are also responsible for ensuring that the
+existing text retains its relevance as Guile evolves.  @xref{Reporting
+Bugs}, for more information on reporting problems in this manual.
 
 The content for the first versions of this manual incorporated and was
 inspired by documents from Aubrey Jaffer, author of the SCM system on