From bb0da648424b140231a4d72c95d1b9eba43ab135 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Fri, 15 Feb 2008 14:06:21 +0000
Subject: [PATCH] revise syntax scribblings

svn: r8671
---
 .../syntax/scribblings/module-helpers.scrbl   | 10 +++
 .../syntax/scribblings/module-reader.scrbl    | 64 +++++++++++++++++++
 .../syntax/scribblings/reader-helpers.scrbl   |  7 ++
 .../scribblings/syntax-object-helpers.scrbl   | 12 ++++
 collects/syntax/scribblings/syntax.scrbl      | 35 ++++------
 collects/syntax/scribblings/toplevel.scrbl    |  4 +-
 .../scribblings/transformer-helpers.scrbl     | 11 ++++
 7 files changed, 117 insertions(+), 26 deletions(-)
 create mode 100644 collects/syntax/scribblings/module-helpers.scrbl
 create mode 100644 collects/syntax/scribblings/module-reader.scrbl
 create mode 100644 collects/syntax/scribblings/reader-helpers.scrbl
 create mode 100644 collects/syntax/scribblings/syntax-object-helpers.scrbl
 create mode 100644 collects/syntax/scribblings/transformer-helpers.scrbl

diff --git a/collects/syntax/scribblings/module-helpers.scrbl b/collects/syntax/scribblings/module-helpers.scrbl
new file mode 100644
index 0000000000..fcdc392d5a
--- /dev/null
+++ b/collects/syntax/scribblings/module-helpers.scrbl
@@ -0,0 +1,10 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "module-helpers"]{Module-Processing Helpers}
+
+@include-section["modread.scrbl"]
+@include-section["modcode.scrbl"]
+@include-section["modresolve.scrbl"]
+@include-section["modcollapse.scrbl"]
+@include-section["moddep.scrbl"]
diff --git a/collects/syntax/scribblings/module-reader.scrbl b/collects/syntax/scribblings/module-reader.scrbl
new file mode 100644
index 0000000000..abc32d2f76
--- /dev/null
+++ b/collects/syntax/scribblings/module-reader.scrbl
@@ -0,0 +1,64 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@(define-syntax-rule (go)
+  (begin
+    (require (for-label syntax/module-reader))
+@begin{
+@title[#:tag "module-reader"]{Module Reader}
+
+@defmodule[syntax/module-reader]
+
+The @schememodname[syntax/module-reader] language provides support
+for defining @hash-lang[] readers.
+
+@defform[(#%module-begin module-path)]{
+
+Causes a module written in the @schememodname[syntax/module-reader]
+language to define and provide @schemeidfont{read} and
+@schemeidfont{read-syntax} functions, making the module an
+implementation of a reader. In particular, the exported reader
+functions read all S-expressions until an end-of-file, and it packages
+them into a new module in the @scheme[module-path] language.
+
+That is, a module @scheme[_something]@scheme[/lang/reader] implemented
+as
+
+@schemeblock[
+(module reader module-syntax/module-reader
+  module-path)
+]
+
+creates a reader that converts @scheme[#, @hash-lang[] _something]
+into
+
+@schemeblock[
+(module _name-id module-path
+  ....)
+]
+
+where @scheme[_name-id] is derived from the name of the port used by
+the reader.
+
+For example, @scheme[scheme/base/lang/reader] is implemented as
+
+@schemeblock[
+(module reader module-syntax/module-reader
+  scheme/base)
+]}
+
+@defproc[(wrap-read-all [mod-path module-path?]
+                        [in input-port?]
+                        [read (input-port . -> . any/c)])
+         any/c]{
+
+Repeatedly calls @scheme[read] on @scheme[in] until an end of file,
+collecting the results in order into @scheme[_lst], and derives a
+@scheme[_name-id] from @scheme[(object-name in)].  The result is
+
+@schemeblock[
+`(module ,_name-id ,mod-path ,@_lst)
+]}
+
+}))
+@(go)
diff --git a/collects/syntax/scribblings/reader-helpers.scrbl b/collects/syntax/scribblings/reader-helpers.scrbl
new file mode 100644
index 0000000000..87dc601b28
--- /dev/null
+++ b/collects/syntax/scribblings/reader-helpers.scrbl
@@ -0,0 +1,7 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "reader-helpers"]{Reader Helpers}
+
+@include-section["readerr.scrbl"]
+@include-section["module-reader.scrbl"]
diff --git a/collects/syntax/scribblings/syntax-object-helpers.scrbl b/collects/syntax/scribblings/syntax-object-helpers.scrbl
new file mode 100644
index 0000000000..ea9c505da2
--- /dev/null
+++ b/collects/syntax/scribblings/syntax-object-helpers.scrbl
@@ -0,0 +1,12 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "syntax-helpers"]{Syntax Object Helpers}
+
+@include-section["stx.scrbl"]
+@include-section["kerncase.scrbl"]
+@include-section["boundmap.scrbl"]
+@include-section["to-string.scrbl"]
+@include-section["free-vars.scrbl"]
+@include-section["zodiac.scrbl"]
+
diff --git a/collects/syntax/scribblings/syntax.scrbl b/collects/syntax/scribblings/syntax.scrbl
index f6631512f5..f5387c2f67 100644
--- a/collects/syntax/scribblings/syntax.scrbl
+++ b/collects/syntax/scribblings/syntax.scrbl
@@ -5,33 +5,20 @@
 
 @table-of-contents[]
 
-@include-section["stx.scrbl"]
-@include-section["kerncase.scrbl"]
+@include-section["syntax-object-helpers.scrbl"]
+
+@include-section["module-helpers.scrbl"]
+
+@include-section["transformer-helpers.scrbl"]
+
+@include-section["reader-helpers.scrbl"]
+
+
 @include-section["toplevel.scrbl"]
-@include-section["define.scrbl"]
-@include-section["struct.scrbl"]
-@include-section["name.scrbl"]
-@include-section["docprovide.scrbl"]
-
-@include-section["moddep.scrbl"]
-@include-section["modread.scrbl"]
-@include-section["modcode.scrbl"]
-@include-section["modresolve.scrbl"]
-@include-section["modcollapse.scrbl"]
-
-@include-section["readerr.scrbl"]
-
-@include-section["boundmap.scrbl"]
-
-@include-section["path-spec.scrbl"]
-
-@include-section["zodiac.scrbl"]
-
-@include-section["context.scrbl"]
 
 @include-section["trusted-xforms.scrbl"]
 
-@include-section["to-string.scrbl"]
-@include-section["free-vars.scrbl"]
+@include-section["docprovide.scrbl"]
+
 
 @index-section[]
diff --git a/collects/syntax/scribblings/toplevel.scrbl b/collects/syntax/scribblings/toplevel.scrbl
index c9a17e3b8c..7f7aac91af 100644
--- a/collects/syntax/scribblings/toplevel.scrbl
+++ b/collects/syntax/scribblings/toplevel.scrbl
@@ -2,7 +2,7 @@
 @(require "common.ss"
           (for-label syntax/toplevel))
 
-@title[#:tag "toplevel"]{Helper for Non-Module Compilation And Expansion}
+@title[#:tag "toplevel"]{Non-Module Compilation And Expansion}
 
 @defmodule[syntax/toplevel]
 
@@ -22,7 +22,7 @@ top-level expressions.)
 The @scheme[stx] should have a context already, possibly introduced with
 @scheme[namespace-syntax-introduce].}
 
-@defproc[(expand-top-level-with-compile-time-evals [stx syntax]) 
+@defproc[(expand-top-level-with-compile-time-evals [stx syntax?]) 
          syntax?]{
 
 Like @scheme[expand-syntax-top-level-with-compile-time-evals], but
diff --git a/collects/syntax/scribblings/transformer-helpers.scrbl b/collects/syntax/scribblings/transformer-helpers.scrbl
new file mode 100644
index 0000000000..6f8aa521cb
--- /dev/null
+++ b/collects/syntax/scribblings/transformer-helpers.scrbl
@@ -0,0 +1,11 @@
+#lang scribble/doc
+@(require "common.ss")
+
+@title[#:tag "transformer-helpers"]{Macro Transformer Helpers}
+
+@include-section["name.scrbl"]
+@include-section["context.scrbl"]
+@include-section["define.scrbl"]
+@include-section["struct.scrbl"]
+@include-section["path-spec.scrbl"]
+