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

Previous Next

Full log

View this message in rfc822 format

From: Bake Timmons <b3timmons <at> speedymail.org>
To: Andy Wingo <wingo <at> pobox.com>
Cc: b3timmons <at> speedymail.org, guile-devel <guile-devel <at> gnu.org>, 10522 <at> debbugs.gnu.org
Subject: bug#10522: Patch: Improve optional variable and keyword notation in manual
Date: Sat, 04 Feb 2012 08:16:13 -0500

Andy Wingo <wingo <at> pobox.com> writes:

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

Previous Next

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