scribble/manual: generalize deprecated

original commit: 9dd9ffc2e2d63616a3f1790eff34a2cdafbc15de

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}
 

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

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))