From 7403e409f047d930b2c24aa71d39c5f3c2dba2a3 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Sun, 17 Nov 2002 22:08:45 +0000 Subject: [PATCH] Applied patches (mostly Texinfo markup) from Stephen Compall. --- doc/ref/ChangeLog | 13 ++ doc/ref/posix.texi | 346 +++++++++++++++++++------------------- doc/ref/scheme-data.texi | 348 +++++++++++++++++++-------------------- 3 files changed, 361 insertions(+), 346 deletions(-) diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index d18e02a58..38ef61477 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,16 @@ +2002-11-17 Neil Jerram + + Applied patch from Stephen Compall as follows. (Thanks!) + + 2002-10-26 Stephen Compall + + * scheme-data.texi: Addition and change of many Texinfo tags, + particularly usage of @var and @samp, as well as reformatting of + some lists into tables and usage of @result. + + Notes about some things I didn't understand, as well as a + missing section on non-control characters. + 2002-10-27 Gary Houston * scheme-modules.texi (Environments): only available when diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index 5ecceaf89..f0dc4bf1c 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1,5 +1,5 @@ @node POSIX -@chapter POSIX System Calls and Networking +@chapter @acronym{POSIX} System Calls and Networking @menu * Conventions:: Conventions employed by the POSIX interface. @@ -20,17 +20,17 @@ @end menu @node Conventions -@section POSIX Interface Conventions +@section @acronym{POSIX} Interface Conventions These interfaces provide access to operating system facilities. They provide a simple wrapping around the underlying C interfaces to make usage from Scheme more convenient. They are also used -to implement the Guile port of @ref{The Scheme shell (scsh)}. +to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}). Generally there is a single procedure for each corresponding Unix facility. There are some exceptions, such as procedures implemented for speed and convenience in Scheme with no primitive Unix equivalent, -e.g., @code{copy-file}. +e.g.@: @code{copy-file}. The interfaces are intended as far as possible to be portable across different versions of Unix. In some cases procedures which can't be @@ -66,9 +66,9 @@ succeed, e.g., @code{getenv} returns @code{#f} if it the requested string is not found in the environment. These cases are noted in the documentation. -For ways to deal with exceptions, @ref{Exceptions}. +For ways to deal with exceptions, see @ref{Exceptions}. -Errors which the C-library would report by returning a NULL pointer or +Errors which the C library would report by returning a null pointer or through some other means are reported by raising a @code{system-error} exception. The value of the Unix @code{errno} variable is available in the data passed by the exception. @@ -98,8 +98,8 @@ It can be extracted with the function @code{system-error-errno}: Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}. File ports are implemented using low-level operating system I/O -facilities, with optional buffering to improve efficiency -@pxref{File Ports} +facilities, with optional buffering to improve efficiency; see +@ref{File Ports}. Note that some procedures (e.g., @code{recv!}) will accept ports as arguments, but will actually operate directly on the file descriptor @@ -122,28 +122,28 @@ it's likely that the garbage collector would free the port, with the side-effect of closing the file descriptor prematurely. To assist the programmer in avoiding this problem, each port has an -associated "revealed count" which can be used to keep track of how many +associated @dfn{revealed count} which can be used to keep track of how many times the underlying file descriptor has been stored in other places. If a port's revealed count is greater than zero, the file descriptor will not be closed when the port is garbage collected. A programmer can therefore ensure that the revealed count will be greater than zero if the file descriptor is needed elsewhere. -For the simple case where a file descriptor is "imported" once to become +For the simple case where a file descriptor is ``imported'' once to become a port, it does not matter if the file descriptor is closed when the port is garbage collected. There is no need to maintain a revealed -count. Likewise when "exporting" a file descriptor to the external +count. Likewise when ``exporting'' a file descriptor to the external environment, setting the revealed count is not required provided the port is kept open (i.e., is pointed to by a live Scheme binding) while the file descriptor is in use. -To correspond with traditional Unix behaviour, the three file -descriptors (0, 1 and 2) are automatically imported when a program -starts up and assigned to the initial values of the current input, -output and error ports. The revealed count for each is initially set to -one, so that dropping references to one of these ports will not result -in its garbage collection: it could be retrieved with fdopen or -fdes->ports. +To correspond with traditional Unix behaviour, three file descriptors +(0, 1, and 2) are automatically imported when a program starts up and +assigned to the initial values of the current/standard input, output, +and error ports, respectively. The revealed count for each is +initially set to one, so that dropping references to one of these +ports will not result in its garbage collection: it could be retrieved +with @code{fdopen} or @code{fdes->ports}. @deffn {Scheme Procedure} port-revealed port @deffnx {C Function} scm_port_revealed (port) @@ -152,7 +152,7 @@ Return the revealed count for @var{port}. @deffn {Scheme Procedure} set-port-revealed! port rcount @deffnx {C Function} scm_set_port_revealed_x (port, rcount) -Sets the revealed count for a port to a given value. +Sets the revealed count for a @var{port} to @var{rcount}. The return value is unspecified. @end deffn @@ -169,10 +169,10 @@ side effect the revealed count of @var{port} is incremented. @deffn {Scheme Procedure} fdopen fdes modes @deffnx {C Function} scm_fdopen (fdes, modes) -Return a new port based on the file descriptor @var{fdes}. -Modes are given by the string @var{modes}. The revealed count -of the port is initialized to zero. The modes string is the -same as that accepted by @ref{File Ports, open-file}. +Return a new port based on the file descriptor @var{fdes}. Modes are +given by the string @var{modes}. The revealed count of the port is +initialized to zero. The @var{modes} string is the same as that +accepted by @code{open-file} (@pxref{File Ports, open-file}). @end deffn @deffn {Scheme Procedure} fdes->ports fd @@ -228,9 +228,9 @@ The return value is unspecified. @deffnx {C Function} scm_open (path, flags, mode) Open the file named by @var{path} for reading and/or writing. @var{flags} is an integer specifying how the file should be opened. -@var{mode} is an integer specifying the permission bits of the file, if -it needs to be created, before the umask is applied. The default is 666 -(Unix itself has no default). +@var{mode} is an integer specifying the permission bits of the file, +if it needs to be created, before the umask (@pxref{Processes}) is +applied. The default is 666 (Unix itself has no default). @var{flags} can be constructed by combining variables using @code{logior}. Basic flags are: @@ -251,7 +251,7 @@ Append to the file instead of truncating. Create the file if it does not already exist. @end defvar -See the Unix documentation of the @code{open} system call +@xref{File Status Flags,,,libc,The GNU C Library Reference Manual}, for additional flags. @end deffn @@ -263,7 +263,7 @@ a port. @deffn {Scheme Procedure} close fd_or_port @deffnx {C Function} scm_close (fd_or_port) -Similar to close-port (@pxref{Closing, close-port}), +Similar to @code{close-port} (@pxref{Closing, close-port}), but also works on file descriptors. A side effect of closing a file descriptor is that any ports using that file descriptor are moved to a different file descriptor and have @@ -272,19 +272,19 @@ their revealed counts set to zero. @deffn {Scheme Procedure} close-fdes fd @deffnx {C Function} scm_close_fdes (fd) -A simple wrapper for the @code{close} system call. -Close file descriptor @var{fd}, which must be an integer. -Unlike close (@pxref{Ports and File Descriptors, close}), -the file descriptor will be closed even if a port is using it. -The return value is unspecified. +A simple wrapper for the @code{close} system call. Close file +descriptor @var{fd}, which must be an integer. Unlike @code{close}, +the file descriptor will be closed even if a port is using it. The +return value is unspecified. @end deffn @deffn {Scheme Procedure} unread-char char [port] @deffnx {C Function} scm_unread_char (char, port) -Place @var{char} in @var{port} so that it will be read by the -next read operation. If called multiple times, the unread characters -will be read again in last-in first-out order. If @var{port} is -not supplied, the current input port is used. +Place @var{char} in @var{port} so that it will be read by the next +read operation on that port. If called multiple times, the unread +characters will be read again in ``last-in, first-out'' order (i.e.@: +a stack). If @var{port} is not supplied, the current input port is +used. @end deffn @deffn {Scheme Procedure} unread-string str port @@ -297,8 +297,8 @@ unread characters will be read again in last-in first-out order. If @deffn {Scheme Procedure} pipe @deffnx {C Function} scm_pipe () Return a newly created pipe: a pair of ports which are linked -together on the local machine. The @emph{car} is the input -port and the @emph{cdr} is the output port. Data written (and +together on the local machine. The @acronym{CAR} is the input +port and the @acronym{CDR} is the output port. Data written (and flushed) to the output port can be read from the input port. Pipes are commonly used for communication with a newly forked child process. The need to flush the output port can be @@ -384,7 +384,7 @@ Copies the file descriptor @var{oldfd} to descriptor number @var{newfd}, replacing the previous meaning of @var{newfd}. Both @var{oldfd} and @var{newfd} must be integers. -Unlike for dup->fdes or primitive-move->fdes, no attempt +Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt is made to move away ports which are using @var{newfd}. The return value is unspecified. @end deffn @@ -392,18 +392,19 @@ The return value is unspecified. @deffn {Scheme Procedure} port-mode port Return the port modes associated with the open port @var{port}. These will not necessarily be identical to the modes used when -the port was opened, since modes such as "append" which are +the port was opened, since modes such as ``append'' which are used only during port creation are not retained. @end deffn @deffn {Scheme Procedure} port-for-each proc @deffnx {C Function} scm_port_for_each (proc) Apply @var{proc} to each port in the Guile port table +(FIXME: what is the Guile port table?) in turn. The return value is unspecified. More specifically, -@var{proc} is applied exactly once to every port that exists -in the system at the time @var{port-for-each} is invoked. -Changes to the port table while @var{port-for-each} is running -have no effect as far as @var{port-for-each} is concerned. +@var{proc} is applied exactly once to every port that exists in the +system at the time @code{port-for-each} is invoked. Changes to the +port table while @code{port-for-each} is running have no effect as far +as @code{port-for-each} is concerned. @end deffn @deffn {Scheme Procedure} setvbuf port mode [size] @@ -444,7 +445,7 @@ Get the process ID of a socket's owner, for @code{SIGIO} signals. @item F_SETOWN Set the process that owns a socket to @var{value}, for @code{SIGIO} signals. @item FD_CLOEXEC -The value used to indicate the "close on exec" flag with @code{F_GETFL} or +The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or @code{F_SETFL}. @end table @end deffn @@ -593,8 +594,9 @@ from stat:mode in a more convenient form: @table @code @item stat:type A symbol representing the type of file. Possible values are -regular, directory, symlink, block-special, char-special, fifo, -socket and unknown +@samp{regular}, @samp{directory}, @samp{symlink}, +@samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket}, +and @samp{unknown}. @item stat:perms An integer representing the access permission bits. @end table @@ -617,12 +619,12 @@ string), i.e., the file that the link points to. @findex lchown @deffn {Scheme Procedure} chown object owner group @deffnx {C Function} scm_chown (object, owner, group) -Change the ownership and group of the file referred to by @var{object} to -the integer values @var{owner} and @var{group}. @var{object} can be -a string containing a file name or, if the platform -supports fchown, a port or integer file descriptor -which is open on the file. The return value -is unspecified. +Change the ownership and group of the file referred to by @var{object} +to the integer values @var{owner} and @var{group}. @var{object} can +be a string containing a file name or, if the platform supports +@code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference +Manual}), a port or integer file descriptor which is open on the file. +The return value is unspecified. If @var{object} is a symbolic link, either the ownership of the link or the ownership of the referenced file will be @@ -660,12 +662,13 @@ modification time to the current time. @findex unlink @deffn {Scheme Procedure} delete-file str @deffnx {C Function} scm_delete_file (str) -Deletes (or "unlinks") the file specified by @var{path}. +Deletes (or ``unlinks'') the file whose path is specified by +@var{str}. @end deffn @deffn {Scheme Procedure} copy-file oldfile newfile @deffnx {C Function} scm_copy_file (oldfile, newfile) -Copy the file specified by @var{path-from} to @var{path-to}. +Copy the file specified by @var{oldfile} to @var{newfile}. The return value is unspecified. @end deffn @@ -686,16 +689,16 @@ system. @deffn {Scheme Procedure} symlink oldpath newpath @deffnx {C Function} scm_symlink (oldpath, newpath) -Create a symbolic link named @var{path-to} with the value (i.e., pointing to) -@var{path-from}. The return value is unspecified. +Create a symbolic link named @var{newpath} with the value (i.e., pointing to) +@var{oldpath}. The return value is unspecified. @end deffn @deffn {Scheme Procedure} mkdir path [mode] @deffnx {C Function} scm_mkdir (path, mode) Create a new directory named by @var{path}. If @var{mode} is omitted then the permissions of the directory file are set using the current -umask. Otherwise they are set to the decimal value specified with -@var{mode}. The return value is unspecified. +umask (@pxref{Processes}). Otherwise they are set to the decimal +value specified with @var{mode}. The return value is unspecified. @end deffn @deffn {Scheme Procedure} rmdir path @@ -706,31 +709,31 @@ be empty for this to succeed. The return value is unspecified. @deffn {Scheme Procedure} opendir dirname @deffnx {C Function} scm_opendir (dirname) -Open the directory specified by @var{path} and return a directory +Open the directory specified by @var{dirname} and return a directory stream. @end deffn -@deffn {Scheme Procedure} directory-stream? obj -@deffnx {C Function} scm_directory_stream_p (obj) +@deffn {Scheme Procedure} directory-stream? object +@deffnx {C Function} scm_directory_stream_p (object) Return a boolean indicating whether @var{object} is a directory stream as returned by @code{opendir}. @end deffn -@deffn {Scheme Procedure} readdir port -@deffnx {C Function} scm_readdir (port) +@deffn {Scheme Procedure} readdir stream +@deffnx {C Function} scm_readdir (stream) Return (as a string) the next directory entry from the directory stream @var{stream}. If there is no remaining entry to be read then the end of file object is returned. @end deffn -@deffn {Scheme Procedure} rewinddir port -@deffnx {C Function} scm_rewinddir (port) +@deffn {Scheme Procedure} rewinddir stream +@deffnx {C Function} scm_rewinddir (stream) Reset the directory port @var{stream} so that the next call to @code{readdir} will return the first directory entry. @end deffn -@deffn {Scheme Procedure} closedir port -@deffnx {C Function} scm_closedir (port) +@deffn {Scheme Procedure} closedir stream +@deffnx {C Function} scm_closedir (stream) Close the directory stream @var{stream}. The return value is unspecified. @end deffn @@ -755,13 +758,13 @@ The return value is unspecified. @deffn {Scheme Procedure} mknod path type perms dev @deffnx {C Function} scm_mknod (path, type, perms, dev) Creates a new special file, such as a file corresponding to a device. -@var{path} specifies the name of the file. @var{type} should -be one of the following symbols: -regular, directory, symlink, block-special, char-special, -fifo, or socket. @var{perms} (an integer) specifies the file permissions. -@var{dev} (an integer) specifies which device the special file refers -to. Its exact interpretation depends on the kind of special file -being created. +@var{path} specifies the name of the file. @var{type} should be one +of the following symbols: @samp{regular}, @samp{directory}, +@samp{symlink}, @samp{block-special}, @samp{char-special}, +@samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the +file permissions. @var{dev} (an integer) specifies which device the +special file refers to. Its exact interpretation depends on the kind +of special file being created. E.g., @lisp @@ -785,7 +788,7 @@ Care should be taken if opening the file, e.g., use the Create a new unique file in the file system and returns a new buffered port open for reading and writing to the file. @var{tmpl} is a string specifying where the file should be -created: it must end with @code{XXXXXX} and will be changed in +created: it must end with @samp{XXXXXX} and will be changed in place to return the name of the temporary file. @end deffn @@ -949,14 +952,14 @@ information cannot be obtained. @deffn {Scheme Procedure} current-time @deffnx {C Function} scm_current_time () -Return the number of seconds since 1970-01-01 00:00:00 UTC, +Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. @end deffn @deffn {Scheme Procedure} gettimeofday @deffnx {C Function} scm_gettimeofday () Return a pair containing the number of seconds and microseconds -since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note: +since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note: whether true microsecond resolution is available depends on the operating system. @end deffn @@ -984,10 +987,10 @@ Day of the week (0-6) with Sunday represented as 0. @item tm:yday, set-tm:yday Day of the year (0-364, 365 in leap years). @item tm:isdst, set-tm:isdst -Daylight saving indicator (0 for "no", greater than 0 for "yes", less than -0 for "unknown"). +Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than +0 for ``unknown''). @item tm:gmtoff, set-tm:gmtoff -Time zone offset in seconds west of UTC (-46800 to 43200). +Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200). @item tm:zone, set-tm:zone Time zone label (a string), not necessarily unique. @end table @@ -998,31 +1001,32 @@ Return an object representing the broken down components of @var{time}, an integer like the one returned by @code{current-time}. The time zone for the calculation is optionally specified by @var{zone} (a string), otherwise the -@code{TZ} environment variable or the system default is used. +@env{TZ} environment variable or the system default is used. @end deffn @deffn {Scheme Procedure} gmtime time @deffnx {C Function} scm_gmtime (time) Return an object representing the broken down components of @var{time}, an integer like the one returned by -@code{current-time}. The values are calculated for UTC. +@code{current-time}. The values are calculated for @acronym{UTC}. @end deffn @deffn {Scheme Procedure} mktime sbd_time [zone] @deffnx {C Function} scm_mktime (sbd_time, zone) -@var{bd-time} is an object representing broken down time and @code{zone} -is an optional time zone specifier (otherwise the TZ environment variable -or the system default is used). +@var{sbd-time} is an object representing broken down time and +@code{zone} is an optional time zone specifier (otherwise the @env{TZ} +environment variable or the system default is used). -Returns a pair: the car is a corresponding -integer time value like that returned -by @code{current-time}; the cdr is a broken down time object, similar to -as @var{bd-time} but with normalized values. +Returns a pair: the @acronym{CAR} is a corresponding integer time +value like that returned by @code{current-time}; the @acronym{CDR} is +a broken down time object, similar to @var{sbd-time} but with +normalized values; i.e.@: with corrected @code{tm:wday} and +@code{tm:yday} fields. @end deffn @deffn {Scheme Procedure} tzset @deffnx {C Function} scm_tzset () -Initialize the timezone from the TZ environment variable +Initialize the timezone from the @env{TZ} environment variable or the system default. It's not usually necessary to call this procedure since it's done automatically by other procedures that depend on the timezone. @@ -1033,10 +1037,10 @@ timezone. Formats a time specification @var{time} using @var{template}. @var{time} is an object with time components in the form returned by @code{localtime} or @code{gmtime}. @var{template} is a string which can include formatting -specifications introduced by a @code{%} character. The formatting of +specifications introduced by a @samp{%} character. The formatting of month and day names is dependent on the current locale. The value returned is the formatted string. -@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.) +@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}. @lisp (strftime "%c" (localtime (current-time))) @@ -1050,11 +1054,11 @@ Performs the reverse action to @code{strftime}, parsing @var{string} according to the specification supplied in @var{template}. The interpretation of month and day names is dependent on the current locale. The value returned is a pair. -The car has an object with time components +The @acronym{CAR} has an object with time components in the form returned by @code{localtime} or @code{gmtime}, but the time zone components are not usefully set. -The cdr reports the number of characters from @var{string} +The @acronym{CDR} reports the number of characters from @var{string} which were used for the conversion. @end deffn @@ -1143,8 +1147,8 @@ If @var{env} is omitted, return the current environment (in the Unix sense) as a list of strings. Otherwise set the current environment, which is also the default environment for child processes, to the supplied list of strings. Each member of -@var{env} should be of the form @code{NAME=VALUE} and values of -@code{NAME} should not be duplicated. If @var{env} is supplied +@var{env} should be of the form @var{NAME}=@var{VALUE} and values of +@var{NAME} should not be duplicated. If @var{env} is supplied then the return value is unspecified. @end deffn @@ -1182,11 +1186,13 @@ Return the name of the current working directory. @deffn {Scheme Procedure} umask [mode] @deffnx {C Function} scm_umask (mode) -If @var{mode} is omitted, returns a decimal number representing the current -file creation mask. Otherwise the file creation mask is set to -@var{mode} and the previous value is returned. +If @var{mode} is omitted, returns a decimal number representing the +current file creation mask. Otherwise the file creation mask is set +to @var{mode} and the previous value is returned. @xref{Setting +Permissions,,Assigning File Permissions,libc,The GNU C Library +Reference Manual}, for more on how to use umasks. -E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18. +E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18. @end deffn @deffn {Scheme Procedure} chroot path @@ -1259,7 +1265,7 @@ The return value is unspecified. @deffnx {C Function} scm_seteuid (id) Sets the effective user ID to the integer @var{id}, provided the process has appropriate privileges. If effective IDs are not supported, the -real ID is set instead -- @code{(provided? 'EIDs)} reports whether the +real ID is set instead---@code{(provided? 'EIDs)} reports whether the system supports effective IDs. The return value is unspecified. @end deffn @@ -1268,7 +1274,7 @@ The return value is unspecified. @deffnx {C Function} scm_setegid (id) Sets the effective group ID to the integer @var{id}, provided the process has appropriate privileges. If effective IDs are not supported, the -real ID is set instead -- @code{(provided? 'EIDs)} reports whether the +real ID is set instead---@code{(provided? 'EIDs)} reports whether the system supports effective IDs. The return value is unspecified. @end deffn @@ -1276,7 +1282,7 @@ The return value is unspecified. @deffn {Scheme Procedure} getpgrp @deffnx {C Function} scm_getpgrp () Return an integer representing the current process group ID. -This is the POSIX definition, not BSD. +This is the @acronym{POSIX} definition, not @acronym{BSD}. @end deffn @deffn {Scheme Procedure} setpgid pid pgid @@ -1305,17 +1311,17 @@ child process is eligible then one will be chosen by the operating system. The value of @var{pid} determines the behaviour: -@table @r +@table @asis @item @var{pid} greater than 0 Request status information from the specified child process. -@item @var{pid} equal to -1 or WAIT_ANY +@item @var{pid} equal to -1 or @code{WAIT_ANY} Request status information for any child process. -@item @var{pid} equal to 0 or WAIT_MYPGRP +@item @var{pid} equal to 0 or @code{WAIT_MYPGRP} Request status information for any child process in the current process group. @item @var{pid} less than -1 Request status information for any child process whose process group ID -is -@var{PID}. +is @minus{}@var{pid}. @end table The @var{options} argument, if supplied, should be the bitwise OR of the @@ -1366,8 +1372,8 @@ otherwise @code{#f}. @deffn {Scheme Procedure} system [cmd] @deffnx {C Function} scm_system (cmd) -Execute @var{cmd} using the operating system's "command -processor". Under Unix this is usually the default shell +Execute @var{cmd} using the operating system's ``command +processor''. Under Unix this is usually the default shell @code{sh}. The value returned is @var{cmd}'s exit status as returned by @code{waitpid}, which can be interpreted using the functions above. @@ -1421,7 +1427,7 @@ call, but we call it @code{execle} because of its Scheme calling interface. @deffn {Scheme Procedure} primitive-fork @deffnx {C Function} scm_fork () -Creates a new "child" process by duplicating the current "parent" process. +Creates a new ``child'' process by duplicating the current ``parent'' process. In the child the return value is 0. In the parent the return value is the integer process ID of the child. @@ -1446,11 +1452,11 @@ or @code{PRIO_USER}, and @var{who} is interpreted relative to hhhhprocess group identifier for @code{PRIO_PGRP}, and a user identifier for @code{PRIO_USER}. A zero value of @var{who} denotes the current process, process group, or user. -@var{prio} is a value in the range -20 and 20, the default -priority is 0; lower priorities cause more favorable -scheduling. Sets the priority of all of the specified -processes. Only the super-user may lower priorities. -The return value is not specified. +@var{prio} is a value in the range [@minus{}20,20]. The default +priority is 0; lower priorities (in numerical terms) cause more +favorable scheduling. Sets the priority of all of the specified +processes. Only the super-user may lower priorities. The return +value is not specified. @end deffn @deffn {Scheme Procedure} getpriority which who @@ -1458,10 +1464,10 @@ The return value is not specified. Return the scheduling priority of the process, process group or user, as indicated by @var{which} and @var{who}. @var{which} is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} -or @code{PRIO_USER}, and @var{who} is interpreted relative to +or @code{PRIO_USER}, and @var{who} should be interpreted depending on @var{which} (a process identifier for @code{PRIO_PROCESS}, process group identifier for @code{PRIO_PGRP}, and a user -identifier for @code{PRIO_USER}. A zero value of @var{who} +identifier for @code{PRIO_USER}). A zero value of @var{who} denotes the current process, process group, or user. Return the highest priority (lowest numerical value) of any of the specified processes. @@ -1479,7 +1485,7 @@ Sends a signal to the specified process or group of processes. @var{pid} specifies the processes to which the signal is sent: -@table @r +@table @asis @item @var{pid} greater than 0 The process whose identifier is @var{pid}. @item @var{pid} equal to 0 @@ -1502,12 +1508,15 @@ Hang-up signal. @defvar SIGINT Interrupt signal. @end defvar + +A full list of signals on the GNU system may be found in @ref{Standard +Signals,,,libc,The GNU C Library Reference Manual}. @end deffn @deffn {Scheme Procedure} raise sig @deffnx {C Function} scm_raise (sig) Sends a specified signal @var{sig} to the current process, where -@var{sig} is as described for the kill procedure. +@var{sig} is as described for the @code{kill} procedure. @end deffn @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]] @@ -1519,11 +1528,12 @@ Install or report the signal handler for a specified signal. of variables such as @code{SIGINT}. If @var{handler} is omitted, @code{sigaction} returns a pair: the -CAR is the current -signal hander, which will be either an integer with the value @code{SIG_DFL} -(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which -handles the signal, or @code{#f} if a non-Scheme procedure handles the -signal. The CDR contains the current @code{sigaction} flags for the handler. +@acronym{CAR} is the current signal hander, which will be either an +integer with the value @code{SIG_DFL} (default action) or +@code{SIG_IGN} (ignore), or the Scheme procedure which handles the +signal, or @code{#f} if a non-Scheme procedure handles the signal. +The @acronym{CDR} contains the current @code{sigaction} flags for the +handler. If @var{handler} is provided, it is installed as the new handler for @var{signum}. @var{handler} can be a Scheme procedure taking one @@ -1539,7 +1549,7 @@ will always be added if it's available and the system is using restartable system calls.) The return value is a pair with information about the old handler as described above. -This interface does not provide access to the "signal blocking" +This interface does not provide access to the ``signal blocking'' facility. Maybe this is not needed, since the thread support may provide solutions to the problem of consistent access to data structures. @@ -1580,8 +1590,8 @@ of seconds remaining otherwise. @deffn {Scheme Procedure} usleep i @deffnx {C Function} scm_usleep (i) -Sleep for I microseconds. @code{usleep} is not available on -all platforms. +Sleep for @var{i} microseconds. @code{usleep} is not available on +all platforms. [FIXME: so what happens when it isn't?] @end deffn @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds @@ -1591,8 +1601,6 @@ Set the timer specified by @var{which_timer} according to the given @var{value_seconds}, and @var{value_microseconds} values. Return information about the timer's previous setting. -Errors are handled as described in the guile info pages under ``POSIX -Interface Conventions''. The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, and @code{ITIMER_PROF}. @@ -1605,9 +1613,7 @@ the seconds and microseconds of the timer @code{it_value}. @deffn {Scheme Procedure} getitimer which_timer @deffnx {C Function} scm_getitimer (which_timer) -Return information about the timer specified by @var{which_timer} -Errors are handled as described in the guile info pages under ``POSIX -Interface Conventions''. +Return information about the timer specified by @var{which_timer}. The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, and @code{ITIMER_PROF}. @@ -1667,7 +1673,7 @@ controlling terminal. The return value is unspecified. @section Pipes The following procedures provide an interface to the @code{popen} and -@code{pclose} system routines. The code is in a separate "popen" +@code{pclose} system routines. The code is in a separate ``popen'' module: @smalllisp @@ -1826,7 +1832,7 @@ The following functions accept a host object and return a selected component: @deffn {Scheme Procedure} hostent:name host -The "official" hostname for @var{host}. +The ``official'' hostname for @var{host}. @end deffn @deffn {Scheme Procedure} hostent:aliases host A list of aliases for @var{host}. @@ -1900,7 +1906,7 @@ The following functions accept an object representing a network and return a selected component: @deffn {Scheme Procedure} netent:name net -The "official" network name. +The ``official'' network name. @end deffn @deffn {Scheme Procedure} netent:aliases net A list of aliases for the network. @@ -1958,7 +1964,7 @@ The following functions accept an object representing a protocol and return a selected component: @deffn {Scheme Procedure} protoent:name protocol -The "official" protocol name. +The ``official'' protocol name. @end deffn @deffn {Scheme Procedure} protoent:aliases protocol A list of aliases for the protocol. @@ -2011,7 +2017,7 @@ The following functions accept an object representing a service and return a selected component: @deffn {Scheme Procedure} servent:name serv -The "official" name of the network service. +The ``official'' name of the network service. @end deffn @deffn {Scheme Procedure} servent:aliases serv A list of aliases for the network service. @@ -2080,12 +2086,13 @@ Otherwise it is equivalent to @code{setservent stayopen}. Socket ports can be created using @code{socket} and @code{socketpair}. The ports are initially unbuffered, to make reading and writing to the same port more reliable. A buffer can be added to the port using -@code{setvbuf}, @xref{Ports and File Descriptors}. +@code{setvbuf}; see @ref{Ports and File Descriptors}. -The convention used for "host" vs "network" addresses is that addresses -are always held in host order at the Scheme level. The procedures in -this section automatically convert between host and network order when -required. The arguments and return values are thus in host order. +The convention used for ``host'' vs.@: ``network'' addresses is that +addresses are always held in host order at the Scheme level. The +procedures in this section automatically convert between host and +network order when required. The arguments and return values are thus +in host order. @deffn {Scheme Procedure} socket family style proto @deffnx {C Function} scm_socket (family, style, proto) @@ -2255,9 +2262,9 @@ one is available unless the non-blocking option has been set on the socket. The return value is a -pair in which the @emph{car} is a new socket port for the +pair in which the @acronym{CAR} is a new socket port for the connection and -the @emph{cdr} is an object with address information about the +the @acronym{CDR} is an object with address information about the client which initiated the connection. @var{sock} does not become part of the @@ -2310,8 +2317,8 @@ protocols, if a packet larger than this limit is encountered then some data will be irrevocably lost. -The optional @var{flags} argument is a value or -bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. +The optional @var{flags} argument is a value or bitwise OR of +@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. The value returned is the number of bytes read from the socket. @@ -2324,14 +2331,11 @@ any unread buffered port data is ignored. @deffn {Scheme Procedure} send sock message [flags] @deffnx {C Function} scm_send (sock, message, flags) Transmit the string @var{message} on a socket port @var{sock}. -@var{sock} must already be bound to a destination address. The -value returned is the number of bytes transmitted -- -it's possible for -this to be less than the length of @var{message} -if the socket is -set to be non-blocking. The optional @var{flags} argument -is a value or -bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. +@var{sock} must already be bound to a destination address. The value +returned is the number of bytes transmitted---it's possible for this +to be less than the length of @var{message} if the socket is set to be +non-blocking. The optional @var{flags} argument is a value or bitwise +OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. Note that the data is written directly to the socket file descriptor: @@ -2352,8 +2356,8 @@ data will be irrevocably lost. The optional @var{flags} argument is a value or bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. -The value returned is a pair: the @emph{car} is the number of -bytes read from the socket and the @emph{cdr} an address object +The value returned is a pair: the @acronym{CAR} is the number of +bytes read from the socket and the @acronym{CDR} an address object in the same form as returned by @code{accept}. The address will given as @code{#f} if not available, as is usually the case for stream sockets. @@ -2375,7 +2379,7 @@ destination address is specified using the @var{fam}, @code{connect} procedure. @var{args_and_flags} contains the usual connection arguments optionally followed by a flags argument, which is a value or -bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. +bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. The value returned is the number of bytes transmitted -- it's possible for @@ -2388,7 +2392,7 @@ any unflushed buffered port data is ignored. @end deffn The following functions can be used to convert short and long integers -between "host" and "network" order. Although the procedures above do +between ``host'' and ``network'' order. Although the procedures above do this automatically for addresses, the conversion will still need to be done when sending or receiving encoded integer data from the network. @@ -2479,8 +2483,8 @@ client. @example (let ((s (socket AF_INET SOCK_STREAM 0))) (setsockopt s SOL_SOCKET SO_REUSEADDR 1) - ;; Specific address? - ;; (bind s AF_INET (inet-aton "127.0.0.1") 2904) + ;; @r{Specific address?} + ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)} (bind s AF_INET INADDR_ANY 2904) (listen s 5) @@ -2498,7 +2502,7 @@ client. (gethostbyaddr (sockaddr:addr client-details))) (newline) - ;; Send back the greeting to the client port + ;; @r{Send back the greeting to the client port} (display "Hello client\r\n" client) (close client)))) @end example @@ -2547,10 +2551,12 @@ specified. @c FIXME::martin: Not in libguile! @deffn {Scheme Procedure} software-type Return a symbol describing the current platform's operating system. -This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2, -THINKC, AMIGA, ATARIST, MACH, or ACORN. +This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX}, +@samp{COHERENT}, @samp{WINDOWS}, @samp{MS-DOS}, @samp{OS/2}, +@samp{THINKC}, @samp{AMIGA}, @samp{ATARIST}, @samp{MACH}, or +@samp{ACORN}. -Note that most varieties of Unix are considered to be simply "UNIX". +Note that most varieties of Unix are considered to be simply @samp{UNIX}. That is because when a program depends on features that are not present on every operating system, it is usually better to test for the presence or absence of that specific feature. The return value of @@ -2563,10 +2569,10 @@ no other easy or unambiguous way of detecting such features. @deffn {Scheme Procedure} setlocale category [locale] @deffnx {C Function} scm_setlocale (category, locale) -If @var{locale} is omitted, return the current value of the -specified locale category as a system-dependent string. -@var{category} should be specified using the values -@code{LC_COLLATE}, @code{LC_ALL} etc. +If @var{locale} is omitted, return the current value of the specified +locale @var{category} as a system-dependent string. @var{category} +should be specified using the values @code{LC_COLLATE}, @code{LC_ALL} +etc; see @inforef{Locating Catalogs,, gettext}. Otherwise the specified locale category is set to the string @var{locale} and the new value is returned as a diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi index e557ecd6b..d26ce7cae 100755 --- a/doc/ref/scheme-data.texi +++ b/doc/ref/scheme-data.texi @@ -5,13 +5,13 @@ This chapter describes those of Guile's simple data types which are primarily used for their role as items of generic data. By @dfn{simple} we mean data types that are not primarily used as -containers to hold other data --- i.e. pairs, lists, vectors and so on. +containers to hold other data --- i.e.@: pairs, lists, vectors and so on. For the documentation of such @dfn{compound} data types, see @ref{Compound Data Types}. One of the great strengths of Scheme is that there is no straightforward distinction between ``data'' and ``functionality''. For example, -Guile's support for dynamic linking could be described +Guile's support for dynamic linking could be described: @itemize @bullet @item @@ -59,16 +59,13 @@ equality predicates @code{eq?}, @code{eqv?} and @code{equal?} @lisp (<= 3 8) -@result{} -#t +@result{} #t (<= 3 -3) -@result{} -#f +@result{} #f (equal? "house" "houses") -@result{} -#f +@result{} #f (eq? #f #f) @result{} @@ -82,16 +79,13 @@ value at all except @code{#f}. @lisp (if #t "yes" "no") -@result{} -"yes" +@result{} "yes" (if 0 "yes" "no") -@result{} -"yes" +@result{} "yes" (if #f "yes" "no") -@result{} -"no" +@result{} "no" @end lisp A result of this asymmetry is that typical Scheme source code more often @@ -133,7 +127,7 @@ data. This section of the manual documents those types and functions. You may also find it illuminating to read R5RS's presentation of numbers in Scheme, which is particularly clear and accessible: see -@xref{Numbers,,,r5rs}. +@ref{Numbers,,,r5rs,R5RS}. @menu * Numerical Tower:: Scheme's numerical "tower". @@ -161,22 +155,28 @@ in Scheme, which is particularly clear and accessible: see Scheme's numerical ``tower'' consists of the following categories of numbers: -@itemize @bullet -@item -integers (whole numbers) +@table @dfn +@item integers +Whole numbers, positive or negative; e.g.@: --5, 0, 18. -@item -rationals (the set of numbers that can be expressed as P/Q where P and Q -are integers) +@item rationals +The set of numbers that can be expressed as @math{@var{p}/@var{q}} +where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but +pi (an irrational number) doesn't. These include integers +(@math{@var{n}/1}). -@item -real numbers (the set of numbers that describes all possible positions -along a one dimensional line) +@item real numbers +The set of numbers that describes all possible positions along a +one-dimensional line. This includes rationals as well as irrational +numbers. -@item -complex numbers (the set of numbers that describes all possible -positions in a two dimensional space) -@end itemize +@item complex numbers +The set of numbers that describes all possible positions in a two +dimensional space. This includes real as well as imaginary numbers +(@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part}, +@var{b} is the @dfn{imaginary part}, and @math{i} is the square root of +@minus{}1.) +@end table It is called a tower because each category ``sits on'' the one that follows it, in the sense that every integer is also a rational, every @@ -200,17 +200,14 @@ For example: @lisp (number? 3) -@result{} -#t +@result{} #t (number? "hello there!") -@result{} -#f +@result{} #f (define pi 3.141592654) (number? pi) -@result{} -#t +@result{} #t @end lisp The next few subsections document each of Guile's numerical data types @@ -224,7 +221,7 @@ in detail. @rnindex integer? Integers are whole numbers, that is numbers with no fractional part, -such as 2, 83 and -3789. +such as 2, 83, and @minus{}3789. Integers in Guile can be arbitrarily big, as shown by the following example. @@ -237,16 +234,13 @@ example. (loop (- n 1) (* product n))))) (factorial 3) -@result{} -6 +@result{} 6 (factorial 20) -@result{} -2432902008176640000 +@result{} 2432902008176640000 (- (factorial 45)) -@result{} --119622220865480194561963161495657715064383733760000000000 +@result{} -119622220865480194561963161495657715064383733760000000000 @end lisp Readers whose background is in programming languages where integers are @@ -259,7 +253,7 @@ representation where the required number does not fit in the native form. Conversion between these two representations is automatic and completely invisible to the Scheme level programmer. -The infinities @code{+inf.0} and @code{-inf.0} are considered to be +The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be inexact integers. They are explained in detail in the next section, together with reals and rationals. @@ -272,16 +266,13 @@ Return @code{#t} if @var{x} is an integer number, else @code{#f}. @lisp (integer? 487) -@result{} -#t +@result{} #t (integer? -3.4) -@result{} -#f +@result{} #f (integer? +inf.0) -@result{} -#t +@result{} #t @end lisp @end deffn @@ -297,9 +288,9 @@ Return @code{#t} if @var{x} is an integer number, else @code{#f}. Mathematically, the real numbers are the set of numbers that describe all possible points along a continuous, infinite, one-dimensional line. The rational numbers are the set of all numbers that can be written as -fractions P/Q, where P and Q are integers. All rational numbers are -also real, but there are real numbers that are not rational, for example -the square root of 2, and pi. +fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers. +All rational numbers are also real, but there are real numbers that +are not rational, for example the square root of 2, and pi. Guile represents both real and rational numbers approximately using a floating point encoding with limited precision. Even though the actual @@ -318,9 +309,9 @@ numbers. For example: The limited precision of Guile's encoding means that any ``real'' number in Guile can be written in a rational form, by multiplying and then dividing by sufficient powers of 10 (or in fact, 2). For example, -@code{-0.00000142857931198} is the same as @code{142857931198} divided by -@code{100000000000000000}. In Guile's current incarnation, therefore, -the @code{rational?} and @code{real?} predicates are equivalent. +@samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by +100000000000000000. In Guile's current incarnation, therefore, the +@code{rational?} and @code{real?} predicates are equivalent. Another aspect of this equivalence is that Guile currently does not preserve the exactness that is possible with rational arithmetic. @@ -344,13 +335,13 @@ respectibly. This syntax is also recognized by @code{read} as an extension to the usual Scheme syntax. Dividing zero by zero yields something that is not a number at all: -@samp{+nan.0}. This is the special 'not a number' value. +@samp{+nan.0}. This is the special `not a number' value. -On platforms that follow IEEE 754 for their floating point arithmetic, -the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values are -implemented using the corresponding IEEE 754 values. They behave in -arithmetic operations like IEEE 754 describes it, i.e., @code{(= -+nan.0 +nan.0) @result{#f}}. +On platforms that follow @acronym{IEEE} 754 for their floating point +arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values +are implemented using the corresponding @acronym{IEEE} 754 values. +They behave in arithmetic operations like @acronym{IEEE} 754 describes +it, i.e., @code{(= +nan.0 +nan.0) @result{#f}}. The infinities are inexact integers and are considered to be both even and odd. While @samp{+nan.0} is not @code{=} to itself, it is @@ -437,9 +428,9 @@ rational or integer number. R5RS requires that a calculation involving inexact numbers always produces an inexact result. To meet this requirement, Guile -distinguishes between an exact integer value such as @code{5} and the +distinguishes between an exact integer value such as @samp{5} and the corresponding inexact real value which, to the limited precision -available, has no fractional part, and is printed as @code{5.0}. Guile +available, has no fractional part, and is printed as @samp{5.0}. Guile will only convert the latter value to the former when forced to do so by an invocation of the @code{inexact->exact} procedure. @@ -474,70 +465,71 @@ preceded by a minus or plus character, a code indicating the base in which the integer is encoded, and a code indicating whether the number is exact or inexact. The supported base codes are: -@itemize @bullet -@item -@code{#b}, @code{#B} --- the integer is written in binary (base 2) +@table @code +@item #b +@itemx #B +the integer is written in binary (base 2) -@item -@code{#o}, @code{#O} --- the integer is written in octal (base 8) +@item #o +@itemx #O +the integer is written in octal (base 8) -@item -@code{#d}, @code{#D} --- the integer is written in decimal (base 10) +@item #d +@itemx #D +the integer is written in decimal (base 10) -@item -@code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16). -@end itemize +@item #x +@itemx #X +the integer is written in hexadecimal (base 16) +@end table If the base code is omitted, the integer is assumed to be decimal. The following examples show how these base codes are used. @lisp -13 -@result{} --13 +@result{} -13 #d-13 -@result{} --13 +@result{} -13 #x-13 -@result{} --19 +@result{} -19 #b+1101 -@result{} -13 +@result{} 13 #o377 -@result{} -255 +@result{} 255 @end lisp The codes for indicating exactness (which can, incidentally, be applied to all numerical values) are: -@itemize @bullet -@item -@code{#e}, @code{#E} --- the number is exact +@table @code +@item #e +@itemx #E +the number is exact -@item -@code{#i}, @code{#I} --- the number is inexact. -@end itemize +@item #i +@itemx #I +the number is inexact. +@end table If the exactness indicator is omitted, the integer is assumed to be exact, since Guile's internal representation for integers is always exact. Real numbers have limited precision similar to the precision of the @code{double} type in C. A consequence of the limited precision is that -all real numbers in Guile are also rational, since any number R with a -limited number of decimal places, say N, can be made into an integer by -multiplying by 10^N. +all real numbers in Guile are also rational, since any number @var{r} with a +limited number of decimal places, say @var{n}, can be made into an integer by +multiplying by @math{10^n}. Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for plus and minus infinity, respectively. The value must be written exactly as shown, that is, the always must have a sign and exactly one zero digit after the decimal point. It also understands @samp{+nan.0} -and @samp{-nan.0} for the special 'not-a-number' value. The sign is -ignored for 'not-a-number' and the value is always printed as @samp{+nan.0}. +and @samp{-nan.0} for the special `not-a-number' value. The sign is +ignored for `not-a-number' and the value is always printed as @samp{+nan.0}. @node Integer Operations @subsection Operations on Integer Values @@ -963,7 +955,8 @@ Return the arccosine of @var{x}. @c begin (texi-doc-string "guile" "$atan") @deffn {Scheme Procedure} $atan x -Return the arctangent of @var{x} in the range -PI/2 to PI/2. +Return the arctangent of @var{x} in the range @minus{}@math{PI/2} to +@math{PI/2}. @end deffn @deffn {Scheme Procedure} $atan2 x y @@ -1058,7 +1051,7 @@ Naturally, these C functions expect and return @code{double} arguments. @subsection Bitwise Operations @deffn {Scheme Procedure} logand n1 n2 -Return the bitwise AND of the integer arguments. +Return the bitwise @sc{and} of the integer arguments. @lisp (logand) @result{} -1 @@ -1068,7 +1061,7 @@ Return the bitwise AND of the integer arguments. @end deffn @deffn {Scheme Procedure} logior n1 n2 -Return the bitwise OR of the integer arguments. +Return the bitwise @sc{or} of the integer arguments. @lisp (logior) @result{} 0 @@ -1078,7 +1071,7 @@ Return the bitwise OR of the integer arguments. @end deffn @deffn {Scheme Procedure} logxor n1 n2 -Return the bitwise XOR of the integer arguments. A bit is +Return the bitwise @sc{xor} of the integer arguments. A bit is set in the result if it is set in an odd number of arguments. @lisp (logxor) @result{} 0 @@ -1126,12 +1119,12 @@ argument. @deffn {Scheme Procedure} ash n cnt @deffnx {C Function} scm_ash (n, cnt) -The function ash performs an arithmetic shift left by @var{cnt} -bits (or shift right, if @var{cnt} is negative). 'Arithmetic' -means, that the function does not guarantee to keep the bit +The function @code{ash} performs an arithmetic shift left by @var{cnt} +bits (or shift right, if @var{cnt} is negative). `Arithmetic' +means that the function does not guarantee to keep the bit structure of @var{n}, but rather guarantees that the result will always be rounded towards minus infinity. Therefore, the -results of ash and a corresponding bitwise shift will differ if +results of @code{ash} and a corresponding bitwise shift will differ if @var{n} is negative. Formally, the function returns an integer equivalent to @@ -1212,11 +1205,11 @@ Return a copy of the random state @var{state}. @deffn {Scheme Procedure} random n [state] @deffnx {C Function} scm_random (n, state) -Return a number in [0, N). +Return a number in [0, @var{n}). Accepts a positive integer or real n and returns a number of the same type between zero (inclusive) and -N (exclusive). The values returned have a uniform +@var{n} (exclusive). The values returned have a uniform distribution. The optional argument @var{state} must be of the type produced @@ -1229,43 +1222,42 @@ as a side effect of the random operation. @deffn {Scheme Procedure} random:exp [state] @deffnx {C Function} scm_random_exp (state) Return an inexact real in an exponential distribution with mean -1. For an exponential distribution with mean u use (* u -(random:exp)). +1. For an exponential distribution with mean @var{u} use @code{(* +@var{u} (random:exp))}. @end deffn -@deffn {Scheme Procedure} random:hollow-sphere! v [state] -@deffnx {C Function} scm_random_hollow_sphere_x (v, state) -Fills vect with inexact real random numbers -the sum of whose squares is equal to 1.0. -Thinking of vect as coordinates in space of -dimension n = (vector-length vect), the coordinates -are uniformly distributed over the surface of the -unit n-sphere. +@deffn {Scheme Procedure} random:hollow-sphere! vect [state] +@deffnx {C Function} scm_random_hollow_sphere_x (vect, state) +Fills @var{vect} with inexact real random numbers the sum of whose +squares is equal to 1.0. Thinking of @var{vect} as coordinates in +space of dimension @var{n} @math{=} @code{(vector-length @var{vect})}, +the coordinates are uniformly distributed over the surface of the unit +n-sphere. @end deffn @deffn {Scheme Procedure} random:normal [state] @deffnx {C Function} scm_random_normal (state) -Return an inexact real in a normal distribution. The -distribution used has mean 0 and standard deviation 1. For a -normal distribution with mean m and standard deviation d use -@code{(+ m (* d (random:normal)))}. +Return an inexact real in a normal distribution. The distribution +used has mean 0 and standard deviation 1. For a normal distribution +with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m} +(* @var{d} (random:normal)))}. @end deffn -@deffn {Scheme Procedure} random:normal-vector! v [state] -@deffnx {C Function} scm_random_normal_vector_x (v, state) -Fills vect with inexact real random numbers that are +@deffn {Scheme Procedure} random:normal-vector! vect [state] +@deffnx {C Function} scm_random_normal_vector_x (vect, state) +Fills @var{vect} with inexact real random numbers that are independent and standard normally distributed (i.e., with mean 0 and variance 1). @end deffn -@deffn {Scheme Procedure} random:solid-sphere! v [state] -@deffnx {C Function} scm_random_solid_sphere_x (v, state) -Fills vect with inexact real random numbers -the sum of whose squares is less than 1.0. -Thinking of vect as coordinates in space of -dimension n = (vector-length vect), the coordinates -are uniformly distributed within the unit n-sphere. -The sum of the squares of the numbers is returned. +@deffn {Scheme Procedure} random:solid-sphere! vect [state] +@deffnx {C Function} scm_random_solid_sphere_x (vect, state) +Fills @var{vect} with inexact real random numbers the sum of whose +squares is less than 1.0. Thinking of @var{vect} as coordinates in +space of dimension @var{n} @math{=} @code{(vector-length @var{vect})}, +the coordinates are uniformly distributed within the unit +@var{n}-sphere. The sum of the squares of the numbers is returned. +@c FIXME: What does this mean, particularly the n-sphere part? @end deffn @deffn {Scheme Procedure} random:uniform [state] @@ -1284,9 +1276,14 @@ Return a new random state using @var{seed}. @section Characters @tpindex Characters -Most of the characters in the ASCII character set may be referred to by -name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on. -The following table describes the ASCII names for each character. +@noindent +[@strong{FIXME}: how do you specify regular (non-control) characters?] + +Most of the ``control characters'' (those below codepoint 32) in the +@acronym{ASCII} character set, as well as the space, may be referred +to by name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and +so on. The following table describes the @acronym{ASCII} names for +each character. @multitable @columnfractions .25 .25 .25 .25 @item 0 = @code{#\nul} @@ -1324,27 +1321,21 @@ The following table describes the ASCII names for each character. @item 32 = @code{#\sp} @end multitable -The @code{delete} character (octal 177) may be referred to with the name +The ``delete'' character (octal 177) may be referred to with the name @code{#\del}. Several characters have more than one name: -@itemize @bullet -@item -@code{#\space}, @code{#\sp} -@item -@code{#\newline}, @code{#\nl} -@item -@code{#\tab}, @code{#\ht} -@item -@code{#\backspace}, @code{#\bs} -@item -@code{#\return}, @code{#\cr} -@item -@code{#\page}, @code{#\np} -@item -@code{#\null}, @code{#\nul} -@end itemize +@multitable {@code{#\backspace}} {Original} +@item Alias @tab Original +@item @code{#\space} @tab @code{#\sp} +@item @code{#\newline} @tab @code{#\nl} +@item @code{#\tab} @tab @code{#\ht} +@item @code{#\backspace} @tab @code{#\bs} +@item @code{#\return} @tab @code{#\cr} +@item @code{#\page} @tab @code{#\np} +@item @code{#\null} @tab @code{#\nul} +@end multitable @rnindex char? @deffn {Scheme Procedure} char? x @@ -1359,26 +1350,26 @@ Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}. @rnindex char? @deffn {Scheme Procedure} char>? x y -Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII +Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII} sequence, else @code{#f}. @end deffn @rnindex char>=? @deffn {Scheme Procedure} char>=? x y Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the -ASCII sequence, else @code{#f}. +@acronym{ASCII} sequence, else @code{#f}. @end deffn @rnindex char-ci=? @@ -1389,81 +1380,81 @@ case, else @code{#f}. @rnindex char-ci? @deffn {Scheme Procedure} char-ci>? x y -Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII +Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII} sequence ignoring case, else @code{#f}. @end deffn @rnindex char-ci>=? @deffn {Scheme Procedure} char-ci>=? x y Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the -ASCII sequence ignoring case, else @code{#f}. +@acronym{ASCII} sequence ignoring case, else @code{#f}. @end deffn @rnindex char-alphabetic? @deffn {Scheme Procedure} char-alphabetic? chr @deffnx {C Function} scm_char_alphabetic_p (chr) Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. -Alphabetic means the same thing as the isalpha C library function. +Alphabetic means the same thing as the @code{isalpha} C library function. @end deffn @rnindex char-numeric? @deffn {Scheme Procedure} char-numeric? chr @deffnx {C Function} scm_char_numeric_p (chr) Return @code{#t} iff @var{chr} is numeric, else @code{#f}. -Numeric means the same thing as the isdigit C library function. +Numeric means the same thing as the @code{isdigit} C library function. @end deffn @rnindex char-whitespace? @deffn {Scheme Procedure} char-whitespace? chr @deffnx {C Function} scm_char_whitespace_p (chr) Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. -Whitespace means the same thing as the isspace C library function. +Whitespace means the same thing as the @code{isspace} C library function. @end deffn @rnindex char-upper-case? @deffn {Scheme Procedure} char-upper-case? chr @deffnx {C Function} scm_char_upper_case_p (chr) Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. -Uppercase means the same thing as the isupper C library function. +Uppercase means the same thing as the @code{isupper} C library function. @end deffn @rnindex char-lower-case? @deffn {Scheme Procedure} char-lower-case? chr @deffnx {C Function} scm_char_lower_case_p (chr) Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. -Lowercase means the same thing as the islower C library function. +Lowercase means the same thing as the @code{islower} C library function. @end deffn @deffn {Scheme Procedure} char-is-both? chr @deffnx {C Function} scm_char_is_both_p (chr) -Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}. -Uppercase and lowercase are as defined by the isupper and islower -C library functions. +Return @code{#t} iff @var{chr} is either uppercase or lowercase, else +@code{#f}. Uppercase and lowercase are as defined by the +@code{isupper} and @code{islower} C library functions. @end deffn @rnindex char->integer @deffn {Scheme Procedure} char->integer chr @deffnx {C Function} scm_char_to_integer (chr) Return the number corresponding to ordinal position of @var{chr} in the -ASCII sequence. +@acronym{ASCII} sequence. @end deffn @rnindex integer->char @deffn {Scheme Procedure} integer->char n @deffnx {C Function} scm_integer_to_char (n) -Return the character at position @var{n} in the ASCII sequence. +Return the character at position @var{n} in the @acronym{ASCII} sequence. @end deffn @rnindex char-upcase @@ -1478,6 +1469,10 @@ Return the uppercase character version of @var{chr}. Return the lowercase character version of @var{chr}. @end deffn +@xref{Classification of Characters,,,libc,GNU C Library Reference +Manual}, for information about the @code{is*} Standard C functions +mentioned above. + @node Strings @section Strings @@ -1485,7 +1480,7 @@ Return the lowercase character version of @var{chr}. Strings are fixed-length sequences of characters. They can be created by calling constructor procedures, but they can also literally get -entered at the REPL or in Scheme source files. +entered at the @acronym{REPL} or in Scheme source files. Guile provides a rich set of string processing procedures, because text handling is very important when Guile is used as a scripting language. @@ -1493,7 +1488,7 @@ handling is very important when Guile is used as a scripting language. Strings always carry the information about how many characters they are composed of with them, so there is no special end-of-string character, like in C. That means that Scheme strings can contain any character, -even the NUL character @code{'\0'}. But note: Since most operating +even the @samp{NUL} character @samp{\0}. But note: Since most operating system calls dealing with strings (such as for file operations) expect strings to be zero-terminated, they might do unexpected things when called with string containing unusual characters. @@ -1515,11 +1510,12 @@ called with string containing unusual characters. @subsection String Read Syntax The read syntax for strings is an arbitrarily long sequence of -characters enclosed in double quotes (@code{"}). @footnote{Actually, the -current implementation restricts strings to a length of 2^24 -characters.} If you want to insert a double quote character into a -string literal, it must be prefixed with a backslash @code{\} character -(called an @dfn{escape character}). +characters enclosed in double quotes (@code{"}).@footnote{Actually, +the current implementation restricts strings to a length of +@math{2^24}, or 16,777,216, characters. Sorry.} If you want to +insert a double quote character into a string literal, it must be +prefixed with a backslash @samp{\} character (called an @dfn{escape +character}). The following are examples of string literals: @@ -1656,7 +1652,7 @@ ending with index @var{end} (exclusive). @var{str} must be a string, @var{start} and @var{end} must be exact integers satisfying: -0 <= @var{start} <= @var{end} <= (string-length @var{str}). +0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}. @end deffn @node String Modification @@ -2103,7 +2099,7 @@ specified @var{item}s and returns that. @end deffn The following example takes a regular expression that matches a standard -YYYYMMDD-format date such as @code{"20020828"}. The +@sc{yyyymmdd}-format date such as @code{"20020828"}. The @code{regexp-substitute} call returns a string computed from the information in the match structure, consisting of the fields and text from the original string reordered and reformatted. @@ -2124,7 +2120,7 @@ argument, @code{regexp-substitute/global} takes two string arguments: a @var{regexp} string describing a regular expression, and a @var{target} string which should be matched against this regular expression. -Each @var{item} behaves as in @var{regexp-substitute}, with the +Each @var{item} behaves as in @code{regexp-substitute}, with the following exceptions: @itemize @bullet