doc scribble/comment-reader

svn: r13575

original commit: 8cf310d8fc82fcfda45fc9d879a746b458620afb

collects/scribble/private/manual-mod.ss

@@ -11,8 +11,8 @@
          (for-syntax scheme/base)
          (for-label scheme/base))
 
-(provide defmodule defmodule* defmodulelang defmodulelang*
-         defmodule*/no-declare defmodulelang*/no-declare
+(provide defmodule defmodule* defmodulelang defmodulelang* defmodulereader defmodulereader*
+         defmodule*/no-declare defmodulelang*/no-declare defmodulereader*/no-declare
          declare-exporting)
 
 (define spacer (hspace 1))
@@ -47,7 +47,21 @@
 (define-syntax-rule (defmodulelang lang . content)
   (defmodulelang* (lang) . content))
 
-(define (*defmodule names lang? content)
+(define-syntax-rule (defmodulereader*/no-declare (lang ...) . content)
+  (*defmodule (list (schememodname lang) ...) 'reader (list . content)))
+
+(define-syntax defmodulereader*
+  (syntax-rules ()
+    [(_ (name ...) #:use-sources (pname ...) . content)
+     (begin (declare-exporting name ... #:use-sources (pname ...))
+            (defmodulereader*/no-declare (name ...) . content))]
+    [(_ (name ...) . content)
+     (defmodulereader* (name ...) #:use-sources () . content)]))
+
+(define-syntax-rule (defmodulereader lang . content)
+  (defmodulereader* (lang) . content))
+
+(define (*defmodule names lang content)
   (make-splice
    (cons
     (make-table
@@ -60,9 +74,11 @@
            (make-omitable-paragraph
             (cons
              spacer
-             (if lang?
-               (list (hash-lang) spacer (make-defschememodname name))
-               (list (scheme (require #,(make-defschememodname name)))))))))))
+             (if lang
+                 (if (eq? lang 'reader)
+                     (list (schememetafont "#reader") spacer (make-defschememodname name))
+                     (list (hash-lang) spacer (make-defschememodname name)))
+                 (list (scheme (require #,(make-defschememodname name)))))))))))
       names))
     (append (map (lambda (name)
                    (make-part-tag-decl `(mod-path ,(element->string name))))

collects/scribblings/scribble/manual.scrbl

@@ -106,6 +106,7 @@ A few other escapes are recognized symbolically:
 
 }
 
+See also @schememodname[scribble/comment-reader].
 }
 
 @defform[(SCHEMEBLOCK datum ...)]{Like @scheme[schemeblock], but with
@@ -201,6 +202,47 @@ procedure, but use @scheme[var] if that cannot work for some reason.}
 @defform[(svar datum)]{Like @scheme[var], but for subform non-terminals
 in a form definition.}
 
+@; ------------------------------------------------------------------------
+
+@subsection{Typesetting Comments}
+
+@defmodulereader[scribble/comment-reader]
+
+As a reader module, @schememodname[scribble/comment-reader] reads a
+single S-expression that contains @litchar{;}-based comment lines, and
+it wraps the comments with @scheme[code:comment] for use with forms
+like @scheme[schemeblock]. More precisely,
+@schememodname[scribble/comment-reader] extends the current reader to
+adjust the parsing of @litchar{;}.
+
+For example, within a Scribble document that imports
+@schememodname[scribble/manual],
+
+@verbatim[#:indent 2]|{
+  @#reader scribble/comment-reader
+   (schemeblock
+    ;; This is not a pipe
+    (make-pipe)
+   )
+}|
+
+generates
+
+@#reader scribble/comment-reader
+ (schemeblock
+  ;; This is not a pipe
+  (make-pipe)
+ )
+
+The initial @litchar["@"] is needed above to shift into S-expression
+mode, so that @schememetafont{#reader} is recognized as a reader
+declaration instead of literal text. Also, the example uses
+@scheme[(schemeblock ....)]  instead of
+@schememetafont["@"]@scheme[schemeblock]@schememetafont["["]@scheme[....]@schememetafont["]"]
+because the @"@"-reader would drop comments within the
+@scheme[schemeblock] before giving
+@schememodname[scribble/comment-reader] a chance to convert them.
+
 @; ------------------------------------------------------------------------
 @section[#:tag "doc-modules"]{Documenting Modules}
 
@@ -230,33 +272,33 @@ Like @scheme[defmodule], but documents @scheme[id] as a module path
 suitable for use by either @scheme[require] or @schememodfont{#lang}.}
 
 
-@defform[(defmodule* (id ...+) maybe-sources pre-flow ...)]{
+@defform[(defmodulereader id maybe-sources pre-flow ...)]{
 
-Like @scheme[defmodule], but introduces multiple module paths instead
+Like @scheme[defmodule], but documents @scheme[id] as a module path
+suitable for use with @schememetafont{#reader}.}
+
+
+@deftogether[(
+@defform[(defmodule* (id ...+) maybe-sources pre-flow ...)]
+@defform[(defmodulelang* (id ...+) maybe-sources pre-flow ...)]
+@defform[(defmodulereader* (id ...+) maybe-sources pre-flow ...)]
+)]{
+
+Like @scheme[defmodule], etc., but introduces multiple module paths instead
 of just one.}
 
+@deftogether[(
+@defform[(defmodule*/no-declare (id ...) pre-flow ...)]
+@defform[(defmodulelang*/no-declare (id ...) pre-flow ...)]
+@defform[(defmodulereader*/no-declare (id ...) pre-flow ...)]
+)]{
 
-@defform[(defmodulelang* (id ...+) maybe-sources pre-flow ...)]{
-
-Like @scheme[defmodulelang], but introduces multiple module paths
-instead of just one.}
-
-
-@defform[(defmodule*/no-declare (id ...) pre-flow ...)]{
-
-Like @scheme[defmodule*], but without expanding to
+Like @scheme[defmodule*], etc., but without expanding to
 @scheme[declare-exporting]. Use this form when you want to provide a
 more specific list of modules (e.g., to name both a specific module
 and one that combines several modules) via your own
 @scheme[declare-exporting] declaration.}
 
-
-@defform[(defmodulelang*/no-declare (id ...) pre-flow ...)]{
-
-Like @scheme[defmodulelang*], but without expanding to
-@scheme[declare-exporting].}
-
-
 @defform/subs[(declare-exporting mod-path ... maybe-sources)
               ([maybe-sources code:blank
                               (code:line #:use-sources (mod-path ...))])]{

collects/scribblings/scribble/scheme.scrbl

@@ -9,4 +9,3 @@ provides utilities for typesetting Scheme code. The
 @scheme[scribble/manual] forms provide a higher-level interface.}
 
 @italic{To do:} document this library!
-