revise syntax scribblings

svn: r8671

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"]

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)

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"]

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"]
+

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[]

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

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"]
+