diff options
author | Bake Timmons <b3timmons@speedymail.org> | 2013-03-02 20:33:56 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2013-03-02 20:34:29 +0100 |
commit | 994d87be35769480b04c9f96085a7a0b41040c9d (patch) | |
tree | 359a138620d48f1897bfff3397dbf76cfe8d46bc /doc | |
parent | 183d2ace576710079a2bcf2a8bfcbc39b7d9becc (diff) | |
download | guile-994d87be35769480b04c9f96085a7a0b41040c9d.tar.gz |
Improve keyword notation of Texinfo function definitions.
* doc/ref/api-debug.texi:
* doc/ref/api-evaluation.texi:
* doc/ref/api-modules.texi:
* doc/ref/compiler.texi:
* doc/ref/web.texi: Make Texinfo function headers more consistent.
Change lesser used keyword notation to the predominant form.
* 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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ref/api-debug.texi | 6 | ||||
-rw-r--r-- | doc/ref/api-evaluation.texi | 18 | ||||
-rw-r--r-- | doc/ref/api-modules.texi | 9 | ||||
-rw-r--r-- | doc/ref/api-procedures.texi | 6 | ||||
-rw-r--r-- | doc/ref/compiler.texi | 9 | ||||
-rw-r--r-- | doc/ref/srfi-modules.texi | 7 | ||||
-rw-r--r-- | doc/ref/web.texi | 18 |
7 files changed, 48 insertions, 25 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index dd2a3d19d..f6c706c78 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010, 2011, 2012 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010, 2011, 2012, 2013 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -1175,7 +1175,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?=#t] @ + [#:instructions?=#f] @ + [#:width=80] [#: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 0ffb5014e..5c932a720 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -488,7 +488,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=#f] [#:file=#f] @ + [#:line=#f] [#:column=#f] @ + [#:lang=(current-language)] @ + [#: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. @@ -691,7 +694,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=#f] @ + [#:from=(current-language)] @ + [#:to=value] [#: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}. @@ -700,10 +705,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=#f] @ + [#:from=(current-language)] [#:to='objcode] @ + [#:env=(default-environment from)] @ + [#:opts='()] @ + [#: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-modules.texi b/doc/ref/api-modules.texi index 17ab46277..b9befc00c 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010, 2011, 2012 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010, 2011, 2012, 2013 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -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=#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=#f] @ + [#:hide='()] [#:prefix=#f] @ + [#:renamer=#f] [#: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 bef3386e8..38ae1bb69 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -333,7 +333,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 0fe75e3e3..400814080 100644 --- a/doc/ref/compiler.texi +++ b/doc/ref/compiler.texi @@ -53,10 +53,11 @@ 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] [for-humans?=#t] @ -[make-default-environment=make-fresh-user-module] + [#:name] [#:title] [#:reader] [#:printer] @ + [#:parser=#f] [#:compilers='()] @ + [#:decompilers='()] [#:evaluator=#f] @ + [#:joiner=#f] [#:for-humans?=#t] @ + [#:make-default-environment=make-fresh-user-module] Define a language. This syntax defines a @code{#<language>} object, bound to @var{name} diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index dff8ca986..af1afc013 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -3429,9 +3429,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 6c33f3225..ae387ce14 100644 --- a/doc/ref/web.texi +++ b/doc/ref/web.texi @@ -1615,7 +1615,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, @@ -1627,16 +1629,20 @@ 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 to @var{handler} are taken from @var{arg} +@enddots{}. These arguments comprise a @dfn{state}. Additional return +values are accumulated into a new 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=#f] @ + [#:family=AF_INET] @ + [#:addr=INADDR_LOOPBACK] @ + [#: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 |