summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/censor/censor.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/censor/censor.tex')
-rw-r--r--macros/latex/contrib/censor/censor.tex349
1 files changed, 220 insertions, 129 deletions
diff --git a/macros/latex/contrib/censor/censor.tex b/macros/latex/contrib/censor/censor.tex
index ef64629f13..f16ebc497b 100644
--- a/macros/latex/contrib/censor/censor.tex
+++ b/macros/latex/contrib/censor/censor.tex
@@ -1,5 +1,5 @@
\documentclass{article}
-\usepackage{verbatimbox,xcolor}
+\usepackage{verbatimbox,xcolor,mathtools}
\usepackage{censor}
\parindent 0in
@@ -13,7 +13,7 @@
\small \rule{0in}{1em}Tools for Producing Redacted Documents\\
\large \rule{0in}{2em} Steven B. Segletes\\
SSegletes@verizon.net\\
-\rule{0em}{2em}\today\\
+\rule{0em}{2em}\censorversiondate\\
v\censorversionnumber
\end{center}
@@ -21,8 +21,8 @@ v\censorversionnumber
The \textsf{censor} package allows a convenient redaction/censor
capability to be employed, for those who need to protect restricted
-information, as well as for those who are forced to work in a more
-inefficient environment when dealing with restricted information.
+information, as well as for those who are forced to work in a less
+efficient environment when dealing with restricted information.
Let us assume you have a document for internal use, containing some
restricted (\textit{i.e.}, private, sensitive, proprietary or
@@ -195,10 +195,11 @@ detailed in Table 1.
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
-\verb|\blackout{Block of text}|. This nice thing about this command is
-that it can stretch across line and paragraph boundaries conveniently.
+ capability, for redacting larger blocks of text.
+This new command is \verb|\blackout|, and is used in the form
+ \verb|\blackout{Block of text}|. This nice thing about this command
+ is that it can stretch across line, paragraph, and page boundaries
+ conveniently.
For example,
{\addtolength{\leftskip}{2.3em}
@@ -227,31 +228,50 @@ New paragraph.
}
Prior to V4.0, \verb|\blackout| did not conveniently work across
- environment boundaries, such as math or tabular mode.
-One inconvenient option had been to \verb|\censor| text in the \texttt{tabular},
- cell by cell.
-Alternatively, to blackout the whole tabular environment, you should use
+ environment boundaries, such as math or tabular.
+To blackout the whole tabular environment, one could use
the \verb|\censorbox| command as has been shown.
-Presently, there is a third option---to censor cell-by-cell using a
- shorthand notation.
+Presently, however, there is another option---to censor
+ cell-by-cell using a shorthand notation.
The \verb|\blackout| macro now allows uncensored content to be \textit{escaped}
- from its argument by delimiting it between \verb+|...|+ bars.
-Thus, the censoring directive \verb+\blackout{This |is a| test}+ renders as
- \blackout{This |is a| test}.
-
+ from its argument by delimiting it between \verb+|...|+ bars (note: the
+ closing escape bar must be in the same grouping level).
+Thus, the censoring directive {\ttfamily\detokenize
+ {\blackout{This |is a| test}}}
+ renders as \blackout{This |is a| test}.
+
+This escaping of text becomes essential if one wishes to execute
+ environments within a \verb|\blackout| argument.
+Unless the environment name is escaped, it will break the command,
+ since the environment name itself would be replaced with censoring
+ commands.
+As of v4.2, tokens of catcode 4 (the \verb|&| token) are intercepted
+ and automatically passed through to the output stream, which can
+ be of use in censoring \verb|tabular| expressions.
+Here shows how a partial and full censor could be accomplished, with
+ the use of appropriate text-escaping delimiters, instead of a
+ \verb|\censorbox|:
+
\begingroup
-
\begin{verbatim}
\blackout{
|\begin{tabular}{|c|c|}
\hline
Title 1 & Title 2 \\
\hline
-|a| & |bbb|\\
-|cc| & dd\\
+a & |bbb\\
+cc| & dd\\
\hline
\end{tabular}|
+|\begin{tabular}{|c|c|}|
+\hline
+Title 1 & Title 2 \\
+\hline
+ a & bbb \\
+ cc & dd\\
+\hline
+|\end{tabular}|
}
\end{verbatim}
@@ -260,12 +280,24 @@ Title 1 & Title 2 \\
\hline
Title 1 & Title 2 \\
\hline
-|a| & |bbb|\\
-|cc| & dd\\
+a & |bbb\\
+cc| & dd\\
\hline
\end{tabular}|
+|\begin{tabular}{|c|c|}|
+\hline
+Title 1 & Title 2 \\
+\hline
+ a & bbb \\
+ cc & dd\\
+\hline
+|\end{tabular}|
}
+
\StopCensoring
+
+For comparison, the uncensored tabulars are:
+
\blackout{
|\begin{tabular}{|c|c|}
\hline
@@ -275,6 +307,14 @@ Title 1 & Title 2 \\
|cc| & dd\\
\hline
\end{tabular}|
+|\begin{tabular}{|c|c|}|
+\hline
+Title 1 & Title 2 \\
+\hline
+a&bbb\\
+cc&dd\\
+\hline
+|\end{tabular}|
}
\endgroup
@@ -291,76 +331,6 @@ See section~\ref{S:A} for details on what is possible with respect to
the censoring of macro content with this package.
-The author received some negative feedback concerning the appearance
- resulting from a \verb|\blackout| command. Generally, people did not
- like the fact that spaces were not blacked out.
-To this end, the \verb|\xblackout| command is introduced in V3.10, which
- \textit{cosmetically} blacks out the text more completely
- (note, however, that underneath the more complete blackout are still
- the word-length blackouts that otherwise compose \verb|\blackout|).
-
-As of v4.0 of the package,
- the additional blacking-out of the \verb|\xblackout| macro is controlled
- by one resettable length which laps additional blacking atop the
- result of \verb|\blackout|.
-This length is defined in the macro \verb|\spacelap|, with
- a default value of \spacelap.
-
-During \verb|\xblackout|, a
- right- and left-lapped blacking of dimension \verb|\spacelap| is
- applied before and after each space character, respectively.
-
-The blacking from \verb|\xblackout| is intended to be less ``choppy''
-than that of \verb|\blackout|. However, it too has some drawbacks. The
-x-blacking will extend past the margin(s). It is also
-possible that not all margin extensions will be uniform in size.
-With all these caveats,
-it may still be found preferable to the \verb|\blackout| macro, as
- shown in the example below.
-
-{\addtolength{\leftskip}{2.3em}
-UNCENSORED RESTRICTED SOURCE: \hrulefill
-
-
-\verb|{%|\\
-\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|\\
-\verb|in recent testing here. The tests were into armor steel.}|\\
-\verb| |\\
-\verb|New paragraph} with open text.|
-
-UNCENSORED RESTRICTED OUTPUT: \hrulefill
-
-{%
-The Liberty missile, with charge diameter (CD) of
-80~mm, revealed a penetration capability of 1.30, 1.19, and
-1.37~CD in recent testing here. The tests were into armor steel.
-
-New paragraph} with open text.
-
-CENSORED UNRESTRICTED OUTPUT (\verb|\blackout{}|): \hrulefill
-
-\blackout{%
-The Liberty missile, with charge diameter (CD) of
-80~mm, revealed a penetration capability of 1.30, 1.19, and
-1.37~CD in recent testing here. The tests were into armor steel.
-
-New paragraph} with open text.
-
-CENSORED UNRESTRICTED OUTPUT (\verb|\xblackout{}|): \hrulefill
-
-\xblackout{%
-The Liberty missile, with charge diameter (CD) of
-80~mm, revealed a penetration capability of 1.30, 1.19, and
-1.37~CD in recent testing here. The tests were into armor steel.
-
-New paragraph} with open text.
-
-\hrulefill
-
-}
-
-\clearpage
\section{Mode II: Public/Unsecure Source (.tex file)}
This mode is envisioned for users who must bear a large level of
@@ -430,10 +400,11 @@ optional argument can include commands that you want in force for the
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 may be added after the
-keyword identifiers so as to produce the proper interaction with the
-surrounding whitespace and punctuation.
+ censored and uncensored originals might have differing text
+ justification.
+In the text, empty braces may be added after the
+ keyword identifier macros so as to produce the proper interaction
+ with the subsequent whitespace and punctuation.
Because the source (.tex) file contains no restricted information, the
use of \verb|\StopCensoring| cannot (in and of itself) produce the
@@ -473,7 +444,7 @@ 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:
-\clearpage{\addtolength{\leftskip}{2.3em}
+{\addtolength{\leftskip}{2.3em}
UNCENSORED NO-LONGER-UNRESTRICTED SOURCE: \hrulefill
\verb|\StopCensoring|\\
@@ -541,10 +512,89 @@ remained unaltered. Note also that the censored, unrestricted output
may also be obtained from the no-longer-unrestricted source by removing
the \verb|\StopCensoring| command at the beginning of the file.
-It is not envisioned that the \verb|\blackout| or \verb|\xblackout|
-commands, discussed in the prior section, are used in this mode, where
+It is not envisioned that the \verb|\blackout|
+command, discussed in the prior section, is used in this mode, where
the source file is in an unsecure environment.
+\section{Contiguous Blackout}
+
+The author received some negative feedback concerning the appearance
+ resulting from the \verb|\blackout| command. Generally, people did not
+ like the fact that spaces were not blacked out.
+To this end, the \verb|\xblackout| command is introduced in V3.10, which
+ \textit{cosmetically} blacks out the text more completely
+ (note, however, that underneath the more complete blackout are still
+ the word-length blackouts that otherwise compose \verb|\blackout|).
+
+As of v4.2 of this package,
+ additional blacking-out provided by the \verb|\xblackout| macro
+ does not make use of any tunable parameters, but merely employs
+ the \verb|\fontdimen| parameters already provided by each font.
+% is controlled
+% by one resettable length which laps additional blacking atop the
+% result of \verb|\blackout|.
+%This length is defined in the macro \verb|\spacelap|, with
+% a default value of \spacelap.
+
+%During \verb|\xblackout|, a
+% right- and left-lapped blacking of dimension \verb|\spacelap| is
+% applied before and after each space character, respectively.
+
+The blacking from \verb|\xblackout| is intended to be less ``choppy''
+than that of \verb|\blackout|. However, it too has some drawbacks.
+Importantly, because spaces are now subject to blackout, any
+ space that would otherwise be ignored by \verb|\ignorespaces| or
+ \verb|\ignorespacesafterend| will not be ignored during
+ the \verb|\xblackout|.
+These will include bounding spaces in \verb|tabular| cells as well
+as trailing spaces after the \verb|\end| of environments.
+
+With these caveats,
+it may still be found preferable to the \verb|\blackout| macro, as
+ shown in the example below.
+
+{\addtolength{\leftskip}{2.3em}
+UNCENSORED RESTRICTED SOURCE: \hrulefill
+
+
+\verb|\|\textit{x}\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|\\
+\verb|in recent testing here. The tests were into armor steel.}|\\
+\verb| |\\
+\verb|New paragraph} with open text.|
+
+UNCENSORED RESTRICTED OUTPUT: \hrulefill
+
+{
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in recent testing here. The tests were into armor steel.
+
+New paragraph} with open text.
+
+CENSORED UNRESTRICTED OUTPUT (\verb|\blackout{}|): \hrulefill
+
+\blackout{
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in recent testing here. The tests were into armor steel.
+
+New paragraph} with open text.
+
+CENSORED UNRESTRICTED OUTPUT (\verb|\xblackout{}|): \hrulefill
+
+\xblackout{
+The Liberty missile, with charge diameter (CD) of
+80~mm, revealed a penetration capability of 1.30, 1.19, and
+1.37~CD in recent testing here. The tests were into armor steel.
+
+New paragraph} with open text.
+
+\hrulefill
+
+}
+
\section{Can I Censor Control Sequences?\label{S:A}}
In general, the \textsf{censor} package is designed to operate on
@@ -574,12 +624,11 @@ For macros outside of these special cases, the default behavior is
Consider the following line of \LaTeX{} code:
-\verb|This is \textit{italic text}|\\
+\verb|\blackout{This is \textit{italic text}}|\\
\blackout{|This is \textit{italic text}|\\This is \textit{italic text}}
-It would normally render as in the 2nd line.
-When included as part of the \verb|\blackout| argument, it renders as the
- 3rd line.
+With censoring disabled, it would normally render as in the 2nd line.
+When enabled, it renders as the 3rd line.
The \verb|\textit| is still part of the blackout rendering, but the
\textit{input} to \verb|\textit| has been censored and the
censor rule does not change its presented shape under the influence
@@ -589,9 +638,10 @@ Some macros, however, expand to literal text.
Because macros are, by default, carried literally into the output, they
will only expand into text \textit{after} the censoring has been
applied.
-Consider the following line of \LaTeX{} code:
+Consider the following line of \LaTeX{} code, in which the macro
+ \verb|\today| is not rendered until after censoring is complete:
-\verb|Today's date is \today.|\\
+\verb|\blackout{Today's date is \today.}|\\
\blackout{|Today's date is \today.|\\Today's date is \today.}
If the macro is expandable (and not all are), the \verb|\blackout|
@@ -600,7 +650,7 @@ If the macro is expandable (and not all are), the \verb|\blackout|
Therefore, with one small change to the above example, the problem
can be remedied:
-\verb|Today's date is \expanded{\today}.|\\
+\verb|\blackout{Today's date is \expanded{\today}.}|\\
\blackout{|Today's date is \expanded{\today}.|\\%
Today's date is \expanded{\today}.}
@@ -615,19 +665,53 @@ In either case, however, the output of the unexpandable macro will be
\verb|\ref| and its argument are escaped from the blackout.
%\settcEscapechar{|}
-\verb+In Section |\ref{S:A}|, we discuss censored macros+\\
+\verb+\blackout{In Section |\ref{S:A}|, we discuss censored macros}+\\
\StopCensoring
\blackout{In Section |\ref{S:A}|, we discuss censored macros}\\
\RestartCensoring
\blackout{In Section |\ref{S:A}|, we discuss censored macros}
-
-\section{Censor Marks}
+\section{Can I Censor Math?}
+
+As of v4.2, the package makes an attempt to facilitate the
+ censoring of mathematical expressions, when given as part of the
+ argument to \verb|\blackout| and \verb|\xblackout|.
+Namely, tokens with catcodes 3, 7 and 8 (typically,
+ \verb|$|, \verb|^|, and \verb|_|) are intercepted and passed
+ through to the output stream without censoring
+(Note: the same is true of catcode 4, the \verb|&| token, which can
+ be of use in censoring \verb|tabular| as well as
+ \verb|amsmath| expressions.)
+
+Because macros are, likewise, passed through by default without
+ censoring, this means the expression
+ ``\verb|the equation $\frac{E}{m}=c^{2}$,|'' will be rendered under
+ \verb|\blackout| as \blackout{the equation $\frac{E}{m}=c^{2}$,}.
+There are several points that \textbf{\textit{must}} be noted in
+ a case such as this. First, the arguments to super/sub-scripts
+ must be embraced, even if a single character in length.
+Secondly, censored math scripts will not be reduced to script size, but
+ will be censored using the height and depth of the pre-defined
+ censor rule (this can
+ affect the vertical spacing of lines).
+Finally, customary math spacing associated with operators,
+ punctuation, etc., may be lost, depending on the expression.
+
+As of v4.2, \verb|\blackout| will, by default, automatically
+ detect and censor macros of math-mode Greek letters, such as
+ \verb|\alpha|, \verb|\beta|, etc.
+If one, however, wishes to not waste compilation time searching
+ for such instances, one may disable the feature with the switch
+ \verb|\censormathgreekfalse|.
+
+
+\section{Censor-Rule Marks}
The censor (blacking) mark is a \verb|\rule| which has a depth
-\(-\)0.3ex (\textit{i.e.}, below the baseline), and a height of 2.1ex,
-by default. The characteristics of that rule may be changed by setting
-the following two lengths.
+ \(-\)0.3ex (\textit{i.e.}, below the baseline), and a total height
+ of 2.1ex, by default.
+The characteristics of that rule may be changed by setting
+ the following two lengths.
\itshape
\verb| \censorruledepth=|length\\
@@ -659,8 +743,9 @@ height mult.\tt\}\{\it depth mult.\tt\}\\
\verb| \RestartCensoring|\\
\verb| \censorruledepth=|\it length\\
\verb| \censorruleheight=|length\\
-\verb| \renewcommand\spacelap{|\it length\tt\}\\
+%\verb| \renewcommand\spacelap{|\it length expression\tt\}\\
\verb| \renewcommand\censordot{|\it token or instruction\tt\}\\
+\verb| \censormathgreektrue| \rm(default) or \verb|\censormathgreekfalse|\\
~\\}
The star ({\tt*}) version of the commands is envisioned when the source
document is being created in an unsecure environment, whereas, the
@@ -704,10 +789,6 @@ While the syntax of these macros is unchanged, one has the additional
the documented \textsf{tokcycle}-package commands.
-\item 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\blackout{...}|.
-
\item It is preferable not to apply \verb|\censor| to whitespace, or text
justification could be adversely affected. If one wishes to censor a
multi-word phrase, such as ``Little Bo Peep,'' it is recommended to do
@@ -715,16 +796,25 @@ it as follows:\\
\verb| \xblackout{Little Bo Peep}|\\
If such a phrase is to be used repeatedly through a document,
it is most convenient to place it as a macro:\\
-\verb| \def\Name{\xblackout{Little Bo Peep}}|\\
+\verb| \newcommand\CenName{\xblackout{Little Bo Peep}}|\\
such that subsequent reference is done indirectly:\\
-\verb| We examine the life of \Name{} in this report,|\\
-\verb| assured that \Name{} line breaks.|\\
-\def\Name{\xblackout{Little Bo Peep}}
-\verb| |We examine the life of \Name{} in this report, assured that
- \Name{} line breaks.\\
-(Even so, it should be noted that censoring can still affect text
-justification, because censored words are never hyphenated across line
-boundaries, whereas the original text may have been.)
+\verb| We examine the life of \CenName{} in this report,|\\
+\verb| assured that \CenName{} line breaks.|\\
+\newcommand\CenName{\xblackout{Little Bo Peep}}
+\verb| |We examine the life of \CenName{} in this report, assured that
+ \CenName{} line breaks.
+
+\item Censoring can still affect text justification, because
+ censored words are never hyphenated across line
+ boundaries, whereas the original text may have been.
+For this reason, both \verb|\blackout| and \verb|\xblackout|
+ operate locally in \verb|\sloppy| mode, to minimize instances
+ of overfull \verb|\hbox|es.
+(Note however, that effects of \verb|\sloppy| will take hold only
+ for blacked-out text that closes out a paragraph.)
+If necessary, hyphenation points (\verb|\-|) or
+ \verb|\allowbreak| may be added to words subject to blackout
+ or xblackout, to facilitate manual hyphenation.
\item Users have asked for color support in the package.
I do not wish to hardwire color into the package---however,
@@ -752,10 +842,11 @@ The value of \verb|\censorcolor| can be redefined on the fly to change
\end{itemize}
+\clearpage
\section{Source Code}
-The source code for \textsf{censor} is so short as to be included below:
+The source code for \textsf{censor} is included below:
-\verbatiminput{censor.sty}
+\verbfilenobox[\small]{censor.sty}
\end{document}