censor (19feb13)

git-svn-id: svn://tug.org/texlive/trunk@29170 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 269 insertions, 49 deletions

diff --git a/Master/texmf-dist/doc/latex/censor/README b/Master/texmf-dist/doc/latex/censor/README
index 40fcb839a52..ce4473c1614 100644
--- a/Master/texmf-dist/doc/latex/censor/README
+++ b/Master/texmf-dist/doc/latex/censor/README
@@ -6,9 +6,13 @@ 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.00, the ability to blackout larger blocks of text is available,
+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
 (with a small modification required to your text).
 
 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.
diff --git a/Master/texmf-dist/doc/latex/censor/censor.pdf b/Master/texmf-dist/doc/latex/censor/censor.pdf
index b77e70e3be7..d60002d5207 100644
--- a/Master/texmf-dist/doc/latex/censor/censor.pdf
+++ b/Master/texmf-dist/doc/latex/censor/censor.pdf
diff --git a/Master/texmf-dist/doc/latex/censor/censor.tex b/Master/texmf-dist/doc/latex/censor/censor.tex
index 76aedae652d..3de1cfa7152 100644
--- a/Master/texmf-dist/doc/latex/censor/censor.tex
+++ b/Master/texmf-dist/doc/latex/censor/censor.tex
@@ -12,8 +12,8 @@
 \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}2012/09/10\\
-v2.10
+\rule{0em}{2em}2013/02/19\\
+v3.0
 \end{center}
 
 \section{Introduction}
@@ -109,6 +109,89 @@ The \censor{Liberty} missile, with charge diameter (CD) of
 
 \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 
@@ -116,11 +199,10 @@ is \verb|\blackout|, and is used in the form
 that it can stretch across line boundaries conveniently (and across
 paragraph boundaries, a little less conveniently).  For example,
 
-}\RestartCensoring
-
 {\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|\\
@@ -135,6 +217,8 @@ The Liberty missile, with charge diameter (CD) of
 
 \hrulefill
 
+}
+
 There are several caveats regarding the use of \verb|\blackout|.  First,
 its argument cannot, without help, extend across paragraph boundaries.
 The help needed by \textsf{censor} is to insert the token \verb|\bpar|
@@ -170,7 +254,9 @@ in the redacted version that is identical to the unredacted version.
 
 Fourthly, \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.
+by cell; But you cannot blackout the whole tabular environment with the
+\verb|\blackout| command (instead 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
@@ -181,8 +267,6 @@ the expanded token contains spaces.  Thus
 becomes \blackout{\today}, in spite of the fact that \verb|\today|,
 given at the moment by \today, constains spaces.
 
-}\RestartCensoring
-
 \clearpage
 \section{Mode II: Public/Unsecure Source (.tex file)}
 
@@ -194,8 +278,8 @@ 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*| command becomes accessible.  The way this
-author envisions its use is as follows:
+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
@@ -203,19 +287,36 @@ CENSORED UNRESTRICTED SOURCE: \hrulefill
 \verb|% KEYWORD IDENTIFIERS:|\\
 \verb|\def\Missile{\censor*{7}}|\\
 \verb|\def\Size{\censor*{2}}|\\
-\verb| |\\
+\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 of 1.30 1.19,|\\
-\verb|and 1.37~CD in three recent tests into armor steel.|
+\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 of 1.30 1.19, and 1.37~CD in three recent tests
-into armor steel.
+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
 
@@ -224,61 +325,118 @@ into armor steel.
 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).  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.
+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:\clearpage
+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 of 1.30 1.19, and 1.37~CD in three recent tests
-into armor steel.
+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
 
-}\RestartCensoring
+}
 
 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, changing
-the \verb|\censor*| commands to \verb|\censor| commands, in the process.
-This and the addition of the \verb|\StopCensoring| command to the file
-will produce the uncensored, restricted result:
+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:
 
-{\addtolength{\leftskip}{2.3em}
+\clearpage{\addtolength{\leftskip}{2.3em}
 UNCENSORED NO-LONGER-UNRESTRICTED SOURCE: \hrulefill
 
 \verb|\StopCensoring|\\
-\verb|% KEYWORD IDENTIFIERS:|\\
-\verb|\def\Missile{\censor{Liberty}}}|\\
+\verb|\def\Missile{\censor{Liberty}}|\\
 \verb|\def\Size{\censor{80}}|\\
-\verb| |\\
+\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 of 1.30 1.19,|\\
-\verb|and 1.37~CD in three recent tests into armor steel.|
+\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}}
-
-The {\Missile} missile, with charge diameter (CD) of {\Size}~mm, revealed a
-penetration capability of 1.30 1.19, and 1.37~CD in three recent tests
-into armor steel.
+\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
 
