From 2d2c2d17bfcfd3672df01308f9d80a9e3f3d74b8 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 14 Feb 2009 13:34:58 +0000 Subject: [PATCH] doc scribble/comment-reader svn: r13575 original commit: 8cf310d8fc82fcfda45fc9d879a746b458620afb --- collects/scribble/private/manual-mod.ss | 28 ++++++-- collects/scribblings/scribble/manual.scrbl | 78 +++++++++++++++++----- collects/scribblings/scribble/scheme.scrbl | 1 - 3 files changed, 82 insertions(+), 25 deletions(-) diff --git a/collects/scribble/private/manual-mod.ss b/collects/scribble/private/manual-mod.ss index 7376eb3c..e7ec1b79 100644 --- 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 index 5c111a9b..deffd221 100644 --- 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 @@ -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 ...))])]{ diff --git a/collects/scribblings/scribble/scheme.scrbl b/collects/scribblings/scribble/scheme.scrbl index 364cefc7..df959841 100644 --- 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! -