From 098e9a37ff87c4c25a8d82c21bcc941346e39042 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 8 Nov 2013 06:27:39 -0700 Subject: [PATCH] scribble/manual: generalize `deprecated` original commit: 9dd9ffc2e2d63616a3f1790eff34a2cdafbc15de --- .../scribblings/scribble/manual.scrbl | 18 ++++++++++-------- .../scribble-lib/scribble/HISTORY.txt | 2 ++ .../scribble/private/manual-mod.rkt | 19 ++++++++++--------- 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 index 0c4c8aae..3bece6f6 100644 --- 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 index f432c4a4..a6245105 100644 --- 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 index f9ef9e04..99d654da 100644 --- 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))