Any advice about improving the docs?

[42toes@gmail.com]

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