From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/censor/README | 25 ++ macros/latex/contrib/censor/censor.pdf | Bin 0 -> 201874 bytes macros/latex/contrib/censor/censor.sty | 154 ++++++++ macros/latex/contrib/censor/censor.tex | 658 +++++++++++++++++++++++++++++++++ 4 files changed, 837 insertions(+) create mode 100644 macros/latex/contrib/censor/README create mode 100644 macros/latex/contrib/censor/censor.pdf create mode 100644 macros/latex/contrib/censor/censor.sty create mode 100644 macros/latex/contrib/censor/censor.tex (limited to 'macros/latex/contrib/censor') 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 Binary files /dev/null and b/macros/latex/contrib/censor/censor.pdf 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} -- cgit v1.2.3