summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/censor/censor.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/censor/censor.tex')
-rw-r--r--Master/texmf-dist/doc/latex/censor/censor.tex130
1 files changed, 99 insertions, 31 deletions
diff --git a/Master/texmf-dist/doc/latex/censor/censor.tex b/Master/texmf-dist/doc/latex/censor/censor.tex
index 2c0c5650fe3..76aedae652d 100644
--- a/Master/texmf-dist/doc/latex/censor/censor.tex
+++ b/Master/texmf-dist/doc/latex/censor/censor.tex
@@ -1,21 +1,3 @@
-%% Copyright 2009 Steven B. Segletes
-%
-% This work may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.3
-% of this license or (at your option) any later version.
-% The latest version of this license is in
-% http://www.latex-project.org/lppl.txt
-% and version 1.3 or later is part of all distributions of LaTeX
-% version 2005/12/01 or later.
-%
-% This work has the LPPL maintenance status `maintained'.
-%
-% The Current Maintainer of this work is Steven B. Segletes.
-%
-% This work consists of all files listed in manifest.txt.
-%
-% This notice added 2010/01/04 by Clea F. Rees with the permission of
-% Steven B. Segletes.
\documentclass{article}
\usepackage{censor}
@@ -29,9 +11,9 @@
\LARGE The \textsf{censor} Package\\
\small \rule{0in}{1em}Tools for Producing Redacted Documents\\
\large \rule{0in}{2em} Steven B. Segletes\\
-steven@arl.army.mil\\
-\rule{0em}{2em}2009/12/07\\
-v1.00
+steven.b.segletes.civ@mail.mil\\
+\rule{0em}{2em}2012/09/10\\
+v2.10
\end{center}
\section{Introduction}
@@ -114,7 +96,7 @@ UNCENSORED RESTRICTED SOURCE: \hrulefill
\verb|\StopCensoring|\\
\verb| |\\
\verb|The \censor{Liberty} missile, with charge diameter (CD) of|\\
-\verb|\censor{80}~mm, revealed a penetration capability of 1.30|\\
+\verb|\censor{80}~mm, revealed a penetration capability of 1.30,|\\
\verb|1.19, and 1.37~CD in three recent tests into armor steel.|
UNCENSORED RESTRICTED OUTPUT: \hrulefill
@@ -122,11 +104,83 @@ UNCENSORED RESTRICTED OUTPUT: \hrulefill
\StopCensoring
The \censor{Liberty} missile, with charge diameter (CD) of
-\censor{80}~mm, revealed a penetration capability of 1.30 1.19, and
+\censor{80}~mm, revealed a penetration capability of 1.30, 1.19, and
1.37~CD in three recent tests into armor steel.
\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
+\verb|\blackout{Block of text}|. This nice thing about this command is
+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|\\
+\verb|in three recent tests into armor steel.}|
+
+CENSORED UNRESTRICTED OUTPUT: \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 three recent tests into armor steel.}
+
+\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|
+on your blank lines that would normally constitute paragraph boundaries,
+as shown in the example below:
+
+\verb|\blackout{|\\
+\verb|First paragraph to censor.|\\
+\verb| \bpar|\\
+\verb|Second paragraph to censor.}|\\
+
+\vspace{-0.7em}%
+will appear as
+
+\blackout{
+First paragraph to censor.
+ \bpar
+Second paragraph to censor.}
+
+Secondly, the argument cannot end on so-called ``glue,'' such as a space
+or a carriage return. The following examples are, thus, bad forms of
+the \verb|\blackout| command:
+
+\verb|\blackout{Ends in space. Bad form }|
+
+\verb|\blackout{Ends in carriage return. Bad form|\\
+\verb|}|
+
+Thirdly, periods are not censored (as of version 2.1). This is done
+because it is necessary to preserve the period-space combination that
+signifies end-of-sentence. In this way, {\LaTeX} can preserve spacing
+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.
+
+Finally, the argument to \verb|\blackout| can employ tokens; However,
+the tokens are expanded into one large blackout, regardless of whether
+the expanded token contains spaces. Thus
+
+\verb|\blackout{\today}|
+
+becomes \blackout{\today}, in spite of the fact that \verb|\today|,
+given at the moment by \today, constains spaces.
+
}\RestartCensoring
\clearpage
@@ -236,33 +290,38 @@ 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| command, discussed in the
+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| and \verb|\censor*|
-commands constitute the totality of commands available in the
-\textsf{censor} package.
+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.
It is preferable not to apply \verb|\censor| to whitespace, or text
justification could be adversely affected. If one wished to censor a
multi-word phrase, such as ``Little Bo Peep,'' it is recommended to do
it as follows:\\
-\verb| \censor{Little} \censor{Bo} \censor{Peep}|\\
+\verb| \blackout{Little Bo Peep}|\\
If such a phrase is to be used repeatedly through a document,
it is most convenient to place it as a keyword identifier:\\
-\verb| \def\Name{\censor{Little} \censor{Bo} \censor{Peep}}|\\
+\verb| \def\Name{\blackout{Little Bo Peep}}|\\
such that subsequent reference is done indirectly:\\
-\verb| We examine the life of {\Name} in this report|\\
+\verb| We examine the life of {\Name} in this report|
The source code for \textsf{censor} is so short as to be included below:
\verb|\ProvidesPackage{censor}|\\
-\verb|[2009/12/07 v1.00|\\
+\verb|[2012/09/06 v2.10|\\
\verb| Provides capability for redaction of sensitive information]|\\
\verb||\\
\verb|\usepackage{pbox}|\\
+\verb|\usepackage{ifnextok}|\\
\verb||\\
\verb|\newcommand\censor{\@ifstar{\@cenlen}{\@cenword}}|\\
\verb| \newcommand\@cenlen[1]{\protect\rule[-.3ex]{#1 ex}{2.1ex}}|\\
@@ -275,7 +334,16 @@ The source code for \textsf{censor} is so short as to be included below:
\verb||\\
\verb|\newcommand\StopCensoring{\let\censor\un@censor}|\\
\verb|\newcommand\RestartCensoring{%|\\
-\verb| \renewcommand\censor{\@ifstar{\@cenlen}{\@cenword}}}|\\
+\verb| \renewcommand\censor{\@ifstar{\@cenlen}{\@cenword}}}|\\
+\verb||\\
+\verb|\def\stringend{$}|\\
+\verb|\def\blackout#1{\censor@Block#1\stringend}|\\
+\verb|\def\censor@Block{\IfNextToken\stringend{\@gobble}%|\\
+\verb| {\IfNextToken\@sptoken{ \bl@t{\censor@Block}}%|\\
+\verb| {\bl@t{\censor@Block}}}}|\\
+\verb||\\
+\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|\endinput|\\