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

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

[Alan Grover]

[-- 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

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

[Kevin Ryde]

Alan Grover <awgrover@mail.msen.com> writes:
>
> It isn't clear from the documentation how to use the "User Level Options
> Interfaces" (chapter "Configuration, Features and Runtime Options").

Alas, yes.

> 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.

An example of a macro only serving to obscure :(.


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-guile