GNU bug report logs -
#10522
Patch: Improve optional variable and keyword notation in manual
Previous Next
Reported by: b3timmons <at> speedymail.org
Date: Mon, 16 Jan 2012 19:49:02 UTC
Severity: normal
Done: Andy Wingo <wingo <at> pobox.com>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 10522 in the body.
You can then email your comments to 10522 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Mon, 16 Jan 2012 19:49:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
b3timmons <at> speedymail.org:
New bug report received and forwarded. Copy sent to
bug-guile <at> gnu.org.
(Mon, 16 Jan 2012 19:49:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
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
[0001-Improve-optional-variable-and-keyword-notation-of-Te.patch (text/x-diff, attachment)]
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Fri, 03 Feb 2012 19:29:03 GMT)
Full text and
rfc822 format available.
Message #8 received at 10522 <at> debbugs.gnu.org (full text, mbox):
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?
Anyway, I'm interested what others think about changes like this.
Cheers,
Andy
--
http://wingolog.org/
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Fri, 03 Feb 2012 23:55:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 10522 <at> debbugs.gnu.org (full text, mbox):
Hello! :-)
Andy Wingo <wingo <at> pobox.com> skribis:
> 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.
Indeed.
> Also, it seems pedantic to repeat the keyword arguments (once as
> keyword, once as identifier). Surely #:foo=bar is unambiguous?
That’s what I would think.
Perhaps the people behind bug-texinfo <at> gnu.org have something to say
about this kind of thing, since there are other Lispy packages out there
with similar features?
Thanks,
Ludo’.
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sat, 04 Feb 2012 03:43:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 10522 <at> debbugs.gnu.org (full text, mbox):
Andy Wingo <wingo <at> pobox.com> 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"
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sat, 04 Feb 2012 13:18:01 GMT)
Full text and
rfc822 format available.
Message #17 received at 10522 <at> debbugs.gnu.org (full text, mbox):
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
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sat, 02 Mar 2013 19:37:02 GMT)
Full text and
rfc822 format available.
Message #20 received at 10522 <at> debbugs.gnu.org (full text, mbox):
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
:)
Andy
--
http://wingolog.org/
bug closed, send any further explanations to
10522 <at> debbugs.gnu.org and b3timmons <at> speedymail.org
Request was from
Andy Wingo <wingo <at> pobox.com>
to
control <at> debbugs.gnu.org.
(Sat, 02 Mar 2013 19:58:02 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sun, 03 Mar 2013 01:08:02 GMT)
Full text and
rfc822 format available.
Message #25 received at 10522 <at> debbugs.gnu.org (full text, mbox):
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.
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sun, 03 Mar 2013 09:46:01 GMT)
Full text and
rfc822 format available.
Message #28 received at 10522 <at> debbugs.gnu.org (full text, mbox):
On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke <at> gmail.com> 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?
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sat, 09 Mar 2013 02:00:02 GMT)
Full text and
rfc822 format available.
Message #31 received at 10522 <at> debbugs.gnu.org (full text, mbox):
On 3 March 2013 17:45, Andy Wingo <wingo <at> pobox.com> wrote:
> On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke <at> gmail.com> 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=#f] [#:file=#f]
[#:line=#f] [#:column=#f] [#:lang=(current-language)]
[#:compile?=#f]
we see that there is some potential confusion between the close,
unescaped (as with @code, ‘’) nesting of the parens/brackets.
Further, usage of ‘=’ 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.
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sat, 09 Mar 2013 02:04:02 GMT)
Full text and
rfc822 format available.
Message #34 received at 10522 <at> debbugs.gnu.org (full text, mbox):
On 9 March 2013 09:58, Daniel Hartwig <mandyke <at> gmail.com> wrote:
> On 3 March 2013 17:45, Andy Wingo <wingo <at> pobox.com> wrote:
>> On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke <at> gmail.com> 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=#f] [#:file=#f]
> [#:line=#f] [#:column=#f] [#:lang=(current-language)]
> [#:compile?=#f]
>
> we see that there is some potential confusion between the close,
> unescaped (as with @code, ‘’) nesting of the parens/brackets.
> Further, usage of ‘=’ 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.
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 '.
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sat, 09 Mar 2013 08:27:02 GMT)
Full text and
rfc822 format available.
Message #37 received at 10522 <at> debbugs.gnu.org (full text, mbox):
On Sat 09 Mar 2013 02:58, Daniel Hartwig <mandyke <at> gmail.com> writes:
> -- Scheme Procedure: eval-string string [#:module=#f] [#:file=#f]
> [#:line=#f] [#:column=#f] [#:lang=(current-language)]
> [#:compile?=#f]
>
> we see that there is some potential confusion between the close,
> unescaped (as with @code, ‘’) nesting of the parens/brackets.
Should we remove the brackets entirely? i.e
-- Scheme Procedure: eval-string string #:module=#f #:file=#f
#:line=#f #:column=#f #:lang=(current-language)
#:compile?=#f
Or with @code{}:
-- Scheme Procedure: eval-string string #:module=‘#f’ #:file=‘#f’
#:line=‘#f’ #:column=‘#f’ #:lang=‘(current-language)’
#:compile?=‘#f’
Dunno, just throwing more ideas out there...
Andy
--
http://wingolog.org/
Information forwarded
to
bug-guile <at> gnu.org:
bug#10522; Package
guile.
(Sun, 10 Mar 2013 00:12:01 GMT)
Full text and
rfc822 format available.
Message #40 received at 10522 <at> debbugs.gnu.org (full text, mbox):
On 9 March 2013 16:25, Andy Wingo <wingo <at> pobox.com> wrote:
> Should we remove the brackets entirely? i.e
I would not. The brackets are fairly standard for optional arguments.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Sun, 07 Apr 2013 11:24:03 GMT)
Full text and
rfc822 format available.
This bug report was last modified 12 years and 74 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.