scribble reader interface and doc adjustments

svn: r8257

original commit: 4c1856f189d8f829be11f4268864d75df146a558

collects/scribble/comment-reader.ss

@@ -1,20 +1,20 @@
 
-(module comment-reader mzscheme
+(module comment-reader scheme/base
-  (require (lib "kw.ss"))
 
-  (provide (rename *read read)
+  (provide (rename-out [*read read]
-           (rename *read-syntax read-syntax))
+                       [*read-syntax read-syntax])
+           make-comment-readtable)
 
-  (define/kw (*read #:optional [inp (current-input-port)])
+  (define (*read [inp (current-input-port)])
     (parameterize ([current-readtable (make-comment-readtable)])
       (read/recursive inp)))
 
-  (define/kw (*read-syntax #:optional src [port (current-input-port)])
+  (define (*read-syntax src [port (current-input-port)])
     (parameterize ([current-readtable (make-comment-readtable)])
       (read-syntax/recursive src port)))
 
-  (define (make-comment-readtable)
+  (define (make-comment-readtable #:readtable [rt (current-readtable)])
-    (make-readtable (current-readtable)
+    (make-readtable rt
                     #\; 'terminating-macro
                     (case-lambda 
                      [(char port)
@@ -22,7 +22,7 @@
                      [(char port src line col pos)
                       (let ([v (do-comment port (lambda () (read-syntax/recursive src port #\@)))])
                         (let-values ([(eline ecol epos) (port-next-location port)])
-                          (datum->syntax-object
+                          (datum->syntax
                            #f
                            v
                            (list src line col pos (and pos epos (- epos pos))))))])))

collects/scribblings/scribble/reader.scrbl

@@ -757,23 +757,35 @@ Useful for implementing languages that are textual by default (see
 @filepath{docreader.ss} for example).
 }
 
-@defform[(make-at-readtable [keyword-args ...])]{
+@defproc[(make-at-readtable [#:readtable readtable readtable? (current-readtable)]
+                            [#:command-char command-char character? #\@]
+                            [#:start-inside? start-inside? any/c #f]
+                            [#:datum-readtable datum-readtable 
+                                               (or/c readtable? boolean? 
+                                                     (readtable? . -> . readtable?)) 
+                                               #t]
+                            [#:syntax-post-processor syntax-post-proc (syntax? . -> . syntax?) values])
+          readtable?]{
+
 Constructs an @"@"-readtable.  The keyword arguments can customize the
-resulting reader in several ways.
+resulting reader in several ways:
 
 @itemize{
-@item{@scheme[#:readtable] --- a readtable to base the @"@"-readtable
+
-  on.  Defaults to the current readtable.}
+@item{@scheme[readtable] --- a readtable to base the @"@"-readtable
-@item{@scheme[#:command-char] --- the character used for @"@"-forms;
+  on.}
-  defaults to @scheme[#\@].}
+
-@item{@scheme[#:datum-readtable] --- determines the readtable used for
+@item{@scheme[command-char] --- the character used for @"@"-forms.}
-  reading the datum part.  The default (@scheme[#t]) is to use the
+
+@item{@scheme[datum-readtable] --- determines the readtable used for
+  reading the datum part.  A @scheme[#t] values uses the
   @"@"-readtable, otherwise it can be a readtable, or a
   readtable-to-readtable function that will construct one from the
   @"@"-readtable.  The idea is that you may want to have completely
   different uses for the datum part, for example, introducing a
   convenient @litchar["key=val"] syntax for attributes.}
-@item{@scheme[#:syntax-post-processor] --- function that is applied on
+
+@item{@scheme[syntax-post-proc] --- function that is applied on
   each resulting syntax value after it has been parsed (but before it
   is wrapped quoting punctuations).  You can use this to further
   control uses of @"@"-forms, for example, making the command be the
@@ -786,41 +798,18 @@ resulting reader in several ways.
         (syntax-case stx ()
           [(cmd rest ...) #'(list 'cmd rest ...)]
           [_else (error "@ forms must have a body")])))
-  ]
+  ]}
 
-  Beware that the syntax may contain placeholder values at this stage
+@item{@scheme[start-inside?] --- if true, creates a readtable for
-  (e.g: the command part), so you can `plant' your own form that will
+use starting in text mode, instead of S-expression mode.}
-  do some plain processing later.  For example, here's a setup that
-  uses a @schemeid[mk-] prefix for all command names:
 
-  @schemeblock[
-    (use-at-readtable
-      #:syntax-post-processor
-      (lambda (stx)
-        (syntax-case stx ()
-          [(cmd rest ...) #'(add-mk cmd rest ...)]
-          [_else (error "@ forms must have a body")])))
-    (define-syntax (add-mk stx)
-      (syntax-case stx ()
-        [(_ cmd rest ...)
-         (identifier? #'cmd)
-         (with-syntax ([mk-cmd (datum->syntax-object
-                                #'cmd
-                                (string->symbol
-                                 (format "mk-~a" (syntax-e #'cmd)))
-                                #'cmd)])
-           (syntax/loc stx (mk-cmd rest ...)))]))
-  ]
-}
-@item{@scheme[#:start-inside?] --- used internally by the above
-  @schemeid[-inside] variants.}
 }}
 
 @defproc[(use-at-readtable ...) void?]{
-Installs the Scribble readtable as the default.  Useful for REPL
+
-experimentation.  (Note: enables line and column tracking.)  The given
+Passes all arguments to @scheme[make-at-readtable], and installs the
-keyword arguments are used with `make-at-readtable'.
+resulting readtable using @scheme[current-readtable]. It also enables
-}
+line counting for the current input-port via @scheme[port-count-lines!].}
 
 @; *** End reader-import section ***
 ))])]