> I'm working on something that I felt was very necessary for Scheme: a general booklet generally explaining all extant macro systems of Scheme, with some historic background but without delving too deep into technical details.
>
> I still have a bunch of stuff to learn (eg I don't fully understand syntactic closures) and I decided not to include everything there is to know about Racket's macro system, since it'd easily quadruple the scope of the booklet.
>
> It's a fairly long-winded and ambitious project and I'm hoping I don't run out of wind before it's done. (It's only 5% complete.) I might do it in the form of a series of blogposts.

Very ambitious project! If you manage to do even half of it, it's
already great and doubtless useful to both new and experienced Schemers.

Please note that some people have already written fairly involved macro
tutorials. It may even be possible to get permission to incorporate them
into your mega-document.

We should probably collect all of them in one place. Here are some:

A Scheme Syntax-Rules Primer (2008)
<http://www.willdonnelly.net/blog/scheme-syntax-rules/>

Advanced Scheme: Some Naughty Bits (2003-2004)
<https://people.csail.mit.edu/jhbrown/scheme/>

Let Over Lambda macro chapter
<https://letoverlambda.com/index.cl/guest/chap3.html>

Of course, for advanced macros in general, the book "On Lisp":
<http://www.paulgraham.com/onlisptext.html>

Oleg's stuff is always awesome:
<http://okmij.org/ftp/Scheme/macros.html>

An Advanced Syntax-Rules Primer for the Mildly Insane
<https://groups.google.com/forum/#!msg/comp.lang.scheme/hsM4g33joCA/GbZ1F-HGbOsJ>

> Here's the hypothetical table of contents:

LGTM.

> ** Homoiconicity

Some people think Lisp shouldn't be called homoiconic
<https://www.expressionsofchange.org/dont-say-homoiconic/>. Hacker News
discussion: <https://news.ycombinator.com/item?id=20657798>. I don't
understand their argument, but if you're writing an educational guide,
it's probably worth being precise about terminology.

> * Legacy macros
> ** Textual substitution
> ** fexprs
> ** define-macro

As Arthur said, some people still favor define-macro so it's not
necessarily legacy :) I don't know enough to comment about the other two.

> * Plus ultra
> ** State machines
> ** Continuation passing style

Would these be about macros in particular, or about call/cc tricks that
just go well with the topic? I think some of the above links also touch
upon this ground.

CPS would be good to discuss in a guide about Scheme compilation
strategies (either instead of, or in addition to the macro guide).

Good luck. Big projects take a ton of energy :) Please don't hesitate to
ask us for help or feedback if you need it.