From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Nala Ginrut Newsgroups: gmane.lisp.guile.devel Subject: Re: manual examples - self contained or not? Date: Mon, 20 Feb 2012 01:50:46 +0800 Message-ID: References: <87d39ag4fv.fsf@Kagami.home> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=f46d042fd72249f53304b954d1e3 X-Trace: dough.gmane.org 1329673857 17969 80.91.229.3 (19 Feb 2012 17:50:57 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 19 Feb 2012 17:50:57 +0000 (UTC) Cc: guile-devel@gnu.org To: Ian Price Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sun Feb 19 18:50:54 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 1RzAuT-0002W1-TN for guile-devel@m.gmane.org; Sun, 19 Feb 2012 18:50:54 +0100 Original-Received: from localhost ([::1]:33616 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RzAuT-0007hm-3W for guile-devel@m.gmane.org; Sun, 19 Feb 2012 12:50:53 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:47746) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RzAuQ-0007hh-Hi for guile-devel@gnu.org; Sun, 19 Feb 2012 12:50:51 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RzAuP-00036b-1U for guile-devel@gnu.org; Sun, 19 Feb 2012 12:50:50 -0500 Original-Received: from mail-vx0-f169.google.com ([209.85.220.169]:59933) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RzAuO-00036X-R2 for guile-devel@gnu.org; Sun, 19 Feb 2012 12:50:48 -0500 Original-Received: by vcbf13 with SMTP id f13so4001880vcb.0 for ; Sun, 19 Feb 2012 09:50:48 -0800 (PST) Received-SPF: pass (google.com: domain of nalaginrut@gmail.com designates 10.220.141.201 as permitted sender) client-ip=10.220.141.201; Authentication-Results: mr.google.com; spf=pass (google.com: domain of nalaginrut@gmail.com designates 10.220.141.201 as permitted sender) smtp.mail=nalaginrut@gmail.com; dkim=pass header.i=nalaginrut@gmail.com Original-Received: from mr.google.com ([10.220.141.201]) by 10.220.141.201 with SMTP id n9mr9674798vcu.66.1329673848032 (num_hops = 1); Sun, 19 Feb 2012 09:50:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=w720gZFj6IS2PNHd85MK0+suQRcuWGDif7LBa/oNcJY=; b=QLwfR+KCj9bK4ylBG2ntxR6pfwQeydvrXk3QM8+W8HcjcAzM5/QYUU6UvmLMzzPw4w CB1M6kZWmsdp2w35Xv4RZcmlMyLScs4948qwD6Acc7+mUmnDzlskBBrL+eKWo1xDeHVG 4s8eTQ1iIMBrLTydLnAyfwV5WOQH118bEEWaI= Original-Received: by 10.220.141.201 with SMTP id n9mr7674262vcu.66.1329673846518; Sun, 19 Feb 2012 09:50:46 -0800 (PST) Original-Received: by 10.52.158.34 with HTTP; Sun, 19 Feb 2012 09:50:46 -0800 (PST) In-Reply-To: <87d39ag4fv.fsf@Kagami.home> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 209.85.220.169 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:13894 Archived-At: --f46d042fd72249f53304b954d1e3 Content-Type: text/plain; charset=UTF-8 well, I don't believe in copy-paste code too. But my vote would be "at least I can trust the official manual"... On Mon, Feb 20, 2012 at 12:42 AM, Ian Price wrote: > > Hi guilers, > > is there an "official" policy on whether or not examples in the manual > should be self contained? > > On IRC, kudkudyak was confused about read-line not being found when he > tried to run one of the socket examples. Naturally, I pointed out that > this is because read-line is in (ice-9 rdelim). > > Some manual examples, however, do include imports > > https://www.gnu.org/software/guile/manual/html_node/Hash-Table-Reference.html > includes srfis 1 and 13. An example in > https://www.gnu.org/software/guile/manual/html_node/Dynamic-FFI.html > includes (rnrs bytevectors). > > With the obvious exception of examples whose entire purpose is to show > off the module system, and similar, I think we should adopt a consistent > policy one way or the other, and adapt all the examples to it. > > My vote would be for self-contained: it can be copied directly into a > file or REPL and executed, and IMO reduces confusion. I already try to > do this when posting any examples on paste.lisp.org or in a gist. > > Other people may feel differently, as it is relatively easy to search > the manual for missing procedures and, as cky put it, "I don't believe > in copypasta coding". > > -- > Ian Price > > "Programming is like pinball. The reward for doing it well is > the opportunity to do it again" - from "The Wizardy Compiled" > > > --f46d042fd72249f53304b954d1e3 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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"...

On Mon, Feb 20, 2012 at 12:42 AM, Ian Price <ianprice90@goo= glemail.com> wrote:

Hi guilers,

is there an "official" policy on whether or not examples in the m= anual
should be self contained?

On IRC, kudkudyak was confused about read-line not being found when he
tried to run one of the socket examples. Naturally, I pointed out that
this is because read-line is in (ice-9 rdelim).

Some manual examples, however, do include imports
https://www.gnu.org/software/guile/manual/= html_node/Hash-Table-Reference.html
includes srfis 1 and 13. =C2=A0An example in
https://www.gnu.org/software/guile/manual/html_node= /Dynamic-FFI.html
includes (rnrs bytevectors).

With the obvious exception of examples whose entire purpose is to show
off the module system, and similar, I think we should adopt a consistent policy one way or the other, and adapt all the examples to it.

My vote would be for self-contained: it can be copied directly into a
file or REPL and executed, and IMO reduces confusion. I already try to
do this when posting any examples on paste.lisp.org or in a gist.

Other people may feel differently, as it is relatively easy to search
the manual for missing procedures and, as cky put it, "I don't bel= ieve
in copypasta coding".

--
Ian Price

"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"= ;



--f46d042fd72249f53304b954d1e3--