From acb7be83d5d453836b01e39f8dd27c8c341978e8 Mon Sep 17 00:00:00 2001
From: Ben Greenman <benjaminlgreenman@gmail.com>
Date: Wed, 27 Feb 2019 10:33:42 -0500
Subject: [PATCH] doc: the match pattern 'else' binds a variable (#2505)

In the guide & reference, explain that `match` treats `else` like any other variable and say how this is different from how `cond` and `case` treat the default `else` identifier.

This commit is inspired by two mailing list discussions:

- https://groups.google.com/d/msg/racket-users/hqXX_GL2Vlo/c6mT7W0_BwAJ
- https://lists.racket-lang.org/dev/archive/2013-May/012240.html
---
 pkgs/racket-doc/scribblings/guide/match.scrbl  | 18 ++++++++++++++++++
 .../scribblings/reference/match.scrbl          |  9 ++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/pkgs/racket-doc/scribblings/guide/match.scrbl b/pkgs/racket-doc/scribblings/guide/match.scrbl
index 2670ffc03a..72bec46f55 100644
--- a/pkgs/racket-doc/scribblings/guide/match.scrbl
+++ b/pkgs/racket-doc/scribblings/guide/match.scrbl
@@ -92,6 +92,24 @@ which does not bind (and thus is usually used as a catch-all):
   [_ 'something-else])
 ]
 
+Note that the identifier @racket[else] is @bold{not} a reserved catch-all (like @racket[_]).
+If @racket[else] appears in a pattern then its binding from
+@racketmodname[racket/base] may be shadowed, and this can cause problems with
+@racket[cond] and @racket[case].
+
+@interaction[
+#:eval match-eval
+(match 1
+  [else
+   (case 2
+     [(a 1 b) 3]
+     [else 4])])
+(match #f
+  [else
+   (cond
+     [#f 'not-evaluated]
+     [else 'also-not-evaluated])])
+]
 
 An ellipsis, written @litchar{...}, acts like a Kleene star within a
 list or vector pattern: the preceding sub-pattern can be used to match
diff --git a/pkgs/racket-doc/scribblings/reference/match.scrbl b/pkgs/racket-doc/scribblings/reference/match.scrbl
index 812d12f189..d2079fd336 100644
--- a/pkgs/racket-doc/scribblings/reference/match.scrbl
+++ b/pkgs/racket-doc/scribblings/reference/match.scrbl
@@ -91,7 +91,9 @@ In more detail, patterns match as follows:
        @racketidfont{...}, @racketidfont{___},
        @racketidfont{..}@racket[_k], and
        @racketidfont{..}@racket[_k] for non-negative integers
-       @racket[_k]) or @racket[(var _id)] --- matches anything, and binds @racket[_id] to the
+       @racket[_k]) @margin-note{Unlike in @racket[cond] and @racket[case],
+       @racket[else] is not a keyword in @racket[match].} or @racket[(var _id)]
+       --- matches anything, and binds @racket[_id] to the
        matching values. If an @racket[_id] is used multiple times
        within a pattern, the corresponding matches must be the same
        according to @racket[(match-equality-test)], except that
@@ -107,6 +109,11 @@ In more detail, patterns match as follows:
        (match '(1 (x y z) 1)
          [(list a b a) (list a b)]
          [(list a b c) (list c b a)])
+       (match #f
+         [else
+          (cond
+            [#f 'not-evaluated]
+            [else 'also-not-evaluated])])
        ]}
 
  @item{@racketidfont{_} --- matches anything, without binding any