commit 098e9a37ff87c4c25a8d82c21bcc941346e39042
parent 644ea52438f62415701d07bb3e74718f442c1073
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Fri, 8 Nov 2013 06:27:39 -0700
scribble/manual: generalize `deprecated`
original commit: 9dd9ffc2e2d63616a3f1790eff34a2cdafbc15de
Diffstat:
3 files changed, 22 insertions(+), 17 deletions(-)
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl
@@ -689,14 +689,6 @@ per section, since the declaration applies to the entire section,
although overriding @racket[declare-exporting] forms can appear in
sub-sections.}
-@defform/subs[(deprecated replacement additional-notes ...)
- ([replacement pre-content]
- [additional-notes pre-content])]{
- produces a warning for deprecated modules. Requires a replacement suggestion;
- additional notes are welcome.
-}
-
-
@defform*[[(defmodulelang one-or-multi maybe-sources option ... pre-flow ...)
(defmodulelang one-or-multi #:module-path module-path
option ... pre-flow ...)]]{
@@ -1750,6 +1742,16 @@ Typesets the @racket[pre-flow]s as the content of
with @racket[filename] above it. If @racket[filename] is a string, it
is passed to @racket{filepath} to obtain an @racket[element].}
+@defproc[(deprecated [#:what what content? "library"]
+ [replacement content?]
+ [additional-notes content?] ...)
+ block?]{
+Produces an inset warning for deprecated libraries, functions, @|etc| (as
+described by @racket[what]), where @racket[replacement] describes a
+suitable replacement. The @racket[additional-notes] are included after the
+initial deprecation message.}
+
+
@; ------------------------------------------------------------------------
@section[#:tag "index-entries"]{Index-Entry Descriptions}
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/HISTORY.txt b/pkgs/scribble-pkgs/scribble-lib/scribble/HISTORY.txt
@@ -4,6 +4,8 @@ Add `--html-tree' option to for rendering to multi-page HTML
with nested directories for nested parts
For HTML rendering, merge generated `style' attributes within
a single tag
+scribble/manual: changed `deprecated` to a function, and
+ generalized it by adding an optional `#:what` argument
Older versions
See the "Racket core" release notes for a history of changes before
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-mod.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-mod.rkt
@@ -29,15 +29,16 @@
;; @deprecated[Precontent]{Precontent ... }
;; produces a nested paragraph with a yellow NOTE label to warn readers of deprecated modules
-(define-syntax-rule
- (deprecated replacement-library additional-notes ...)
- ;; ==>
- (nested #:style 'inset
- (para (yellow (bold "NOTE:"))
- " This library is deprecated. Use "
- replacement-library
- " instead. "
- additional-notes ...)))
+(define (deprecated #:what [what "library"]
+ replacement
+ . additional-notes)
+ (apply nested #:style 'inset
+ (yellow (bold "NOTE:"))
+ " This " what
+ " is deprecated; use "
+ replacement
+ ", instead. "
+ additional-notes))
(define (yellow . content)
(make-element (make-style #f (list (make-background-color-property "yellow"))) content))
