diff --git a/Dockerfile b/Dockerfile index 3f62332..16fcbf7 100644 --- a/Dockerfile +++ b/Dockerfile @@ -217,6 +217,7 @@ RUN tlmgr update --self && tlmgr install \ unicode-math \ upquote \ varwidth \ + wrapfig \ xcolor \ xetex \ xltabular \ diff --git a/filter/style-fenced-divs.lua b/filter/style-fenced-divs.lua index f96ade1..0e3e6e1 100644 --- a/filter/style-fenced-divs.lua +++ b/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 diff --git a/guide.tcg b/guide.tcg index 2f8f046..730669a 100644 --- a/guide.tcg +++ b/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: + + +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. diff --git a/template/tcg.tex b/template/tcg.tex index 6ea5d86..cea2c92 100644 --- a/template/tcg.tex +++ b/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}