summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBake Timmons <b3timmons@speedymail.org>2013-03-02 20:33:56 +0100
committerAndy Wingo <wingo@pobox.com>2013-03-02 20:34:29 +0100
commit994d87be35769480b04c9f96085a7a0b41040c9d (patch)
tree359a138620d48f1897bfff3397dbf76cfe8d46bc /doc
parent183d2ace576710079a2bcf2a8bfcbc39b7d9becc (diff)
downloadguile-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.texi6
-rw-r--r--doc/ref/api-evaluation.texi18
-rw-r--r--doc/ref/api-modules.texi9
-rw-r--r--doc/ref/api-procedures.texi6
-rw-r--r--doc/ref/compiler.texi9
-rw-r--r--doc/ref/srfi-modules.texi7
-rw-r--r--doc/ref/web.texi18
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