diff --git a/collects/scribble/base.ss b/collects/scribble/base.ss index 0ad2bcd42b..be8f578475 100644 --- a/collects/scribble/base.ss +++ b/collects/scribble/base.ss @@ -564,9 +564,9 @@ (provide get-index-entries) (provide/contract [index-block (-> delayed-block?)] - [index (((or/c string? (listof string?))) () #:rest (listof any/c) . ->* . index-element?)] ; XXX pre-content docs - [index* (((listof string?) (listof any/c)) () #:rest (listof any/c) . ->* . index-element?)] ; XXX pre-content docs and first any/c wrong in docs - [as-index (() () #:rest (listof any/c) . ->* . index-element?)] ; XXX pre-content docs + [index (((or/c string? (listof string?))) () #:rest (listof pre-content?) . ->* . index-element?)] + [index* (((listof string?) (listof any/c)) () #:rest (listof pre-content?) . ->* . index-element?)] ; XXX first any/c wrong in docs + [as-index (() () #:rest (listof pre-content?) . ->* . index-element?)] [section-index (() () #:rest (listof string?) . ->* . part-index-decl?)] [index-section (() (#:tag (or/c false/c string?)) . ->* . part?)]) diff --git a/collects/scribble/private/manual-bib.ss b/collects/scribble/private/manual-bib.ss index 2c6ee7fd16..ee86d2e3b7 100644 --- a/collects/scribble/private/manual-bib.ss +++ b/collects/scribble/private/manual-bib.ss @@ -9,8 +9,8 @@ (define-struct a-bib-entry (key val)) (provide/contract - [cite ((string?) () #:rest (listof string?) . ->* . element?)] ; XXX docs wrong - [bib-entry ((#:key string? #:title any/c) ; XXX bad contracts + [cite ((string?) () #:rest (listof string?) . ->* . element?)] + [bib-entry ((#:key string? #:title any/c) ; XXX should be pre-content or #f (#:is-book? any/c #:author any/c #:location any/c #:date any/c #:url any/c) . ->* . a-bib-entry?)] diff --git a/collects/scribble/private/manual-scheme.ss b/collects/scribble/private/manual-scheme.ss index 689b5174ec..4e1bf23a4e 100644 --- a/collects/scribble/private/manual-scheme.ss +++ b/collects/scribble/private/manual-scheme.ss @@ -18,7 +18,6 @@ scheme SCHEME scheme/form schemeresult schemeid schememodname schememodlink indexed-scheme - ; XXX doc says this is function schemelink) (define-code schemeblock0 to-paragraph) diff --git a/collects/scribble/private/manual-style.ss b/collects/scribble/private/manual-style.ss index 341dcb70a8..a20869e53b 100644 --- a/collects/scribble/private/manual-style.ss +++ b/collects/scribble/private/manual-style.ss @@ -18,16 +18,14 @@ itemize aux-elem) -; XXX pre-content (define styling-f/c - (() () #:rest (listof any/c) . ->* . element?)) + (() () #:rest (listof pre-content?) . ->* . element?)) (define-syntax-rule (provide-styling id ...) (provide/contract [id styling-f/c] ...)) -(provide-styling onscreen defterm - schememodfont schemeoutput ; XXX no docs +(provide-styling schememodfont schemeoutput schemeerror schemefont schemevalfont schemeresultfont schemeidfont schemevarfont schemeparenfont schemekeywordfont schememetafont - filepath exec envvar Flag DFlag PFlag DPFlag math + onscreen defterm filepath exec envvar Flag DFlag PFlag DPFlag math procedure indexed-file indexed-envvar idefterm pidefterm) (provide/contract @@ -37,9 +35,9 @@ [hash-lang (-> element?)] [etc string?] [inset-flow (() () #:rest (listof any/c) . ->* . any/c)] ; XXX no docs and bad return contract - [litchar (() () #:rest (listof string?) . ->* . element?)] ; XXX docs wrong - [t (() () #:rest (listof any/c) . ->* . paragraph?)] ; XXX pre-content - [commandline (() () #:rest (listof any/c) . ->* . paragraph?)] ; XXX pre-content + [litchar (() () #:rest (listof string?) . ->* . element?)] + [t (() () #:rest (listof pre-content?) . ->* . paragraph?)] + [commandline (() () #:rest (listof pre-content?) . ->* . paragraph?)] [menuitem (string? string? . -> . element?)]) (define PLaneT (make-element "planetName" '("PLaneT"))) @@ -47,9 +45,6 @@ (define etc "etc.") ; so we can fix the latex space, one day (define (litchar . strs) - ; XXX Remove not-contract - (unless (andmap string? strs) - (raise-type-error 'litchar "strings" strs)) (let ([s (string-append* (map (lambda (s) (regexp-replace* "\n" s " ")) strs))]) (if (regexp-match? #rx"^ *$" s) diff --git a/collects/scribble/private/manual-tech.ss b/collects/scribble/private/manual-tech.ss index 93929fcf71..799d108be4 100644 --- a/collects/scribble/private/manual-tech.ss +++ b/collects/scribble/private/manual-tech.ss @@ -7,10 +7,10 @@ "manual-style.ss") (provide/contract - ; XXX boolean? and precontent? - [deftech (() (#:style? any/c) #:rest (listof any/c) . ->* . element?)] - [tech (() (#:doc (or/c module-path? false/c) #:tag-prefixes (or/c (listof string?) false/c)) #:rest (listof any/c) . ->* . element?)] - [techlink (() (#:doc (or/c module-path? false/c) #:tag-prefixes (or/c (listof string?) false/c)) #:rest (listof any/c) . ->* . element?)]) + ; XXX boolean? + [deftech (() (#:style? any/c) #:rest (listof pre-content?) . ->* . element?)] + [tech (() (#:doc (or/c module-path? false/c) #:tag-prefixes (or/c (listof string?) false/c)) #:rest (listof pre-content?) . ->* . element?)] + [techlink (() (#:doc (or/c module-path? false/c) #:tag-prefixes (or/c (listof string?) false/c)) #:rest (listof pre-content?) . ->* . element?)]) (define (*tech make-elem style doc prefix s) (let* ([c (decode-content s)] diff --git a/collects/scribble/private/manual-unit.ss b/collects/scribble/private/manual-unit.ss index 814c2a8d57..b8dadcbddb 100644 --- a/collects/scribble/private/manual-unit.ss +++ b/collects/scribble/private/manual-unit.ss @@ -42,8 +42,7 @@ (make-sig-desc l)) (provide/contract - ; XXX preflow & docs - [signature-desc (() () #:rest (listof any/c) . ->* . sig-desc?)]) + [signature-desc (() () #:rest (listof pre-flow?) . ->* . sig-desc?)]) (define (*defsignature stx-id supers body-thunk indent?) (*defthing diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index a6d150c3b8..698adf8811 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -168,43 +168,49 @@ Like @scheme[schememodlink], but separating the module path to link from the content to be linked. The @scheme[datum] module path is always linked, even if it is not an identifier.} -@defproc[(litchar [str string?]) element?]{Typesets @scheme[str] as a +@defproc[(litchar [str string?] ...) element?]{Typesets @scheme[str]s as a representation of literal text. Use this when you have to talk about the individual characters in a stream of text, as as when documenting a reader extension.} -@defproc[(schemefont [pre-content any/c] ...) element?]{Typesets +@defproc[(schemefont [pre-content pre-content?] ...) element?]{Typesets @tech{decode}d @scheme[pre-content] as uncolored, unhyperlinked Scheme. This procedure is useful for typesetting things like @schemefont{#lang}, which are not @scheme[read]able by themselves.} -@defproc[(schemevalfont [pre-content any/c] ...) element?]{Like +@defproc[(schemevalfont [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored as a value.} -@defproc[(schemeresultfont [pre-content any/c] ...) element?]{Like +@defproc[(schemeresultfont [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored as a REPL result.} -@defproc[(schemeidfont [pre-content any/c] ...) element?]{Like +@defproc[(schemeidfont [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored as an identifier.} -@defproc[(schemevarfont [pre-content any/c] ...) element?]{Like +@defproc[(schemevarfont [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored as a variable (i.e., an argument or sub-form in a procedure being documented).} -@defproc[(schemekeywordfont [pre-content any/c] ...) element?]{Like +@defproc[(schemekeywordfont [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored as a syntactic form name.} -@defproc[(schemeparenfont [pre-content any/c] ...) element?]{Like +@defproc[(schemeparenfont [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored like parentheses.} -@defproc[(schememetafont [pre-content any/c] ...) element?]{Like +@defproc[(schememetafont [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored as meta-syntax, such as backquote or unquote.} -@defproc[(schemeerror [pre-content any/c] ...) element?]{Like +@defproc[(schemeerror [pre-content pre-content?] ...) element?]{Like @scheme[schemefont], but colored as error-message text.} -@defproc[(procedure [pre-content any/c] ...) element?]{Typesets +@defproc[(schememodfont [pre-content pre-content?] ...) element?]{Like +@scheme[schemefont], but colored as module name.} + +@defproc[(schemeoutput [pre-content pre-content?] ...) element?]{Like +@scheme[schemefont], but colored as output.} + +@defproc[(procedure [pre-content pre-content?] ...) element?]{Typesets @tech{decode}d @scheme[pre-content] as a procedure name in a REPL result (e.g., in typewriter font with a @litchar{#} suffix.).} @@ -817,7 +823,7 @@ Like @scheme[defsignature], but the @tech{decode}d @scheme[pre-flow]s are not typeset under the signature declaration, and new sections, @|etc| can be started in the @scheme[pre-flow]s.} -@defproc[(signature-desc [pre-flow any/c] ...) any/c]{ +@defproc[(signature-desc [pre-flow pre-flow?] ...) any/c]{ Produces an opaque value that @scheme[defsignature] recognizes to outdent in the typeset form. This is useful for text describing the @@ -831,46 +837,46 @@ as a member of the signature named by @scheme[sig-id].} @; ------------------------------------------------------------------------ @section[#:tag "doc-strings"]{Various String Forms} -@defproc[(aux-elem [pre-content any/c] ...) element?]{ +@defproc[(aux-elem [pre-content pre-content?] ...) element?]{ Like @scheme[elem], but adds an @scheme['aux] @tech{style property}.} -@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the +@defproc[(defterm [pre-content pre-content?] ...) element?]{Typesets the @tech{decode}d @scheme[pre-content] as a defined term (e.g., in italic). Consider using @scheme[deftech] instead, though, so that uses of @scheme[tech] can hyper-link to the definition.} -@defproc[(onscreen [pre-content any/c] ...) element?]{ Typesets the +@defproc[(onscreen [pre-content pre-content?] ...) element?]{ Typesets the @tech{decode}d @scheme[pre-content] as a string that appears in a GUI, such as the name of a button.} @defproc[(menuitem [menu-name string?] [item-name string?]) element?]{ Typesets the given combination of a GUI's menu and item name.} -@defproc[(filepath [pre-content any/c] ...) element?]{Typesets the +@defproc[(filepath [pre-content pre-content?] ...) element?]{Typesets the @tech{decode}d @scheme[pre-content] as a file name (e.g., in typewriter font and in in quotes).} -@defproc[(exec [pre-content any/c] ...) element?]{Typesets the +@defproc[(exec [pre-content pre-content?] ...) element?]{Typesets the @tech{decode}d @scheme[pre-content] as a command line (e.g., in typewriter font).} -@defproc[(envvar [pre-content any/c] ...) element?]{Typesets the given +@defproc[(envvar [pre-content pre-content?] ...) element?]{Typesets the given @tech{decode}d @scheme[pre-content] as an environment variable (e.g., in typewriter font).} -@defproc[(Flag [pre-content any/c] ...) element?]{Typesets the given +@defproc[(Flag [pre-content pre-content?] ...) element?]{Typesets the given @tech{decode}d @scheme[pre-content] as a flag (e.g., in typewriter font with a leading @litchar{-}).} -@defproc[(DFlag [pre-content any/c] ...) element?]{Typesets the given +@defproc[(DFlag [pre-content pre-content?] ...) element?]{Typesets the given @tech{decode}d @scheme[pre-content] a long flag (e.g., in typewriter font with two leading @litchar{-}s).} -@defproc[(PFlag [pre-content any/c] ...) element?]{Typesets the given +@defproc[(PFlag [pre-content pre-content?] ...) element?]{Typesets the given @tech{decode}d @scheme[pre-content] as a @litchar{+} flag (e.g., in typewriter font with a leading @litchar{+}).} -@defproc[(DPFlag [pre-content any/c] ...) element?]{Typesets the given +@defproc[(DPFlag [pre-content pre-content?] ...) element?]{Typesets the given @tech{decode}d @scheme[pre-content] a long @litchar{+} flag (e.g., in typewriter font with two leading @litchar{+}s).} @@ -879,9 +885,11 @@ typewriter font with two leading @litchar{+}s).} See also @secref["base-links"]. -@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{ +@defform[(schemelink id pre-content ...) + #:contracts ([id identifier?] + [pre-content pre-content?])]{ -The @tech{decode}d @scheme[pre-content] is hyperlinked to the definition +An element where the @tech{decode}d @scheme[pre-content] is hyperlinked to the definition of @scheme[id].} @defproc[(link [url string?] [pre-content any/c] ... @@ -897,7 +905,7 @@ An alias of @scheme[hyperlink] for backward compatibility.} An alias of @scheme[other-doc] for backward compatibility.} -@defproc[(deftech [pre-content any/c] ... +@defproc[(deftech [pre-content pre-content?] ... [#:style? style? any/c #t]) element?]{ Produces an element for the @tech{decode}d @scheme[pre-content], and @@ -926,7 +934,7 @@ that differ slightly from a defined form. For example, a definition of If @scheme[style?] is true, then @scheme[defterm] is used on @scheme[pre-content].} -@defproc[(tech [pre-content any/c] ... +@defproc[(tech [pre-content pre-content?] ... [#:doc module-path (or/c module-path? false/c) #f] [#:tag-prefixes prefixes (or/c (listof string?) false/c) #f]) element?]{ @@ -949,7 +957,7 @@ normalization performed on the term. For example, if ``bind'' is defined, but a sentence uses the term ``binding,'' the latter can be linked to the former using @schemefont["@tech{bind}ing"].} -@defproc[(techlink [pre-content any/c] ... +@defproc[(techlink [pre-content pre-content?] ... [#:doc module-path (or/c module-path? false/c) #f] [#:tag-prefixes prefixes (or/c (listof string?) false/c) #f]) element?]{ @@ -979,20 +987,20 @@ following special cases when a single @scheme[datum] is provided: ]} -@defproc[(idefterm [pre-content any/c] ...) element?]{Combines +@defproc[(idefterm [pre-content pre-content?] ...) element?]{Combines @scheme[as-index] and @scheme[defterm]. The content normally should be plural, rather than singular. Consider using @scheme[deftech], instead, which always indexes.} -@defproc[(pidefterm [pre-content any/c] ...) element?]{Like +@defproc[(pidefterm [pre-content pre-content?] ...) element?]{Like @scheme[idefterm], but plural: adds an ``s'' on the end of the content for the index entry. Consider using @scheme[deftech], instead.} -@defproc[(indexed-file [pre-content any/c] ...) element?]{A +@defproc[(indexed-file [pre-content pre-content?] ...) element?]{A combination of @scheme[file] and @scheme[as-index], but where the sort key for the index iterm does not include quotes.} -@defproc[(indexed-envvar [pre-content any/c] ...) element?]{A +@defproc[(indexed-envvar [pre-content pre-content?] ...) element?]{A combination of @scheme[envvar] and @scheme[as-index].} @; ------------------------------------------------------------------------ @@ -1009,9 +1017,9 @@ combination of @scheme[envvar] and @scheme[as-index].} @margin-note{See also @schememodname[scriblib/autobib].} -@defproc[(cite [key string?]) element?]{ +@defproc[(cite [key string?] ...+) element?]{ -Links to a bibliography entry, using @scheme[key] both to indicate the +Links to a bibliography entry, using the @scheme[key]s both to indicate the bibliography entry and, in square brackets, as the link text.} @defproc[(bibliography [#:tag tag string? "doc-bibliography"] @@ -1073,10 +1081,10 @@ Returns @scheme[#t] if @scheme[v] is a bibliography entry created by @; ------------------------------------------------------------------------ @section{Miscellaneous} -@defproc[(t [pre-content any/c] ...) paragraph?]{Wraps the +@defproc[(t [pre-content pre-content?] ...) paragraph?]{Wraps the @tech{decode}d @scheme[pre-content] as a paragraph.} -@defthing[PLaneT string?]{@scheme["PLaneT"] (to help make sure you get +@defthing[PLaneT element?]{@scheme["PLaneT"] (to help make sure you get the letters in the right case).} @defproc[(hash-lang) element?]{Returns an element for @hash-lang[] @@ -1086,7 +1094,7 @@ that is hyperlinked to an explanation.} @defthing[undefined-const element?]{Returns an element for @|undefined-const|.} -@defproc[(commandline [pre-content any/c] ...) paragraph?]{Produces +@defproc[(commandline [pre-content pre-content?] ...) paragraph?]{Produces an inset command-line example (e.g., in typewriter font).} @defproc[(centerline [pre-flow pre-flow?] ...) nested-flow?]{