[PATCH v1 6/6] docs/match:style reviewing with pdf, adding newlines

[Blake Shaw <blake@reproduciblemedia.com>]

---
 doc/ref/match.texi | 78 ++++++++++++++++++++++++++++------------------
 1 file changed, 47 insertions(+), 31 deletions(-)

diff --git a/doc/ref/match.texi b/doc/ref/match.texi
index 5512103c4..38745e173 100644
--- a/doc/ref/match.texi
+++ b/doc/ref/match.texi
@@ -19,15 +19,15 @@
 @cindex pattern matching
 @cindex (ice-9 match)
 
-The @code{(ice-9 match)} module provides a @dfn{pattern matcher},
+@* The @code{(ice-9 match)} module provides a @dfn{pattern matcher},
 written by Alex Shinn, and compatible with Andrew K. Wright's pattern
 matcher found in many Scheme implementations.
 
-A pattern matcher does precisely what the name implies: it matches
-some arbitrary pattern, and returns some result accordingly.
-
-@lisp
+@* @noindent A pattern matcher does precisely what the name implies: it
+matches some arbitrary pattern, and returns some result accordingly.
 
+@*
+@example
 (define (english-base-ten->number name)
   (match name
     ('zero   0)
@@ -40,40 +40,43 @@ some arbitrary pattern, and returns some result accordingly.
     ('seven  7)
     ('eight  8)
     ('nine   9)))
-
-@end lisp
+@end example
       
-@lisp
+@*
+@example
 (english-base-ten->number 'six)
-
 @result{} 6
-@end lisp
+@end example
 
-@lisp
+@example
 (apply + (map english-base-ten->number '(one two three four)))
 @result{} 10 
-@end lisp 
+@end example
 
-@cindex pattern variable
-Pattern matchers may contain @dfn{pattern variables}, local bindings
-to all elements that match a pattern.
+@*
+@page
+@cindex pattern variable 
+@noindent Pattern matchers may contain @dfn{pattern variables},
+local bindings to all elements that match a pattern.
 
-@example
-(let re ((ns '(one two three four ten))
-         (total 0)) 
+@example 
+
+(let re ([ns '(one two three four 9)] [total 0]) 
   (match ns
-    ((e) (+ total (english-base-ten->number e)))
-    ((e . es) 
-     (re es (+ total (english-base-ten->number e))))))
-@result{} 20
+    [(e) (+ total (english-base-ten->number e))]
+    [(e . es) 
+     (re es (+ total (english-base-ten->number e)))]))
+
+@result{} 19
 @end example
 
-In this example, the list @var{ns} matches the pattern
+@*
+@noindent In this example, the list @var{ns} matches the pattern
 @code{(e . es)}, where the pattern variable @var{e} corresponds 
-to the `car` of @var{ns} and the pattern variable @var{es}
-corresponds to the `cdr` of @var{ns}.
+to the metaphoical "car" of @var{ns} and the pattern variable @var{es}
+corresponds to the "cdr" of @var{ns}.
 
-A tail call @code{re} is then initiated and we `cdr` down the
+A tail call @code{re} is then initiated and we "cdr" down the
 list by recurring on the tail @var{es}, applying our matcher
 @code{english-base-ten->number} to each element of @var{ns} until
 only a single element @code{(e)} remains, causing the @var{total}
@@ -82,15 +85,16 @@ to be computed.  In modern Scheme programming it is common to use
 of @code{cond}, @code{car} and @code{cdr}, so it's important to
 understand how these idioms translate. 
 
+@*
 Patterns can be composed and nested.  For instance, @code{...}
 (ellipsis) means that the previous pattern may be matched zero or more
 times in a list:
 
 @example
+
 (match lst
-  (((heads tails ...) ...)
-     heads))
-@result{} 
+  (((heads tails ...) ...) heads))
+
 @end example
 
 @noindent
@@ -104,25 +108,31 @@ A pattern matcher can match an object against several patterns and
 extract the elements that make it up. 
 
 @example
+
 (let ((m '((l1 . r1) (l2 . r2) (l3 . r3))))
   (match m
     (((left . right) ...) 
      (list left right)))) 
+
 @result{} ((l1 l2 l3) (r1 r2 r3))
 @end example
 
 @example
+
 (let ((m '((1 . (a . b)) (2 . (c . d)) (3 . (e . f)))))
   (match m
     (((key . (left . right)) ...) 
      (fold-right acons '() key right ))))
+
 @result{} ((1 . b) (2 . d) (3 . f))
 @end example
 
 @example
+
 (match '(((a b c) e f g) 1 2 3)  
   ((((head ...) . rest) tails ...)
    (acons tails head rest )))
+
 @result {} (((1 2 3) a b c) e f g)
 @end example
 
@@ -130,6 +140,7 @@ Patterns can represent any Scheme object: lists, strings, symbols,
 records, etc.
 
 @example
+
 (let re ((m #(a "b" c "d" e "f" g)))
    (match m
      ((or (e) #(e)) e)
@@ -137,7 +148,9 @@ records, etc.
 	   (e1 e2 es ...)) 
        (cons (cons e1 e2)
  	     (re es)))))
+
 @result{} ((a . "b") (c . "d") (e . "f") . g) 
+
 @end example
 
 When a matching pattern is found, an expression associated with the
@@ -145,12 +158,15 @@ pattern is evaluated, optionally with all pattern variables bound to
 the corresponding elements of the object.
 
 @example
+
 (let re ((m '(a b c d e f g h i)))
    (match m
      ((e) e)
      ((e1 e2 es ...) 
       (acons e1 e2 (re es)))))
+
 @result{} ((a . b) (c . d) (e . f) (g . h) . i)
+
 @end example
 
 Compared to hand-written code, pattern matching noticeably improves
@@ -161,7 +177,7 @@ pattern---conversely, hand-written code often trades robustness for
 conciseness.  And of course, @code{match} is a macro, and the code it
 expands to is just as efficient as equivalent hand-written code.
 
-The pattern matcher is defined as follows:
+@noindent @* We define @emph{match} as follows. @*
 
 @deffn {Scheme Syntax} match exp clause1 clause2 @dots{}
 Match object @var{exp} against the patterns in @var{clause1}
@@ -188,7 +204,7 @@ arbitrary Scheme expression, possibly referring to pattern variables of
 @c
 @c clause ::= (pat body) | (pat => exp)
 
-The syntax and interpretation of patterns is as follows:
+@noindent @* The syntax and interpretation of patterns is as follows: @*
 
 @verbatim
         patterns:                       matches:
-- 
2.39.1