Any advice about improving the docs?

Any advice about improving the docs?

[42toes]

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

Re: Any advice about improving the docs?

[Ludovic Courtès]

Hi,

42toes@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’.

Re: Any advice about improving the docs?

[Andy Wingo]

On Thu 03 Nov 2011 14:37, 42toes@gmail.com writes:

> I seek advice on making the Guile manual and docstrings clearer and more
> consistent, two qualities that I think novices especially appreciate.

We are still very much interested in your contributions, especially now
that the assignment forms are in :-)

We will be releasing a 2.0.4 soonish, perhaps within a week, and so now
is a perfect time to send a series of small, easy-to-apply,
git-format-patch produced attachments to the list :-)

Cheers,

Andy
-- 
http://wingolog.org/

Re: Any advice about improving the docs?

[Bake Timmons]

Andy Wingo <wingo@pobox.com> writes:

> We are still very much interested in your contributions, especially now
> that the assignment forms are in :-)
>
> We will be releasing a 2.0.4 soonish, perhaps within a week, and so now
> is a perfect time to send a series of small, easy-to-apply,
> git-format-patch produced attachments to the list :-)
>

Hi Andy,

I did have a huge patch, but the dog... No, my motherboard started
flaking, and I ended up w/ a new system. :)

Anyway, I will now work on some small patches.

Thanks for the reminder.

Bake