summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-02-19 23:59:36 +0000
committerKarl Berry <karl@freefriends.org>2013-02-19 23:59:36 +0000
commitdedf8767147c2376fa8eb76db9f363228890a8b4 (patch)
tree53d79622be5f1db2dc1a826269b6c29e92fc04a6 /Master/texmf-dist/doc
parent9759eb626127d860fadc3f37d96158685b176e65 (diff)
censor (19feb13)
git-svn-id: svn://tug.org/texlive/trunk@29170 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/censor/README6
-rw-r--r--Master/texmf-dist/doc/latex/censor/censor.pdfbin139641 -> 176295 bytes
-rw-r--r--Master/texmf-dist/doc/latex/censor/censor.tex312
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
Binary files differ
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}