From: Alan Grover <awgrover@mail.msen.com>
Subject: Unclear documentation: "Options and Config", set! and enable/disable
Date: Tue, 21 Jun 2005 11:55:40 -0400 [thread overview]
Message-ID: <42B8387C.4040903@mail.msen.com> (raw)
[-- Attachment #1.1: Type: text/plain, Size: 1700 bytes --]
Guile 1.6.4
Documentation guile-1.6.4/doc/ref/guile_36.html
Summary:
It isn't clear from the documentation how to use the "User Level Options
Interfaces" (chapter "Configuration, Features and Runtime Options"). In
particular, it isn't clear when the "option-symbol" should not be
quoted. I lost quite a bit of time before I realized that <group>-set!
are macros.
Example/notes:
(debug-set! 'width 80) => Unknown mode flag: (quote width)
(debug-set! width 80) => ok
(debug-enable 'breakpoints) -> ok
(debug-enable breakpoints) -> Unbound variable: breakpoints
Apparently, all of the <group>-set! are macros, and interpret the first
argument as a symbol. Perhaps this was an attempt to make this interface
appear analogous to set!, despite the option-symbols not being
defined/bound.
In contrast, the <group>-enable/<group>-disable are procedures, and thus
you have to pass a symbol as the first argument.
Suggested changes:
I would suggest the following:
In "User Level Options Interfaces" (section 33.3.2 of my manual), in the
subsection on <group>-set!, add some verbiage like:
These are macros, the first argument is the name of the option: do not
quote it. E.g. (print-set! closure-hook some-fn).
And, in the two subsections on <group>-disable/<group>:w
-enable:
These are procedures, the first argument is a symbol. E.g. (read-enable
'case-insensitive).
If possible, <name>-set! should give a more helpful error message when
it is expecting a (unquoted) symbol but sees a list.
While you're at it, the "Low Level Options Interfaces" (section 33.3.1)
is unclear. At least give a working example of each argument-list variation.
--
Alan Grover
awgrover@mail.msen.com
+1.734.476.0969
[-- Attachment #1.2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]
[-- Attachment #2: Type: text/plain, Size: 137 bytes --]
_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-guile
next reply other threads:[~2005-06-21 15:55 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-06-21 15:55 Alan Grover [this message]
2005-06-23 23:48 ` Unclear documentation: "Options and Config", set! and enable/disable Kevin Ryde
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=42B8387C.4040903@mail.msen.com \
--to=awgrover@mail.msen.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).