Hi,
42t...@gmail.com skribis:
> I seek advice on making the Guile manual and docstrings clearer and more
> consistent, two qualities that I think novices especially appreciate.
Thanks for looking into it!
> ----------------------------------------------------------------------
> @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}".
Three considerations: it has to be the same name for the Scheme proc and
the C function, it has to be a valid C identifier, and of course it has
to be descriptive.
So in this example I would stick to ‘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" ?
Yes, definitely.
> ----------------------------------------------------------------------
> @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}"?
Agreed.
> ----------------------------------------------------------------------
> @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} ..."?
Agreed.
> B. Minor issues
>
> 1. Case errors (e.g., unnecessary caps in a @var or on a @deffn line)
Like @var{VAR}? Did you find it? If so, it probably needs to be fixed, yes.
> 2. Redundant plurals (e.g., bindings @dots{} instead of binding @dots{})
It’s not necessary redundant, I think. As in ‘args ...’.
> 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)
Indeed, should be fixed.
> 4. Typographical problems (e.g., using "..." instead of "@dots{}")
>
> OK to fix these?
Yes!
> 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?
Don’t bother!
We’d be happy to accept a patch.
It may be necessary to assign copyright to the FSF, if this is not a
problem for you. We can discuss this off-line if you want.
Thanks,
Ludo’.
