From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 16 14:48:06 2012 Received: (at submit) by debbugs.gnu.org; 16 Jan 2012 19:48:06 +0000 Received: from localhost ([127.0.0.1]:60642 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RmsXE-0007JG-6c for submit@debbugs.gnu.org; Mon, 16 Jan 2012 14:48:05 -0500 Received: from eggs.gnu.org ([140.186.70.92]:50975) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from <42toes@gmail.com>) id 1RmsXA-0007Iq-9P for submit@debbugs.gnu.org; Mon, 16 Jan 2012 14:48:03 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RmsWD-0000Jb-Iz for submit@debbugs.gnu.org; Mon, 16 Jan 2012 14:47:04 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,FREEMAIL_FROM, RCVD_IN_DNSWL_LOW,T_DKIM_INVALID autolearn=unavailable version=3.3.2 Received: from lists.gnu.org ([140.186.70.17]:33263) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RmsWD-0000JX-HI for submit@debbugs.gnu.org; Mon, 16 Jan 2012 14:47:01 -0500 Received: from eggs.gnu.org ([140.186.70.92]:49711) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RmsW7-0006s5-KX for bug-guile@gnu.org; Mon, 16 Jan 2012 14:47:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RmsW5-0000IM-1X for bug-guile@gnu.org; Mon, 16 Jan 2012 14:46:55 -0500 Received: from mail-qy0-f169.google.com ([209.85.216.169]:53532) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RmsW4-0000I7-SC for bug-guile@gnu.org; Mon, 16 Jan 2012 14:46:52 -0500 Received: by qcsf14 with SMTP id f14so264931qcs.0 for ; Mon, 16 Jan 2012 11:46:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=sender:from:to:subject:reply-to:date:message-id:user-agent :mime-version:content-type; bh=NbB2oOY5UsX6HPOksNMvAI+51N5iRgsagCoGUTa5kdg=; b=MvzluxWKM2aef+5yQeIDxwqrwvKhcA9J12lyerZDusdcb2X7a2TuIouauIpsUdd3cf sedZ/7Pvy1akU9kNrCbRuJ9ZiLbndXgow5iuV6JiVlbHRyo4FDuhzlvzO6MnlM8kcHlj dNj2VxWClDTYzmevwcFbSNYvUy/VozhlkM9dM= Received: by 10.229.102.95 with SMTP id f31mr4997917qco.70.1326743212114; Mon, 16 Jan 2012 11:46:52 -0800 (PST) Received: from goof.localdomain (dialup-4.248.251.152.Dial1.Washington2.Level3.net. [4.248.251.152]) by mx.google.com with ESMTPS id a19sm38770546qau.21.2012.01.16.11.46.42 (version=TLSv1/SSLv3 cipher=OTHER); Mon, 16 Jan 2012 11:46:51 -0800 (PST) Received: by goof.localdomain (Postfix, from userid 1000) id E428A800B4; Mon, 16 Jan 2012 14:46:38 -0500 (EST) From: Bake Timmons To: bug-guile@gnu.org Subject: Patch: Improve optional variable and keyword notation in manual Date: Mon, 16 Jan 2012 14:46:38 -0500 Message-ID: <87d3ajh1lt.fsf@goof.localdomain> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.92 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.17 X-Spam-Score: -3.4 (---) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list Reply-To: b3timmons@speedymail.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.4 (---) --=-=-= Content-Type: text/plain 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 --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Improve-optional-variable-and-keyword-notation-of-Te.patch Content-Description: Improve optional variable and keyword notation in manual >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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Fri Feb 03 14:29:00 2012 Received: (at 10522) by debbugs.gnu.org; 3 Feb 2012 19:29:00 +0000 Received: from localhost ([127.0.0.1]:52649 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtOod-0001RU-Qv for submit@debbugs.gnu.org; Fri, 03 Feb 2012 14:29:00 -0500 Received: from a-pb-sasl-sd.pobox.com ([74.115.168.62]:57464 helo=sasl.smtp.pobox.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtOoc-0001RO-Cl for 10522@debbugs.gnu.org; Fri, 03 Feb 2012 14:28:58 -0500 Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id 25C7D91CF; Fri, 3 Feb 2012 14:28:24 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=oLQ2mb8HX7yudwt1g42vMXrec/Y=; b=w0yj3R mHmyAya1Z7M8TNGCXH8ViRhOWRdpWmEEZCdqxxibnBDsbF3+4U/CTCKrhuG0s4qL YDQORfgK5ulYp5/S/k2q2PPoXI+Nnr2+Ehf2435ZBknIedFuqvBRGwOk5rUX2WUn rrP/xZRw8AmG6Z3g+XwSBqb8ZZbX2xIuVa3YI= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; q=dns; s=sasl; b=NZk2JyR1JXo/qQISmep3pAz0h86qXvE/ qOof9XM272VjqtYTZstBHJwvKJEVroh82oJxe4+pSbPpAPmHOuVSdLoZ7cLilsdl 7YN97jj88EyXeT320HgZAOqtlcgzQYXgs1jIvseuccOVuKYoAQ4SfGt1J1neK/Cb 3tXUUEZHbTc= Received: from a-pb-sasl-sd.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id 1F36591CE; Fri, 3 Feb 2012 14:28:24 -0500 (EST) Received: from badger (unknown [94.139.51.40]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTPSA id 825B491CD; Fri, 3 Feb 2012 14:28:23 -0500 (EST) From: Andy Wingo To: b3timmons@speedymail.org Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> Date: Fri, 03 Feb 2012 14:28:55 +0100 In-Reply-To: <87d3ajh1lt.fsf@goof.localdomain> (Bake Timmons's message of "Mon, 16 Jan 2012 14:46:38 -0500") Message-ID: <87obtgjbag.fsf@pobox.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Pobox-Relay-ID: 3CEA788C-4E9D-11E1-9AA8-65B1DE995924-02397024!a-pb-sasl-sd.pobox.com X-Spam-Score: -0.3 (/) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -0.3 (/) 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 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/ From debbugs-submit-bounces@debbugs.gnu.org Fri Feb 03 18:54:45 2012 Received: (at 10522) by debbugs.gnu.org; 3 Feb 2012 23:54:45 +0000 Received: from localhost ([127.0.0.1]:52903 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtSxp-0000Ks-7U for submit@debbugs.gnu.org; Fri, 03 Feb 2012 18:54:45 -0500 Received: from xanadu.aquilenet.fr ([88.191.123.111]:52491) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtSxk-0000Ki-W3 for 10522@debbugs.gnu.org; Fri, 03 Feb 2012 18:54:44 -0500 Received: from localhost (xanadu.aquilenet.fr [127.0.0.1]) by xanadu.aquilenet.fr (Postfix) with ESMTP id 2300C2077; Sat, 4 Feb 2012 00:54:04 +0100 (CET) Received: from xanadu.aquilenet.fr ([127.0.0.1]) by localhost (xanadu.aquilenet.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 2ogrvwDjSgmo; Sat, 4 Feb 2012 00:54:04 +0100 (CET) Received: from pluto (126.1-64-87.adsl-dyn.isp.belgacom.be [87.64.1.126]) by xanadu.aquilenet.fr (Postfix) with ESMTPSA id 51E42A7A; Sat, 4 Feb 2012 00:54:03 +0100 (CET) From: ludo@gnu.org (Ludovic =?iso-8859-1?Q?Court=E8s?=) To: Andy Wingo Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 16 =?iso-8859-1?Q?Pluvi=F4se?= an 220 de la =?iso-8859-1?Q?R=E9volution?= X-PGP-Key-ID: 0xEA52ECF4 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 83C4 F8E5 10A3 3B4C 5BEA D15D 77DD 95E2 EA52 ECF4 X-OS: x86_64-unknown-linux-gnu Date: Sat, 04 Feb 2012 00:54:02 +0100 In-Reply-To: <87obtgjbag.fsf@pobox.com> (Andy Wingo's message of "Fri, 03 Feb 2012 14:28:55 +0100") Message-ID: <87d39vjwx1.fsf@gnu.org> User-Agent: Gnus/5.110018 (No Gnus v0.18) Emacs/24.0.93 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -1.2 (-) X-Debbugs-Envelope-To: 10522 Cc: b3timmons@speedymail.org, guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.2 (-) Hello! :-) Andy Wingo skribis: > On Mon 16 Jan 2012 20:46, Bake Timmons writes: >> -@deffn {Scheme Procedure} resolve-module name [autoload=3D#t] [version= =3D#f] [#:ensure=3D#t] >> +@deffn {Scheme Procedure} resolve-module name [autoload=3D#t [version= =3D#f]] @ >> + [#:ensure ensure=3D#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=3Dbar is unambiguous? That=E2=80=99s 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=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Fri Feb 03 22:42:57 2012 Received: (at 10522) by debbugs.gnu.org; 4 Feb 2012 03:42:57 +0000 Received: from localhost ([127.0.0.1]:52974 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtWWe-0005ic-P2 for submit@debbugs.gnu.org; Fri, 03 Feb 2012 22:42:57 -0500 Received: from mail-we0-f172.google.com ([74.125.82.172]:54475) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtWWb-0005iO-7s for 10522@debbugs.gnu.org; Fri, 03 Feb 2012 22:42:54 -0500 Received: by werm10 with SMTP id m10so3201574wer.3 for <10522@debbugs.gnu.org>; Fri, 03 Feb 2012 19:42:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=gamma; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-type; bh=8tBDNueTx/pkg6XbTRGcePz0a+I9eYeSFeixk6j0pUQ=; b=eG/dsNNIuQ2GNi8atB1RKniV/ETwM/jE+DrPjtgk5cw+KBjH8asQsY4Xa0slTQRvV+ PfDyUqCc5ucrK+rJVIU2JAugzPop9VmDB6j+cF5/fqCcCow1+UD1FCjEe70rHy70NZxl sxE8B0kNRle7HZL24FAPSUb0n1mIhhKuQ5/KE= Received: by 10.216.137.82 with SMTP id x60mr3902321wei.42.1328326931226; Fri, 03 Feb 2012 19:42:11 -0800 (PST) Received: from Kagami.home (host86-168-33-252.range86-168.btcentralplus.com. [86.168.33.252]) by mx.google.com with ESMTPS id cb8sm10646237wib.0.2012.02.03.19.42.08 (version=TLSv1/SSLv3 cipher=OTHER); Fri, 03 Feb 2012 19:42:09 -0800 (PST) From: Ian Price To: Andy Wingo Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> Date: Sat, 04 Feb 2012 03:34:43 +0000 In-Reply-To: <87obtgjbag.fsf@pobox.com> (Andy Wingo's message of "Fri, 03 Feb 2012 14:28:55 +0100") Message-ID: <87obtfnuek.fsf@Kagami.home> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 10522 Cc: b3timmons@speedymail.org, guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.3 (--) Andy Wingo 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" From debbugs-submit-bounces@debbugs.gnu.org Sat Feb 04 08:17:50 2012 Received: (at 10522) by debbugs.gnu.org; 4 Feb 2012 13:17:50 +0000 Received: from localhost ([127.0.0.1]:53211 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtfUz-0006XT-OQ for submit@debbugs.gnu.org; Sat, 04 Feb 2012 08:17:50 -0500 Received: from mx.sdf.org ([192.94.73.19]:54983 helo=sdf.lonestar.org ident=root) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1RtfUv-0006XI-49 for 10522@debbugs.gnu.org; Sat, 04 Feb 2012 08:17:48 -0500 Received: from goof.localdomain (core-estn-208-103-134-123.dynamic-dialup.coretel.net [208.103.134.123] (may be forged)) (authenticated (0 bits)) by sdf.lonestar.org (8.14.5/8.14.3) with ESMTP id q14DGMpo017120; Sat, 4 Feb 2012 13:16:58 GMT Received: by goof.localdomain (Postfix, from userid 1000) id 25DB680FC0; Sat, 4 Feb 2012 08:16:13 -0500 (EST) From: Bake Timmons To: Andy Wingo Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> Date: Sat, 04 Feb 2012 08:16:13 -0500 In-Reply-To: <87obtgjbag.fsf@pobox.com> (Andy Wingo's message of "Fri, 03 Feb 2012 14:28:55 +0100") Message-ID: <87wr82u4bm.fsf@goof.localdomain> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.92 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -1.1 (-) X-Debbugs-Envelope-To: 10522 Cc: b3timmons@speedymail.org, guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list Reply-To: b3timmons@speedymail.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.1 (-) Andy Wingo writes: > On Mon 16 Jan 2012 20:46, Bake Timmons 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 From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 02 14:36:36 2013 Received: (at 10522) by debbugs.gnu.org; 2 Mar 2013 19:36:36 +0000 Received: from localhost ([127.0.0.1]:55798 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UBsEV-0006Dt-7S for submit@debbugs.gnu.org; Sat, 02 Mar 2013 14:36:36 -0500 Received: from a-pb-sasl-quonix.pobox.com ([208.72.237.25]:63945 helo=sasl.smtp.pobox.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UBsET-0006Dm-9R for 10522@debbugs.gnu.org; Sat, 02 Mar 2013 14:36:34 -0500 Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id EE55CC3E5; Sat, 2 Mar 2013 14:36:27 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=fY8Pcs+Iw1Xrk37goMTrzkahtYU=; b=JJZV8u 2D6laWPa/h0Yy8wwe83WPT2xMqwhd3t4cqduJL1Lwscl6kT8yiaBrmE+iyJO0gfL Li+M7H+IDktda6LQzjK7lsDT+6vyhMdkFgIs9pKloSidXsZ+nlIOBw4E4YSv/Mdw vppUKuRed7Gs0jxMDl/VaffCKoZkB9MICTTx0= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; q=dns; s=sasl; b=HHIHPdCXustztFXhzAB+ZnCmr4c/2JTK xwADghYMqcXVD/vzEUwcKK6huw86Qe+GU4tyosoAd4io4CnJSaDWT83LuYHsGIUc egKB0nwquKJGR86wgq5DsdrI1Z/4XXArVSV4wsPHVXzEP0ItbJAhpDOFVJ01p0eH wQa/xzRWA/g= Received: from a-pb-sasl-quonix.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id E71FFC3E4; Sat, 2 Mar 2013 14:36:27 -0500 (EST) Received: from badger (unknown [88.160.190.192]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTPSA id 6D3FCC3E3; Sat, 2 Mar 2013 14:36:27 -0500 (EST) From: Andy Wingo To: b3timmons@speedymail.org Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> Date: Sat, 02 Mar 2013 20:36:24 +0100 In-Reply-To: <87obtgjbag.fsf@pobox.com> (Andy Wingo's message of "Fri, 03 Feb 2012 14:28:55 +0100") Message-ID: <876219egqv.fsf@pobox.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Pobox-Relay-ID: 79B0C8DA-8370-11E2-9DFF-034D0E5B5709-02397024!a-pb-sasl-quonix.pobox.com X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) Hi Bake, On Fri 03 Feb 2012 14:28, Andy Wingo 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 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/ From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 02 14:57:20 2013 Received: (at control) by debbugs.gnu.org; 2 Mar 2013 19:57:20 +0000 Received: from localhost ([127.0.0.1]:55831 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UBsYZ-0006is-Qq for submit@debbugs.gnu.org; Sat, 02 Mar 2013 14:57:20 -0500 Received: from a-pb-sasl-quonix.pobox.com ([208.72.237.25]:41500 helo=sasl.smtp.pobox.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UBsYX-0006il-Om for control@debbugs.gnu.org; Sat, 02 Mar 2013 14:57:18 -0500 Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id 9F1ACC4D9 for ; Sat, 2 Mar 2013 14:57:12 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=4oCHTHMle7T2HqBN/fxDiHEoKMc=; b=EvQYCb Fpn2iGlKNBnoSIv/KExLpV1pgAITJTVyL26SJVNKNLaSzUww+2cl8rFgvf7av4lx hjytoZdxP3gVZyz0fopItlbEIUGbKf4H4W02OHTKdjcd2JC4NN7g05bLQLtZGi0U XQZTZYHMCveTt2VN2/EZ6F5gf/DlnU5WBnXKg= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:subject :references:date:in-reply-to:message-id:mime-version :content-type; q=dns; s=sasl; b=SVmBnx02gql9+CEEiyz6sJMojxKCJCVQ 0BP1wxFh97lBH7VLX7n5DSYIY4SoSJuv5XB6AgKEQeFJY22Py6XMd0AAHiveEcvZ 5NzqnQW4apayNWbPNTLFcfJgEKXuxu9ZXVgBl33b49wayFFz1T1W+XtLAtoGxwCH jZU9BkafiEQ= Received: from a-pb-sasl-quonix.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id 982B6C4D8 for ; Sat, 2 Mar 2013 14:57:12 -0500 (EST) Received: from badger (unknown [88.160.190.192]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTPSA id 267A0C4D7 for ; Sat, 2 Mar 2013 14:57:11 -0500 (EST) From: Andy Wingo To: control@debbugs.gnu.org Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> <876219egqv.fsf@pobox.com> Date: Sat, 02 Mar 2013 20:57:05 +0100 In-Reply-To: <876219egqv.fsf@pobox.com> (Andy Wingo's message of "Sat, 02 Mar 2013 20:36:24 +0100") Message-ID: <87haktd17y.fsf@pobox.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Pobox-Relay-ID: 5F001B1E-8373-11E2-B880-034D0E5B5709-02397024!a-pb-sasl-quonix.pobox.com X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) close 10522 thanks -- http://wingolog.org/ From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 02 20:07:39 2013 Received: (at 10522) by debbugs.gnu.org; 3 Mar 2013 01:07:39 +0000 Received: from localhost ([127.0.0.1]:56057 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UBxOs-00065H-Rn for submit@debbugs.gnu.org; Sat, 02 Mar 2013 20:07:39 -0500 Received: from mail-ie0-f170.google.com ([209.85.223.170]:59571) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UBxOq-000655-CN for 10522@debbugs.gnu.org; Sat, 02 Mar 2013 20:07:37 -0500 Received: by mail-ie0-f170.google.com with SMTP id c11so4972758ieb.1 for <10522@debbugs.gnu.org>; Sat, 02 Mar 2013 17:07:24 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:in-reply-to:references:date:message-id :subject:from:to:cc:content-type; bh=VF2X8kEfp9f1bvohdElb3Stejm5Z1Gbfj6d1c2bO5/4=; b=WA34770sdyKHz/SG9nQV/K0KvTqUVCX2hUUkWxAKotiXQnjUCU3PSczI6V+0mI2zLb FkqFmyNkjTUPqJao9v5KyWVSVojVqboKQF73Ly2khMUyTGIb4AD3C4qa7lIIJTG4HOwq f3CDRrSTNLZnYt0LGEQqT8jeOBjrxNBL6lcZ8hxeg/AY3eKDXhwUnHRomboguHQuSsBT spFntEsTiEEmzjjgjX8v/8wHuRYAsjPBNWgk/MPNRGhMlVlzXyL3JRydJ/WjLaSHXfri mBuKIQ+L1U2ST7NcgprkpVRrlZ4vM+dRW64DI8uHz2fnq8t0nhRHSf1WeX5sMreF3E1l NGpg== MIME-Version: 1.0 X-Received: by 10.43.65.195 with SMTP id xn3mr18289081icb.5.1362272844751; Sat, 02 Mar 2013 17:07:24 -0800 (PST) Received: by 10.64.26.168 with HTTP; Sat, 2 Mar 2013 17:07:24 -0800 (PST) In-Reply-To: <876219egqv.fsf@pobox.com> References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> <876219egqv.fsf@pobox.com> Date: Sun, 3 Mar 2013 09:07:24 +0800 Message-ID: Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual From: Daniel Hartwig To: Andy Wingo Content-Type: text/plain; charset=UTF-8 X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) On 3 March 2013 03:36, Andy Wingo wrote: > Hi Bake, > > On Fri 03 Feb 2012 14:28, Andy Wingo 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 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. From debbugs-submit-bounces@debbugs.gnu.org Sun Mar 03 04:45:50 2013 Received: (at 10522) by debbugs.gnu.org; 3 Mar 2013 09:45:50 +0000 Received: from localhost ([127.0.0.1]:56518 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UC5UM-0002D6-CD for submit@debbugs.gnu.org; Sun, 03 Mar 2013 04:45:50 -0500 Received: from a-pb-sasl-quonix.pobox.com ([208.72.237.25]:48388 helo=sasl.smtp.pobox.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UC5UK-0002Cy-MB for 10522@debbugs.gnu.org; Sun, 03 Mar 2013 04:45:49 -0500 Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id 6C1FECC24; Sun, 3 Mar 2013 04:45:39 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=xDL01ln+h4qNbjdnOceROEIG7Ug=; b=jkskla hNHYScOlM3a/Q1cs9jkyPrL31pDjgrc3YQ9b6b4Gi/RsazFtzfRKvllALcmnAgx3 NpwegasOdpCqOCTIqvDfNUlmOtnmB922cWMsapQLZ1H80PAEP9GHRsssB3MXvloK WAtW6Zvfe3bbppAlFNfsrkbSdYkiVdgeLVB3U= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; q=dns; s=sasl; b=W78pAVC6yCuQ0SGuzlYniyqh0SK/kcLc tSqhTw4WDpeks4yi7EwGzILPxSHT+IyJS0+68YexytV27PSSPQrtssobsj/NFShZ wZ5QgppFCeL/xOPO5dWlvVE35IFHda3E/GZiMNobCuV0AbB7P/MtSEpLz17IZ551 Vh0X/n1Qwgk= Received: from a-pb-sasl-quonix.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id 65487CC23; Sun, 3 Mar 2013 04:45:39 -0500 (EST) Received: from badger (unknown [88.160.190.192]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTPSA id EF910CC22; Sun, 3 Mar 2013 04:45:38 -0500 (EST) From: Andy Wingo To: Daniel Hartwig Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> <876219egqv.fsf@pobox.com> Date: Sun, 03 Mar 2013 10:45:36 +0100 In-Reply-To: (Daniel Hartwig's message of "Sun, 3 Mar 2013 09:07:24 +0800") Message-ID: <871ubwg6kf.fsf@pobox.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Pobox-Relay-ID: 1B2B8904-83E7-11E2-84F6-034D0E5B5709-02397024!a-pb-sasl-quonix.pobox.com X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) On Sun 03 Mar 2013 02:07, Daniel Hartwig 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? From debbugs-submit-bounces@debbugs.gnu.org Fri Mar 08 20:59:37 2013 Received: (at 10522) by debbugs.gnu.org; 9 Mar 2013 01:59:37 +0000 Received: from localhost ([127.0.0.1]:40364 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UE94T-0001Nq-0X for submit@debbugs.gnu.org; Fri, 08 Mar 2013 20:59:37 -0500 Received: from mail-ia0-f173.google.com ([209.85.210.173]:65193) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UE94P-0001Na-1B for 10522@debbugs.gnu.org; Fri, 08 Mar 2013 20:59:35 -0500 Received: by mail-ia0-f173.google.com with SMTP id h37so2057176iak.4 for <10522@debbugs.gnu.org>; Fri, 08 Mar 2013 17:58:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:in-reply-to:references:date:message-id :subject:from:to:cc:content-type:content-transfer-encoding; bh=NQOI6ObKqCMxP/1JyNkK6WcHmoMscCYV2IqwmIWLKFs=; b=CQpB/D3wo36iWqvOy0sstTElcFt4SIwuD50biDLS9CGBwQHSDfZFVFQ+CecPH+HAzQ +P5CvZOQE6+b8tOadPnVKNlI7jl3+gqZ4YUN59xR/zFI70DSiQ1R56tRXnLQgi1daYb2 J5pzdoiO2/DsaZpvh/8Iz1xW7aEM4P+gbps5wLxt2MiEB4qVb41hpeLc66efw0Kxf3B5 44jNXk0c2L8KZi/HrmULvcT8oSNiuLXi/Cw96Pq0+X7iAA+6HdHJiiEgxYv3OKSoojv7 zjRy4FvL8dnNTVAnkTQtqb4+lUDpebGRhT1Q6/Q+c65kJlfKmV2dQu4NlCali4UjiIKP DmzA== MIME-Version: 1.0 X-Received: by 10.50.135.105 with SMTP id pr9mr1102888igb.6.1362794327114; Fri, 08 Mar 2013 17:58:47 -0800 (PST) Received: by 10.64.26.168 with HTTP; Fri, 8 Mar 2013 17:58:47 -0800 (PST) In-Reply-To: <871ubwg6kf.fsf@pobox.com> References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> <876219egqv.fsf@pobox.com> <871ubwg6kf.fsf@pobox.com> Date: Sat, 9 Mar 2013 09:58:47 +0800 Message-ID: Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual From: Daniel Hartwig To: Andy Wingo Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) On 3 March 2013 17:45, Andy Wingo wrote: > On Sun 03 Mar 2013 02:07, Daniel Hartwig 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=3D#f] [#:file=3D#f] [#:line=3D#f] [#:column=3D#f] [#:lang=3D(current-language)] [#:compile?=3D#f] we see that there is some potential confusion between the close, unescaped (as with @code, =E2=80=98=E2=80=99) nesting of the parens/bracket= s. Further, usage of =E2=80=98=3D=E2=80=99 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Mar 08 21:03:57 2013 Received: (at 10522) by debbugs.gnu.org; 9 Mar 2013 02:03:57 +0000 Received: from localhost ([127.0.0.1]:40371 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UE98f-0001Us-J6 for submit@debbugs.gnu.org; Fri, 08 Mar 2013 21:03:57 -0500 Received: from mail-ie0-f173.google.com ([209.85.223.173]:49309) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UE98c-0001Ua-SU for 10522@debbugs.gnu.org; Fri, 08 Mar 2013 21:03:55 -0500 Received: by mail-ie0-f173.google.com with SMTP id 9so2842165iec.4 for <10522@debbugs.gnu.org>; Fri, 08 Mar 2013 18:03:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:in-reply-to:references:date:message-id :subject:from:to:cc:content-type:content-transfer-encoding; bh=4BNq79ZUBl/OftxaC1BJcQSPi5dUTdN/jOS3ySJdTq0=; b=h6m++MRrRrqLp9rA5RE9WxJJ/aQxrxjX1/fcPuyOW52/3Ntrm3JPCG2d9IZdkUAVEi 0LqnMA4mQyyXbdp4CUNb6fzh8aH9EsI/ozwAB+H7MrvEDtVc6ZjiBEjc6/iiDd+Bl4Q8 sNyzVL6/W7WuA+lpDfYL7TFFDOPmq+3LDRbChh6LaG2ecZv/4GXyLr/BINUQKd+rT0j3 Mb2eeFzXP5lNCzqsrXumAZ2zTQpKFurr6mfD37zwQJ48XQ0hksQuzvWB5amQnPL4to8+ ySME/aVRri7cu0QoUhyckldriWLtMTToGKjDWYl1+2Cn385Fh1NdiYo9qkV+H7QRJe/r l8qA== MIME-Version: 1.0 X-Received: by 10.42.149.135 with SMTP id w7mr196199icv.25.1362794588794; Fri, 08 Mar 2013 18:03:08 -0800 (PST) Received: by 10.64.26.168 with HTTP; Fri, 8 Mar 2013 18:03:08 -0800 (PST) In-Reply-To: References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> <876219egqv.fsf@pobox.com> <871ubwg6kf.fsf@pobox.com> Date: Sat, 9 Mar 2013 10:03:08 +0800 Message-ID: Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual From: Daniel Hartwig To: Andy Wingo Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) On 9 March 2013 09:58, Daniel Hartwig wrote: > On 3 March 2013 17:45, Andy Wingo wrote: >> On Sun 03 Mar 2013 02:07, Daniel Hartwig 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=3D#f] [#:file=3D#f] > [#:line=3D#f] [#:column=3D#f] [#:lang=3D(current-language)] > [#:compile?=3D#f] > > we see that there is some potential confusion between the close, > unescaped (as with @code, =E2=80=98=E2=80=99) nesting of the parens/brack= ets. > Further, usage of =E2=80=98=3D=E2=80=99 like that is not valid Scheme cod= e, 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 '. From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 09 03:26:08 2013 Received: (at 10522) by debbugs.gnu.org; 9 Mar 2013 08:26:08 +0000 Received: from localhost ([127.0.0.1]:40770 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UEF6W-0001mv-F0 for submit@debbugs.gnu.org; Sat, 09 Mar 2013 03:26:08 -0500 Received: from a-pb-sasl-quonix.pobox.com ([208.72.237.25]:49584 helo=sasl.smtp.pobox.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UEF6U-0001mo-5h for 10522@debbugs.gnu.org; Sat, 09 Mar 2013 03:26:06 -0500 Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id E435ECC8A; Sat, 9 Mar 2013 03:25:23 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; s=sasl; bh=ua4JZFAQ65nY ONkCEV/YAnc/N7g=; b=TVAIxuLTQWMksDiQeGXs9Q9c4slp9cJKSAeEc5WpaiBa J/y1heViqMMwyEJekSoyzZC2EN/cXPPZRif+82gAFEQrQ9L9OLQ2nEa945vmF2tv Fun3uYnN5IQ44Db64S/nJeHy4PaIhdNIrf/QEsleoGZVnydE3pYX/2ap24SwXrk= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; q=dns; s=sasl; b=bjzJp6 atCe1+a0mLigkBfxnup/usgyeEah6+EXiIbOc83/V/YRTFlxSxcwZ+WKm85+xSn2 Y+i+WFpYDnVuJ1RCY+Zn5tvqdZEk6dpNXkqPHiTt7l+dE0dgv6eyrsD20as2eNRr De0oofgW6P4kXXTeV9PdjVvOlxbZywL7hVWjQ= Received: from a-pb-sasl-quonix.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id DBA2FCC89; Sat, 9 Mar 2013 03:25:23 -0500 (EST) Received: from badger (unknown [88.160.190.192]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTPSA id 61B56CC88; Sat, 9 Mar 2013 03:25:23 -0500 (EST) From: Andy Wingo To: Daniel Hartwig Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> <876219egqv.fsf@pobox.com> <871ubwg6kf.fsf@pobox.com> Date: Sat, 09 Mar 2013 09:25:21 +0100 In-Reply-To: (Daniel Hartwig's message of "Sat, 9 Mar 2013 09:58:47 +0800") Message-ID: <871ubp56a6.fsf@pobox.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Pobox-Relay-ID: E35789AA-8892-11E2-A6EB-59240E5B5709-02397024!a-pb-sasl-quonix.pobox.com X-Spam-Score: -1.1 (-) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.5 (--) On Sat 09 Mar 2013 02:58, Daniel Hartwig writes: > -- Scheme Procedure: eval-string string [#:module=3D#f] [#:file=3D#f] > [#:line=3D#f] [#:column=3D#f] [#:lang=3D(current-language)] > [#:compile?=3D#f] > > we see that there is some potential confusion between the close, > unescaped (as with @code, =E2=80=98=E2=80=99) nesting of the parens/brack= ets. Should we remove the brackets entirely? i.e -- Scheme Procedure: eval-string string #:module=3D#f #:file=3D#f #:line=3D#f #:column=3D#f #:lang=3D(current-language) #:compile?=3D#f Or with @code{}: -- Scheme Procedure: eval-string string #:module=3D=E2=80=98#f=E2=80=99 #:= file=3D=E2=80=98#f=E2=80=99 #:line=3D=E2=80=98#f=E2=80=99 #:column=3D=E2=80=98#f=E2=80=99 #:l= ang=3D=E2=80=98(current-language)=E2=80=99 #:compile?=3D=E2=80=98#f=E2=80=99 Dunno, just throwing more ideas out there... Andy --=20 http://wingolog.org/ From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 09 19:11:23 2013 Received: (at 10522) by debbugs.gnu.org; 10 Mar 2013 00:11:23 +0000 Received: from localhost ([127.0.0.1]:42477 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UETrG-0001pU-0N for submit@debbugs.gnu.org; Sat, 09 Mar 2013 19:11:22 -0500 Received: from mail-ie0-f172.google.com ([209.85.223.172]:54684) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UETrC-0001pF-9W for 10522@debbugs.gnu.org; Sat, 09 Mar 2013 19:11:20 -0500 Received: by mail-ie0-f172.google.com with SMTP id c10so3489350ieb.3 for <10522@debbugs.gnu.org>; Sat, 09 Mar 2013 16:10:27 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:in-reply-to:references:date:message-id :subject:from:to:cc:content-type; bh=/n/kY5PaOv0l/PGGIzGlW3cDzWm5B180qJMnvBv2UG8=; b=BZCGYlViUC5CvwnBQtxaUkZOY2wkOJgZhL8qH7lciqCaJeOyNr/JfUjJLXSKuQ7lOn aqPNOQ6ocCRftsEGcOrSXS6eJG86G/5gow00xEgKdEZWpl1DH0wZdRSARpk9gYpTh0Vo Iwu68g70OYqflSwtyHtJw5G5ubUzSfxUDTuaAyRgyttQiJA9KpkD7JQU0eaGkiMCrWJB HL/a/ccAW7JZrN5CLspQQjRAyR+aXiVmife8JWwiVj8Wm7NNck58lJRhlavi/tXZcqvb Tz3h3wNkg6rGZXrbG4xZhLIeoJI4l/qraBinSRP1b7+V9D1wfB4+qOx9FmpqVKamluzV Qcbg== MIME-Version: 1.0 X-Received: by 10.50.36.169 with SMTP id r9mr3568396igj.96.1362874227160; Sat, 09 Mar 2013 16:10:27 -0800 (PST) Received: by 10.64.26.168 with HTTP; Sat, 9 Mar 2013 16:10:27 -0800 (PST) In-Reply-To: <871ubp56a6.fsf@pobox.com> References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> <876219egqv.fsf@pobox.com> <871ubwg6kf.fsf@pobox.com> <871ubp56a6.fsf@pobox.com> Date: Sun, 10 Mar 2013 08:10:27 +0800 Message-ID: Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation in manual From: Daniel Hartwig To: Andy Wingo Content-Type: text/plain; charset=UTF-8 X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: 10522 Cc: guile-devel , 10522@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.2 (-) On 9 March 2013 16:25, Andy Wingo wrote: > Should we remove the brackets entirely? i.e I would not. The brackets are fairly standard for optional arguments. From unknown Wed Jun 18 00:29:57 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 07 Apr 2013 11:24:03 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator