diff options
author | Karl Berry <karl@freefriends.org> | 2022-04-24 20:16:44 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-04-24 20:16:44 +0000 |
commit | 2f8fad51486080e1ffe9c5023c5a933bf70cc2dc (patch) | |
tree | 60c0acc1eb026130a11de4e05970bbf4ab9632d3 /Master/texmf-dist/doc/latex | |
parent | c211aad0638ce9611752d37202ac7f450b76329a (diff) |
censor
git-svn-id: svn://tug.org/texlive/trunk@63126 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r-- | Master/texmf-dist/doc/latex/censor/censor.pdf | bin | 221880 -> 246320 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/censor/censor.tex | 349 |
2 files changed, 220 insertions, 129 deletions
diff --git a/Master/texmf-dist/doc/latex/censor/censor.pdf b/Master/texmf-dist/doc/latex/censor/censor.pdf Binary files differindex 16b5780ed8d..637c75f8209 100644 --- a/Master/texmf-dist/doc/latex/censor/censor.pdf +++ b/Master/texmf-dist/doc/latex/censor/censor.pdf diff --git a/Master/texmf-dist/doc/latex/censor/censor.tex b/Master/texmf-dist/doc/latex/censor/censor.tex index ef64629f13d..f16ebc497bf 100644 --- a/Master/texmf-dist/doc/latex/censor/censor.tex +++ b/Master/texmf-dist/doc/latex/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} |