* Unclear documentation: "Options and Config", set! and enable/disable
@ 2005-06-21 15:55 Alan Grover
2005-06-23 23:48 ` Kevin Ryde
0 siblings, 1 reply; 2+ messages in thread
From: Alan Grover @ 2005-06-21 15:55 UTC (permalink / 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
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2005-06-23 23:48 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-06-21 15:55 Unclear documentation: "Options and Config", set! and enable/disable Alan Grover
2005-06-23 23:48 ` Kevin Ryde
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).