add deprecation notice support

Dockerfile

@@ -217,6 +217,7 @@ RUN tlmgr update --self && tlmgr install \
     unicode-math \
     upquote \
     varwidth \
+    wrapfig \
     xcolor \
     xetex \
     xltabular \

filter/style-fenced-divs.lua

@@ -12,21 +12,33 @@ div_classes =
   ["example"] = {
     ["label"] = "Example",
   },
+  ["deprecated"] = {
+    ["label"] = "Deprecation Notice",
+  },
 }
 
 function Div(el)
   local class = el.classes[1]
   if(class) then
-    local class_spec = div_classes[string.lower(class)]
+    class = string.lower(class)
+    local class_spec = div_classes[class]
     if(class_spec) then
       local label = class_spec["label"]
 
       if FORMAT == 'latex' then
-        return{
-          pandoc.RawBlock('latex', string.format('\\BeginInformative{%s}\n', label)),
-          el,
-          pandoc.RawBlock('latex', string.format('\\EndInformative{%s}', label)),
-        }
+        if class == 'deprecated' then
+          return {
+            pandoc.RawBlock('latex', '\\BeginDeprecated\n'),
+            el,
+            pandoc.RawBlock('latex', '\\EndDeprecated'),
+          }
+        else
+          return {
+            pandoc.RawBlock('latex', string.format('\\BeginInformative{%s}\n', label)),
+            el,
+            pandoc.RawBlock('latex', string.format('\\EndInformative{%s}', label)),
+          }
+        end
       end
 
       if FORMAT == 'docx' then

guide.tcg

@@ -531,6 +531,32 @@ This is an "Example" block.
 
 The behavior of blocks with labels not specified above may change meaningfully in future versions of this toolkit, so use them at your own risk.
 
+### Deprecation Notices
+
+Specifications occasionally need to deprecate features or commands. Use the
+"Deprecated" block to create a visually distinctive notice of the deprecation.
+
+Minimal example:
+
+::: Deprecated :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+TDES was deprecated in version 123.
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+Best practices for deprecation:
+
+1. Explain which version of the document introduced the deprecation.
+2. If applicable, explain why the feature was deprecated.
+3. Explain what users should use instead.
+
+Better example:
+
+::: Deprecated :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+TDES was deprecated in version 123. It was withdrawn by NIST at the end of 2023:
+<https://csrc.nist.gov/News/2023/nist-to-withdraw-sp-800-67-rev-2>
+
+Users are encouraged to use AES instead.
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
 # Figures {#sec:figures}
 
 There are two ways to include a figure in a document: as an image file checked into the repository, and as a [Mermaid](http://mermaid.js.org) diagram.

template/tcg.tex

@@ -140,6 +140,7 @@
 $if(logo)$
 \usepackage[export]{adjustbox}
 \usepackage{graphicx}
+\usepackage{wrapfig}
 \usepackage{anyfontsize}
 \usepackage{rotating}
 $endif$
@@ -287,6 +288,12 @@
 \definecolor{informative-header}{RGB}{10, 10, 10}
 \definecolor{informative-foreground}{RGB}{10, 10, 10}
 
+% Colors used for deprecation notices
+% HSL transformation on the informative colors: H = 0', S = 10%
+\definecolor{deprecated-background}{RGB}{224, 202, 202}
+\definecolor{deprecated-header}{RGB}{10, 9, 9}
+\definecolor{deprecated-foreground}{RGB}{10, 9, 9}
+
 \definecolor{table-section-background}{RGB}{224, 224, 224}
 \definecolor{table-section-foreground}{RGB}{10, 10, 10}
 
@@ -324,6 +331,29 @@
   \vskip -7pt%
   \renewcommand{\hlineifmdframed}{}
 }
+\newcommand{\BeginDeprecated}{
+  % HACK: We need to add an extra hline to the ends of tables inside of notes, because
+  % (we don't know why) footers are dropped in tables inside of mdframeds.
+  \renewcommand{\hlineifmdframed}{\hline}
+  % This manual skip is here in case a section begins with a an informative block.
+  \vskip 3pt%
+  \begin{informative}
+  % The size of the triangle is calculated so that it doesn't overflow the box
+  % at its minimum height (one line of text)
+  \begin{wrapfigure}{R}{0.08\textwidth}
+    % Position the triangle a little higher in the box.
+    \vskip -1em%
+    \includegraphics[width=0.07\textwidth]{img/deprecated.pdf}
+  \end{wrapfigure}
+  \textbf{\textit{\textcolor{informative-header}{\small \BeginDemarcated{Deprecation Notice}}}}
+  \color{informative-foreground}
+}
+\newcommand{\EndDeprecated}{
+  \textbf{\textit{\textcolor{informative-header}{\small \EndDemarcated{Deprecation Notice}}}}
+  \end{informative}%
+  \vskip -7pt%
+  \renewcommand{\hlineifmdframed}{}
+}
 
 \usepackage{fontspec}
 \setmainfont{Arial}