@@ -295,16 +453,48 @@ prior section, is used in this mode, where the source file is in an
 unsecure environment.
 
 \clearpage
-\section{Miscellany}
-
-Censoring may be dynamically turned on and off in a document with the
-use of the \verb|\StopCensoring| and \verb|\RestartCensoring| commands.
-In addition to these two commands, the \verb|\censor|, \verb|\censor*|.
-and \verb|\blackout| commands constitute the totality of commands
-available in the \textsf{censor} package.
+\section{Summary \& Miscellany}
+
+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|   \bpar|\\
+\verb|   \StopCensoring|\\
+\verb|   \RestartCensoring|\\
+~\\}
+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 provided as a
+paragraph separator for use with \verb|\blackout|, for censoring across
+paragraph boundaries. 
+
+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.'  
+
+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 wished to censor a
+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}|\\
@@ -317,7 +507,7 @@ such that subsequent reference is done indirectly:\\
 The source code for \textsf{censor} is so short as to be included below:
 
 \verb|\ProvidesPackage{censor}|\\
-\verb|[2012/09/06 v2.10|\\
+\verb|[2013/02/19 v3.00|\\
 \verb| Provides capability for redaction of sensitive information]|\\
 \verb||\\
 \verb|\usepackage{pbox}|\\
@@ -332,9 +522,14 @@ The source code for \textsf{censor} is so short as to be included below:
 \verb|  \newcommand\un@cenlen[1]{\protect\underline{\hspace{#1 ex}}}|\\
 \verb|  \newcommand\un@cenword[1]{#1}|\\
 \verb||\\
-\verb|\newcommand\StopCensoring{\let\censor\un@censor}|\\
+\verb|\newcommand\StopCensoring{%|\\
+\verb|           \let\censor\un@censor%|\\
+\verb|           \let\censorbox\un@censorbox%|\\
+\verb|}|\\
 \verb|\newcommand\RestartCensoring{%|\\
-\verb| \renewcommand\censor{\@ifstar{\@cenlen}{\@cenword}}}|\\
+\verb|           \renewcommand\censor{\@ifstar{\@cenlen}{\@cenword}}%|\\
+\verb|           \renewcommand\censorbox{\@ifstar{\censor@dim}{\censor@box}}%|\\
+\verb|}|\\
 \verb||\\
 \verb|\def\stringend{$}|\\
 \verb|\def\blackout#1{\censor@Block#1\stringend}|\\
@@ -342,9 +537,30 @@ The source code for \textsf{censor} is so short as to be included below:
 \verb|  {\IfNextToken\@sptoken{ \bl@t{\censor@Block}}%|\\
 \verb|  {\bl@t{\censor@Block}}}}|\\
 \verb||\\
+\verb|% V2.00 DEFINITION:|\\
+\verb|% \def\bl@t#1#2{\censor{#2}#1}|\\
+\verb||\\
+\verb|% V2.10 DEFINITION:|\\
 \verb|\def\bl@t#1#2{\if\bpar#2\par\else\if.#2#2\else\censor{#2}\fi\fi#1}|\\
 \verb|\def\bpar{_}|\\
 \verb||\\
+\verb|% ALTERNATE DEFINITION IF ABOVE PROVES PROBLEMATIC|\\
+\verb|%\def\bl@t#1#2{\if.#2#2\else\censor{#2}\fi#1} % JUST PERIODS, NO \bpar|\\
+\verb||\\
+\verb|\newcommand\censorbox{\@ifstar{\censor@dim}{\censor@box}}|\\
+\verb|  \newcommand\censor@dim[4][]{{#1%|\\
+\verb|                      \rule[-#4\baselineskip]{#2ex}{#3\baselineskip}}}|\\
+\verb|  \newcommand\censor@box[2][]{#1\setbox0\hbox{#2}%|\\
+\verb|                      \rule[-\the\dp0]{\the\wd0}{\the\ht0+\the\dp0}}|\\
+\verb||\\
+\verb|\newcommand\un@censorbox{\@ifstar{\un@censor@dim}{\un@censor@box}}|\\
+\verb|  \newcommand\un@censor@dim[4][]{{#1%|\\
+\verb|                      \fbox{\rule[-#4\baselineskip]{0ex}{#3\baselineskip}|\\
+\verb|                      \rule{#2ex}{0ex}}}}|\\
+\verb|  \newcommand\un@censor@box[2][]{#1#2}|\\
+\verb||\\
+\verb|% NOTE: A \protect\censorbox{} MAY BE REQUIRED INSIDE SOME ENVIRONMENTS|\\
+\verb||\\
 \verb|\endinput|\\
 
 \end{document}