From c971d20757eaf189bcec52bee69878d1a70ba12d Mon Sep 17 00:00:00 2001
From: Matthias Felleisen <matthias@ccs.neu.edu>
Date: Sat, 28 Apr 2012 13:17:47 -0400
Subject: [PATCH] add a form to declare a module/library deprecated

original commit: 9ef66b80eac46a18fd200cef2f8c084ca7f6a0b7
---
 collects/scribble/private/manual-mod.rkt   | 38 +++++++++++++++++-----
 collects/scribblings/scribble/manual.scrbl |  8 +++++
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/collects/scribble/private/manual-mod.rkt b/collects/scribble/private/manual-mod.rkt
index 265ed54f..43eb6177 100644
--- a/collects/scribble/private/manual-mod.rkt
+++ b/collects/scribble/private/manual-mod.rkt
@@ -15,6 +15,28 @@
          defmodule*/no-declare defmodulelang*/no-declare defmodulereader*/no-declare
          declare-exporting)
 
+;; ---------------------------------------------------------------------------------------------------
+(provide deprecated)
+
+(require (only-in scribble/core make-style make-background-color-property)
+         (only-in scribble/base para nested))
+
+;; @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 (yellow . content)
+  (make-element (make-style #f (list (make-background-color-property "yellow"))) content))
+;; ---------------------------------------------------------------------------------------------------
+
 (define spacer (hspace 1))
 
 (define-syntax defmodule*/no-declare
@@ -62,20 +84,20 @@
 (define-syntax defmodulelang*
   (syntax-rules ()
     [(_ (name ...) #:module-paths (modpath ...)
-                   #:use-sources (pname ...)
-                   . content)
+        #:use-sources (pname ...)
+        . content)
      (begin (declare-exporting modpath ... #:use-sources (pname ...))
             (defmodulelang*/no-declare (name ...)
-                                       #:module-paths (modpath ...)
-                                       . content))]
+              #:module-paths (modpath ...)
+              . content))]
     [(_ (name ...) #:module-paths (modpath ...) . content)
      (defmodulelang* (name ...)
-                     #:module-paths (modpath ...)
-                     #:use-sources () . content)]
+       #:module-paths (modpath ...)
+       #:use-sources () . content)]
     [(_ (name ...) #:use-sources (pname ...) . content)
      (defmodulelang* ((racketmodname name) ...)
-                     #:module-paths (name ...)
-                     #:use-sources (pname ...) . content)]
+       #:module-paths (name ...)
+       #:use-sources (pname ...) . content)]
     [(_ (name ...) . content)
      (defmodulelang* (name ...) #:use-sources () . content)]))
 
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
index 7a99dc35..36933db3 100644
--- a/collects/scribblings/scribble/manual.scrbl
+++ b/collects/scribblings/scribble/manual.scrbl
@@ -660,6 +660,14 @@ 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. 
+}
+
+
 @; ------------------------------------------------------------------------
 @section[#:tag "doc-forms"]{Documenting Forms, Functions, Structure Types, and Values}