From c4926b56847f83dd7107e9ce8c19395f441b3e27 Mon Sep 17 00:00:00 2001
From: Robby Findler <robby@racket-lang.org>
Date: Fri, 30 Dec 2016 08:46:57 -0600
Subject: [PATCH] clarify the purpose of the (bad) match expander example

closes #1553
---
 pkgs/racket-doc/scribblings/reference/match.scrbl | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/pkgs/racket-doc/scribblings/reference/match.scrbl b/pkgs/racket-doc/scribblings/reference/match.scrbl
index 42b2844091..7f8ef3d7d7 100644
--- a/pkgs/racket-doc/scribblings/reference/match.scrbl
+++ b/pkgs/racket-doc/scribblings/reference/match.scrbl
@@ -623,8 +623,9 @@ For example, to extend the pattern matcher and destructure syntax lists,
 
 And here is an example showing how 
 @racket[define-match-expander]-bound identifiers are
-not treated specially unless they appear
-in the first position of pattern sequence.
+@emph{not} treated specially unless they appear
+in the first position of pattern sequence. Consider
+this (incorrect) definition of a length function:
 @examples[#:label #f
   #:eval match-eval
   (eval:no-prompt
@@ -634,11 +635,17 @@ in the first position of pattern sequence.
    (define (len l)
      (match l
        [nil 0]
-       [(cons hd tl) (+ 1 (len tl))])))
+       [(cons hd tl) (+ 1 (len tl))])))]
+
+Because there are no parenthesis around @racket[nil],
+@racket[match] treats the first case as an identifier
+(which matches everything) instead of a use of the match
+expander and @racket[len] always returns @racket[0].
+
+@examples[#:label #f #:eval match-eval
   (len nil)
   (len (cons 1 nil))
   (len (cons 1 (cons 2 nil)))]
-
 }
 
 @defthing[prop:match-expander struct-type-property?]{