bug#10522: Patch: Improve optional variable and keyword notation in manual

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Bake Timmons]

[-- Attachment #1: Type: text/plain, Size: 2643 bytes --]

Attached is a patch to improve optional variable and keyword notation of
Texinfo function definitions.

While this patch fixes blatant errors, it's not particularly
interesting, except for how we improve some keyword notation in the
manual.  It is useful and natural to refer to the associated value of a
keyword '#:foo' by using '@var{foo}'.  Consider the following example
from the patch and the associated final version of the function
definition:

----------------------------------------------------------------------
-@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




@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
can't be found that way either, create an empty module if @var{ensure}
is true, otherwise return @code{#f}.  If @var{version} is true, ensure
that the resulting module is compatible with the given version reference
(@pxref{R6RS Version References}).  The name is a list of symbols.
@end deffn
----------------------------------------------------------------------


'[ensure]' cannot be used here, since that refers to an optional
variable 'ensure'.  '[#:ensure]' could be used, but then we lose the
default value.  '[#:ensure=#t]' is reasonable and concise, but sloppy
conceptually since the keyword by itself is meaningless without its
associated value.  This could confuse a novice.

The only other possibility I can think of right now is something like

    resolve-module name [autoload=#t [version=#f]] [keyword-options]

where the keyword-options are elaborated on, in, say, a table presented
in the body of the function definition.

This in fact is being used in the manual.  I see the choice right now
being between this one and the one I made in the patch.  We could go
with either one.  Another option is to do as my patch does, but use
'[keyword-options]' on a case-by-case basis, i.e., for a certain minimum number
of keywords, an advantage conferred by a table to present complex or
important information, etc.

Or maybe there is a better notation entirely?  Thoughts anyone?

Bake


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Improve optional variable and keyword notation in manual --]
[-- Type: text/x-diff, Size: 18483 bytes --]

From 14b1d2a56a21e0768812ef4210645f83efbdba11 Mon Sep 17 00:00:00 2001
From: Bake Timmons <b3timmons@speedymail.org>
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{#<language>} 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

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Andy Wingo]

Hi Bake,

This patch looks great.  I do have a couple of comments before
applying.  It would probably be useful to have input from others as
well, so I'm copying guile-devel.

On Mon 16 Jan 2012 20:46, Bake Timmons <b3timmons@speedymail.org> writes:
> -@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]

Nesting the optional arguments in brackets can get a bit ugly.  It is
precise but verbose.  But I suppose we should not encourage interfaces
with many optional arguments, so perhaps it is a moot point.

Also, it seems pedantic to repeat the keyword arguments (once as
keyword, once as identifier).  Surely #:foo=bar is unambiguous?

Anyway, I'm interested what others think about changes like this.

Cheers,

Andy
-- 
http://wingolog.org/

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Ludovic Courtès]

Hello!  :-)

Andy Wingo <wingo@pobox.com> skribis:

> On Mon 16 Jan 2012 20:46, Bake Timmons <b3timmons@speedymail.org> writes:
>> -@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]
>
> Nesting the optional arguments in brackets can get a bit ugly.  It is
> precise but verbose.  But I suppose we should not encourage interfaces
> with many optional arguments, so perhaps it is a moot point.

Indeed.

> Also, it seems pedantic to repeat the keyword arguments (once as
> keyword, once as identifier).  Surely #:foo=bar is unambiguous?

That’s what I would think.

Perhaps the people behind bug-texinfo@gnu.org have something to say
about this kind of thing, since there are other Lispy packages out there
with similar features?

Thanks,
Ludo’.

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Ian Price]

Andy Wingo <wingo@pobox.com> writes:

> Also, it seems pedantic to repeat the keyword arguments (once as
> keyword, once as identifier).  Surely #:foo=bar is unambiguous?

Since guile use the same name for both the keyword and identifier, I'd
say so.

-- 
Ian Price

