commit 1558ad553261d94c014e79642e3ca172d9500abd
parent 54376250e012a27ddd9e30bee5c96b86edf06d8d
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 14 Jul 2014 11:36:26 +0100
scribble: fix documentation for `tt` and `racketfont`
The `tt` and `racketfont` functions treat their arguments strangely,
applying styles only to immediate strings and symbols.
Add `racketplainfont`, which is a non-strange version of `racketfont`.
original commit: 737330deb63dcfa01ebf304c3e5c06276a283c81
Diffstat:
4 files changed, 41 insertions(+), 21 deletions(-)
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl
@@ -419,7 +419,16 @@ Wraps the @tech{decode}d @racket[pre-content] as an element with style
@def-style-proc[italic]
@def-style-proc[bold]
-@def-style-proc[tt]
+
+@defproc[(tt [pre-content pre-content?] ...) element?]{
+
+Similar to @racket[elem], but the @racket['tt] style is used for
+immediate strings and symbols among the @racket[pre-content]
+arguments.
+
+To apply the @racket['tt] style uniformly to all @racket[pre-content]
+arguments, use @racket[(elem #:style 'tt pre-content ...)], instead.}
+
@def-style-proc[subscript]
@def-style-proc[superscript]
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl
@@ -482,48 +482,57 @@ representation of literal text. Use this when you have to talk about
the individual characters in a stream of text, as when documenting
a reader extension.}
-@defproc[(racketfont [pre-content pre-content?] ...) element?]{Typesets
-@tech{decode}d @racket[pre-content] as uncolored, unhyperlinked
-Racket. This procedure is useful for typesetting things like
-@racketfont{#lang}, which are not @racket[read]able by themselves.}
+@defproc[(racketfont [pre-content pre-content?] ...) element?]{The
+same as @racket[(tt pre-content ...)], which applies the @racket['tt]
+style to immediate strings and symbols among the @racket[pre-content]
+arguments. Beware that @racket[pre-content] is @racket[decode]d as
+usual, making @racket[racketfont] a poor choice for typesetting
+literal code.}
+
+@defproc[(racketplainfont [pre-content pre-content?] ...) element?]{Applies
+the @racket['tt] style to @racket[pre-content]. Beware
+that @racket[pre-content] is @racket[decode]d as usual, making
+@racket[racketplainfont] a poor choice for typesetting literal code
+directly but useful for implementing code-formatting functions.
+
+@history[#:added "1.6"]}
@defproc[(racketvalfont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as a value.}
+@racket[racketplainfont], but colored as a value.}
@defproc[(racketresultfont [#:decode? decode? boolean? #t] [pre-content pre-content?] ...) element?]{
- Like @racket[racketfont], but colored as a REPL result when @racket[decode?] is
- @racket[#t]. When @racket[decode?] is @racket[#f], it also avoids @racket[decode]ing
- its argument.
-}
+Like @racket[racketplainfont], but colored as a REPL result. When
+@racket[decode?] is @racket[#f], then unlike @racket[racketplainfont],
+@racket[racketresultfont] avoids @racket[decode]ing its argument.}
@defproc[(racketidfont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as an identifier.}
+@racket[racketplainfont], but colored as an identifier.}
@defproc[(racketvarfont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as a variable (i.e., an argument or
+@racket[racketplainfont], but colored as a variable (i.e., an argument or
sub-form in a procedure being documented).}
@defproc[(racketkeywordfont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as a syntactic form name.}
+@racket[racketplainfont], but colored as a syntactic form name.}
@defproc[(racketparenfont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored like parentheses.}
+@racket[racketplainfont], but colored like parentheses.}
@defproc[(racketmetafont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as meta-syntax, such as backquote or
+@racket[racketplainfont], but colored as meta-syntax, such as backquote or
unquote.}
@defproc[(racketcommentfont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as a comment.}
+@racket[racketplainfont], but colored as a comment.}
@defproc[(racketerror [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as error-message text.}
+@racket[racketplainfont], but colored as error-message text.}
@defproc[(racketmodfont [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as module name.}
+@racket[racketplainfont], but colored as module name.}
@defproc[(racketoutput [pre-content pre-content?] ...) element?]{Like
-@racket[racketfont], but colored as output.}
+@racket[racketplainfont], but colored as output.}
@defproc[(procedure [pre-content pre-content?] ...) element?]{Typesets
@tech{decode}d @racket[pre-content] as a procedure name in a REPL
diff --git a/pkgs/scribble-pkgs/scribble-lib/info.rkt b/pkgs/scribble-pkgs/scribble-lib/info.rkt
@@ -21,4 +21,4 @@
(define pkg-authors '(mflatt eli))
-(define version "1.5")
+(define version "1.6")
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-style.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-style.rkt
@@ -29,7 +29,7 @@
(define-syntax-rule (provide-styling id ...)
(provide/contract [id styling-f/c] ...))
(provide-styling racketmodfont racketoutput
- racketerror racketfont racketvalfont racketidfont racketvarfont
+ racketerror racketfont racketplainfont racketvalfont racketidfont racketvarfont
racketcommentfont racketparenfont racketkeywordfont racketmetafont
onscreen defterm filepath exec envvar Flag DFlag PFlag DPFlag math
procedure
@@ -91,6 +91,8 @@
(make-element 'italic c)))
(define (racketfont . str)
(apply tt str))
+(define (racketplainfont . str)
+ (make-element 'tt (decode-content str)))
(define (racketvalfont . str)
(make-element value-color (decode-content str)))
(define (racketresultfont #:decode? [decode? #t] . str)
