Re: Any advice about improving the docs?

[Ludovic Courtès]

Hi,

address@hidden 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’.