secretx.dtx

% \iffalse meta-comment
%
% Copyright (c) 2019-2021 by Keith F. Prussing <kprussing74@gmail.com>
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3c of this license
% or (at your option) any later version.  The latest version of this
% license is in
%
%     http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Keith F. Prussing.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{\jobname.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[2003/12/01]
%<package>\ProvidesPackage{secretx}
%<package>[2020/09/17 v0.9.1 Classification marking macros]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{hypdoc}
\usepackage{secretx}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\usepackage{listings}
\usepackage[columns=2]{idxlayout}
\usepackage[style=ieee]{biblatex}
\addbibresource{secretx.bib}
\usepackage{cleveref}
\begin{document}
    \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{240}
%
% \CharacterTable
%  {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits     \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v0.5}{2019/04/24}{Initial version}
% \changes{v0.6}{2019/04/27}{Implementation reorganization}
% \changes{v0.7}{2019/04/27}{Correctly roll over marking level}
% \changes{v0.8}{2019/05/03}{Consolidate macros}
% \changes{v0.8.5}{2019/05/11}{Add explicit environments}
% \changes{v0.8.6}{2019/05/11}{Make all new commands robust}
% \changes{v0.9.0}{2020/09/16}{Provide manual heading override}
% \changes{v0.10.0}{2021/03/13}{Move development to trunk branch}
% \GetFileInfo{\jobname.sty}
%
%^^A Package macros
% \DoNotIndex{\begin, \end, \newenvironment, \newrobustcmd, \renewcommand}
% \DoNotIndex{\csdef, \csuse, \ifcsdef, \if, \else, \fi, \everypar}
% \DoNotIndex{\iftoggle, \ifnum, \toggletrue, \togglefalse, \thepage}
% \DoNotIndex{\newcounter, \newtoggle, \setcounter, \stepcounter}
% \DoNotIndex{\PackageError, \RequirePackage, \PackageWarning, \llap}
% \DoNotIndex{\protect, \makebox, \parindent, \PushPostHook, \aftergroup}
% \DoNotIndex{\bgroup, \egroup, \@ifclassloaded, \centering, \kern}
% \DoNotIndex{\hfill, \null, \edef, \vspace, \setlist, \Large, \bfseries}
%^^A Other package macros
% \DoNotIndex{\AtBeginShipout}
% \DoNotIndex{\lhead, \chead, \rhead, \lfoot, \cfoot, \rfoot, \fancyhf}
% \DoNotIndex{\headerrulewidth, \pagestyle, \thispagestyle}
% \DoNotIndex{\zref, \zref@extract, \zlabel, \defbeamertemplate}
% \DoNotIndex{\BODY, \NewEnviron, \userbeamerfont, \setbeamerfont}
% \DoNotIndex{\ifdefempty, \DeclareStringOption, \ProcessKeyvalOptions}
%^^A Package specific to ignore
% \DoNotIndex{\thesecretx@doclevel, \thesecretx@pagelevel, \reset}
% \DoNotIndex{\thesecretx@markcount, \thesecretx@currentlevel, \curcnt}
%^^A Writing to the aux file macros
% \DoNotIndex{\@auxout, \immediate, \\, \AtEndDocument, \write, \string}
% \DoNotIndex{\space}
%
% \title{
%   Classification Marking Macros for \LaTeX{} \thanks{This document
%   corresponds to \textsf{\jobname}~\fileversion, % dated~\filedate.}
% }
%
% \author{Keith F. Prussing \\ \texttt{kprussing74@gmail.com}}
%
% \maketitle
% \tableofcontents
% \thispagestyle{fancy}
%
% \begin{abstract}
% This package provides a set of \LaTeX{} macros for marking paragraphs
% in a document with a leading string and modifying the header and the
% footer of each page.  This is the spiritual successor to
% \textsf{secret.sty} but add the feature of marking the header and the
% footer correctly.
% \end{abstract}
%
% \section{Introduction}
%
% A core component of reporting sensitive information is properly
% marking sections of a document with appropriate labels.
%
% \section{Usage}
% \changes{v0.7.1}{2019/04/28}{Expand usage documentation}
%
% To install the package, simply run the provided |secretx.ins| file
% through your preferred \LaTeX{} engind.  Then, copy the resultant
% |.sty| file to a location where \LaTeX{} can find them.  To generate
% the documentation, run this file (|secretx.dtx|) through \LaTeX{}
% twice.  The second time is only to make sure the references and index
% are typeset correctly.
%
% The better way to build the files is to simply use
% \href{https://scons.org}{\textsf{SCons}} with the provided
% |SConstruct|.
%
% \Cref{app:example} provides an example document and \textsf{beamer}
% presentation showing the usage of the package.  The raw source is also
% provided in the \textsf{doc} directory with this reference.  To see
% the typeset result, simply run the example files through \LaTeX{}.
%
% \subsection{Marking Management}
%
% The basic concept behind marking each page is setting a ``level'' for
% each paragraph.  The highest level paragraph on any given page sets
% the overall level of the page in a standard document.  To apply
% headers and footers to \textsf{beamer} slides, use
% \begin{lstlisting}[gobble=2, basicstyle=\ttfamily\small]
% \usebeamertemplate{headline}{secretx}
% \usebeamertemplate{footline}{secretx}
% \end{lstlisting}
% or simply use |\getheading| in your custom \textsf{headline} and
% \textsf{footline}.  Before use, the user must specify every desired
% marking level along with paragraph and header markings.
%
% \DescribeMacro{\setmarking}
% \DescribeMacro{\setheading}
% To register a paragraph marking, use
% |\setmarking|\marg{level}\marg{marking}.  Likewise, to register a
% heading use |\setheading|\marg{level}\marg{heading}.  These marcos
% register a \marg{marking} or \marg{heading} at the specified
% \marg{level}.  The user is responsible for making sure the marker and
% heading for given level are consistent.  Providing a level more than
% once will simply overwrite the previous definition with no warning.
%
% \DescribeMacro{\addmarking}
% |\addmarking|\marg{level}\marg{marking}\marg{heading} will set the
% marking and heading at the given level.  This is simply a convenience
% wrapper around |\setmarking| and |\setheading|.
%
% \DescribeMacro{\getmarking}
% \DescribeMacro{\getheading}
% \changes{v0.8.4}{2019/05/11}{Use current level as default marking}
% Once a level has been registered, retrieving the marking or heading is
% done with |\getmarking|\oarg{level} or |\getheading|\oarg{level}
% respectively.  The argument defaults to the current paragraph or page
% level.  These macros check that the given \oarg{level} has a defined
% marking and heading.  If not, these will raise an error.  These return
% the expanded string given to |\setmarking| and |\setheading|.
%
% \DescribeMacro{\pagelevel}
% \DescribeMacro{\doclevel}
% These provide access to the current page and document levels.  These
% are read only and are provided to reveal the current state for the
% user instead of having to work with the package internals.
%
% \subsection{Document Marking}
%
% \DescribeMacro{\marking}
% Marking a section is done by specifying the numeric level with which
% to mark using |\marking|\marg{level}.  This macro takes care of
% marking each paragraph with the appropriate marker and updating the
% page and document levels.  The page and document levels are only
% updated if the given marking is higher than the current level.
%
% \DescribeEnv{marking block}
% Collecting large bodies of text into a macro is not ideal.  Instead,
% we would like to use an environment.  To this end, this package
% provides the |marking block| environment.  The syntax is analogous to
% the |\marking| macro in that it takes an \marg{level}.  For example:
% \begin{lstlisting}[gobble=2, basicstyle=\ttfamily\small]
% \begin{marking block}{1}
% \ldots
% \end{marking block}
% \end{lstlisting}
%
% For convenience, we provide definitions to set common levels.
% These are:
%
% \DescribeMacro{\unclassified}
% \DescribeEnv{unclassified block}
% Mark unclassified.
% \begin{itemize}
%   \item Level: 1
%   \item Marking: \getmarking[1]
%   \item Heading: \getheading[1]
% \end{itemize}
%
% \DescribeMacro{\fouo}
% \DescribeEnv{fouo block}
% Mark for official use only.
% \begin{itemize}
%   \item Level: 2
%   \item Marking: \getmarking[2]
%   \item Heading: \getheading[2]
% \end{itemize}
%
% \DescribeMacro{\confidential}
% \DescribeEnv{confidential block}
% Mark confidential.
% \begin{itemize}
%   \item Level: 5
%   \item Marking: \getmarking[5]
%   \item Heading: \getheading[5]
% \end{itemize}
%
% \DescribeMacro{\secret}
% \DescribeEnv{secret block}
% Mark secret.
% \begin{itemize}
%   \item Level: 10
%   \item Marking: \getmarking[10]
%   \item Heading: \getheading[10]
% \end{itemize}
%
% \DescribeMacro{\secretnoforn}
% \DescribeEnv{secretnoforn block}
% Mark secret no foreign.
% \begin{itemize}
%   \item Level: 15
%   \item Marking: \getmarking[15]
%   \item Heading: \getheading[15]
% \end{itemize}
%
% \DescribeMacro{\topsecret}
% \DescribeEnv{topsecret block}
% Mark top secret.
% \begin{itemize}
%   \item Level: 25
%   \item Marking: \getmarking[25]
%   \item Heading: \getheading[25]
% \end{itemize}
%
% \subsection{Specific Marking Notes}
%
% In order to mark a caption or section title, the marking macro must
% enclose the syntactic macro as in |\unclassified{\caption{\ldots}}|.
%
% \subsection{Overriding the Default Page Marking}
%
% \DescribeMacro{heading}
% Although this package attempts to automate away many of the underlying
% details of marking a document, it cannot always succeed.  Since it is
% the final responsibility of the document author to ensure appropriate
% overall markings, the |heading| argument to the package provides
% a manual override to the package determined page marking.  If given,
% the value provided will be typeset in the header and footer of all
% pages.
%
% If possible, we would appreciate any representative examples of usages
% that fail to get marked correctly reported to the
% \href{https://github.com/kprussing/secretx/issues}{issue tracker}.
% However, due to the intended use of this package, we understand if
% this is not practical.
%
% \DescribeMacro{\setlevel}
% \changes{v0.10}{2021/08/17}{Add setlevel command}
% This macro explicilty sets the level of a page without marking a
% particular item.  The focus of this is more for a class like
% \textsf{beamer} where the slide may be composed of solely of images
% that are themselves marked but ar unknown to \LaTeX{}.  This lets the
% user explicitly state the classification of the proper page or scope.
%
% \subsection{Additional Statements}
%
% \DescribeMacro{\distribution}
% A distribution statement is a common need for documentation.  Using
% |\distribution| \marg{level}\marg{reason}\marg{date of
% determination}\marg{controlling DoD office} will place the appropriate
% distribution statement following DoDI 5230.24\cite{dodi_5230.24}.
%
% \DescribeMacro{\exportcontrol}
% This macro places the export control warning in a framed box at the
% current location in accordance with DoDI 5230.24\cite{dodi_5230.24}.
% The default is to typeset the box at 90\% of the |\textwidth|.  Using
% |\exportcontrol|\oarg{width} typesets the control statement in a box
% of the given \oarg{width}.
%
% \StopEventually{
% \printbibliography[]
% \PrintChanges{}
% \PrintIndex{}
% }
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%
% The basic logic is to define markings with increasing levels of
% sensitivity.  We track these along with paired line markings and page
% markings in internal arrays.
%
% \subsection{Required Packages}
%
% For this package, we will need to modify the shipout, work with
% counters, control sequences, complex labels, and we will, obviously,
% need to modify the headers and footers.  We add all of the packages in
% one location to keep things organized.
%
%    \begin{macrocode}
\RequirePackage{atbegshi}
\RequirePackage{etoolbox}
\RequirePackage[excludeor]{everyhook}
\RequirePackage{enumitem}
\RequirePackage{environ}
\@ifclassloaded{beamer}{}{%
    \RequirePackage{fancyhdr}%
}
\RequirePackage{kvoptions}
\RequirePackage{zref-user}
\RequirePackage{zref-abspage}
%    \end{macrocode}
%
% \subsection{Package Options}
%
% \begin{macro}{\secretx@heading}
% This optional key-value pair is used to induce a manual override of
% page-level headings.  All pages will be marked with the indicated
% heading if this option is specified.
%    \begin{macrocode}
\DeclareStringOption{heading}
\ProcessKeyvalOptions*
%    \end{macrocode}
% \end{macro}
%
% \subsection{Package Counters}
%
% Define the package counters and toggle.
%
% \begin{macro}{secretx@pagelevel}
% A counter to store the marking level of the highest current page.
%    \begin{macrocode}
\newcounter{secretx@pagelevel}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{secretx@doclevel}
% A counter to store the highest marking level of the current document.
% We also write out the document marking level to the auxiliary file for
% use on the second pass when creating the cover page.
%    \begin{macrocode}
\newcounter{secretx@doclevel}
\AtEndDocument{%
    \immediate\write\@auxout{%
        \string\setcounter{secretx@doclevel}{\thesecretx@doclevel}%
    }
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{secretx@currentlevel}
% A counter to maintain the marking level of the current scope.
%    \begin{macrocode}
\newcounter{secretx@currentlevel}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{secretx@markcount}
% A counter for the classification environment.
%    \begin{macrocode}
\newcounter{secretx@markcount}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Marking and Heading Management}
%
% These are the user facing macros for establishing the markings and
% headings.  These automate away the tasks of storing the information at
% increasing levels and validating the levels when getting a marking or
% heading from the internal storage.  When setting the marking or
% heading, we simply overwrite any previous value.  It is up to the user
% to ensure the markings and headings are set at consistent levels.  For
% this, we also provide a utility macro for setting both simultaneously.
%
% \begin{macro}{\setmarking}
% Set a marking level by defining the level and a line marking (e.g. (U)
% for unclassified, (S) for secret, etc.).  This will overwrite a
% previously defined marking at the same level.
%    \begin{macrocode}
\newrobustcmd{\setmarking}[2]{\csdef{secretx@marking#1}{#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\getmarking}
% Get a line marking from the marking storage.
%    \begin{macrocode}
\newrobustcmd{\getmarking}[1][\thesecretx@currentlevel]{%
    \ifcsdef{secretx@marking#1}{%
        \csuse{secretx@marking#1}%
    }{%
        \PackageError{secretx}{Undefined marking level}{%
            Marking #1 level was not previously defined.  Is it a typo
            or did you simply forget to define it?%
        }
    }
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\setheading}
% Set the heading level by defining the level and the heading (e.g.
% UNCLASSIFIED, SECRET, etc.).  This will overwrite a previously defined
% marking at the given level.
%    \begin{macrocode}
\newrobustcmd{\setheading}[2]{\csdef{secretx@heading#1}{#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\getheading}
% Get the heading on the page.  Use the current page level unless the
% |heading| option was specified.  If it was, always use it.
%    \begin{macrocode}
\newrobustcmd{\getheading}[1][\thesecretx@pagelevel]{%
    \ifdefempty{\secretx@heading}{%
        \ifcsdef{secretx@heading#1}{%
            \csuse{secretx@heading#1}%
        }{%
            \PackageError{secretx}{Undefined heading level}{%
                Marking #1 level was not previously defined.  Is it a typo
               or did you simply forget to define it?%
            }
        }
    }{%
        \secretx@heading%
    }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\addmarking}
% A helper macro to set a marking's level, section marking, and header
% marking.
%    \begin{macrocode}
\newrobustcmd{\addmarking}[3]{%
    \setmarking{#1}{#2}%
    \setheading{#1}{#3}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pagelevel}
% \begin{macro}{\doclevel}
% User facing macros to get the current page and document marking level.
%    \begin{macrocode}
\newrobustcmd{\pagelevel}[0]{\thesecretx@pagelevel}
\newrobustcmd{\doclevel}[0]{\thesecretx@doclevel}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Low Level Macros}
%
% Some low level macros for managing the marking level state.
%
% \begin{macro}{\secretx@updatelevel}
% A macro to update the page and document levels.  We only update if the
% given level is higher than the current level.  We do this for both the
% page and the document.
%    \begin{macrocode}
\newrobustcmd{\secretx@updatelevel}[1]{%
    \ifnum#1 > \thesecretx@pagelevel%
        \setcounter{secretx@pagelevel}{#1}%
    \fi%
    \ifnum#1 > \thesecretx@doclevel%
        \setcounter{secretx@doclevel}{#1}%
    \fi%
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Marking Utilities}
%
% We provide a macro for marking the document.  These will handle the
% lower level details of getting the line markings and adjusting the
% details to set the headings.  Each one starts by incrementing the
% marking count to track the count of the current environment, creates a
% label, sets the marking for each paragraph, and inserts the content.
% At the end, it sets an ending label.
%
% \begin{macro}{\marking}
% \changes{v0.8.1}{2019/05/10}{Remove nested marking restriction}
% \changes{v0.8.2}{2019/05/10}{Resolve multiply-defined labels}
%
% The workhorse macro to actually set the headings and paragraph
% markings.  We begin by incrementing the current marking count and
% storing it for later use.
%    \begin{macrocode}
\newrobustcmd{\marking}[2]{%
    \stepcounter{secretx@markcount}%
    \edef\curcnt{\thesecretx@markcount}%
%    \end{macrocode}
% Next, in order to correctly reset the level in the case of a nested
% marking, we need to wrap everything up in a group and use
% |\aftergroup|.  But, it appears like we need to wrap the counter
% setting in a macro.
%    \begin{macrocode}
    \edef\reset{%
        \setcounter{secretx@currentlevel}{\thesecretx@currentlevel}%
    }%
    \bgroup%
    \aftergroup\reset%
%    \end{macrocode}
% Now step the environment counter to track the current environment.
%    \begin{macrocode}
    \zlabel{secretx@mark-begin-\curcnt}%
    \secretx@updatelevel{#1}%
    \setcounter{secretx@currentlevel}{#1}%
    #2%
%    \end{macrocode}
% We finish by marking the ending and releasing the lock.
%    \begin{macrocode}
    \egroup%
    \zlabel{secretx@mark-end-\curcnt}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{marking block}
% We also provide an environment for marking large bodies of text with a
% common marking.
%    \begin{macrocode}
\NewEnviron{marking block}[1]{\marking{#1}{\BODY}}
%    \end{macrocode}
% \end{environment}
%
% \subsection{Specific Markings}
%
% Now we define specific markings for the known classification levels.
% For each, we define an environment and a macro.
%
% An empty default marking.
%    \begin{macrocode}
\addmarking{0}{}{}
%    \end{macrocode}
%
% \begin{macro}{\unclassified}
% \begin{environment}{unclassified block}
% Unclassified markings.
%    \begin{macrocode}
\addmarking{1}{(U)}{Unclassified}
\newrobustcmd{\unclassified}[1]{\marking{1}{#1}}
\NewEnviron{unclassified block}{\unclassified{\BODY}}
%    \end{macrocode}
% \end{environment}
% \end{macro}
%
% \begin{macro}{\fouo}
% \begin{environment}{fouo block}
% \changes{v0.9.1}{2019/09/19}{Fix capitalization}
% For official use only markings.
%    \begin{macrocode}
\addmarking{2}{(U//FOUO)}{Unclassified//For Official Use Only}
\newrobustcmd{\fouo}[1]{\marking{2}{#1}}
\NewEnviron{fouo block}{\fouo{\BODY}}
%    \end{macrocode}
% \end{environment}
% \end{macro}
%
% \begin{macro}{\confidential}
% \begin{environment}{confidential block}
% Confidential markings.
%    \begin{macrocode}
\addmarking{5}{(C)}{Confidential}
\newrobustcmd{\confidential}[1]{\marking{5}{#1}}
\NewEnviron{confidential block}{\confidential{\BODY}}
%    \end{macrocode}
% \end{environment}
% \end{macro}
%
% \begin{macro}{\secret}
% \begin{environment}{secret block}
% Secret markings.
%    \begin{macrocode}
\addmarking{10}{(S)}{Secret}
\newrobustcmd{\secret}[1]{\marking{10}{#1}}
\NewEnviron{secret block}{\secret{\BODY}}
%    \end{macrocode}
% \end{environment}
% \end{macro}
%
% \begin{macro}{\secretnoforn}
% \begin{environment}{secretnoforn block}
% Secret no forn markings.
%    \begin{macrocode}
\addmarking{15}{(S//NF)}{Secret//No Forn}
\newrobustcmd{\secretnoforn}[1]{\marking{15}{#1}}
\NewEnviron{secretnoforn block}{\secretnoforn{\BODY}}
%    \end{macrocode}
% \end{environment}
% \end{macro}
%
% \begin{macro}{\topsecret}
% \begin{environment}{topsecret block}
% Top secret markings.
%    \begin{macrocode}
\addmarking{25}{(TS)}{Top Secret}
\newrobustcmd{\topsecret}[1]{\marking{25}{#1}}
\NewEnviron{topsecret block}{\topsecret{\BODY}}
%    \end{macrocode}
% \end{environment}
% \end{macro}
%
% \subsection{Overriding the Default Page Marking}
%
% \begin{macro}{\setlevel}
% This macro provides a user interface to explicitly set the page level.
% It is targeted as \textsf{beamer} frames that are predominantly
% explicitly marked.
%    \begin{macrocode}
\newrobustcmd{\setlevel}[1]{%
    \secretx@updatelevel{#1}%
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Deprecated Macros}
%
% These macros are deprecated and are preserved for temporary backwards
% compatibility.  They will be removed in the future.
%
%    \begin{macrocode}
\newrobustcmd{\UCL}[1]{%
    \PackageWarning{secretx}{Macro deprecated! Use
    \protect\unclassified\space instead}%
    \unclassified{#1}%
}
\newrobustcmd{\CNF}[1]{%
    \PackageWarning{secretx}{Macro deprecated! Use
    \\protect\confidential\space instead}%
    \confidential{#1}%
}
\newrobustcmd{\SEC}[1]{%
    \PackageWarning{secretx}{Macro deprecated! Use
    \\protect\secret\space instead}%
    \secret{#1}%
}
\newrobustcmd{\SNF}[1]{%
    \PackageWarning{secretx}{Macro deprecated! Use
    \\protect\secretnoforn\space instead}%
    \secretnoforn{#1}%
}
\newrobustcmd{\TS}[1]{%
    \PackageWarning{secretx}{Macro deprecated! Use
    \\protect\topsecret\space instead}%
    \topsecret{#1}%
}
%    \end{macrocode}
%
% \subsection{Formatting Details}
%
% Now we move on to specific formatting details.  The header and footer
% are determined by the marking level of the current page, but only for
% article style documents and not beamer slides.  For beamer, we need to
% provide a headline and footline template.  We can use our macros to
% set them once.  We only specify the center header and footer and leave
% the left and right marks up to the user; however, we do clear them and
% put the page number in the right footer.
%
% For \textsf{beamer}, simply use
% \begin{lstlisting}[gobble=2, basicstyle=\ttfamily\small]
% \usebeamertemplate{headline}{secretx}
% \usebeamertemplate{footline}{secretx}
% \end{lstlisting}
% to get a centered marking on the header and footer.  To customize your
% headline and footline, simply add |\getheading| to your template.
% See~\cref{app:beamer} for a simple example.
%
% \changes{v0.8.4}{2019/05/11}{Provide beamer head/footline}
% \changes{v0.8.7}{2019/10/17}{Adjust beamer header/footer to keep size}
%    \begin{macrocode}
\@ifclassloaded{beamer}{%
    \defbeamertemplate*{headline}{secretx}{%
        \begin{beamercolorbox}[ht=5ex]{headline}
            \usebeamerfont{secretx}\hfill\getheading\hfill\null%
        \end{beamercolorbox}
    }
    \defbeamertemplate*{footline}{secretx}{%
        \begin{beamercolorbox}[ht=6ex]{footline}
            \usebeamerfont{secretx}\hfill\getheading\hfill\null\vspace{3pt}%
        \end{beamercolorbox}
    }
    \setbeamerfont{secretx}{size=\Large,%
                            series=\bfseries,%
                            parent=structure}
}{%
    \pagestyle{fancy}
    \fancyhf{}
    \chead{\getheading}
    \cfoot{\getheading}
    \rfoot{\thepage}
}
%    \end{macrocode}
%
% \changes{v0.7.2}{2019/05/03}{Use everyhook to mark paragraphs}
% \changes{v0.8.3}{2019/05/10}{Use PushPostHook for everypar}
% We also suppress the indentation and place the marking in the left
% margin based on the current marking level.
%    \begin{macrocode}
\PushPostHook{par}{%
    \llap{\getmarking{} \kern\parindent}%
}
%    \end{macrocode}
%
% \changes{v0.8.7}{2019/10/17}{Fix the list markings}
% To deal with the lists, we need to inject the marking before the
% bullet or enumeration marking.  For this, we use \textsf{enumitem}.
%    \begin{macrocode}
\setlist{listparindent=\parindent}
%    \end{macrocode}
%
% And now we need to deal with resetting the page levels correctly.
% Each marking has been placed between begin and end labels.  We can
% check the last label when a page ships out to see if the begin is on
% the same page.  If it is not, we need to preserve the page level on
% the next page.  Otherwise, we need to reset the page to empty.
%
%    \begin{macrocode}
\AtBeginShipout{%
    \ifnum\zref@extract{secretx@mark-begin-\thesecretx@markcount}{abspage}
            =\zref@extract{secretx@mark-end-\thesecretx@markcount}{abspage}
        \setcounter{secretx@pagelevel}{0}%
    \else%
        \setcounter{secretx@pagelevel}{\thesecretx@currentlevel}%
    \fi%
}
%    \end{macrocode}
%
% \subsection{Additional Statements}
% \changes{v0.10}{2021/03/14}{Add distribution statements}
%
% \begin{macro}{\distribution}
% Define the wrapper for directing to the proper distribution statement.
%    \begin{macrocode}
\newrobustcmd\distribution[4]{%
    DISTRIBUTION STATEMENT #1.  \csuse{secretx@distro@#1}{#2}{#3}{#4}%
}
%    \end{macrocode}
% The individual statements from Table 5 in \cite{dodi_5230.24}.
%    \begin{macrocode}
\newrobustcmd\secretx@distro@A[3]{%
    Approved for public release: distribution unlimited.
}
\newrobustcmd\secretx@distro@B[3]{%
    Distribution authorized to U.S. Government agencies #1 #2. Other
    requests for this document shall be referred to #3.
}
\newrobustcmd\secretx@distro@C[3]{%
    Distribution authorized to U.S. Government agencies and their
    contractors #1 #2. Other requests for this document shall be
    referred to #3.
}
\newrobustcmd\secretx@distro@D[3]{%
    Distribution authorized to Department of Defense and U.S. DoD
    contractors only #1 #2. Other requests for this document shall be
    referred to #3.
}
\newrobustcmd\secretx@distro@E[3]{%
    Distribution authorized to DoD Components only #1 #2. Other requests
    for this document shall be referred to #3.
}
\newrobustcmd\secretx@distro@F[3]{%
    Further dissemination only as directed by #3 #2 or higher DoD
    authority.
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\exportcontrol}
% \changes{v0.10}{2021/03/14}{Add export control statement}
%
% Typeset the export control statement in a framed box.
%    \begin{macrocode}
\newrobustcmd\exportcontrol[1][0.9\textwidth]{
    \fbox{%
        \begin{minipage}{#1}%
            WARNING - This document contains technical data whose export
            is restricted by the Arms Export Control Act (Title 22,
            U.S.C., Sec 2751, et seq.) or the Export Administration Act
            of 1979 (Title 50, U.S.C., App. 2401 et seq.), as amended.
            Violations of these export laws are subject to severe
            criminal penalties. Disseminate in accordance with
            provisions of DoD Directive 5230.25.
        \end{minipage}%
    }%
}
%    \end{macrocode}
% \end{macro}
%
% \iffalse
%</package>
% \fi
%
% \appendix
%
% \section{\label{app:example} Examples}
%
% This is the code demonstrating the use of \textsf{secretx}.  The
% source is in the \textsf{doc/latex/secretx} directory.  Simply run the
% code through \LaTeX{} to see the typeset examples.
%
% \subsection{\label{app:document} Example Document}
% \changes{v0.8.4}{2019/05/11}{Move example article to appendix}
%
% \begin{lstlisting}[basicstyle=\ttfamily\small]
% \iffalse
%<*document>
% \fi
\documentclass{article}
\usepackage{secretx}
\title{\unclassified{An example document with markings}}
\author{Keith F. Prussing}
\date{\today}

% Show the page and document level in the header.
\lhead{Document --- \doclevel}
\rhead{Page --- \pagelevel}
% Remove the header line.
\renewcommand{\headrulewidth}{0pt}
% Redefine headers and markings to avoid unnecessary alarm.
\addmarking{1}{(1)}{Trivial}
\addmarking{5}{(5)}{Sensitive}
\addmarking{10}{(10)}{Important}
\addmarking{25}{(25)}{Very Important}

\usepackage{mwe}
\usepackage[colorlinks]{hyperref}
\begin{document}
\maketitle
\thispagestyle{fancy}
\tableofcontents
\listoffigures

\begin{abstract}
\unclassified{%
    This is an example document showing the usage of the
    \textsf{secretx} package.  The markings in the following are purely
    for demonstration purpose.  All of the material is
    unclassified.\footnote{\unclassified{%
        This document may have been typeset with the markings adjusted
        to prevent unnecessary alarm.  To see the real markings, simply
        remove the redefinitions as described in
        \href{file://secretx.pdf}{secretx.pdf} and rerun through
        \LaTeX{}.
        }
    }
}
\end{abstract}

\unclassified{\lipsum[1]}\par
\unclassified{\lipsum[2]}\par
\unclassified{\lipsum[3]}\par
\confidential{\lipsum[4]}\par
\unclassified{\lipsum[5]}\par
\unclassified{\lipsum[6]}\par
\topsecret{\lipsum[7]}\par
\secret{\lipsum[8]}\par
\unclassified{\section{A New Section}}
\unclassified{\lipsum[9]\par\secret{\lipsum[9]\par}\lipsum[9]}\par
\unclassified{\lipsum[10]}\par
\unclassified{\lipsum[11]}\par
\unclassified{\lipsum[12]}\par
\unclassified{\lipsum[13]}\par
\unclassified{\lipsum[14]}\par
\unclassified{\lipsum[15]}\par

% Demonstrate marking a figure.
\begin{figure}
    \centering
    \secret{%
        \includegraphics{example-image-16x10}%
    }
    \unclassified{%
        \caption{An example image with a classification.  Notice that
                 the \emph{whole caption is marked}.
        }
    }
\end{figure}

% Use as an environment
\begin{unclassified block}
    \lipsum[16-20]
\end{unclassified block}

\begin{secret block}
    \section{A Section within a Block}
    \lipsum[21]\par
    \unclassified{\lipsum[22]}\par
    \lipsum[23]\par
    \begin{figure}
        \includegraphics{example-image-16x10}
        \unclassified{\caption{A short caption}}
    \end{figure}
\end{secret block}

\begin{itemize}
    \item \unclassified{The first unclassified item}
    \item \confidential{The second item is a higher marking}
    \item \unclassified{The third is back to unclassified}
\end{itemize}

\unclassified{\lipsum[1]\par}

\begin{enumerate}
    \item \confidential{First enumerated item}
    \item \unclassified{A second enumerated item}
    \item \unclassified{And a final enumerated item}
\end{enumerate}
\end{document}
% \iffalse
%</document>
% \fi
% \end{lstlisting}
%
% \subsection{\label{app:beamer} Beamer Slides}
% \changes{v0.8.4}{2019/05/11}{Add beamer example}
%
% \begin{lstlisting}[basicstyle=\ttfamily\small]
% \iffalse
%<*slides>
% \fi
\documentclass{beamer}

\usepackage{secretx}

\begin{document}
\begin{frame}
    \frametitle{\unclassified{An example}}
    \begin{itemize}
        \item \unclassified{An unclassified item}
    \end{itemize}
\end{frame}

\begin{frame}
    \frametitle{\unclassified{A slide with secret information}}
    \begin{itemize}
        \item \secret{A secret item}
    \end{itemize}
\end{frame}
\end{document}
% \iffalse
%</slides>
% \fi
% \end{lstlisting}
%
% \Finale{}
%
% \iffalse
%<*bibliography>
@manual{dodi_5230.24,
    title = {{Distribution} {Statements} on {Technical} {Documents}},
    editor = {Frank Kendall},
    type = {{DoD} {Instruction}},
    number = 5230.24,
    year = 2018,
    month = 10,
    day = 15,
    organization = {{Department} of {Defense}},
    location = {Washington, DC},
    url = {https://www.esd.whs.mil/Portals/54/Documents/DD/issuances/dodi/523024p.pdf},
    urldate = {2021-03-13}
}
%</bibliography>
% \fi
%
\endinput