suzanne.soy/scribble-enhanced
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Scribble improvements: defmodule & co.

Browse Source 
svn: r7902

original commit: cd7157641cc8a1dd6266c926675e5909daeb643f
This commit is contained in:
Matthew Flatt 2007-12-05 21:41:07 +00:00
parent 40e6579fea
commit 0aa14ae363
21 changed files with 439 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
collects/scribble/decode.ss
View File

@ -26,7 +26,8 @@
[splice ([run list?])]
[part-index-decl ([plain-seq (listof string?)]
[entry-seq list?])]
[part-collect-decl ([element element?])])
[part-collect-decl ([element element?])]
[part-tag-decl ([tag tag?])])
(define (decode-string s)
(let loop ([l '((#rx"---" mdash)
@ -173,6 +174,8 @@
(loop (cdr l) next? (cons (car l) keys) colls accum title tag-prefix tags style)]
[(part-collect-decl? (car l))
(loop (cdr l) next? keys (cons (part-collect-decl-element (car l)) colls) accum title tag-prefix tags style)]
[(part-tag-decl? (car l))
(loop (cdr l) next? keys colls accum title tag-prefix (cons (part-tag-decl-tag (car l)) tags) style)]
[(and (pair? (cdr l))
(splice? (cadr l)))
(loop (cons (car l) (append (splice-run (cadr l)) (cddr l))) next? keys colls accum title tag-prefix tags style)]

2
collects/scribble/doc/lang/reader.ss
View File

@ -1,4 +1,4 @@
(module reader mzscheme
(require (prefix doc: (lib "docreader.ss" "scribble")))
(require (prefix doc: (lib "reader.ss" "scribble" "doc")))
(provide (rename doc:read read)
(rename doc:read-syntax read-syntax)))

6
collects/scribble/doc/main.ss Normal file
View File

@ -0,0 +1,6 @@
(module main scheme/base
(define-syntax-rule (out)
(begin (require scribble/doclang)
(provide (all-from-out scribble/doclang))))
(out))

4
collects/scribble/docreader.ss → collects/scribble/doc/reader.ss
View File

@ -1,6 +1,6 @@
(module docreader scheme/base
(require (prefix-in scribble: "reader.ss"))
(module reader scheme/base
(require (prefix-in scribble: "../reader.ss"))
(provide (rename-out [*read read])
(rename-out [*read-syntax read-syntax]))

1
collects/scribble/latex-render.ss
View File

@ -50,6 +50,7 @@
(define-color "schemesymbol" "IdentifierColor")
(define-color "schemevalue" "ValueColor")
(define-color "schemevaluelink" "blue")
(define-color "schememodlink" "blue")
(define-color "schemeresult" "ResultColor")
(define-color "schemestdout" "OutputColor")
(define-color "schememeta" "IdentifierColor")

1
collects/scribble/manual-struct.ss
View File

@ -4,6 +4,7 @@
scheme/contract)
(provide-structs
[module-path-index-desc ()]
[exported-index-desc ([name symbol?]
[from-libs (listof module-path?)])]
[(method-index-desc exported-index-desc) ([method-name symbol?]

87
collects/scribble/manual.ss
View File

@ -47,8 +47,11 @@
#'here
`(unsyntax (make-element
#f
(list (schemefont ,(format "#lang "))
(schemeidfont ,(format "~s" (syntax-e #'lang))))))
(list hash-lang
(hspace 1)
(as-modname-link
',#'lang
(to-element ',#'lang)))))
#'lang)])
#'(schemeblock modtag rest ...))]))
@ -83,7 +86,76 @@
(define-code scheme to-element unsyntax keep-s-expr add-sq-prop)
(define-code schemeresult to-element/result unsyntax keep-s-expr add-sq-prop)
(define-code schemeid to-element/id unsyntax keep-s-expr add-sq-prop)
(define-code schememodname to-element unsyntax keep-s-expr add-sq-prop)
(define-code *schememodname to-element unsyntax keep-s-expr add-sq-prop)
(define-syntax-rule (schememodname n)
(as-modname-link 'n (*schememodname n)))
(define (as-modname-link s e)
(if (symbol? s)
(make-link-element "schememodlink"
(list e)
`(mod-path ,(symbol->string s)))
e))
(define-syntax-rule (defmodule*/no-declare (name ...) . content)
(*defmodule (list (schememodname name) ...)
#f
(list . content)))
(define-syntax-rule (defmodule* (name ...) . content)
(begin
(declare-exporting name ...)
(defmodule*/no-declare (name ...) . content)))
(define-syntax-rule (defmodule name . content)
(defmodule* (name) . content))
(define-syntax-rule (defmodulelang*/no-declare (lang ...) . content)
(*defmodule (list (schememodname lang) ...)
#t
(list . content)))
(define-syntax-rule (defmodulelang* (name ...) . content)
(begin
(declare-exporting name ...)
(defmodulelang*/no-declare (name ...) . content)))
(define-syntax-rule (defmodulelang lang . content)
(defmodulelang* (lang) . content))
(define (*defmodule names lang? content)
(make-splice
(cons
(make-table
"defmodule"
(map (lambda (name)
(list
(make-flow
(list (make-paragraph
(if lang?
(list (hspace 1)
hash-lang
(hspace 1)
(make-defschememodname name))
(list
(hspace 1)
(scheme (require #,(make-defschememodname name))))))))))
names))
(append
(map (lambda (name)
(make-part-tag-decl `(mod-path ,(element->string name))))
names)
(flow-paragraphs (decode-flow content))))))
(define (make-defschememodname mn)
(let ([name-str (element->string mn)])
(make-index-element #f
(list mn)
`(mod-path ,name-str)
(list name-str)
(list mn)
(make-module-path-index-desc))))
(define (litchar . strs)
(unless (andmap string? strs)
@ -148,6 +220,8 @@
schemeinput
schememod
scheme scheme/form schemeresult schemeid schememodname
defmodule defmodule* defmodulelang defmodulelang*
defmodule*/no-declare defmodulelang*/no-declare
indexed-scheme
litchar
verbatim)
@ -1375,6 +1449,13 @@
c)))
(provide pidefterm)
(define hash-lang (make-link-element
"schememodlink"
(list (schememodfont "#lang"))
`(part ,(doc-prefix '(lib "scribblings/guide/guide.scrbl")
"hash-lang"))))
;; ----------------------------------------
(provide math)

10
collects/scribble/scribble.css
View File

@ -289,6 +289,11 @@
background-color: #ddddff;
}
.defmodule {
width: 100%;
background-color: #F5F5DC;
}
.specgrammar {
float: right;
}
@ -369,6 +374,11 @@
color: blue;
}
.schememodlink {
text-decoration: none;
color: blue;
}
.schemesyntaxlink {
text-decoration: none;
color: black;

12
collects/scribblings/scribble/basic.scrbl
View File

@ -21,12 +21,12 @@
@title[#:tag "basic"]{Basic Document Forms}
@declare-exporting[scribble/basic]
@defmodule[scribble/basic]{The @schememodname[scribble/basic] libraryp
rovides functions and forms that can be used from code written either
in Scheme or with @elem["@"] expressions.}
The @filepath{basic.ss} libraryprovides functions and forms that can be
used from code written either in Scheme or with @elem["@"]
expressions. For example, the @scheme[title] and @scheme[italic]
functions might be called from Scheme as
For example, the @scheme[title] and @scheme[italic] functions might be
called from Scheme as
@schemeblock[
(title #:tag "how-to" "How to Design " (italic "Great") " Programs")
@ -42,7 +42,7 @@ EOS
Although the procedures are mostly design to be used from @elem["@"]
mode, they are easier to document in Scheme mode (partly because we
have Scribble's @filepath{scheme.ss} and @filepath{manual.ss}).
have @schememodname[scribble/manual]).
@; ------------------------------------------------------------------------

59
collects/scribblings/scribble/bnf.scrbl Normal file
View File

@ -0,0 +1,59 @@
#lang scribble/doc
@(require scribble/manual
"utils.ss"
(for-label scribble/bnf))
@title[#:tag "bnf"]{Typesetting Grammars}
@defmodule[scribble/bnf]{The @scheme[scribble/bnf] library
provides utilities for typesetting grammars.}
See also @scheme[schemegrammar].
@defproc[(BNF [prod (cons element? (listof element?))] ...) table?]{
Typesets a grammar table. Each production starts with an element
(typically constructed with @scheme[nonterm]) for the non-terminal
being defined, and then a list of possibilities (typically constructed
with @scheme[BNF-seq], etc.) to show on separate lines.}
@defproc[(nonterm (pre-content any/c) ...) element?]{
Typesets a non-terminal: italic in angle brackets.}
@defproc[(BNF-seq [elem element?] ...) element?]{
Typesets a sequence.}
@defproc[(BNF-group [pre-content any/c] ...) element?]{
Typesets a group surrounded by curly braces (so the entire group can
be repeated, for example).}
@defproc[(optional [pre-content any/c] ...) element?]{
Typesets an optional element: in square brackets.}
@defproc[(kleenestar [pre-content any/c] ...) element?]{
Typesets a 0-or-more repetition.}
@defproc[(kleeneplus [pre-content any/c] ...) element?]{
Typesets a 1-or-more repetition.}
@defproc[(kleenerange [n any/c] [m any/c] [pre-content any/c] ...) element?]{
Typesets a @scheme[n]-to-@scheme[m] repetition. The @scheme[n] and
@scheme[m] arguments are converted to a string using @scheme[(format
"~a" n)] and @scheme[(format "~a" m)].}
@defproc[(BNF-alt [elem element?] ...) element?]{
Typesets alternatives for a production's right-hand side to appear on
a single line. The result is normally used as a single possibility in
a production list for @scheme[BNF].}
@defthing[BNF-etc string?]{
A string to use for omitted productions or content.}

24
collects/scribblings/scribble/decode.scrbl
View File

@ -4,12 +4,11 @@
@title[#:tag "decode"]{Text Decoder}
@declare-exporting[scribble/decode]
The @filepath{decode.ss} library helps you write document content in a
natural way---more like plain text, except for @litchar["@"] escapes.
Roughly, it processes a stream of strings to produces instances of the
@filepath{struct.ss} datatypes (see @secref["struct"]).
@defmodule[scribble/decode]{The @schememodname[scribble/decode]
library helps you write document content in a natural way---more like
plain text, except for @litchar["@"] escapes. Roughly, it processes a
stream of strings to produces instances of the
@schememodname[scribble/struct] datatypes (see @secref["struct"]).}
At the flow level, decoding recognizes a blank line as a paragraph
separator. At the paragraph-content level, decoding makes just a few
@ -39,9 +38,10 @@ Decodes a document, producing a part. In @scheme[lst], instances of
@scheme[part-index-decl] (that precede any sub-part) add index entries
that point to the section. Instances of @scheme[part-collect-decl] add
elements to the part that are used only during the @techlink{collect
pass}. Instances of @scheme[part-start] at level 0 trigger sub-part
parsing. Instances of @scheme[section] trigger are used as-is as
subsections, and instances of @scheme[paragraph] and other
pass}. Instances of @scheme[part-tag-decl] add hyperlink tags to the
section title. Instances of @scheme[part-start] at level 0 trigger
sub-part parsing. Instances of @scheme[section] trigger are used as-is
as subsections, and instances of @scheme[paragraph] and other
flow-element datatypes are used as-is in the enclosing flow.
}
@ -129,6 +129,12 @@ See @scheme[decode].
}
@defstruct[part-tag-decl ([tag tag?])]{
See @scheme[decode].
}
@defstruct[splice ([run list?])]{
See @scheme[decode], @scheme[decode-part], and @scheme[decode-flow].

13
collects/scribblings/scribble/doclang.scrbl
View File

@ -4,13 +4,14 @@
@title[#:tag "doclang"]{Document Module Language}
The @filepath{doclang.ss} module is suitable for use as a module
language. It provides everything from @scheme[mzscheme], except that
it replaces the @scheme[#%module-begin] form.
@defmodule[scribble/doclang]{The @schememodname[scribble/doclang]
language provides everything from @scheme[scheme/base], except that it
replaces the @scheme[#%module-begin] form.}
The @filepath{doclang.ss} @scheme[#%module-begin] essentially packages the
body of the module into a call to @scheme[decode], binds the result to
@scheme[doc], and exports @scheme[doc].
The @schememodname[scribble/doclang] @scheme[#%module-begin]
essentially packages the body of the module into a call to
@scheme[decode], binds the result to @scheme[doc], and exports
@scheme[doc].
Any module-level form other than an expression (e.g., a
@scheme[require] or @scheme[define]) is remains at the top level, and

11
collects/scribblings/scribble/docreader.scrbl
View File

@ -5,9 +5,8 @@
@title[#:tag "docreader"]{Document Reader}
The @filepath{docreader.ss} module is suitable for use with
@schemefont{#reader} at the beginning of a file. It reads the entire
file with @scheme[read-inside-syntax] from Scribble's
@filepath{reader.ss}, and then wraps the result with @scheme[(module #,
@nonterm{name} (lib "doclang.ss" "scribble") ...)], where
@nonterm{name} is derived from the enclosing file's name.
@defmodule[scribble/doc]{The @schememodname[scribble/doc] language is
the same as @schememodname[scribble/doclang], except that
@scheme[read-inside-syntax] is used to read the body of the module. In
other words, the module body starts in Scribble ``text'' mode instead
of S-expression mode.}

9
collects/scribblings/scribble/eval.scrbl
View File

@ -4,11 +4,10 @@
@title[#:tag "eval"]{Evaluation and Examples}
@declare-exporting[scribble/eval]
The @filepath{eval.ss} library provides utilities for evaluating code at
document-build time and incorporating the results in the document,
especially to show example uses of defined procedures and syntax.
@defmodule[scribble/eval]{The @scheme[scribble/eval] library provides
utilities for evaluating code at document-build time and incorporating
the results in the document, especially to show example uses of
defined procedures and syntax.}
@defform[(interaction datum ...)]{Like @scheme[schemeinput], except
that the result for each input @scheme[datum] is shown on the next

145
collects/scribblings/scribble/how-to.scrbl
View File

@ -19,7 +19,7 @@ To document a collection or @|PLaneT| package:
@item{Start @filepath{manual.scrbl} like this:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual)]
@(require scribble/manual)
@title{My Library}
@ -52,8 +52,14 @@ EOS
collection name to limit the build process to the collection.}
@item{The generated documentation is
@filepath{compiled/doc/manual/index.html} within the collection or
@|PLaneT| package directory.}
@filepath{compiled/doc/manual/index.html} within the
collection or @|PLaneT| package directory.
If you want the output to be relative to the PLT Scheme
documentation directory (which is recommend only for those who
produce the ``official'' PLT Scheme distribution), add the
@scheme['main-doc] option to the @scheme[scribblings]
definition in @filepath{info.ss}.}
}
@ -88,13 +94,20 @@ A @nonterm{cmd} or @nonterm{datum} is a Scheme datum, while a
The expansion of a @litchar["@"] form into Scheme code is
@schemeblock[
@nonterm{cmd}
]
if neither @litchar["["] @litchar["]"] nor @litchar["{"] @litchar["}"]
are used, otherwise
@schemeblock[
(#, @nonterm{cmd} #, @kleenestar{@nonterm{datum}} #, @kleenestar{@nonterm{parsed-body}})
]
where @kleenestar{@nonterm{parsed-body}} is the parse result of the
@nonterm{text-body}. It often turns out to be a sequence of Scheme
strings.
@nonterm{text-body}. The @kleenestar{@nonterm{parsed-body}} part often
turns out to be a sequence of Scheme strings.
In practice, the @nonterm{cmd} is normally a Scheme identifier that is
bound to a procedure or syntactic form. If the procedure or form
@ -136,18 +149,20 @@ information on the decoding process.
@; ----------------------------------------
@section[#:tag "scheme-hyperlinks"]{Scheme Typesetting and Hyperlinks}
With the document source in @secref["getting-started"], the Scheme
expression @scheme[(#,(schemeidfont "list") 'testing 1 2 3)] is
typeset properly, but the @schemeidfont{list} identifier is not
hyperlinked to the usual definition. To cause @schemeidfont{list} to
be hyperlinked, add the following to the @tt["@begin"] body:
In the document source at the start of this chapter
(@secref["getting-started"]), the Scheme expression
@scheme[(#,(schemeidfont "list") 'testing 1 2 3)] is typeset properly,
but the @schemeidfont{list} identifier is not hyperlinked to the usual
definition. To cause @schemeidfont{list} to be hyperlinked, extend the
@scheme[require] form like this:
@schemeblock[
(require (for-label (lib "scheme")))
(require scribble/manual
(for-label #,(schememodname scheme)))
]
This @scheme[require] with @scheme[for-label] declaration introduces a
document-time binding for each export of the @scheme[(lib "scheme")]
document-time binding for each export of the @schememodname[scheme]
module. When the document is built, the @scheme[scheme] form detects
the binding for @scheme[list], and so it generates a reference to the
specification of @scheme[list]. The setup process detects the
@ -162,8 +177,8 @@ binding is documented elsewhere:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual
(for-label (lib "scheme")))]
@(require scribble/manual
(for-label scheme))
@title{My Library}
@ -178,8 +193,8 @@ and it preserves the expression's formatting from the document source.
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual
(for-label (lib "scheme"))]
@(require scribble/manual
(for-label scheme))
@title{My Library}
@ -209,8 +224,8 @@ The following example illustrates section hyperlinks:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual
(for-label (lib "scheme")))]
@(require scribble/manual
(for-label scheme))
@title{My Library}
@ -231,9 +246,9 @@ The following example illustrates section hyperlinks:
EOS
]
Since the page is so short, it the hyperlinks are more effective if
you change the @filepath{info.ss} file to add the @scheme['multi-file]
flag:
Since the page is so short, it the hyperlinks in the above example are
more effective if you change the @filepath{info.ss} file to add the
@scheme['multi-file] flag:
@schemeblock[
(define scribblings '(("manual.scrbl" (multi-page))))
@ -249,10 +264,10 @@ manual:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual
(for-label (lib "scheme")))
(define ref-src
'(lib "scribblings/reference/reference.scrbl"))]
@(require scribble/manual
(for-label scheme))
@(define ref-src
'(lib "scribblings/reference/reference.scrbl"))]
@title{My Library}
@ -261,9 +276,9 @@ EOS
]
As mentioned in @secref{scheme-hyperlinks}, however, cross-document
references based on @scheme[require-for-label] and @scheme[scheme] are
usually better than to cross-document references using
@scheme[secref].
references based on @scheme[(require (for-label ....))] and
@scheme[scheme] are usually better than to cross-document references
using @scheme[secref].
@; ----------------------------------------
@section{Defining Scheme Bindings}
@ -275,16 +290,16 @@ and they declare hyperlink targets for @scheme[scheme]-based
hyperlinks.
To document a @scheme[my-helper] procedure that is exported by
@filepath{helper.ss} in the collection that contains @filepath{manual.scrbl},
first use @scheme[require-for-label] to import the binding information
of @filepath{helper.ss}. Then use @scheme[defproc] to document the
procedure:
@filepath{helper.ss} in the collection that contains
@filepath{manual.scrbl}, first use @scheme[(require (for-label ....))]
to import the binding information of @filepath{helper.ss}. Then use
@scheme[defproc] to document the procedure:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual
(for-label (lib "scheme")
"helper.ss"))]
@(require scribble/manual
(for-label scheme
"helper.ss"))
@title{My Library}
@ -305,6 +320,30 @@ of the result must be given; in this case, @scheme[my-helper]
guarantees a result that is a list where none of the elements are
@scheme['cow].
Finally, the documentation should declare the module that is being
defined. Use @scheme[defmodule] to declare the module name before any
other definitions.
@verbatim[#<<EOS
#lang scribble/doc
@(require scribble/manual
(for-label scheme
"helper.ss"))
@title{My Library}
@defmodule[my-lib/helper]{The @schememodname[my-lib/helper]
module---now with extra cows!}
@defproc[(my-helper [lst list?])
(listof
(not/c (one-of/c 'cow)))]{
Replaces each @scheme['cow] in @scheme[lst] with
@scheme['aardvark].}
EOS
]
Some things to notice in this example and the documentation that it
generates:
@ -324,9 +363,12 @@ generates:
it's used in the scope of a procedure with argument
@scheme[_lst].}
@item{If you hover the mouse pointer over @scheme[my-helper], a popup
reports that it is provided from @schemeidfont{my-lib/helper}.}
@item{If you use @scheme[my-helper] in any documentation now, as long
as that documentation source also has a
@scheme[require-for-label] of @filepath{my-helper.ss}, then the
as that documentation source also has a @scheme[(require
(for-label ....))] of @filepath{my-helper.ss}, then the
reference is hyperlinked to the definition above.}
}
@ -350,14 +392,17 @@ via @scheme[require-for-label] and @scheme[require]:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual
scribble/eval ; <--- added
"helper.ss" ; <--- added
(for-label (lib "scheme")
"helper.ss"))]
@(require scribble/manual
scribble/eval ; <--- added
"helper.ss" ; <--- added
(for-label scheme
"helper.ss"))]
@title{My Library}
@defmodule[my-lib/helper]{The @schememodname[my-lib/helper]
module---now with extra cows!}
@defproc[(my-helper [lst list?])
(listof (not/c (one-of/c 'cow)))]{
@ -384,10 +429,13 @@ In @filepath{manual.scrbl}:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual)]
@(require scribble/manual)
@title{My Library}
@defmodule[my-lib/helper]{The @schememodname[my-lib/helper]
module---now with extra cows!}
@include-section["cows.scrbl"]
@include-section["aardvarks.scrbl"]
EOS
@ -397,7 +445,7 @@ In @filepath{cows.scrbl}:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual)]
@(require scribble/manual)
@title{Cows}
@ -409,9 +457,9 @@ In @filepath{aardvarks.scrbl}:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual
(for-label (lib "scheme")
"helper.ss"))]
@(require scribble/manual
(for-label scheme
"helper.ss"))
@title{Aardvarks}
@ -423,7 +471,6 @@ In @filepath{aardvarks.scrbl}:
EOS
]
@;----------------------------------------
@section{Multi-Page Sections}
@ -441,7 +488,7 @@ Revising @filepath{cows.scrbl} from the previous section:
@verbatim[#<<EOS
#lang scribble/doc
@begin[(require scribble/manual)]
@(require scribble/manual)
@title[#:style '(toc)]{Cows}

80
collects/scribblings/scribble/manual.scrbl
View File

@ -5,10 +5,10 @@
@title[#:tag "manual"]{PLT Manual Forms}
@declare-exporting[scribble/manual]
The @filepath{manual.ss} module provides all of @filepath{basic.ss}, and
more...
@defmodule[scribble/manual]{The @schememodname[scribble/manual]
provides all of @schememodname[scribble/basic], plus additional
functions that are relatively specific to writing PLT Scheme
documentation.}
@; ------------------------------------------------------------------------
@section[#:tag "scribble:manual:code"]{Typesetting Code}
@ -102,7 +102,7 @@ without insetting the code.}
@scheme[datum] are typeset after a prompt representing a REPL.}
@defform[(schememod lang datum ...)]{Like @scheme[schemeblock], but
the @scheme[datum] are typeset inside a @schemefont{#module}-form
the @scheme[datum] are typeset inside a @schememodfont{#lang}-form
module whose language is @scheme[lang].}
@defform[(scheme datum ...)]{Like @scheme[schemeblock], but typeset on
@ -115,8 +115,10 @@ as a REPL value (i.e., a single color with no hyperlinks).}
@defform[(schemeid datum ...)]{Like @scheme[scheme], but typeset
as an unbound identifier (i.e., no coloring or hyperlinks).}
@defform[(schememodname datum ...)]{Like @scheme[scheme], but typeset
as a @schemefont{#module} language name.}
@defform[(schememodname datum)]{Like @scheme[scheme], but typeset as a
module path. If @scheme[datum] is an identifier, then it is
hyperlinked to the module path's definition as created by
@scheme[defmodule].}
@defproc[(litchar [str string?]) element?]{Typesets @scheme[str] as a
representation of literal text. Use this when you have to talk about
@ -130,7 +132,7 @@ useful with @scheme[verbatim].}
@defproc[(schemefont [pre-content any/c] ...) element?]{Typesets the given
content as uncolored, unhyperlinked Scheme. This procedure is useful
for typesetting things like @scheme{#module}, which are not
for typesetting things like @schemefont{#lang}, which are not
@scheme[read]able by themselves.}
@defproc[(schemevalfont [pre-content any/c] ...) element?]{Like
@ -167,7 +169,65 @@ cannot work for some reason.}
in a form definition.}
@; ------------------------------------------------------------------------
@section{Definition Reference}
@section{Documenting Modules}
@defform[(defmodule id pre-flow ...)]{
Produces a sequence of flow elements (encaptured in a @scheme[splice])
to start the documentation for a module that can be @scheme[require]d
using the path @scheme[id]. The @scheme[pre-flow]s list is parsed as a
flow that documents the procedure (see @scheme[decode-flow]).
Besides generating text, this form expands to a use of
@scheme[declare-exporting] with @scheme[id].
Hyperlinks created by @scheme[schememodname] are associated with the
enclosing section, rather than the local @scheme[id] text.}
@defform[(defmodulelang id pre-flow ...)]{
Like @scheme[defmodule], but documents @scheme[id] as a module path
suitable for use by either @scheme[require] or @schememodfont{#lang}.}
@defform[(defmodule* (id ...) pre-flow ...)]{
Like @scheme[defmodule], but introduces multiple module paths instead
of just one.}
@defform[(defmodulelang* (id ...) 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
@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[(declare-exporting module-path ...)]{
Associates the @scheme[module-paths]s to all bindings defined within
the enclosing section, except as overridden by other
@scheme[declare-exporting] declarations in nested sub-sections. The
list of @scheme[module-path]s is shown, for example, when the user
hovers the mouse over one of the bindings defined within the section.}
@; ------------------------------------------------------------------------
@section{Documenting Forms, Functions, Structure Types, and Values}
@defform/subs[(defproc (id arg-spec ...)
result-contract-expr-datum
@ -378,7 +438,7 @@ Like @scheme[schemegrammar], but for typesetting multiple productions
at once, aligned around the @litchar{=} and @litchar{|}.}
@; ------------------------------------------------------------------------
@section{Classes and Interfaces}
@section{Documenting Classes and Interfaces}
@defform[(defclass id super-id (intf-id ...) pre-flow ...)]{

11
collects/scribblings/scribble/reader.scrbl
View File

@ -23,9 +23,7 @@ meaning of these S-expressions depends on the rest of your own code.
A PLT Scheme manual more likely starts with
@schemeblock[
#, @schemefont{#lang scribble/doc}
]
@schememod[scribble/doc]
which installs a reader, wraps the file content afterward into a
MzScheme module, and parses the body into a document using
@ -35,7 +33,7 @@ Another way to use the reader is to use the @scheme[use-at-readtable]
function to switch the current readtable to a readtable that parses
@"@"-forms. You can do this in a single command line:
@commandline{mzscheme -Le reader.ss scribble "(use-at-readtable)"}
@commandline{mzscheme -l scheme -l scribble/reader -e "(use-at-readtable)"}
@;--------------------------------------------------------------------
@section{Concrete Syntax}
@ -721,9 +719,8 @@ an example of this.
@;--------------------------------------------------------------------
@section{Interface}
@declare-exporting[scribble/reader]
The @filepath{reader.ss} module provides functionality for advanced needs.
@defmodule[scribble/reader]{The @schememodname[scribble/reader] module
provides direct Scribble reader functionality for advanced needs.}
@; The `with-scribble-read' trick below shadows `read' and
@; `read-syntax' with for-label bindings from the Scribble reader

35
collects/scribblings/scribble/renderer.scrbl
View File

@ -13,23 +13,36 @@ tends to be format-independent, and it usually implemented completely
by the base renderer. The latter method generates the actual output,
which is naturally specific to a particular format.
The @filepath{base-render.ss} module provides @scheme[render%], which
implements the core of a renderer. The @filepath{html-renderer.ss},
@filepath{latex-renderer.ss}, and @filepath{text-renderer.ss} modules each
provide @scheme[renderer-mixin] to extend the base. The
@filepath{html-renderer.ss} module also provides
@scheme[multi-renderer-mixin] to produce multi-file HTML instead
instead of single-file HTML.
@defmodule[scribble/base-render]{The
@schememodname[scribble/base-render] module provides @scheme[render%],
which implements the core of a renderer.}
@defmodule*/no-declare[(scribble/text-render)]{The
@schememodname[scribble/text-render] module provides
@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
generating plain text.}
@defmodule*/no-declare[(scribble/html-render)]{The
@schememodname[scribble/html-render] module provides
@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
generating a single HTML file. It also supplies
@schemeidfont{multi-renderer-mixin}, which further specializes the
renderer to produce multi-file HTML.}
@defmodule*/no-declare[(scribble/latex-render)]{The
@schememodname[scribble/latex-render] module provides
@schemeidfont{renderer-mixin}, which specializes @scheme[render%] for
generating Latex.}
The mixin structure is meant to support document-specific extensions
to the renderers. For example, the @exec{scribble} command-line tool
might, in the future, extract rendering mixins from a document module
(in addition to the document proper).
See @filepath{base-render.ss} for more information about the methods of
the renderer. Documents built with higher layers, such as
@filepath{manual.ss}, generally do not call the render object's methods
directly.
See the @filepath{base-render.ss} source for more information about
the methods of the renderer. Documents built with higher layers, such
as @schememodname[scribble/manual], generally do not call the render
object's methods directly.
@defclass[render% object% ()]{

12
collects/scribblings/scribble/scheme.scrbl Normal file
View File

@ -0,0 +1,12 @@
#lang scribble/doc
@require[scribble/manual]
@require["utils.ss"]
@title[#:tag "scheme"]{Scheme}
@defmodule[scribble/scheme]{The @scheme[scribble/scheme] library
provides utilities for typesetting Scheme code. The
@scheme[scribble/manual] forms provide a higher-level interface.}
@italic{To do:} document this library!

53
collects/scribblings/scribble/scribble.scrbl
View File

@ -26,52 +26,51 @@ The layers are:
@itemize{
@item{@filepath{reader.ss}: a reader that extends the syntax of Scheme
with @"@"-forms for conveniently embedding a mixin of text and
escapes. See @secref["reader"].}
@item{@schememodname[scribble/reader]: a reader that extends the
syntax of Scheme with @"@"-forms for conveniently embedding a
mixin of text and escapes. See @secref["reader"].}
@item{@filepath{struct.ss}: a set of document datatypes and utilities
@item{@schememodname[scribble/struct]: a set of document datatypes and utilities
that define the basic layout and processing of a document. See
@secref["struct"].}
@item{@filepath{base-render.ss} with @filepath{html-render.ss},
@filepath{latex-render.ss}, or @filepath{text-render.ss}: A base
@item{@schememodname[scribble/base-render] with @schememodname[scribble/html-render],
@schememodname[scribble/latex-render], or @schememodname[scribble/text-render]: A base
renderer and mixins that generate documents in various formats
from instances of the @filepath{struct.ss} datatypes. See
from instances of the @schememodname[scribble/struct] datatypes. See
@secref["renderer"].}
@item{@filepath{decode.ss}: Processes a stream of text, section-start
markers, etc. to produce instances of the @filepath{struct.ss}
@item{@schememodname[scribble/decode]: Processes a stream of text, section-start
markers, etc. to produce instances of the @schememodname[scribble/struct]
datatypes. See @secref["decode"].}
@item{@filepath{doclang.ss}: to be used for the initial import of a
@item{@schememodname[scribble/doclang]: to be used for the initial import of a
module; processes the module top level through
@filepath{decode.ss}, and otherwise provides all of
@schememodname[big]. See @secref["doclang"].}
@schememodname[scribble/decode], and otherwise provides all of
@schememodname[scheme/base]. See @secref["doclang"].}
@item{@filepath{docreader.ss}: a reader that is meant to tbe used to
process an entire file; it essentially combines
@filepath{reader.ss} with @filepath{doclang.ss}. See
@secref["docreader"].}
@item{@schememodname[scribble/doc]: a language that essentially
combines @schememodname[scribble/reader] with
@schememodname[scribble/doclang]. See @secref["docreader"].}
@item{@filepath{basic.ss}: a library of basic document operators---such
@item{@schememodname[scribble/basic]: a library of basic document operators---such
as @scheme[title], @scheme[section], and @scheme[secref]---for
use with @filepath{decode.ss} and a renderer. See
use with @schememodname[scribble/decode] and a renderer. See
@secref["basic"].}
@item{@filepath{scheme.ss}: a library of support functions for
typesetting Scheme code.}
@item{@schememodname[scribble/scheme]: a library of support functions for
typesetting Scheme code. See @secref["scheme"].}
@item{@filepath{manual.ss}: a library of support functions for writing
PLT Scheme documentation; re-exports @filepath{basic.ss}. See
@item{@schememodname[scribble/manual]: a library of support functions for writing
PLT Scheme documentation; re-exports @schememodname[scribble/basic]. See
@secref["manual"].}
@item{@filepath{eval.ss}: a library of support functions for ealuating
@item{@schememodname[scribble/eval]: a library of support functions for ealuating
code at document-build time, especially for showing
examples. See @secref["eval"].}
@item{@filepath{bnf.ss}: a library of support functions for writing
grammars.}
@item{@schememodname[scribble/bnf]: a library of support functions for writing
grammars. See @secref["bnf"].}
}
@ -80,7 +79,7 @@ exports a @scheme{struct.ss}-based document, generating output with a
specified renderer. More specifically, the executable installs a
renderer, loads the specified modules and extracts the @scheme[doc]
export of each (which must be an instance of @scheme[section] from
@filepath{struct.ss}), and renders each. Use @exec{scribble -h} for more
@schememodname[scribble/struct]), and renders each. Use @exec{scribble -h} for more
information.
@; ------------------------------------------------------------------------
@ -91,7 +90,9 @@ information.
@include-section["doclang.scrbl"]
@include-section["docreader.scrbl"]
@include-section["basic.scrbl"]
@include-section["scheme.scrbl"]
@include-section["manual.scrbl"]
@include-section["eval.scrbl"]
@include-section["bnf.scrbl"]
@index-section[]

2
collects/scribblings/scribble/struct.scrbl
View File

@ -4,7 +4,7 @@
@title[#:tag "struct"]{Document Structures And Processing}
@declare-exporting[scribble/struct]
@defmodule[scribble/struct]
A document is represented as a @techlink{part}, as described in
@secref["parts"]. This representation is intended to