From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.devel Subject: Re: manual examples - self contained or not? Date: Tue, 21 Feb 2012 21:14:32 +0000 Message-ID: <87wr7fc2iv.fsf@neil-laptop.ossau.uklinux.net> References: <87d39ag4fv.fsf@Kagami.home> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1329858894 29722 80.91.229.3 (21 Feb 2012 21:14:54 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 21 Feb 2012 21:14:54 +0000 (UTC) Cc: Ian Price , guile-devel@gnu.org To: Nala Ginrut Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Tue Feb 21 22:14:51 2012 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Rzx2v-0003a3-6r for guile-devel@m.gmane.org; Tue, 21 Feb 2012 22:14:49 +0100 Original-Received: from localhost ([::1]:60492 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rzx2r-0003ne-6T for guile-devel@m.gmane.org; Tue, 21 Feb 2012 16:14:45 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:34079) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rzx2l-0003nH-8j for guile-devel@gnu.org; Tue, 21 Feb 2012 16:14:43 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Rzx2h-000141-Ek for guile-devel@gnu.org; Tue, 21 Feb 2012 16:14:39 -0500 Original-Received: from out1.ip03ir2.opaltelecom.net ([62.24.128.239]:32442) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rzx2h-00013m-8w for guile-devel@gnu.org; Tue, 21 Feb 2012 16:14:35 -0500 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Av8EAFAIRE9OlcyG/2dsb2JhbAA5CoUTrS6BCIFzAQEEASMzIwULCAMaAgUhAgIPAQQNGCQTiAADphOSOoEvh01fgiQHHwUWAQkCFgMCg18CAS0cgheBFgSgT4dW X-IronPort-AV: E=Sophos;i="4.73,459,1325462400"; d="scan'208";a="376172873" Original-Received: from host-78-149-204-134.as13285.net (HELO arudy) ([78.149.204.134]) by out1.ip03ir2.opaltelecom.net with ESMTP; 21 Feb 2012 21:14:33 +0000 Original-Received: from neil-laptop.ossau.uklinux.net.ossau.homelinux.net (host-78-149-204-134.as13285.net [78.149.204.134]) by arudy (Postfix) with ESMTPA id 963B338037; Tue, 21 Feb 2012 21:14:32 +0000 (GMT) In-Reply-To: (Nala Ginrut's message of "Mon, 20 Feb 2012 01:50:46 +0800") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 62.24.128.239 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:13920 Archived-At: Nala Ginrut writes: > well, I don't believe in=C2=A0copy-paste=C2=A0code 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