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

[Bake Timmons <b3timmons@speedymail.org>]

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