From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Andy Wingo Newsgroups: gmane.lisp.guile.devel Subject: Re: Syntax Parameters documentation for guile Date: Sun, 08 Jan 2012 14:47:39 +0100 Message-ID: <87boqee26c.fsf@pobox.com> References: <87pqff8f5g.fsf@Kagami.home> <20222.48501.219043.125940@winooski.ccs.neu.edu> <87sjjwz8u9.fsf@Kagami.home> <20227.40509.861506.889987@winooski.ccs.neu.edu> <87mxa0llbd.fsf@pobox.com> <87aa60mflr.fsf@Kagami.home> <87y5tjl8gn.fsf@Kagami.home> <87y5tjdpm6.fsf@pobox.com> <87ipkmlxyd.fsf@Kagami.home> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1326030474 2812 80.91.229.12 (8 Jan 2012 13:47:54 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 8 Jan 2012 13:47:54 +0000 (UTC) Cc: Guile Mailing List To: Ian Price Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sun Jan 08 14:47:50 2012 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Rjt6D-0005nb-LX for guile-devel@m.gmane.org; Sun, 08 Jan 2012 14:47:49 +0100 Original-Received: from localhost ([::1]:35674 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rjt6D-0002jB-1a for guile-devel@m.gmane.org; Sun, 08 Jan 2012 08:47:49 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:56373) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rjt6A-0002iv-2t for guile-devel@gnu.org; Sun, 08 Jan 2012 08:47:47 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Rjt68-0003UP-UL for guile-devel@gnu.org; Sun, 08 Jan 2012 08:47:46 -0500 Original-Received: from a-pb-sasl-sd.pobox.com ([74.115.168.62]:61019 helo=sasl.smtp.pobox.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rjt68-0003UJ-Q6 for guile-devel@gnu.org; Sun, 08 Jan 2012 08:47:44 -0500 Original-Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id 572D86D8A; Sun, 8 Jan 2012 08:47:44 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=xdTBmZCoveu0Pn+xxXEHI1GKabM=; b=GCKbO4 xIZiMk9WH7vE4Ubpekc9UcgNdTdvkO3lzj6L9R3T0itXd+KSalw2NbpdtZ2/s97C urD6ZXwIH5EiTq6ejy5nqNgh6ABYmgsDT8OcRhzKrwTBDFJ8unUeYH5YDzG6Ve/d aQdsJmX4rXMuGaDGOHAFZhx1QKeL6N+kTnW/U= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; q=dns; s=sasl; b=V37uMmiiqL3B5FlNcFAaVC6XKtz/Z3ub aBrLpLgyV1oyDT0WHLNkzqEC00iWXtSzEx4ZKKaT31gSRjrbZbqGrbxm0sNFLTuC rcfx3SDB7U8umzv4lRjKMSrTmitoh1GdKLBSHlpjjBHcqUQCyXpHmbPFvOaD7iG2 VezvzKRuO3I= Original-Received: from a-pb-sasl-sd.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id 4E3E36D89; Sun, 8 Jan 2012 08:47:44 -0500 (EST) Original-Received: from badger (unknown [90.164.198.39]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTPSA id 8A27F6D88; Sun, 8 Jan 2012 08:47:43 -0500 (EST) In-Reply-To: <87ipkmlxyd.fsf@Kagami.home> (Ian Price's message of "Sun, 08 Jan 2012 02:39:22 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) X-Pobox-Relay-ID: 5703893C-39FF-11E1-8D4C-65B1DE995924-02397024!a-pb-sasl-sd.pobox.com X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-Received-From: 74.115.168.62 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:13438 Archived-At: On Sun 08 Jan 2012 03:39, Ian Price writes: > From b7d764179d5546698617993e5a648d6c1393b5c0 Mon Sep 17 00:00:00 2001 > From: Ian Price > Date: Sat, 7 Jan 2012 01:59:33 +0000 > Subject: [PATCH] document syntax parameters > > * doc/ref/api-macros.texi (Macros): Add subsection for "Syntax Parameters" Applied, thanks! I committed some additional edits. I wanted to point them out to you, as you might be interested in the tao of texinfo: > +definition within the dynamic extent of a macro expansion. It provides We use two spaces after periods in the Guile manual. > +a convenient solution to one of the most common types of unhygienic > +macro: those that introduce a unhygienic binding each time the macro > +is used. Examples include a @code{lambda} form with a @code{return} keyword, or > +class macros that introduce a special @code{self} binding. And, we try to keep things wrapped to 72 columns. M-q in emacs will refill a paragraph for you. > +With syntax parameters, instead of introducing the binding > +unhygienically each time, we instead create one binding for the > +keyword, which we can then adjust later when we want the keyword to > +have a different meaning. As no new bindings are introduced, hygiene > +is preserved. This is similar to the dynamic binding mechanisms we > +have at run-time like @ref{SRFI-39, parameters} or > +@ref{Fluids and Dynamic States, fluids}, except that the dynamic @ref in mid-sentence doesn't look very nice in print output: http://www.gnu.org/savannah-checkouts/gnu/texinfo/manual/texinfo/html_node/ref.html#ref I changed this to be (@pxref{...}). > + ;; in the body we adjust the 'return' keyword so that calls > + ;; to 'return' are replaced with calls to the escape continuation Unless it's an inline comment, it's best to make whole sentences. Lovely example, by the way. Thanks for the docs! Andy -- http://wingolog.org/