summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/censor/censor.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-05-02 21:47:46 +0000
committerKarl Berry <karl@freefriends.org>2013-05-02 21:47:46 +0000
commit6cdb75282c226eb14173774707ff1d26629c47ac (patch)
tree0f342f7e8d6eeec8ce843a1f0442c38cc834477a /Master/texmf-dist/doc/latex/censor/censor.tex
parent3a564ce7121a94acea4334b6f89c6e6fe09442a5 (diff)
censor (2may13)
git-svn-id: svn://tug.org/texlive/trunk@30208 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/censor/censor.tex')
-rw-r--r--Master/texmf-dist/doc/latex/censor/censor.tex213
1 files changed, 116 insertions, 97 deletions
diff --git a/Master/texmf-dist/doc/latex/censor/censor.tex b/Master/texmf-dist/doc/latex/censor/censor.tex
index 3de1cfa7152..09870223b16 100644
--- a/Master/texmf-dist/doc/latex/censor/censor.tex
+++ b/Master/texmf-dist/doc/latex/censor/censor.tex
@@ -1,4 +1,5 @@
\documentclass{article}
+\usepackage{segletes}
\usepackage{censor}
\parindent 0in
@@ -12,8 +13,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}2013/02/19\\
-v3.0
+\rule{0em}{2em}2013/05/02\\
+v3.10
\end{center}
\section{Introduction}
@@ -196,8 +197,8 @@ 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,
+that it can stretch across line and paragraph boundaries conveniently.
+For example,
{\addtolength{\leftskip}{2.3em}
UNCENSORED RESTRICTED SOURCE: \hrulefill
@@ -206,39 +207,25 @@ 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.}|
+\verb|in three recent tests into armor steel.}|\\
+\verb| |\\
+\verb|New paragraph.}|
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.}
+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.
+\bpar
+New paragraph.}
\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
+There is a caveat regarding the use of \verb|\blackout|.
+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:
@@ -247,15 +234,16 @@ the \verb|\blackout| command:
\verb|\blackout{Ends in carriage return. Bad form|\\
\verb|}|
-Thirdly, periods are not censored (as of version 2.1). This is done
+Secondly, 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.
+signifies end-of-sentence. In this way, {\LaTeX} can preserve
+inter-word spacing in the redacted version that is identical to the
+unredacted version.
-Fourthly, \verb|\blackout| does not work across environment boundaries,
+Thirdly, \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 with the
-\verb|\blackout| command (instead should use the \verb|\censorbox|
+\verb|\blackout| command (instead, you should use the \verb|\censorbox|
command for tabular environments).
Finally, the argument to \verb|\blackout| can employ tokens; However,
@@ -265,7 +253,92 @@ 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.
+given at the moment by \today, contains spaces.
+
+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, whether it was a concern
+over security or merely cosmetic. To this end, the \verb|\xblackout|
+command is introduced in V3.10, which blacks out the text more
+completely, while simultaneously preserving the layout indentical to
+that of the uncensored document.
+
+The additional blacking-out of the \verb|\xblackout| macro is controlled
+by five resettable lengths which lap additional blacking atop the
+result of \verb|\blackout|. By default, these lengths are defined as:
+
+\verb|\periodrlap = 1.6ex|\\
+\verb|\afterperiodlap = 1.2ex|\\
+\verb|\lletterlap = 0.55ex|\\
+\verb|\rletterlap = 0.55ex|\\
+\verb|\afterspacelap = 0.0ex|
+
+The length \verb|\periodrlap| is the length of right-lapped blackout
+applied just before printing a period. Thus, this blacking is intended
+to cover the period not treated by \verb|\blackout|. The length
+\verb|\afterperiodlap| is a left-lapped blackout applied just prior to
+word following a period. Its intent is to back-cover the extra-wide
+spacing that follows a period. The length \verb|\lletterlap| is the
+left-lapped blacking applied before a character. It will help cover
+inter-word space if \verb|\afterspacelap| is not employed. The length
+\verb|\rletterlap| is the right-lapped blacking applied after a
+character, which as with \verb|\lletterlap|, can help cover inter-word
+spacing if \verb|\afterspacelap| is not employed. Finally, there is
+\verb|\afterspacelap| which, if employed, is a left-lapped blacking
+applied before the character that follows a space.
+
+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 left and right margins. If a line of
+output ends on a period (as we show in our example below), that line and
+the beginning of the next line may have their blacked-out margins not in
+uniformity with other lines, based on the settings of the various
+lapping lengths employed. If \verb|\periodrlap| is too large, it could
+blackout subsequent text in an unintended way. With all these caveats,
+it may still be found preferable to \verb|\blackout|, 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.
+\bpar
+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.
+\bpar
+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.
+\bpar
+New paragraph} with open text.
+
+\hrulefill
+
+}
\clearpage
\section{Mode II: Public/Unsecure Source (.tex file)}
@@ -448,9 +521,9 @@ 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.
+It is not envisioned that the \verb|\blackout| or \verb|\xblackout|
+commands, discussed in the prior section, are used in this mode, where
+the source file is in an unsecure environment.
\clearpage
\section{Summary \& Miscellany}
@@ -464,7 +537,9 @@ to bring about text redaction, are:\\
\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| \xblackout{|\it extended text passage\tt\}\\
+\verb| \bpar| \rmfamily\upshape(\it retained for backward compatibility
+ only\upshape)\\
\verb| \StopCensoring|\\
\verb| \RestartCensoring|\\
~\\}
@@ -481,9 +556,8 @@ 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.
+The \verb|\bpar| command is no longer needed, as of V3.10. It is now
+made equivalent to \verb|\par|.
Censoring may be dynamically turned off and on in a document with the
use of the \verb|\StopCensoring| and \verb|\RestartCensoring| commands,
@@ -506,61 +580,6 @@ 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|[2013/02/19 v3.00|\\
-\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}}|\\
-\verb| \newcommand\@cenword[1]{%|\\
-\verb| \protect\rule[-.3ex]{\widthofpbox{#1}}{2.1ex}}|\\
-\verb||\\
-\verb|\newcommand\un@censor{\@ifstar{\un@cenlen}{\un@cenword}}|\\
-\verb| \newcommand\un@cenlen[1]{\protect\underline{\hspace{#1 ex}}}|\\
-\verb| \newcommand\un@cenword[1]{#1}|\\
-\verb||\\
-\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\censorbox{\@ifstar{\censor@dim}{\censor@box}}%|\\
-\verb|}|\\
-\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|% 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|\\
+\verbatiminput{censor.sty}
\end{document}