From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Bake Timmons Newsgroups: gmane.lisp.guile.bugs,gmane.lisp.guile.devel Subject: bug#10522: Patch: Improve optional variable and keyword notation in manual Date: Sat, 04 Feb 2012 08:16:13 -0500 Message-ID: <87wr82u4bm.fsf@goof.localdomain> References: <87d3ajh1lt.fsf@goof.localdomain> <87obtgjbag.fsf@pobox.com> Reply-To: b3timmons@speedymail.org NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: dough.gmane.org 1328361451 27872 80.91.229.3 (4 Feb 2012 13:17:31 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 4 Feb 2012 13:17:31 +0000 (UTC) Cc: b3timmons@speedymail.org, guile-devel , 10522@debbugs.gnu.org To: Andy Wingo Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Sat Feb 04 14:17:29 2012 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RtfUf-00019g-GC for guile-bugs@m.gmane.org; Sat, 04 Feb 2012 14:17:29 +0100 Original-Received: from localhost ([::1]:40788 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RtfUf-0000HT-08 for guile-bugs@m.gmane.org; Sat, 04 Feb 2012 08:17:29 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:57770) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RtfUc-0000HL-IZ for bug-guile@gnu.org; Sat, 04 Feb 2012 08:17:27 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RtfUZ-0006wY-U3 for bug-guile@gnu.org; Sat, 04 Feb 2012 08:17:26 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:49588) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RtfUZ-0006wO-ND for bug-guile@gnu.org; Sat, 04 Feb 2012 08:17:23 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1RtfVB-0006Xr-Hc for bug-guile@gnu.org; Sat, 04 Feb 2012 08:18:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Bake Timmons Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-guile@gnu.org Resent-Date: Sat, 04 Feb 2012 13:18:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 10522 X-GNU-PR-Package: guile X-GNU-PR-Keywords: Original-Received: via spool by 10522-submit@debbugs.gnu.org id=B10522.132836147025143 (code B ref 10522); Sat, 04 Feb 2012 13:18:01 +0000 Original-Received: (at 10522) by debbugs.gnu.org; 4 Feb 2012 13:17:50 +0000 Original-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 Original-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 Original-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 Original-Received: by goof.localdomain (Postfix, from userid 1000) id 25DB680FC0; Sat, 4 Feb 2012 08:16:13 -0500 (EST) In-Reply-To: <87obtgjbag.fsf@pobox.com> (Andy Wingo's message of "Fri, 03 Feb 2012 14:28:55 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.92 (gnu/linux) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:6195 gmane.lisp.guile.devel:13799 Archived-At: 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