From 42e81e99bdde779007adf0c258a171fea70959dc Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Sun, 28 Feb 2016 18:15:50 -0800 Subject: [PATCH] Update the documentation of several parameters. --- doc/ref-manual/error.texi | 6 +-- doc/ref-manual/numbers.texi | 32 +++++++++------ doc/ref-manual/os-interface.texi | 70 ++++++++++++++++++++------------ 3 files changed, 66 insertions(+), 42 deletions(-) diff --git a/doc/ref-manual/error.texi b/doc/ref-manual/error.texi index 260f510f3..1788f2322 100644 --- a/doc/ref-manual/error.texi +++ b/doc/ref-manual/error.texi @@ -439,7 +439,6 @@ signalled it is best to actually put a breakpoint on entry to @deffn procedure standard-error-handler condition @findex error @findex ignore-error -@vindex standard-error-hook @cindex REP loop Called internally by @code{error} after it calls @code{signal-condition}. Normally creates a new @sc{repl} with @@ -449,7 +448,7 @@ order to simulate the effect of calling @code{error}, code may call @code{standard-error-handler} if @code{signal-condition} returns. @end deffn -@defvr variable standard-error-hook +@defvr parameter standard-error-hook @findex standard-error-handler @cindex dynamic binding @cindex REP loop @@ -463,7 +462,6 @@ changed to a procedure of one argument and will then be invoked (with @end defvr @deffn procedure standard-warning-handler condition -@vindex standard-warning-hook @findex signal-condition @findex notification-output-port @findex write-condition-report @@ -483,7 +481,7 @@ In order to simulate the effect of calling @code{warn}, code may call however. For that purpose an explicit restart must be provided.) @end deffn -@defvr variable standard-warning-hook +@defvr parameter standard-warning-hook @findex standard-warning-handler @cindex dynamic binding This parameter controls the behavior of the procedure diff --git a/doc/ref-manual/numbers.texi b/doc/ref-manual/numbers.texi index b8edf9caa..9fcb40489 100644 --- a/doc/ref-manual/numbers.texi +++ b/doc/ref-manual/numbers.texi @@ -24,14 +24,14 @@ as fixed point and floating point are referred to by names such as @emph{fixnum} and @emph{flonum}. @menu -* Numerical types:: -* Exactness:: -* Implementation restrictions:: -* Syntax of numerical constants:: -* Numerical operations:: -* Numerical input and output:: -* Fixnum and Flonum Operations:: -* Random Numbers:: +* Numerical types:: +* Exactness:: +* Implementation restrictions:: +* Syntax of numerical constants:: +* Numerical operations:: +* Numerical input and output:: +* Fixnum and Flonum Operations:: +* Random Numbers:: @end menu @node Numerical types, Exactness, Numbers, Numbers @@ -522,7 +522,7 @@ For integers @var{n1} and @var{n2} with @var{n2} not equal to 0, @example @group -(= @var{n1} +(= @var{n1} (+ (* @var{n2} (quotient @var{n1} @var{n2})) (remainder @var{n1} @var{n2}))) @result{} #t @@ -934,9 +934,17 @@ the result, and consequently can be tolerated by many applications. @end defvr @defvr variable flonum-unparser-cutoff +This variable is @strong{deprecated}; use +@code{param:flonum-unparser-cutoff} instead. +@end defvr + +@defvr parameter param:flonum-unparser-cutoff This parameter controls the action of @code{number->string} when @var{number} is a flonum (and consequently controls all printing of -flonums). The value of this parameter is normally a list of three items: +flonums). This parameter may be called with an argument to set its +value. + +The value of this parameter is normally a list of three items: @table @var @item rounding-type @@ -1074,8 +1082,8 @@ used improperly, these operations can return incorrect answers, or even malformed objects that confuse the garbage collector. @menu -* Fixnum Operations:: -* Flonum Operations:: +* Fixnum Operations:: +* Flonum Operations:: @end menu @node Fixnum Operations, Flonum Operations, Fixnum and Flonum Operations, Fixnum and Flonum Operations diff --git a/doc/ref-manual/os-interface.texi b/doc/ref-manual/os-interface.texi index 1cde5e567..9f71ae403 100644 --- a/doc/ref-manual/os-interface.texi +++ b/doc/ref-manual/os-interface.texi @@ -154,7 +154,7 @@ a host object or @code{#f}, and @var{defaults} must be a pathname. @var{Host} specifies the syntax used to parse the string. If @var{host} is not given or @code{#f}, the host component from @var{defaults} is used instead; if @var{defaults} is not given, the host component from -@code{*default-pathname-defaults*} is used. +@code{param:default-pathname-defaults} is used. @end deffn @deffn procedure ->namestring pathname @@ -495,7 +495,7 @@ otherwise returns @code{#f}. @cindex defaulting, of pathname Returns a pathname whose components are obtained by combining those of @var{pathname} and @var{defaults}. @var{Defaults} defaults to the value -of @code{*default-pathname-defaults*} and @var{default-version} defaults +of @code{param:default-pathname-defaults} and @var{default-version} defaults to @code{newest}. The pathnames are combined by components: if @var{pathname} has a @@ -541,14 +541,19 @@ nothing, or just a directory, the name, type and version will come over from @var{defaults} together. @end deffn -@defvr variable *default-pathname-defaults* +@defvr parameter param:default-pathname-defaults @cindex defaulting, of pathname The value of this parameter (@pxref{Parameters}) is the default pathname-defaults pathname; if any pathname primitive that needs a set -of defaults is not given one, it uses this one. -@code{set-working-directory-pathname!} sets this parameter to a new value, -computed by merging the new working directory with the parameter's old -value. +of defaults is not given one, it uses this one. Modifying the +@code{working-directory-pathname} parameter also changes this +parameter to the same value, computed by merging the new working +directory with the parameter's old value. +@end defvr + +@defvr variable *default-pathname-defaults* +This variable is @strong{deprecated}; use +@code{param:default-pathname-defaults} instead. @end defvr @deffn procedure pathname-default pathname device directory name type version @@ -582,10 +587,11 @@ represents just the @var{host}, @var{device}, and @var{directory} components; and @code{host-namestring} returns a string for just the @var{host} portion. -@code{enough-namestring} takes another argument, @var{defaults}. -It returns an abbreviated namestring that is just sufficient to identify +@code{enough-namestring} takes another argument, @var{defaults}. It +returns an abbreviated namestring that is just sufficient to identify the file named by @var{pathname} when considered relative to the -@var{defaults} (which defaults to @code{*default-pathname-defaults*}). +@var{defaults} (which defaults to the value of +@code{param:default-pathname-defaults}). @example @group @@ -610,10 +616,11 @@ These procedures return a pathname corresponding to a subset of the The result of @code{directory-pathname} is a pathname containing the @var{host}, @var{device} and @var{directory} components of @var{pathname}. -@code{enough-pathname} takes another argument, @var{defaults}. -It returns an abbreviated pathname that is just sufficient to identify +@code{enough-pathname} takes another argument, @var{defaults}. It +returns an abbreviated pathname that is just sufficient to identify the file named by @var{pathname} when considered relative to the -@var{defaults} (which defaults to @code{*default-pathname-defaults*}). +@var{defaults} (which defaults to the value of +@code{param:default-pathname-defaults}). These procedures are similar to @code{file-namestring}, @code{directory-namestring} and @code{enough-namestring}, but they @@ -788,28 +795,36 @@ procedure. Each @acronym{REP} loop has its own working directory, and inferior @acronym{REP} loops initialize their working directory from the value in effect in their superior at the time they are created. -@deffn procedure working-directory-pathname -@deffnx procedure pwd +@deffn parameter working-directory-pathname +@deffnx parameter pwd Returns the current working directory as a pathname that has no name, type, or version components, just host, device, and directory components. @code{pwd} is an alias for @code{working-directory-pathname}; the long name is intended for programs and the short name for interactive use. + +This parameter may be called with an argument to set its value, in +which case it also modifies the value of +@code{param:default-pathname-defaults} by merging the new working +directory into it. @end deffn @deffn procedure set-working-directory-pathname! filename @deffnx procedure cd filename @findex ->pathname @findex pathname-as-directory +This procedure is @strong{deprecated}; instead call +@code{working-directory-pathname} with an argument. + Makes @var{filename} the current working directory and returns the new current working directory as a pathname. @var{Filename} is coerced to a pathname using @code{pathname-as-directory}. @code{cd} is an alias for @code{set-working-directory-pathname!}; the long name is intended for programs and the short name for interactive use. -Additionally, @code{set-working-directory-pathname!} modifies the value -of@* @code{*default-pathname-defaults*} by merging the new working -directory into it. +Additionally, @code{set-working-directory-pathname!} modifies the +value of @code{param:default-pathname-defaults} by merging the new +working directory into it. When this procedure is executed in the top-level @acronym{REP} loop, it changes the working directory of the running Scheme executable. @@ -841,13 +856,16 @@ directory, before changing the working directory. @end deffn @deffn procedure with-working-directory-pathname filename thunk -This procedure dynamically binds (@pxref{Dynamic Binding}) the current -working directory to @var{filename} and returns the value of -@var{thunk} (a procedure of no arguments). @var{Filename} is coerced -to a pathname using @code{pathname-as-directory}. In addition to -binding the working directory, @code{with-working-directory-pathname} -also dynamically binds the @code{*default-pathname-defaults*} parameter, -merging the old value with the new working directory pathname. +This procedure is @strong{deprecated}; instead bind +@code{working-directory-pathname} using @code{parameterize}. + +This procedure dynamically binds the current working directory to +@var{filename} and returns the value of @var{thunk} (a procedure of no +arguments). @var{Filename} is coerced to a pathname using +@code{pathname-as-directory}. In addition to binding the working +directory, @code{with-working-directory-pathname} also dynamically +binds the @code{param:default-pathname-defaults} parameter, merging +the old value with the new working directory pathname. @end deffn @node File Manipulation, Directory Reader, Working Directory, Operating-System Interface @@ -990,7 +1008,7 @@ Under Windows, the following directories on the system drive: @item Under Windows, the current directory, as specified by -@code{*default-pathname-defaults*}. +@code{param:default-pathname-defaults}. @end itemize @end deffn -- 2.25.1