GNU bug report logs - #10522
Patch: Improve optional variable and keyword notation in manual

Previous Next

Full log

Message #25 received at 10522 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Hartwig <mandyke <at> gmail.com>
To: Andy Wingo <wingo <at> pobox.com>
Cc: guile-devel <guile-devel <at> gnu.org>, 10522 <at> debbugs.gnu.org
Subject: Re: bug#10522: Patch: Improve optional variable and keyword notation
	in manual
Date: Sun, 3 Mar 2013 09:07:24 +0800

On 3 March 2013 03:36, Andy Wingo <wingo <at> pobox.com> wrote:
> Hi Bake,
>
> On Fri 03 Feb 2012 14:28, Andy Wingo <wingo <at> 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 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.