GNU bug report logs - #10163
Incomplete/vague section of Guile Manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 10163 in the body.
You can then email your comments to 10163 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ryan Fox <ryan <at> rcfox.ca>
To: bug-guile <at> gnu.org
Subject: Incomplete/vague section of Guile Manual
Date: Tue, 29 Nov 2011 20:17:18 -0500

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

Message #10 received at 10163-done <at> debbugs.gnu.org (full text, mbox):

From: Andy Wingo <wingo <at> pobox.com>
To: Ryan Fox <ryan <at> rcfox.ca>
Cc: 10163-done <at> debbugs.gnu.org
Subject: Re: bug#10163: Incomplete/vague section of Guile Manual
Date: Thu, 22 Dec 2011 09:34:28 -0500

Hi Ryan,

Thanks for the report.

On Tue 29 Nov 2011 20:17, Ryan Fox <ryan <at> rcfox.ca> 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/

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.