diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/censor/censor.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/censor/censor.tex | 213 |
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} |