Hi,
I seek advice on making the Guile manual and docstrings clearer and more
consistent, two qualities that I think novices especially appreciate.
Some considerations:
A. Variable names of definition headers not matching those in bodies.
E.g.,
----------------------------------------------------------------------
@deffn {Scheme Procedure} eval exp module_or_state
@deffnx {C Function} scm_eval (exp, module_or_state)
Evaluate @var{exp}, a list representing a Scheme expression,
in the top-level environment specified by @var{module}.
----------------------------------------------------------------------
I recall seeing several @deffn's w/ hyphentated variable names. So would
I change in the @deffn line "module_or_state" to "module-or-state"? I
assume that I would then change "@var{module}" to
"@var{module-or-state}".
----------------------------------------------------------------------
@deffn {Scheme Procedure} symbol-set! o s v
@deffnx {C Function} scm_symbol_set_x (o, s, v)
Find the symbol in @var{obarray} whose name is @var{string}, and rebind
----------------------------------------------------------------------
Just spell out the names in the @deffn? I.e.,
"... obarray string value" ?
----------------------------------------------------------------------
@deffn {Scheme Procedure} seek fd_port offset whence
@deffnx {C Function} scm_seek (fd_port, offset, whence)
Sets the current position of @var{fd/port} to the integer
----------------------------------------------------------------------
Why not, in keeping w/ the first example above, just "... seek
fd-or-port", "... scm_seek (fd_or_port", and "@var{fd-or-port}"?
----------------------------------------------------------------------
@deffn {Scheme Procedure} get-char port
Reads from @var{textual-input-port}, blocking as necessary, until a
----------------------------------------------------------------------
"textual-input-port" implies the type of port, but why not just say
"Reads from textual input port @var{port} ..."?
B. Minor issues
1. Case errors (e.g., unnecessary caps in a @var or on a @deffn line)
2. Redundant plurals (e.g., bindings @dots{} instead of binding @dots{})
3. Bad option notation on variables (non-keyword names)
(e.g., ... pointer->string pointer [length] [encoding] (bad)
instead of ... pointer->string pointer [length [encoding]] (good)
4. Typographical problems (e.g., using "..." instead of "@dots{}")
OK to fix these?
C. Things not to fix
1. doc/maint/guile.texi -- seems neglected
2. Variable name mismatches for a proc in the manual versus its docstring
Don't bother with these?
Thanks,
Bake
