summaryrefslogtreecommitdiff
path: root/libguile/root.c
diff options
context:
space:
mode:
Diffstat (limited to 'libguile/root.c')
-rw-r--r--libguile/root.c87
1 files changed, 40 insertions, 47 deletions
diff --git a/libguile/root.c b/libguile/root.c
index 30d80747c..f248528cc 100644
--- a/libguile/root.c
+++ b/libguile/root.c
@@ -337,48 +337,42 @@ cwdr (SCM proc, SCM a1, SCM args, SCM handler, SCM_STACKITEM *stack_start)
SCM_DEFINE (scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
(SCM thunk, SCM handler),
-"Evaluate @var{(thunk)} in a new dynamic context, returning its value.
-
-If an error occurs during evaluation, apply @var{handler} to the
-arguments to the throw, just as @code{throw} would. If this happens,
-@var{handler} is called outside the scope of the new root -- it is
-called in the same dynamic context in which
-@code{call-with-dynamic-root} was evaluated.
-
-If @var{thunk} captures a continuation, the continuation is rooted at
-the call to @var{thunk}. In particular, the call to
-@code{call-with-dynamic-root} is not captured. Therefore,
-@code{call-with-dynamic-root} always returns at most one time.
-
-Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
-the root and a new chain started for @var{thunk}. Therefore, this call
-may not do what you expect:
-
-@example
-;; Almost certainly a bug:
-(with-output-to-port
- some-port
-
- (lambda ()
- (call-with-dynamic-root
- (lambda ()
- (display 'fnord)
- (newline))
- (lambda (errcode) errcode))))
-@end example
-
-The problem is, on what port will @samp{fnord\n} be displayed? You
-might expect that because of the @code{with-output-to-port} that
-it will be displayed on the port bound to @code{some-port}. But it
-probably won't -- before evaluating the thunk, dynamic winds are
-unwound, including those created by @code{with-output-to-port}.
-So, the standard output port will have been re-set to its default value
-before @code{display} is evaluated.
-
-(This function was added to Guile mostly to help calls to functions in C
-libraries that can not tolerate non-local exits or calls that return
-multiple times. If such functions call back to the interpreter, it should
-be under a new dynamic root.)")
+ "Evaluate @var{(thunk)} in a new dynamic context, returning its value.\n\n"
+ "If an error occurs during evaluation, apply @var{handler} to the\n"
+ "arguments to the throw, just as @code{throw} would. If this happens,\n"
+ "@var{handler} is called outside the scope of the new root -- it is\n"
+ "called in the same dynamic context in which\n"
+ "@code{call-with-dynamic-root} was evaluated.\n\n"
+ "If @var{thunk} captures a continuation, the continuation is rooted at\n"
+ "the call to @var{thunk}. In particular, the call to\n"
+ "@code{call-with-dynamic-root} is not captured. Therefore,\n"
+ "@code{call-with-dynamic-root} always returns at most one time.\n\n"
+ "Before calling @var{thunk}, the dynamic-wind chain is un-wound back to\n"
+ "the root and a new chain started for @var{thunk}. Therefore, this call\n"
+ "may not do what you expect:\n\n"
+ "@example\n"
+ ";; Almost certainly a bug:\n"
+ "(with-output-to-port\n"
+ " some-port\n\n"
+ " (lambda ()\n"
+ " (call-with-dynamic-root\n"
+ " (lambda ()\n"
+ " (display 'fnord)\n"
+ " (newline))\n"
+ " (lambda (errcode) errcode))))\n"
+ "@end example\n\n"
+ "The problem is, on what port will @samp{fnord\n"
+ "} be displayed? You\n"
+ "might expect that because of the @code{with-output-to-port} that\n"
+ "it will be displayed on the port bound to @code{some-port}. But it\n"
+ "probably won't -- before evaluating the thunk, dynamic winds are\n"
+ "unwound, including those created by @code{with-output-to-port}.\n"
+ "So, the standard output port will have been re-set to its default value\n"
+ "before @code{display} is evaluated.\n\n"
+ "(This function was added to Guile mostly to help calls to functions in C\n"
+ "libraries that can not tolerate non-local exits or calls that return\n"
+ "multiple times. If such functions call back to the interpreter, it should\n"
+ "be under a new dynamic root.)")
#define FUNC_NAME s_scm_call_with_dynamic_root
{
SCM_STACKITEM stack_place;
@@ -388,11 +382,10 @@ be under a new dynamic root.)")
SCM_DEFINE (scm_dynamic_root, "dynamic-root", 0, 0, 0,
(),
-"Return an object representing the current dynamic root.
-
-These objects are only useful for comparison using @code{eq?}.
-They are currently represented as numbers, but your code should
-in no way depend on this.")
+ "Return an object representing the current dynamic root.\n\n"
+ "These objects are only useful for comparison using @code{eq?}.\n"
+ "They are currently represented as numbers, but your code should\n"
+ "in no way depend on this.")
#define FUNC_NAME s_scm_dynamic_root
{
return scm_ulong2num (SCM_SEQ (scm_root->rootcont));