From 14b1d2a56a21e0768812ef4210645f83efbdba11 Mon Sep 17 00:00:00 2001 From: Bake Timmons Date: Mon, 16 Jan 2012 13:43:17 -0500 Subject: [PATCH] Improve optional variable and keyword notation of Texinfo function definitions. * doc/ref/api-debug.texi: * doc/ref/api-evaluation.texi: * doc/ref/api-foreign.texi: * doc/ref/api-io.texi: * doc/ref/api-modules.texi: * doc/ref/compiler.texi: * doc/ref/web.texi: * doc/sources/strings.texi: * doc/sources/unix.texi: Make Texinfo function headers more consistent. Nest optional variable names that should be be nested. Add variable names to keyword notation having associated values that are cited in a Texinfo function definition body. Change lesser used keyword notation to the predominant form. * doc/sources/unix.texi: Make singular the variable name followed by repeated argument notation. * doc/ref/api-procedures.texi: Fix an argument name in a header that should use repeated argument notation. * doc/ref/srfi-modules.texi: Update references in Texinfo function definition body to match previously updated variable notation in definition header. --- doc/ref/api-debug.texi | 4 +++- doc/ref/api-evaluation.texi | 18 ++++++++++++------ doc/ref/api-foreign.texi | 2 +- doc/ref/api-io.texi | 7 ++++--- doc/ref/api-modules.texi | 7 +++++-- doc/ref/api-procedures.texi | 6 +++++- doc/ref/compiler.texi | 11 ++++++++--- doc/ref/srfi-modules.texi | 7 ++++--- doc/ref/web.texi | 25 +++++++++++++++---------- doc/sources/strings.texi | 12 ++++++------ doc/sources/unix.texi | 12 ++++++------ 11 files changed, 69 insertions(+), 42 deletions(-) diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index 453ad30..4853e11 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -1150,7 +1150,9 @@ calls to @var{proc}. In addition, Guile defines a procedure to call a thunk, tracing all procedure calls and returns within the thunk. -@deffn {Scheme Procedure} call-with-trace thunk #:key (calls? #t) (instructions? #f) (width 80) (vm (the-vm)) +@deffn {Scheme Procedure} call-with-trace thunk [#:calls? calls?=#t] @ + [#:instructions? instructions?=#f] @ + [#:width width=80] [#:vm vm=(the-vm)] Call @var{thunk}, tracing all execution within its dynamic extent. If @var{calls?} is true, Guile will print a brief report at each diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 9fffb87..f9b19dd 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -470,7 +470,10 @@ procedure in the default environment, but you really want the one from (use-modules (ice-9 eval-string)) @end example -@deffn {Scheme Procedure} eval-string string [module=#f] [file=#f] [line=#f] [column=#f] [lang=(current-language)] [compile?=#f] +@deffn {Scheme Procedure} eval-string string [#:module module=#f] [#:file file=#f] @ + [#:line line=#f] [#:column column=#f] @ + [#:lang lang=(current-language)] @ + [#:compile? compile?=#f] Parse @var{string} according to the current language, normally Scheme. Evaluate or compile the expressions it contains, in order, returning the last expression. @@ -656,7 +659,9 @@ coding declaration as recognized by @code{file-encoding} The compiler can also be invoked directly by Scheme code using the procedures below: -@deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()] +@deffn {Scheme Procedure} compile exp [#:env env=#f] @ + [#:from from=(current-language)] @ + [#:to to=value] [#:opts opts=()] Compile the expression @var{exp} in the environment @var{env}. If @var{exp} is a procedure, the result will be a compiled procedure; otherwise @code{compile} is mostly equivalent to @code{eval}. @@ -665,10 +670,11 @@ For a discussion of languages and compiler options, @xref{Compiling to the Virtual Machine}. @end deffn -@deffn {Scheme Procedure} compile-file file [output-file=#f] @ - [from=(current-language)] [to='objcode] @ - [env=(default-environment from)] [opts='()] @ - [canonicalization 'relative] +@deffn {Scheme Procedure} compile-file file [#:output-file output-file=#f] @ + [#:from from=(current-language)] [#:to to='objcode] @ + [#:env env=(default-environment from)] @ + [#:opts opts='()] @ + [#:canonicalization canonicalization='relative] Compile the file named @var{file}. Output will be written to a @var{output-file}. If you do not supply an diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi index da926f4..2fbcf67 100644 --- a/doc/ref/api-foreign.texi +++ b/doc/ref/api-foreign.texi @@ -634,7 +634,7 @@ string is freed when the returned foreign pointer becomes unreachable. This is the Scheme equivalent of @code{scm_to_stringn}. @end deffn -@deffn {Scheme Procedure} pointer->string pointer [length] [encoding] +@deffn {Scheme Procedure} pointer->string pointer [length [encoding]] Return the string representing the C string pointed to by @var{pointer}. If @var{length} is omitted or @code{-1}, the string is assumed to be nul-terminated. Otherwise @var{length} is the number of bytes in memory diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index 24c2706..27dced6 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -494,7 +494,7 @@ module from guile-scsh, but does not use multiple values or character sets and has an extra procedure @code{write-line}. @c begin (scm-doc-string "rdelim.scm" "read-line") -@deffn {Scheme Procedure} read-line [port] [handle-delim] +@deffn {Scheme Procedure} read-line [port [handle-delim]] Return a line of text from @var{port} if specified, otherwise from the value returned by @code{(current-input-port)}. Under Unix, a line of text is terminated by the first end-of-line character or by end-of-file. @@ -529,7 +529,7 @@ specified, otherwise from the value returned by @code{(current-input-port)}. @end deffn @c begin (scm-doc-string "rdelim.scm" "read-delimited") -@deffn {Scheme Procedure} read-delimited delims [port] [handle-delim] +@deffn {Scheme Procedure} read-delimited delims [port [handle-delim]] Read text until one of the characters in the string @var{delims} is found or end-of-file is reached. Read from @var{port} if supplied, otherwise from the value returned by @code{(current-input-port)}. @@ -537,7 +537,8 @@ from the value returned by @code{(current-input-port)}. @end deffn @c begin (scm-doc-string "rdelim.scm" "read-delimited!") -@deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end] +@deffn {Scheme Procedure} read-delimited! delims buf @ + [port [handle-delim [start [end]]]] Read text into the supplied string @var{buf}. If a delimiter was found, return the number of characters written, diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index a941900..eeb6cde 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -827,7 +827,8 @@ the time @var{thunk}'s dynamic extent was last entered) is restored. If saved, and the previously saved inner module is set current again. @end deffn -@deffn {Scheme Procedure} resolve-module name [autoload=#t] [version=#f] [#:ensure=#t] +@deffn {Scheme Procedure} resolve-module name [autoload=#t [version=#f]] @ + [#:ensure ensure=#t] @deffnx {C Function} scm_resolve_module (name) Find the module named @var{name} and return it. When it has not already been defined and @var{autoload} is true, try to auto-load it. When it @@ -837,7 +838,9 @@ that the resulting module is compatible with the given version reference (@pxref{R6RS Version References}). The name is a list of symbols. @end deffn -@deffn {Scheme Procedure} resolve-interface name [#:select=#f] [#:hide='()] [#:select=()] [#:prefix=#f] [#:renamer] [#:version=#f] +@deffn {Scheme Procedure} resolve-interface name [#:select select=#f] @ + [#:hide hide='()] [#:prefix prefix=#f] @ + [#:renamer] [#:version version=#f] Find the module named @var{name} as with @code{resolve-module} and return its interface. The interface of a module is also a module object, but it contains only the exported bindings. diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi index aa929cf..64fc181 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -302,7 +302,11 @@ cheaply, without allocating a rest list. @code{lambda*} is like @code{lambda}, except with some extensions to allow optional and keyword arguments. -@deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body +@deffn {library syntax} lambda* ([var@dots{}] @* @ + [#:optional vardef@dots{}] @* @ + [#:key vardef@dots{} [#:allow-other-keys]] @* @ + [#:rest var | . var]) @* @ + body1 body2 @dots{} @sp 1 Create a procedure which takes optional and/or keyword arguments specified with @code{#:optional} and @code{#:key}. For example, diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi index 692cb36..c9721d9 100644 --- a/doc/ref/compiler.texi +++ b/doc/ref/compiler.texi @@ -53,9 +53,14 @@ Languages are registered in the module, @code{(system base language)}: They are registered with the @code{define-language} form. @deffn {Scheme Syntax} define-language @ -name title reader printer @ -[parser=#f] [compilers='()] [decompilers='()] [evaluator=#f] @ -[joiner=#f] [make-default-environment=make-fresh-user-module] + [#:name name] [#:title] [#:reader] [#:printer] @ + [#:parser parser=#f] @ + [#:compilers compilers='()] @ + [#:decompilers decompilers='()] @ + [#:evaluator evaluator=#f] @ + [#:joiner joiner=#f] @ + [#:make-default-environment @ + make-default-environment=make-fresh-user-module] Define a language. This syntax defines a @code{#} object, bound to @var{name} diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index d00fbc4..4258c28 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -3520,9 +3520,10 @@ Note that all fields of @var{type} and its supertypes must be specified. @end deffn @deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{} -Return a new compound condition composed of @var{conditions}. The -returned condition has the type of each condition of @var{conditions} -(per @code{condition-has-type?}). +Return a new compound condition composed of @var{condition1} +@var{condition2} @enddots{}. The returned condition has the type of +each condition of condition1 condition2 @dots{} (per +@code{condition-has-type?}). @end deffn @deffn {Scheme Procedure} condition-has-type? c type diff --git a/doc/ref/web.texi b/doc/ref/web.texi index 81c77dd..a850c93 100644 --- a/doc/ref/web.texi +++ b/doc/ref/web.texi @@ -437,18 +437,18 @@ Write the given header alist to @var{port}. Doesn't write the final The @code{(web http)} module also has some utility procedures to read and write request and response lines. -@deffn {Scheme Procedure} parse-http-method str [start] [end] +@deffn {Scheme Procedure} parse-http-method str [start [end]] Parse an HTTP method from @var{str}. The result is an upper-case symbol, like @code{GET}. @end deffn -@deffn {Scheme Procedure} parse-http-version str [start] [end] +@deffn {Scheme Procedure} parse-http-version str [start [end]] Parse an HTTP version from @var{str}, returning it as a major-minor pair. For example, @code{HTTP/1.1} parses as the pair of integers, @code{(1 . 1)}. @end deffn -@deffn {Scheme Procedure} parse-request-uri str [start] [end] +@deffn {Scheme Procedure} parse-request-uri str [start [end]] Parse a URI from an HTTP request line. Note that URIs in requests do not have to have a scheme or host name. The result is a URI object. @end deffn @@ -1165,7 +1165,7 @@ more information on the format of parsed headers. Return the given request header, or @var{default} if none was present. @end deffn -@deffn {Scheme Procedure} request-absolute-uri r [default-host=#f] [default-port=#f] +@deffn {Scheme Procedure} request-absolute-uri r [default-host=#f [default-port=#f]] A helper routine to determine the absolute URI of a request, using the @code{host} header and the default host and port. @end deffn @@ -1479,7 +1479,9 @@ and body, and write the response to the client. Return the new state produced by the handler procedure. @end deffn -@deffn {Scheme Procedure} run-server handler [impl='http] [open-params='()] . state +@deffn {Scheme Procedure} run-server handler @ + [impl='http [open-params='()]] @ + arg @dots{} Run Guile's built-in web server. @var{handler} should be a procedure that takes two or more arguments, @@ -1491,16 +1493,19 @@ For examples, skip ahead to the next section, @ref{Web Examples}. The response and body will be run through @code{sanitize-response} before sending back to the client. -Additional arguments to @var{handler} are taken from @var{state}. -Additional return values are accumulated into a new @var{state}, which -will be used for subsequent requests. In this way a handler can -explicitly manage its state. +Additional arguments comprising a @var{state} to @var{handler} are taken +from @var{arg} @enddots{}. Additional return values are accumulated +into a new @var{state}, which will be used for subsequent requests. In +this way a handler can explicitly manage its state. @end deffn The default web server implementation is @code{http}, which binds to a socket, listening for request on that port. -@deffn {HTTP Implementation} http [#:host=#f] [#:family=AF_INET] [#:addr=INADDR_LOOPBACK] [#:port 8080] [#:socket] +@deffn {HTTP Implementation} http [#:host host=#f] @ + [#:family family=AF_INET] @ + [#:addr addr=INADDR_LOOPBACK] @ + [#:port port=8080] [#:socket] The default HTTP implementation. We document it as a function with keyword arguments, because that is precisely the way that it is -- all of the @var{open-params} to @code{run-server} get passed to the diff --git a/doc/sources/strings.texi b/doc/sources/strings.texi index 9a1ddc9..eff7b13 100644 --- a/doc/sources/strings.texi +++ b/doc/sources/strings.texi @@ -19,19 +19,19 @@ @end deffn @deffn procedure string-append arg ... @end deffn -@deffn procedure make-shared-substring string [from] [to] +@deffn procedure make-shared-substring string [from [to]] @end deffn @deffn procedure string-set! string index char @end deffn -@deffn procedure string-index string char [from] [to] +@deffn procedure string-index string char [from [to]] @end deffn -@deffn procedure string-rindex string char [from] [to] +@deffn procedure string-rindex string char [from [to]] @end deffn -@deffn procedure substring-move-left! string1 start1 [end1] [string2] [start2] +@deffn procedure substring-move-left! string1 start1 [end1 [string2 [start2]]] @end deffn -@deffn procedure substring-move-right! string1 start1 [end1] [string2] [start2] +@deffn procedure substring-move-right! string1 start1 [end1 [string2 [start2]]] @end deffn -@deffn procedure substring-fill! string start [end] [fill] +@deffn procedure substring-fill! string start [end [fill]] @end deffn @deffn procedure string-null? string @end deffn diff --git a/doc/sources/unix.texi b/doc/sources/unix.texi index b8bf2cd..72cf564 100644 --- a/doc/sources/unix.texi +++ b/doc/sources/unix.texi @@ -123,7 +123,7 @@ Interfaces to @code{read}/@code{fread} and @code{write}/@code{fwrite} are also available, as @code{uniform-array-read!} and @code{uniform-array-write!}, @ref{Uniform arrays}. -@deffn procedure read-line [port] [handle-delim] +@deffn procedure read-line [port [handle-delim]] Return a line of text from @var{port} if specified, otherwise from the value returned by @code{(current-input-port)}. Under Unix, a line of text is terminated by the first end-of-line character or by end-of-file. @@ -154,7 +154,7 @@ number of characters added to @var{buf}. If @var{buf} is filled, then Read from @var{port} if specified, otherwise from the value returned by @code{(current-input-port)}. @end deffn -@deffn procedure read-delimited delims [port] [handle-delim] +@deffn procedure read-delimited delims [port [handle-delim]] Read text until one of the characters in the string @var{delims} is found or end-of-file is reached. Read from @var{port} if supplied, otherwise from the value returned by @code{(current-input-port)}. @@ -163,7 +163,7 @@ from the value returned by @code{(current-input-port)}. NOTE: if the scsh module is loaded then @var{delims} must be an scsh char-set, not a string. @end deffn -@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end] +@deffn procedure read-delimited! delims buf [port [handle-delim [start [end]]]] Read text into the supplied string @var{buf} and return the number of characters added to @var{buf} (subject to @var{handle-delim}, which takes the same values specified for @code{read-line}. If @var{buf} is filled, @@ -310,7 +310,7 @@ file it points to. @var{path} must be a string. @end deffn @deffn procedure chmod port-or-path mode @end deffn -@deffn procedure utime path [actime] [modtime] +@deffn procedure utime path [actime [modtime]] @end deffn @deffn procedure delete-file path @end deffn @@ -529,9 +529,9 @@ Interrupt signal. @end deffn @deffn procedure send socket message [flags] @end deffn -@deffn procedure recvfrom! socket buf [flags] [start] [end] +@deffn procedure recvfrom! socket buf [flags [start [end]]] @end deffn -@deffn procedure sendto socket message family address args ... [flags] +@deffn procedure sendto socket message family address arg @dots{} [flags] @end deffn @node Miscellaneous Unix -- 1.7.8.3