commit 2d2c2d17bfcfd3672df01308f9d80a9e3f3d74b8
parent 919845d306b1b59b7e2f30fcd565bec43970ac37
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Sat, 14 Feb 2009 13:34:58 +0000
doc scribble/comment-reader
svn: r13575
original commit: 8cf310d8fc82fcfda45fc9d879a746b458620afb
Diffstat:
3 files changed, 80 insertions(+), 23 deletions(-)
diff --git a/collects/scribble/private/manual-mod.ss b/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))))
diff --git a/collects/scribblings/scribble/manual.scrbl b/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
@@ -202,6 +203,47 @@ procedure, but use @scheme[var] if that cannot work for some reason.}
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}
@defform/subs[(defmodule id maybe-sources pre-flow ...)
@@ -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 ...)]{
-
-Like @scheme[defmodule], but introduces multiple module paths instead
-of just one.}
+@defform[(defmodulereader id maybe-sources pre-flow ...)]{
+Like @scheme[defmodule], but documents @scheme[id] as a module path
+suitable for use with @schememetafont{#reader}.}
-@defform[(defmodulelang* (id ...+) maybe-sources pre-flow ...)]{
-Like @scheme[defmodulelang], but introduces multiple module paths
-instead of just one.}
+@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.}
-@defform[(defmodule*/no-declare (id ...) pre-flow ...)]{
+@deftogether[(
+@defform[(defmodule*/no-declare (id ...) pre-flow ...)]
+@defform[(defmodulelang*/no-declare (id ...) pre-flow ...)]
+@defform[(defmodulereader*/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 ...))])]{
diff --git a/collects/scribblings/scribble/scheme.scrbl b/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!
-
