6.4.1 ⁎Redaction: The censor Package

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:

\censor {⟨text⟩}

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:

\censor{mind}-\censor{controlling} \censor{cookies},

A box can be redacted using:

\censorbox [⟨declarations⟩]{⟨box⟩}

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}

This produces Table 6.2.

**Table 6.2:** A Redacted Table

A paragraph can be redacted using:

\blackout {⟨text⟩}

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:

\xblackout {⟨text⟩}

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

\StopCensoring

at the beginning of the document. You can also restart redaction with:

\RestartCensoring

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:

\censor*{⟨size⟩}

where ⟨size⟩ is the approximate width (in ex) of the redacted text, and:

\censorbox*[⟨declarations⟩]{⟨width⟩}{⟨height⟩}{⟨depth⟩}

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:

**Table 6.3:** Project Success Rates

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*):

**Table 6.4:** Project Success Rates

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.

Example 33. Redaction

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:

\InputIfFileExists {⟨file⟩}{⟨true part⟩}{⟨false part⟩}

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}

You can download or view this example.

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).