Re: Syntax Parameters documentation for guile

[Andy Wingo <wingo@pobox.com>]

On Sun 08 Jan 2012 03:39, Ian Price <ianprice90@googlemail.com> writes:

> From b7d764179d5546698617993e5a648d6c1393b5c0 Mon Sep 17 00:00:00 2001
> From: Ian Price <ianprice90@googlemail.com>
> 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/