6.4.1 ⁎Redaction: The censor Package
The censor package [87] provides a way to black out
redacted words or phrases, paragraphs, or boxes (such as included
graphics or a tabular environment). Note that the code
used for redaction affects line-breaking and paragraph
justification, so don't expect the redacted version of the document
to look as well as an unedited version.
Redacted words or phrases are tagged using:
Example:
Following the research group's unsuccessful attempt to create \censor{mind-controlling} \censor{cookies}, they will now be working on a new \censor{ray gun}.
produces:
Note that the argument of \censor is placed in a box so its contents
can't be broken across a line, which is why I split up “mind-controlling”
and “cookies”. In fact, it may even be necessary to do:
A box can be redacted using:
where ⟨box⟩ is the box being redacted and ⟨declarations⟩ are any commands (such as font-changing declarations) that should be applied before the start of the box.
Example:
\begin{table} \caption{A Redacted Table} \label{tab:redacted} \centering \censorbox{% \begin{tabular}{lc} \bfseries Project & \bfseries Success Rate \\ Mind-controlling Cookies & 2\%\\ Telepathic Cakes & 1\%\\ Exploding Chocolates & 25\% \end{tabular}% } \end{table}
A paragraph can be redacted using:
Example:
\blackout{Following the research group's unsuccessful attempt to create mind-controlling cookies, they will now be working on a new ray gun.}
produces:
Note that there are restrictions on the use of \blackout:
⟨text⟩ can't end with “glue”, such as a space or
EOL character; periods aren't redacted; it can't be used
across changes in scope, such as environment boundaries or across
cells within a tabular-like environment. This command also
shows spaces between words (unless the spaces are hidden within
a token), but there is an alternative command that hides these
spaces:
Example:
\xblackout{Following the research group's unsuccessful attempt to create mind-controlling cookies, they will now be working on a new ray gun.}
produces:
This command also suffers from drawbacks. For example, the redaction can cause lines to protrude into the left and right margins. See the censor documentation for further details.
The unredacted version of the document can be created by placing
at the beginning of the document. You can also restart redaction with:
It's possible that you may need to work on your document at an insecure location. In which case, you won't want your sensitive information in your .tex file. The censor package provides:
where ⟨size⟩ is the approximate width (in ex) of the redacted text, and:
where ⟨width⟩ is the approximate width (in ex) of the box,
⟨height⟩ is the approximate height (in multiples of \baselineskip)
and ⟨depth⟩ is the approximate depth (in multiples of
\baselineskip). The optional argument should be used to specify
any commands (such as font changing declarations) that may effect
the size of an ex or the value of \baselineskip. (For example,
\small.) There's no starred version of \blackout or
\xblackout.
Example:
\newcommand*{\OldProject}{\censor*{4}-\censor*{11} \censor*{7}} \newcommand*{\NewProject}{\censor*{3} \censor*{3}} \newcommand*{\SuccessRates}{\censorbox*{40}{4}{0}} Following the research group's unsuccessful attempt to create \OldProject, they will now be working on a new \NewProject. The success rate of previous projects is shown in Table~\ref{tab:success}. \begin{table} \caption{Project Success Rates} \label{tab:success} \centering \SuccessRates \end{table}
If the censoring is on, the redacted text will again be replaced by filled rectangles:
However if censoring is switched off using
\StopCensoring, the redacted text will now be replaced by an underlined
blank space (in the case of \censor*) or an unfilled
rectangle (in the case of \censorbox*):
In your secure environment, you can change the definitions of the macros for the redacted material:
\newcommand*{\OldProject}{% \censor{mind}-\censor{controlling} \censor{cookies}} \newcommand*{\NewProject}{\censor{ray} \censor{gun}} \newcommand*{\SuccessRates}{% \censorbox{% \begin{tabular}{lc} \bfseries Project & \bfseries Success Rate \\ Mind-controlling Cookies & 2\%\\ Telepathic Cakes & 1\%\\ Exploding Chocolates & 25\% \end{tabular}% }% }
There may be minor discrepancies in the formatting caused by approximate measurements.
It's possible you may not want to keep editing the definitions of commands
like the example \OldProject, \NewProject and
\SuccessRates, if you keep transferring your document between
a secure and an insecure location. Instead, it's better to keep the
real definitions of these commands (using the unstarred versions of
\censor and \censorbox) in a separate file, and only
input the file if it exists. Then, when you transfer your document to an
insecure location, make sure you don't also transfer this sensitive file.
Suppose you have a file called definitions.tex that contains:
\newcommand*{\OldProject}{% \censor{mind}-\censor{controlling} \censor{cookies}} \newcommand*{\NewProject}{\censor{ray} \censor{gun}} \newcommand*{\SuccessRates}{% \censorbox{% \begin{tabular}{lc} \bfseries Project & \bfseries Success Rate \\ Mind-controlling Cookies & 2\%\\ Telepathic Cakes & 1\%\\ Exploding Chocolates & 25\% \end{tabular}% } }
This is your secret file that shouldn't leave your secure location. In your main document you can test for a file's existence, and only input it if it exists, using:
This tests if the file named ⟨file⟩ exists (the .tex extension may be omitted). If the file exists, this command does ⟨true part⟩ and then loads ⟨file⟩. If the file doesn't exist, this command just does ⟨false part⟩. So the main document can include this command to determine whether to use the starred or unstarred versions:
\documentclass[captions=tableheading]{scrartcl} \usepackage{censor} \InputIfFileExists{definitions}{}% {\newcommand*{\OldProject}{\censor*{4}-\censor*{11} \censor*{7}} \newcommand*{\NewProject}{\censor*{3} \censor*{3}} \newcommand*{\SuccessRates}{\censorbox*{40}{4}{0}} } \begin{document} Following the research group's unsuccessful attempt to create \OldProject, they will now be working on a new \NewProject. The success rate of previous projects is shown in Table \ref{tab:success}. \begin{table} \caption{Project Success Rates} \label{tab:success} \centering \SuccessRates \end{table} \end{document}
This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).