Re: bug#10522: Patch: Improve optional variable and keyword notation in manual
On Sat 09 Mar 2013 02:58, Daniel Hartwig mand...@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/
Re: bug#10522: Patch: Improve optional variable and keyword notation in manual
On 9 March 2013 16:25, Andy Wingo wi...@pobox.com wrote: Should we remove the brackets entirely? i.e I would not. The brackets are fairly standard for optional arguments.
Re: bug#10522: Patch: Improve optional variable and keyword notation in manual
On 9 March 2013 09:58, Daniel Hartwig mand...@gmail.com wrote: On 3 March 2013 17:45, Andy Wingo wi...@pobox.com wrote: On Sun 03 Mar 2013 02:07, Daniel Hartwig mand...@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 '.
Re: bug#10522: Patch: Improve optional variable and keyword notation in manual
On Sun 03 Mar 2013 02:07, Daniel Hartwig mand...@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?
Re: bug#10522: Patch: Improve optional variable and keyword notation in manual
Hi Bake, On Fri 03 Feb 2012 14:28, Andy Wingo wi...@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 b3timm...@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/
Re: bug#10522: Patch: Improve optional variable and keyword notation in manual
On 3 March 2013 03:36, Andy Wingo wi...@pobox.com wrote: Hi Bake, On Fri 03 Feb 2012 14:28, Andy Wingo wi...@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 b3timm...@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.
Re: bug#10522: Patch: Improve optional variable and keyword notation in manual
Hello! :-) Andy Wingo wi...@pobox.com skribis: On Mon 16 Jan 2012 20:46, Bake Timmons b3timm...@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-texi...@gnu.org have something to say about this kind of thing, since there are other Lispy packages out there with similar features? Thanks, Ludo’.