From ec6cb60c00c92d30ecbc6756adeea026d5971295 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 23 Jan 2013 11:40:36 -0500
Subject: [PATCH] paser-tools: doc clarifications

Nothing in the docs said that `parser-tools/yacc' is for LALR grammars
--- although I guess that it implied for most reader by the name "yacc",
but it doesn't hurt to say so explicitly. Meanwhile,
`parser-tools/cfg-parser' is useful for non-ambigious (non-LALR) grammars.

Also, from the style guide:
 * Section Titles Should be In Titlecase, Like This
 * Don't start a setence with an uncapitalized identifier.

original commit: 9e0fce224b9fb48e3b79e10863ca303c21c936c4
---
 collects/parser-tools/parser-tools.scrbl | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/collects/parser-tools/parser-tools.scrbl b/collects/parser-tools/parser-tools.scrbl
index 71ce3df..bdf7fff 100644
--- a/collects/parser-tools/parser-tools.scrbl
+++ b/collects/parser-tools/parser-tools.scrbl
@@ -486,7 +486,7 @@ the right choice when using @racket[lexer] in other situations.
 
 @; ----------------------------------------------------------------------
 
-@section{Parsers}
+@section{LALR(1) Parsers}
 
 @section-index["yacc"]
 
@@ -685,14 +685,13 @@ the right choice when using @racket[lexer] in other situations.
                                             
                                             
                                             
-@section{Ambiguous parsing}
+@section{Context-Free Parsers}
 
 @section-index["cfg-parser"]
 
-@defmodule[parser-tools/cfg-parser]
-
-@racketmodname[parser-tools/cfg-parser] provides another parser
-generator as an alternative to @racketmodname[parser-tools/yacc].
+@defmodule[parser-tools/cfg-parser]{The @racketmodname[parser-tools/cfg-parser]
+library provides a parser generator that is an alternative to that of 
+@racketmodname[parser-tools/yacc].}
 
 @defform/subs[#:literals (grammar tokens start end precs src-pos
                           suppress debug yacc-output prec)
@@ -706,10 +705,11 @@ generator as an alternative to @racketmodname[parser-tools/yacc].
                        (end token-id ...)
                        (@#,racketidfont{error} expr)
                        (src-pos)])]{
+
     Creates a parser similar to that of @racket[parser].  Unlike @racket[parser],
-    @racket[cfg-parser] can consume ambiguous grammars.
-    Its interface is a subset of @racketmodname[parser-tools/yacc].
-    The major differences in the interface are:
+    @racket[cfg-parser], can consume arbitrary and potentially ambiguous context-free
+    grammars. Its interface is a subset of @racketmodname[parser-tools/yacc], with
+    the following differences:
                                         
     @itemize[
 
@@ -718,12 +718,11 @@ generator as an alternative to @racketmodname[parser-tools/yacc].
       Unlike @racket[parser], @racket[cfg-parser] only allows for
       a single non-terminal-id.}
                        
-      @item{@racket[cfg-parser] does not support the @racket[precs], 
+      @item{The @racket[cfg-parser] form does not support the @racket[precs], 
              @racket[suppress], @racket[debug], or @racket[yacc-output]
              options of @racket[parser].}
    ]
-                                             }
-                                            
+}                                            
                                             
 @; ----------------------------------------------------------------------