guile-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: manual examples - self contained or not?


From: Neil Jerram
Subject: Re: manual examples - self contained or not?
Date: Tue, 21 Feb 2012 21:14:32 +0000
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux)

Nala Ginrut <address@hidden> writes:

> well, I don't believe in copy-paste code too.
> But my vote would be "at least I can trust the official manual"...

I did think it would be nice, a while back, if we could implement a way
of automatically checking that the examples in the manual are still
correct, and that they generate the results that the manual says they
do.  I think that would contribute to being able to trust the manual, or
else flag up any areas that might have rotted a bit.

In order to do that, without requiring too much special casing code, the
checker would need to be able to identify any required module uses.

So, in addition to the direct benefit for people reading the manual, I
think that motivates that the example should be by some definition self
contained.  As others have suggested, I'd favour automatically picking
up (use-modules ...) forms from earlier or higher up in the current
hierarchy, so that it isn't necessary to keep repeating those in every
@example.

Does anyone fancy the automatic checking project?

      Neil



reply via email to

[Prev in Thread] Current Thread [Next in Thread]