commit 0aa14ae363c66dc13d931729945bc85d80c6cacd parent 40e6579feaa17bb0d92aa2e15d6addf81fa430c9 Author: Matthew Flatt <mflatt@racket-lang.org> Date: Wed, 5 Dec 2007 21:41:07 +0000 Scribble improvements: defmodule & co. svn: r7902 original commit: cd7157641cc8a1dd6266c926675e5909daeb643f Diffstat:
22 files changed, 461 insertions(+), 165 deletions(-)
diff --git a/collects/scribble/decode.ss b/collects/scribble/decode.ss @@ -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)] diff --git a/collects/scribble/doc/lang/reader.ss b/collects/scribble/doc/lang/reader.ss @@ -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))) diff --git a/collects/scribble/doc/main.ss b/collects/scribble/doc/main.ss @@ -0,0 +1,6 @@ +(module main scheme/base + (define-syntax-rule (out) + (begin (require scribble/doclang) + (provide (all-from-out scribble/doclang)))) + (out)) + diff --git a/collects/scribble/doc/reader.ss b/collects/scribble/doc/reader.ss @@ -0,0 +1,24 @@ + +(module reader scheme/base + (require (prefix-in scribble: "../reader.ss")) + + (provide (rename-out [*read read]) + (rename-out [*read-syntax read-syntax])) + + (define (*read [inp (current-input-port)]) + (wrap inp (scribble:read-inside inp))) + + (define (*read-syntax [src #f] [port (current-input-port)]) + (wrap port (scribble:read-inside-syntax src port))) + + (define (wrap port body) + (let* ([p-name (object-name port)] + [name (if (path? p-name) + (let-values ([(base name dir?) (split-path p-name)]) + (string->symbol (path->string (path-replace-suffix name #"")))) + 'page)] + [id 'doc]) + `(module ,name scribble/doclang + (#%module-begin + ,id () + . ,body))))) diff --git a/collects/scribble/docreader.ss b/collects/scribble/docreader.ss @@ -1,24 +0,0 @@ - -(module docreader scheme/base - (require (prefix-in scribble: "reader.ss")) - - (provide (rename-out [*read read]) - (rename-out [*read-syntax read-syntax])) - - (define (*read [inp (current-input-port)]) - (wrap inp (scribble:read-inside inp))) - - (define (*read-syntax [src #f] [port (current-input-port)]) - (wrap port (scribble:read-inside-syntax src port))) - - (define (wrap port body) - (let* ([p-name (object-name port)] - [name (if (path? p-name) - (let-values ([(base name dir?) (split-path p-name)]) - (string->symbol (path->string (path-replace-suffix name #"")))) - 'page)] - [id 'doc]) - `(module ,name scribble/doclang - (#%module-begin - ,id () - . ,body))))) diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.ss @@ -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") diff --git a/collects/scribble/manual-struct.ss b/collects/scribble/manual-struct.ss @@ -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?] diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss @@ -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) diff --git a/collects/scribble/scribble.css b/collects/scribble/scribble.css @@ -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; diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl @@ -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]). @; ------------------------------------------------------------------------ diff --git a/collects/scribblings/scribble/bnf.scrbl b/collects/scribblings/scribble/bnf.scrbl @@ -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.} diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl @@ -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]. diff --git a/collects/scribblings/scribble/doclang.scrbl b/collects/scribblings/scribble/doclang.scrbl @@ -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 diff --git a/collects/scribblings/scribble/docreader.scrbl b/collects/scribblings/scribble/docreader.scrbl @@ -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.} diff --git a/collects/scribblings/scribble/eval.scrbl b/collects/scribblings/scribble/eval.scrbl @@ -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 diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl @@ -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}.} } @@ -89,12 +95,19 @@ 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} diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl @@ -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 ...)]{ diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl @@ -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 diff --git a/collects/scribblings/scribble/renderer.scrbl b/collects/scribblings/scribble/renderer.scrbl @@ -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% ()]{ diff --git a/collects/scribblings/scribble/scheme.scrbl b/collects/scribblings/scribble/scheme.scrbl @@ -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! + diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl @@ -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[] diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl @@ -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