"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Bake Timmons]

Andy Wingo <wingo@pobox.com> writes:

> On Mon 16 Jan 2012 20:46, Bake Timmons <b3timmons@speedymail.org> writes:
>> -@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]
>
> Nesting the optional arguments in brackets can get a bit ugly.  It is
> precise but verbose.  But I suppose we should not encourage interfaces
> with many optional arguments, so perhaps it is a moot point.
>
> Also, it seems pedantic to repeat the keyword arguments (once as
> keyword, once as identifier).  Surely #:foo=bar is unambiguous?
>
> Anyway, I'm interested what others think about changes like this.
>
> Cheers,
>
> Andy

I agree about the verbosity and did not feel strongly about those
changes, so I am OK with reverting them.  BTW, this verbose convention
already existed in the manual.  E.g.,

  ref/api-debug.texi: [#:on-error on-error='debug] [#:post-error post-error='catch] @
  ref/api-debug.texi: [#:pass-keys pass-keys='(quit)] [#:trap-handler trap-handler='debug]

My motivation was to avoid confusing novices unfamiliar with using
keywords, but there are other ways to help them here besides inflicting
ugliness. %^)

Cheers,
Bake

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Andy Wingo]

Hi Bake,

On Fri 03 Feb 2012 14:28, Andy Wingo <wingo@pobox.com> writes:

> Hi Bake,
>
> This patch looks great.  I do have a couple of comments before
> applying.  It would probably be useful to have input from others as
> well, so I'm copying guile-devel.
>
> On Mon 16 Jan 2012 20:46, Bake Timmons <b3timmons@speedymail.org> writes:
>> -@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]
>
> Nesting the optional arguments in brackets can get a bit ugly.  It is
> precise but verbose.  But I suppose we should not encourage interfaces
> with many optional arguments, so perhaps it is a moot point.
>
> Also, it seems pedantic to repeat the keyword arguments (once as
> keyword, once as identifier).  Surely #:foo=bar is unambiguous?

A year later, I pushed a version of your patch that doesn't nest
optional arguments or duplicate the keyword argument names, but it does
apply the other changes (and it makes keyword argument notation more
consistent).  Thanks for the patch, and looking forward to more of them
:)

Andy
-- 
http://wingolog.org/

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Daniel Hartwig]

On 3 March 2013 03:36, Andy Wingo <wingo@pobox.com> wrote:
> Hi Bake,
>
> On Fri 03 Feb 2012 14:28, Andy Wingo <wingo@pobox.com> writes:
>
>> Hi Bake,
>>
>> This patch looks great.  I do have a couple of comments before
>> applying.  It would probably be useful to have input from others as
>> well, so I'm copying guile-devel.
>>
>> On Mon 16 Jan 2012 20:46, Bake Timmons <b3timmons@speedymail.org> writes:
>>> -@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]
>>
>> Nesting the optional arguments in brackets can get a bit ugly.  It is
>> precise but verbose.  But I suppose we should not encourage interfaces
>> with many optional arguments, so perhaps it is a moot point.
>>
>> Also, it seems pedantic to repeat the keyword arguments (once as
>> keyword, once as identifier).  Surely #:foo=bar is unambiguous?
>
> A year later, I pushed a version of your patch that doesn't nest
> optional arguments or duplicate the keyword argument names, but it does
> apply the other changes (and it makes keyword argument notation more
> consistent).  Thanks for the patch, and looking forward to more of them
> :)

Can I ask whether it is preferred to use, e.g. @code{#f}, for the
default values, as some places seem to and others don't.  This patch
is not using @code, but then, neither does it touch any doc. that was
previously.

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Andy Wingo]

On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke@gmail.com> writes:

> Can I ask whether it is preferred to use, e.g. @code{#f}, for the
> default values, as some places seem to and others don't.  This patch
> is not using @code, but then, neither does it touch any doc. that was
> previously.

Good question.  Do you have an opinion?

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Daniel Hartwig]

