Subject: bug#10163: closed (Re: bug#10163: Incomplete/vague section of Guile Manual)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 22 Dec 2011 14:37:02 +0000

Your bug report

#10163: Incomplete/vague section of Guile Manual

which was filed against the guile package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
10163: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=10163
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#10163: Incomplete/vague section of Guile Manual
From: Andy Wingo <[email-masked]>
To: Ryan Fox <[email-masked]>
Cc: [email-masked]
Date: Thu, 22 Dec 2011 09:34:28 -0500
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi Ryan,

Thanks for the report.

On Tue 29 Nov 2011 20:17, Ryan Fox <[email-masked]> writes:

> /* Check that arg is really a shape SMOB. */
> SCM_VALIDATE_SHAPE (SCM_ARG1, shape);
>
> After some searching, I was able to figure out that the
> function scm_assert_smob_type() is probably the intended behaviour for
> this. However,
> there was no indication of this in the description.

I changed the example and the text to use scm_assert_smob_type.  This
entire section could use some modernization and less hand-waving, but
that is a larger project.

Happy hacking,

Andy
-- 
http://wingolog.org/

Subject: Incomplete/vague section of Guile Manual
From: Ryan Fox <[email-masked]>
To: [email-masked]
Date: Tue, 29 Nov 2011 20:17:18 -0500
List-Id: <debbugs-submit.debbugs.gnu.org>

Hello,
In section 5.7.1.4, "Writing Guile Primitives for Dia" at
http://www.gnu.org/software/guile/manual/guile.html, the description of the
square_p() implementation is incomplete. It uses a macro call to ensure
that the SCM value is a shape, but does not explain what that
implementation is:

/* Check that arg is really a shape SMOB. */
SCM_VALIDATE_SHAPE (SCM_ARG1, shape);

The explanation merely states:
"SCM_VALIDATE_SHAPE is a macro that you should define as part of your SMOB
definition: it checks that the passed parameter is of the expected type."

After some searching, I was able to figure out that the
function scm_assert_smob_type() is probably the intended behaviour for
this. However, there was no indication of this in the description.

As a side note: I'm a new Schemer, so perhaps this isn't idiomatic, but
would it make more sense to use the SCM_SMOB_PREDICATE macro instead? This
way, you can simply return false for any type, even if it isn't a shape.
Asking if a number is a shape (for example) doesn't strike me as
particularly exceptional or incorrect.

Thanks,
Ryan Fox