summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/censor
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/censor
Initial commit
Diffstat (limited to 'macros/latex/contrib/censor')
-rw-r--r--macros/latex/contrib/censor/README25
-rw-r--r--macros/latex/contrib/censor/censor.pdfbin0 -> 201874 bytes
-rw-r--r--macros/latex/contrib/censor/censor.sty154
-rw-r--r--macros/latex/contrib/censor/censor.tex658
4 files changed, 837 insertions, 0 deletions
diff --git a/macros/latex/contrib/censor/README b/macros/latex/contrib/censor/README
new file mode 100644
index 0000000000..e3107c9423
--- /dev/null
+++ b/macros/latex/contrib/censor/README
@@ -0,0 +1,25 @@
+The censor package
+
+This package provides simple tools for creating redacted documents with
+blacked-out text. It's tools are useful both for creating documents in
+a restricted environment (for redacted release in an unrestricted
+environment) as well as in an unrestricted environment (for eventual
+transfer and completion in the restricted environment).
+
+As of V2.0, the ability to blackout larger blocks of text is available,
+up to a whole paragraph simply, and even across paragraph boundaries.
+
+V2.1 tries to minimize formatting discrepancies (i.e., text spacing)
+between the redacted and unredacted versions of the document.
+
+V3.0 introduces the \censorbox command (and its starred counterpart) to
+allow the redaction of more than just text, including figures, tables,
+etc.
+
+V3.1 gives unrestricted use of \par in arguments to \blackout. Also,
+\xblackout introduced to give interword blacking not offered by
+\blackout.
+
+V3.2 allows control over the characteristics (depth and height) of the
+censor blackout rule. It also gives additional control on how to handle
+the censoring of periods.
diff --git a/macros/latex/contrib/censor/censor.pdf b/macros/latex/contrib/censor/censor.pdf
new file mode 100644
index 0000000000..6a85c480dd
--- /dev/null
+++ b/macros/latex/contrib/censor/censor.pdf
Binary files differ
diff --git a/macros/latex/contrib/censor/censor.sty b/macros/latex/contrib/censor/censor.sty
new file mode 100644
index 0000000000..49e1190619
--- /dev/null
+++ b/macros/latex/contrib/censor/censor.sty
@@ -0,0 +1,154 @@
+% censor.sty
+\def\censorversionnumber{3.22}
+\ProvidesPackage{censor}
+[2018/11/15 \censorversionnumber
+ Provides capability for redaction of sensitive information]
+
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% 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.3 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 Steven B. Segletes.
+
+% VERSION:
+% 1.00 - Initial release
+% 2.00 - Added \blackout
+% 2.10 - Allowed \blackout to cross paragraph boundaries with use of
+% \bpar. Stopped censoring periods, in order to preserve
+% end-of-sentence spacing, which differs from inter-word spacing.
+% 3.00 - \censorbox introduced to handle figures, tables, etc.
+% 3.10 - Made \blackout work with \par in argument. Introduced
+% \xblackout
+% 3.20 - Specify depth/height of censor rule. Introduced \def\censordot{}
+% 3.21 - Fixed bug regarding \xblackout rules remaining after a
+% \StopCensoring
+% 3.22 - changed `\if to \ifx in definition of \bl@t, to handle macros like \%
+\usepackage{pbox}
+\usepackage{ifnextok}
+
+\newlength\censorruledepth
+\newlength\censorruleheight
+
+\censorruledepth=-0.3ex% -0.3ex DEFAULT
+\censorruleheight=2.1ex% 2.1ex DEFAULT
+\def\censordot{.}% versus \def\censordot{ }%
+
+\newcommand\censorrule[1]{\protect\rule[\censorruledepth]{#1}{\censorruleheight}}
+
+\newcommand\censor{\@ifstar{\@cenlen}{\@cenword}}
+ \newcommand\@cenlen[1]{\censorrule{#1 ex}}
+ \newcommand\@cenword[1]{\censorrule{\widthofpbox{#1}}}
+
+\newcommand\un@censor{\@ifstar{\un@cenlen}{\un@cenword}}
+ \newcommand\un@cenlen[1]{\protect\underline{\hspace{#1 ex}}}
+ \newcommand\un@cenword[1]{#1}
+
+\newcommand\StopCensoring{%
+ \let\censor\un@censor%
+ \let\censorbox\un@censorbox%
+ \let\xblackout\blackout%
+}
+\newcommand\RestartCensoring{%
+ \renewcommand\censor{\@ifstar{\@cenlen}{\@cenword}}%
+ \renewcommand\censorbox{\@ifstar{\censor@dim}{\censor@box}}%
+ \let\xblackout\sv@xblackout%
+}
+
+\let\sv@tilde~
+
+\def\stringend{$}
+
+\long\def\blackout#1{\def~{-}\censor@Block#1\stringend\let~\sv@tilde}
+\long\def\censor@Block{\IfNextToken\stringend{\@gobble}%
+ {\IfNextToken\@sptoken{ \bl@t{\censor@Block}}%
+ {\bl@t{\censor@Block}}}}
+
+% V2.00 DEFINITION:
+% \def\bl@t#1#2{\censor{#2}#1}
+
+% V2.10 DEFINITION (MADE \long IN V3.1):
+%\long\def\bl@t#1#2{\if\bpar#2\par\else\if.#2\censordot\else\censor{#2}\fi\fi#1}
+
+% V3.22 DEFINITION
+\long\def\bl@t#1#2{\ifx\bpar#2\par\else\if.#2\censordot\else\censor{#2}\fi\fi#1}
+
+%\def\bpar{_} %V3.00 DEFINITION
+\let\bpar\par %AS OF V3.1, CAN HANDLE \par
+
+\long\def\xblackout#1{\rule{0ex}{0ex}%
+ \def~{-}%
+ \def\@justpar{F}%
+ \def\@justperiod{F}%
+ \def\@justspace{F}%
+ \xcensor@Block#1\stringend%
+ \let~\sv@tilde%
+ }
+
+\let\sv@xblackout\xblackout
+
+\long\def\xcensor@Block{\IfNextToken\stringend{\@gobble}%
+ {\IfNextToken\@sptoken{ \def\@justspace{T}\xbl@t{\xcensor@Block}}%
+ {\xbl@t{\xcensor@Block}}}}
+
+\newlength\periodrlap\setlength\periodrlap{1.6ex}
+\newlength\afterperiodlap\setlength\afterperiodlap{1.2ex}
+\newlength\lletterlap\setlength\lletterlap{0.55ex}
+\newlength\rletterlap\setlength\rletterlap{0.55ex}
+\newlength\afterspacelap\setlength\afterspacelap{0.0ex}
+
+\def\@periodrlap{\rlap{\censorrule{\periodrlap}}}
+\def\@afterperiodlap{\llap{\censorrule{\afterperiodlap}}}
+\def\@lletterlap{\llap{\censorrule{\lletterlap}}}
+\def\@rletterlap{\rlap{\censorrule{\rletterlap}}}
+\def\@afterspacelap{\llap{\censorrule{\afterspacelap}}}
+
+\long\def\xbl@t#1#2{%
+ \ifx\par#2%
+ \par\def\@justpar{T}%
+ \else%
+ \if T\@justspace%
+ \rule{0ex}{1ex}\@afterspacelap%
+ \fi%
+ \if.#2%
+ \def\@justperiod{T}%
+ \@periodrlap%
+ \censordot%
+ \else%
+ \if F\@justpar%
+ \if T\@justperiod%
+ \@afterperiodlap%
+ \else%
+ \@lletterlap%
+ \fi%
+ \fi%
+ \censor{#2}%
+ \@rletterlap%
+ \def\@justpar{F}%
+ \def\@justperiod{F}%
+ \def\@justspace{F}%
+ \fi%
+ \fi%
+ #1%
+}
+
+\newcommand\censorbox{\@ifstar{\censor@dim}{\censor@box}}
+ \newcommand\censor@dim[4][]{{#1%
+ \rule[-#4\baselineskip]{#2ex}{#3\baselineskip}}}
+ \newcommand\censor@box[2][]{#1\setbox0\hbox{#2}%
+ \rule[-\the\dp0]{\the\wd0}{\the\ht0+\the\dp0}}
+
+\newcommand\un@censorbox{\@ifstar{\un@censor@dim}{\un@censor@box}}
+ \newcommand\un@censor@dim[4][]{{#1%
+ \fbox{\rule[-#4\baselineskip]{0ex}{#3\baselineskip}
+ \rule{#2ex}{0ex}}}}
+ \newcommand\un@censor@box[2][]{#1#2}
+
+% NOTE: A \protect\censorbox{} MAY BE REQUIRED INSIDE SOME ENVIRONMENTS
+\endinput
diff --git a/macros/latex/contrib/censor/censor.tex b/macros/latex/contrib/censor/censor.tex
new file mode 100644
index 0000000000..1348942afa
--- /dev/null
+++ b/macros/latex/contrib/censor/censor.tex
@@ -0,0 +1,658 @@
+\documentclass{article}
+\usepackage{verbatimbox,xcolor}
+\usepackage{censor}
+
+\parindent 0in
+\parskip 1em
+\makeatletter
+\long\def\bl@t#1#2{\ifx\bpar#2\par\else\ifx.#2\censordot\else\censor{#2}\fi\fi#1}
+\makeatother
+
+\begin{document}
+
+\vspace*{0in}
+\begin{center}
+\LARGE The \textsf{censor} Package\\
+\small \rule{0in}{1em}Tools for Producing Redacted Documents\\
+\large \rule{0in}{2em} Steven B. Segletes\\
+steven.b.segletes.civ@mail.mil\\
+\rule{0em}{2em}\today\\
+v\censorversionnumber
+\end{center}
+
+\section{Introduction}
+
+The \textsf{censor} package allows a convenient redaction/censor
+capability to be employed, for those who need to protect restricted
+information, as well as for those who are forced to work in a more
+inefficient environment when dealing with restricted information.
+
+Let us assume you have a document for internal use, containing some
+restricted (\textit{i.e.}, private, sensitive, proprietary or
+classified) information. To give a very short (fictitious) example:
+
+{\addtolength{\leftskip}{2.3em}
+RESTRICTED SOURCE: \hrulefill
+
+\verb|The Liberty missile, with charge diameter (CD) of 80~mm, |\\
+\verb|revealed a penetration capability of 1.30 1.19, and |\\
+\verb|1.37~CD in three recent tests into armor steel.|
+
+RESTRICTED OUTPUT: \hrulefill
+
+The Liberty missile, with charge diameter (CD) of 80~mm, revealed a
+penetration capability of 1.30 1.19, and 1.37~CD in three recent tests
+into armor steel.
+
+\hrulefill
+
+}
+
+Censor/redaction capabilities are desirable to sanitize the information.
+This would accomplish two things: allow for wider distribution of the
+output and/or allow a less sensitive output to be stored locally with
+fewer storage controls.
+
+There are two modes in which the censor package can be used: (i) when
+the source (.tex file) remains restricted/secure; and (ii) when the source
+(.tex file) is public/unsecure.
+
+\clearpage
+\section{Mode I: Restricted/Secure Source (.tex file)}
+
+In this mode, you create the source in a restricted/secure environment,
+but would like to produce output that can be more widely distributed, or
+stored in a less restricted location. With the addition of
+\verb|\usepackage{censor}| to your document preamble, the \verb|\censor|
+command becomes accessible to block out key identifiers:
+
+{\addtolength{\leftskip}{2.3em}
+CENSORED RESTRICTED SOURCE: \hrulefill
+
+\verb|The \censor{Liberty} missile, with charge diameter (CD) of|\\
+\verb|\censor{80}~mm, revealed a penetration capability of 1.30|\\
+\verb|1.19, and 1.37~CD in three recent tests into armor steel.|
+
+CENSORED NO-LONGER-RESTRICTED OUTPUT: \hrulefill
+
+The \censor{Liberty} missile, with charge diameter (CD) of
+\censor{80}~mm, revealed a penetration capability of 1.30 1.19, and
+1.37~CD in three recent tests into armor steel.
+
+\hrulefill
+
+}
+
+The censored version of the output is (presumably) less sensitive in its
+content, and my be stored in or distributed to a less sensitive
+environment (\textit{e.g.}, as a hardcopy). The censored words are not part
+of the output document (hardcopy or electronic), even though the space
+allocated for the redaction is identical to the original word being
+redacted.
+
+The document may also be printed out in its restricted (uncensored)
+form, merely with the addition of the \verb|\StopCensoring| command at
+the beginning of the document:
+
+{\addtolength{\leftskip}{2.3em}
+UNCENSORED RESTRICTED SOURCE: \hrulefill
+
+\verb|\StopCensoring|\\
+\verb| |\\
+\verb|The \censor{Liberty} missile, with charge diameter (CD) of|\\
+\verb|\censor{80}~mm, revealed a penetration capability of 1.30,|\\
+\verb|1.19, and 1.37~CD in three recent tests into armor steel.|
+
+UNCENSORED RESTRICTED OUTPUT: \hrulefill
+
+\StopCensoring
+
+The \censor{Liberty} missile, with charge diameter (CD) of
+\censor{80}~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in three recent tests into armor steel.
+
+\hrulefill
+
+}
+
+As of version 3.0, the ability to censor ``boxed'' objects like images
+and/or tabular environments is made possible with the \verb|\censorbox|
+command. As an example, one could use the following source:
+
+{\addtolength{\leftskip}{2.3em}
+UNCENSORED RESTRICTED SOURCE: \hrulefill
+
+\verb|The \censor{Liberty} missile, with charge diameter (CD) of|\\
+\verb|\censor{80}~mm, revealed a penetration capability into armor|\\
+\verb|steel, as detailed in Table 1.|\\
+\verb||\\
+\verb|\begin{table}[ht]|\\
+\verb|\begin{center}|\\
+\verb|\textbf{Table 1. \censor{Liberty} Missile Test Data}\\|\\
+\verb|\censorbox{%|\\
+\verb| \small\begin{tabular}{cc}|\\
+\verb| Standoff & Penetration \\|\\
+\verb| (CD) & (CD) \\|\\
+\verb| \hline|\\
+\verb| 5.0 & 1.30 \\|\\
+\verb| 6.0 & 1.19 \\|\\
+\verb| 6.8 & 1.37\\|\\
+\verb| \end{tabular}%|\\
+\verb|}|\\
+\verb|\end{center}|\\
+\verb|\end{table}|\\
+
+\hrulefill
+
+}
+
+in order to turn, what would otherwise be the following restricted
+output into a censored, unrestricted table.
+
+{\addtolength{\leftskip}{2.3em}
+UNCENSORED RESTRICTED OUTPUT: \hrulefill
+
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability into armor steel, as detailed
+in Table 1.
+
+\begin{table}[ht]
+\begin{center}
+\textbf{Table 1. Liberty Missile Test Data}\\
+\small\begin{tabular}{cc}
+Standoff & Penetration \\
+(CD) & (CD) \\
+\hline
+ 5.0 & 1.30 \\
+ 6.0 & 1.19 \\
+ 6.8 & 1.37\\
+\end{tabular}
+\end{center}
+\end{table}
+
+\clearpage CENSORED UNRESTRICTED OUTPUT: \hrulefill
+
+The \censor{Liberty} missile, with charge diameter (CD) of
+\censor{80}~mm, revealed a penetration capability into armor steel, as
+detailed in Table 1.
+
+\begin{table}[ht]
+\begin{center}
+\textbf{Table 1. \censor{Liberty} Missile Test Data}\\
+\censorbox{%
+ \small\begin{tabular}{cc}
+ Standoff & Penetration \\
+ (CD) & (CD) \\
+ \hline
+ 5.0 & 1.30 \\
+ 6.0 & 1.19 \\
+ 6.8 & 1.37\\
+ \end{tabular}%
+}
+\end{center}
+\end{table}
+\par
+\hrulefill
+
+}
+
+Additionally, as of version 2.0, there is provided a block-censor
+capability, for redacting larger blocks of text. This new command
+is \verb|\blackout|, and is used in the form
+\verb|\blackout{Block of text}|. This nice thing about this command is
+that it can stretch across line and paragraph boundaries conveniently.
+For example,
+
+{\addtolength{\leftskip}{2.3em}
+UNCENSORED RESTRICTED SOURCE: \hrulefill
+
+
+\verb|\blackout{|\\
+\verb|The Liberty missile, with charge diameter (CD) of 80~mm,|\\
+\verb|revealed a penetration capability of 1.30, 1.19, and 1.37~CD|\\
+\verb|in three recent tests into armor steel.}|\\
+\verb| |\\
+\verb|New paragraph.}|
+
+CENSORED UNRESTRICTED OUTPUT: \hrulefill
+
+\blackout{%
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in three recent tests into armor steel.
+\bpar
+New paragraph.}
+
+\hrulefill
+
+}
+
+There is a caveat regarding the use of \verb|\blackout|.
+The argument cannot end on so-called ``glue,'' such as a space
+or a carriage return. The following examples are, thus, bad forms of
+the \verb|\blackout| command:
+
+\verb|\blackout{Ends in space. Bad form }|
+
+\verb|\blackout{Ends in carriage return. Bad form|\\
+\verb|}|
+
+Secondly, periods are not censored (as of version 2.1). This is done
+because it is necessary to preserve the period-space combination that
+signifies end-of-sentence. In this way, {\LaTeX} can preserve
+inter-word spacing in the redacted version that is identical to the
+unredacted version.
+
+Thirdly, \verb|\blackout| does not work across environment boundaries,
+such as math or tabular mode. You can blackout text in the table, cell
+by cell; But you cannot blackout the whole tabular environment with the
+\verb|\blackout| command (instead, you should use the \verb|\censorbox|
+command for tabular environments).
+
+Finally, the argument to \verb|\blackout| can employ tokens; However,
+the tokens are expanded into one large blackout, regardless of whether
+the expanded token contains spaces. Thus
+
+\verb|\blackout{\today}|
+
+becomes \blackout{\today}, in spite of the fact that \verb|\today|,
+given at the moment by \today, contains spaces.
+
+The author received some negative feedback concerning the appearance
+resulting from a \verb|\blackout| command. Generally, people did not
+like the fact that spaces were not blacked out, whether it was a concern
+over security or merely cosmetic. To this end, the \verb|\xblackout|
+command is introduced in V3.10, which blacks out the text more
+completely, while simultaneously preserving the layout indentical to
+that of the uncensored document.
+
+The additional blacking-out of the \verb|\xblackout| macro is controlled
+by five resettable lengths which lap additional blacking atop the
+result of \verb|\blackout|. By default, these lengths are defined as:
+
+\verb|\periodrlap = 1.6ex|\\
+\verb|\afterperiodlap = 1.2ex|\\
+\verb|\lletterlap = 0.55ex|\\
+\verb|\rletterlap = 0.55ex|\\
+\verb|\afterspacelap = 0.0ex|
+
+The length \verb|\periodrlap| is the length of right-lapped blackout
+applied just before printing a period. Thus, this blacking is intended
+to cover the period not treated by \verb|\blackout|. The length
+\verb|\afterperiodlap| is a left-lapped blackout applied just prior to
+word following a period. Its intent is to back-cover the extra-wide
+spacing that follows a period. The length \verb|\lletterlap| is the
+left-lapped blacking applied before a character. It will help cover
+inter-word space if \verb|\afterspacelap| is not employed. The length
+\verb|\rletterlap| is the right-lapped blacking applied after a
+character, which as with \verb|\lletterlap|, can help cover inter-word
+spacing if \verb|\afterspacelap| is not employed. Finally, there is
+\verb|\afterspacelap| which, if employed, is a left-lapped blacking
+applied before the character that follows a space.
+
+The blacking from \verb|\xblackout| is intended to be less ``choppy''
+than that of \verb|\blackout|. However, it too has some drawbacks. The
+x-blacking will extend past the left and right margins. If a line of
+output ends on a period (as we show in our example below), that line and
+the beginning of the next line may have their blacked-out margins not in
+uniformity with other lines, based on the settings of the various
+lapping lengths employed. If \verb|\periodrlap| is too large, it could
+blackout subsequent text in an unintended way. With all these caveats,
+it may still be found preferable to \verb|\blackout|, as shown in the
+example below.
+
+{\addtolength{\leftskip}{2.3em}
+UNCENSORED RESTRICTED SOURCE: \hrulefill
+
+
+\verb|{%|\\
+\verb|The Liberty missile, with charge diameter (CD) of 80~mm,|\\
+\verb|revealed a penetration capability of 1.30, 1.19, and 1.37~CD|\\
+\verb|in recent testing here. The tests were into armor steel.}|\\
+\verb| |\\
+\verb|New paragraph} with open text.|
+
+UNCENSORED RESTRICTED OUTPUT: \hrulefill
+
+{%
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in recent testing here. The tests were into armor steel.
+\bpar
+New paragraph} with open text.
+
+CENSORED UNRESTRICTED OUTPUT (\verb|\blackout{}|): \hrulefill
+
+\blackout{%
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in recent testing here. The tests were into armor steel.
+\bpar
+New paragraph} with open text.
+
+CENSORED UNRESTRICTED OUTPUT (\verb|\xblackout{}|): \hrulefill
+
+\xblackout{%
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in recent testing here. The tests were into armor steel.
+\bpar
+New paragraph} with open text.
+
+\hrulefill
+
+}
+
+\clearpage
+\section{Mode II: Public/Unsecure Source (.tex file)}
+
+This mode is envisioned for users who must bear a large level of
+inconvenience to work in a restricted/secure environment (generally
+meaning in a location physically removed from one's desk). Its use is
+envisioned to allow a large percentage of a document to be created in an
+public/unsecure environment, with only the restricted details being
+completed in a restricted/secure environment.
+
+After including the \verb|\usepackage{censor}| command in the document
+preamble, the \verb|\censor*| and \verb|\censorbox*| commands becomes
+accessible. The way this author envisions its use is as follows:
+
+{\addtolength{\leftskip}{2.3em}
+CENSORED UNRESTRICTED SOURCE: \hrulefill
+
+\verb|% KEYWORD IDENTIFIERS:|\\
+\verb|\def\Missile{\censor*{7}}|\\
+\verb|\def\Size{\censor*{2}}|\\
+\verb|\def\TableOne{\censorbox*[\small]{26}{5}{3.5}}|\\
+\verb||\\
+\verb|The {\Missile} missile, with charge diameter (CD) of|\\
+\verb|{\Size}~mm, revealed a penetration capability ranging from|\\
+\verb|1.19--1.37~CD in three recent tests into armor steel, as|\\
+\verb|detailed in Table 1.|\\
+\verb||\\
+\verb|\begin{table}[ht]|\\
+\verb|\begin{center}|\\
+\verb|\textbf{Table 1. {\Missile} Missile Test Data}\\|\\
+\verb|{\TableOne}|\\
+\verb|\end{center}|\\
+\verb|\end{table}|\\
+
+CENSORED UNRESTRICTED OUTPUT: \hrulefill
+
+\def\Missile{\censor*{7}}
+\def\Size{\censor*{2}}
+\def\TableOne{\censorbox*[\small]{26}{5}{3.5}}
+
+The {\Missile} missile, with charge diameter (CD) of {\Size}~mm, revealed a
+penetration capability ranging from 1.19--1.37~CD in three recent tests
+into armor steel, as detailed in Table 1.
+
+\begin{table}[ht]
+\begin{center}
+\textbf{Table 1. {\Missile} Missile Test Data}\\
+{\TableOne}
+\end{center}
+\end{table}
+
+\hrulefill
+
+}
+
+In this way, the source (.tex file) contains no restricted information,
+and may thus be prepared in an unrestricted environment. The argument
+to the \verb|\censor*| command is a number representing the approximate
+width of the redaction (in ex's). In the case of the \verb|\censorbox*|
+command, it has three mandatory arguments and one optional argument
+(note that the unstarred form of the \verb|\censorbox| command has not
+three, but one, mandatory arguments). The mandatory arguments to
+\verb|\censorbox*| are box width (in ex's), box height (in multiples of
+\verb|\baselineskip|) and finally the depth below the baseline where the
+bottom of the box should be (in multiples of \verb|\baselineskip|). The
+optional argument can include commands that you want in force for the
+\verb|\censorbox| command, most typically fontsize commands, which will
+affect the size of the an ex and \verb|\baselineskip|.
+
+Because the redaction width is only approximate, it is possible that the
+censored and uncensored originals might have differing text
+justification. In the text, the curly braces are placed around the
+keyword identifiers so as to produce the proper interaction with the
+surrounding whitespace and punctuation.
+
+Because the source (.tex) file contains no restricted information, the
+use of \verb|\StopCensoring| cannot (in and of itself) produce the
+restricted document. Rather it will produce the following:
+
+{\addtolength{\leftskip}{2.3em}
+UNCENSORED UNRESTRICTED OUTPUT: \hrulefill
+
+\StopCensoring
+
+\def\Missile{\censor*{7}}
+\def\Size{\censor*{2}}
+\def\TableOne{\censorbox*[\small]{26}{5}{3.5}}
+
+The {\Missile} missile, with charge diameter (CD) of {\Size}~mm, revealed a
+penetration capability ranging from 1.19--1.37~CD in three recent tests
+into armor steel, as detailed in Table 1.
+
+\begin{table}[ht]
+\begin{center}
+\textbf{Table 1. {\Missile} Missile Test Data}\\
+{\TableOne}
+\end{center}
+\end{table}
+
+\hrulefill
+
+}
+
+In order to produce the uncensored, restricted output, the unrestricted
+source file must be moved into the restricted/secure environment and be
+subject to a small amount of additional editing. Once in the restricted
+environment, the source (.tex file) may be edited such that the censored
+keyword identifiers are filled in with their restricted values and, in
+the process, changing the \verb|\censor*| and \verb|\censorbox*|
+commands to \verb|\censor| and \verb|\censorbox|, respectively. This
+and the addition of the \verb|\StopCensoring| command to the file will
+produce the uncensored, restricted result:
+
+\clearpage{\addtolength{\leftskip}{2.3em}
+UNCENSORED NO-LONGER-UNRESTRICTED SOURCE: \hrulefill
+
+\verb|\StopCensoring|\\
+\verb|\def\Missile{\censor{Liberty}}|\\
+\verb|\def\Size{\censor{80}}|\\
+\verb|\def\TableOne{\censorbox{%|\\
+\verb| \begin{tabular}{cc}|\\
+\verb| Standoff & Penetration \\|\\
+\verb| (CD) & (CD) \\|\\
+\verb| \hline|\\
+\verb| 5.0 & 1.30 \\|\\
+\verb| 6.0 & 1.19 \\|\\
+\verb| 6.8 & 1.37\\|\\
+\verb| \end{tabular}%|\\
+\verb|}}|\\
+\verb||\\
+\verb|The {\Missile} missile, with charge diameter (CD) of|\\
+\verb|{\Size}~mm, revealed a penetration capability ranging|\\
+\verb|from 1.19--1.37~CD in three recent tests into armor|\\
+\verb|steel, as detailed in Table 1.|\\
+\verb||\\
+\verb|\begin{table}[ht]|\\
+\verb|\begin{center}|\\
+\verb|\textbf{Table 1. {\Missile} Missile Test Data}\\|\\
+\verb|{\TableOne}|\\
+\verb|\end{center}|\\
+\verb|\end{table}|\\
+
+UNCENSORED RESTRICTED OUTPUT: \hrulefill
+
+\StopCensoring
+
+\def\Missile{\censor{Liberty}}
+\def\Size{\censor{80}}
+\def\TableOne{\censorbox{%
+ \begin{tabular}{cc}
+ Standoff & Penetration \\
+ (CD) & (CD) \\
+ \hline
+ 5.0 & 1.30 \\
+ 6.0 & 1.19 \\
+ 6.8 & 1.37\\
+ \end{tabular}%
+}}
+
+The {\Missile} missile, with charge diameter (CD) of
+{\Size}~mm, revealed a penetration capability ranging
+from 1.19--1.37~CD in three recent tests into armor
+steel, as detailed in Table 1.
+
+\begin{table}[ht]
+\begin{center}
+\textbf{Table 1. {\Missile} Missile Test Data}\\
+{\TableOne}
+\end{center}
+\end{table}
+
+\hrulefill
+
+}
+
+The only changes required of the document were at the very beginning,
+among the keyword identifiers. The primary text of the source document
+remained unaltered. Note also that the censored, unrestricted output
+may also be obtained from the no-longer-unrestricted source by removing
+the \verb|\StopCensoring| command at the beginning of the file.
+
+It is not envisioned that the \verb|\blackout| or \verb|\xblackout|
+commands, discussed in the prior section, are used in this mode, where
+the source file is in an unsecure environment.
+
+\section{Censor Marks}
+
+The censor (blacking) mark is a \verb|\rule| which has a depth
+\(-\)0.3ex (\textit{i.e.}, below the baseline), and a height of 2.1ex,
+by default. The characteristics of that rule may be changed by setting
+the following two lengths.
+
+\itshape
+\verb| \censorruledepth=|length\\
+\verb| \censorruleheight=|length
+\upshape
+
+In addition, it was mentioned that periods are not censored, so as to
+preserve the ability of \LaTeX{} to produce censored output of
+\textit{identical} spacing to the uncensored output. If, however, the
+preservation of space is not essential, and the user does not wish to
+have periods appear in the censored output, the definition
+\verb|\censordot|, by default
+
+\verb| \def\censordot{.}|
+
+can be redefined as a blank space, as a null character, or something
+else, at the users' discretion.
+
+\section{Usage Summary}
+
+The complete set of commands available to the \textsf{censor} package,
+to bring about text redaction, are:\\
+{~\\
+\verb| \censor{|\it text\tt\}\\
+\verb| \censor*{|\it width mult.\tt\}\\
+\verb| \censorbox[|\it pre-commands\tt]\{\it object box\tt\}\\
+\verb| \censorbox*[|\it pre-commands\tt]\{\it width mult.\tt\}\{\it
+height mult.\tt\}\{\it depth mult.\tt\}\\
+\verb| \blackout{|\it extended text passage\tt\}\\
+\verb| \xblackout{|\it extended text passage\tt\}\\
+\verb| \bpar| \rmfamily\upshape(\it retained for backward compatibility
+ only\upshape)\\
+\verb| \StopCensoring|\\
+\verb| \RestartCensoring|\\
+\verb| \censorruledepth=|\it length\\
+\verb| \censorruleheight=|length\\
+\verb| \def\censordot{.| \upshape or \it character\tt\}\\
+~\\}
+The star ({\tt*}) version of the commands is envisioned when the source
+document is being created in an unsecure environment, whereas, the
+unstarred version is when the document source may be created in a secure
+environment.
+In the star ({\tt*}) commands, width multipliers are given in ex's,
+whereas height and depth multipliers are given in multiples of
+\verb|\baselineskip|. The depth indicates the distance below the
+baseline where the bottom of a boxed object is to be placed (this
+command has a more direct effect for inline use, whereas use within
+environments is often overridden by the environment). The use of
+pre-commands will typically be fontsize commands, so that measurements
+of ex's and \verb|\baselineskip| are done in a relevant fontsize.
+
+The \verb|\bpar| command is no longer needed, as of V3.10. It is now
+made equivalent to \verb|\par|.
+
+Censoring may be dynamically turned off and on in a document with the
+use of the \verb|\StopCensoring| and \verb|\RestartCensoring| commands,
+respectively. The default is censoring `on.'
+
+\subsection{\textit{Caveat Emptor}}
+
+Here is some added information that users of the package should know.
+
+I have found that, in certain cases (for example, with captions created
+using the \textsf{boxhandler} package), the censorbox command needs to
+be protected by way of \verb|\protect\censorbox{...}|.
+
+It is preferable not to apply \verb|\censor| to whitespace, or text
+justification could be adversely affected. If one wishes to censor a
+multi-word phrase, such as ``Little Bo Peep,'' it is recommended to do
+it as follows:\\
+\verb| \blackout{Little Bo Peep}|\\
+If such a phrase is to be used repeatedly through a document,
+it is most convenient to place it as a keyword identifier:\\
+\verb| \def\Name{\blackout{Little Bo Peep}}|\\
+such that subsequent reference is done indirectly:\\
+\verb| We examine the life of {\Name} in this report|\\
+(Even so, it should be noted that censoring can still affect text
+justification, because censored words are never hyphenated across line
+boundaries, whereas the original text may have been.)
+
+Because the censor algorithm's
+ digest one token at a time, you have to be careful if
+ macros appear in the arguments to a \verb|\censor|,
+ \verb|\blackout|, or \verb|\xblackout|.
+In particular, you have to locate the macro \textit{and its arguments}
+ in a group, for example,
+ \verb|\blackout{In equation {\ref{eq:A}},| \verb|you will see...}|.
+The extra braces around \verb|\ref| and its argument are required
+ so that the censoring algorithm does not try to absorb the macro
+ without also absorbing its argument(s).
+
+Users have asked for color support in the package.
+I do not wish to hardwire color into the package---however,
+ if the \textsf{xcolor} package is loaded,
+ the following preamble definition will force censoring to be
+ in the selected color (in this example, red):
+
+\verb| \def\censorcolor{red}|\\
+\verb| \let\svcensorrule\censorrule|\\
+\verb| \renewcommand\censorrule[1]{%|\\
+\verb| \textcolor{\censorcolor}{\svcensorrule{#1}}}|
+
+Let's see if it works:
+
+{\let\svcensorrule\censorrule
+\renewcommand\censorrule[1]{\textcolor{red}{\svcensorrule{#1}}}
+\addtolength\leftskip{2.3em}
+Is this blacked out text censored in red?\\
+\blackout{Is this blacked out text censored in red?}\par}
+
+This technique can be used at the user's discretion to provide color
+ censoring.
+The value of \verb|\censorcolor| can be redefined on the fly to change
+ the color of the censoring.
+
+\section{Source Code}
+
+The source code for \textsf{censor} is so short as to be included below:
+
+\verbatiminput{censor.sty}
+
+\end{document}