diff options
author | Karl Berry <karl@freefriends.org> | 2013-02-19 23:59:36 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-02-19 23:59:36 +0000 |
commit | dedf8767147c2376fa8eb76db9f363228890a8b4 (patch) | |
tree | 53d79622be5f1db2dc1a826269b6c29e92fc04a6 /Master/texmf-dist/doc | |
parent | 9759eb626127d860fadc3f37d96158685b176e65 (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/README | 6 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/censor/censor.pdf | bin | 139641 -> 176295 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/censor/censor.tex | 312 |
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 Binary files differindex 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} |