On 3 March 2013 17:45, Andy Wingo <wingo@pobox.com> wrote:
> On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke@gmail.com> writes:
>
>> Can I ask whether it is preferred to use, e.g. @code{#f}, for the
>> default values, as some places seem to and others don't.  This patch
>> is not using @code, but then, neither does it touch any doc. that was
>> previously.
>
> Good question.  Do you have an opinion?

I suppose that the context of @deffn is somewhat similar to @code, so
the nesting may be considered redundant.  However, when I look at
cases where non-atomic expressions are used, such as #:lang in:

 -- Scheme Procedure: eval-string string [#:module=#f] [#:file=#f]
          [#:line=#f] [#:column=#f] [#:lang=(current-language)]
          [#:compile?=#f]

we see that there is some potential confusion between the close,
unescaped (as with @code, ‘’) nesting of the parens/brackets.
Further, usage of ‘=’ like that is not valid Scheme code, so the
contexts are actually more distinct than the ealier supposition.

This leads me to have a _slight_ preference for using @code, as being
more technically correct.  Though cases such as the above are in the
minority.

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Daniel Hartwig]

On 9 March 2013 09:58, Daniel Hartwig <mandyke@gmail.com> wrote:
> On 3 March 2013 17:45, Andy Wingo <wingo@pobox.com> wrote:
>> On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke@gmail.com> writes:
>>
>>> Can I ask whether it is preferred to use, e.g. @code{#f}, for the
>>> default values, as some places seem to and others don't.  This patch
>>> is not using @code, but then, neither does it touch any doc. that was
>>> previously.
>>
>> Good question.  Do you have an opinion?
>
> I suppose that the context of @deffn is somewhat similar to @code, so
> the nesting may be considered redundant.  However, when I look at
> cases where non-atomic expressions are used, such as #:lang in:
>
>  -- Scheme Procedure: eval-string string [#:module=#f] [#:file=#f]
>           [#:line=#f] [#:column=#f] [#:lang=(current-language)]
>           [#:compile?=#f]
>
> we see that there is some potential confusion between the close,
> unescaped (as with @code, ‘’) nesting of the parens/brackets.
> Further, usage of ‘=’ like that is not valid Scheme code, so the
> contexts are actually more distinct than the ealier supposition.
>
> This leads me to have a _slight_ preference for using @code, as being
> more technically correct.  Though cases such as the above are in the
> minority.

So I should also mention that omitting @code seems a bit more readable
in the resulting documentation.  At least we can clean up where some
values (symbols, empty lists) appear prefixed with unnecessary '.

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Andy Wingo]

On Sat 09 Mar 2013 02:58, Daniel Hartwig <mandyke@gmail.com> writes:

>  -- Scheme Procedure: eval-string string [#:module=#f] [#:file=#f]
>           [#:line=#f] [#:column=#f] [#:lang=(current-language)]
>           [#:compile?=#f]
>
> we see that there is some potential confusion between the close,
> unescaped (as with @code, ‘’) nesting of the parens/brackets.

Should we remove the brackets entirely? i.e

 -- Scheme Procedure: eval-string string #:module=#f #:file=#f
          #:line=#f #:column=#f #:lang=(current-language)
          #:compile?=#f

Or with @code{}:

 -- Scheme Procedure: eval-string string #:module=‘#f’ #:file=‘#f’
          #:line=‘#f’ #:column=‘#f’ #:lang=‘(current-language)’
          #:compile?=‘#f’

Dunno, just throwing more ideas out there...

Andy
-- 
http://wingolog.org/

bug#10522: Patch: Improve optional variable and keyword notation in manual

[Daniel Hartwig]

On 9 March 2013 16:25, Andy Wingo <wingo@pobox.com> wrote:
> Should we remove the brackets entirely? i.e

I would not.  The brackets are fairly standard for optional arguments.