Unclear documentation: "Options and Config", set! and enable/disable

[Alan Grover]

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
address@hidden
+1.734.476.0969

signature.asc
Description: OpenPGP digital signature