Debian Codegraph @

texmf-dist/doc/lualatex/luacensor/luacensor-documentation.tex

raw
1 \documentclass{article}
2 \usepackage{xcolor}
3 \usepackage[hidelinks]{hyperref}
4 \usepackage[british]{babel}
5 \usepackage[useregional]{datetime2}
6 \DTMlangsetup[en-GB]{ord=omit}
7 \definecolor{LightGray}{gray}{0.9}
8 \usepackage{mathpazo}
9 \usepackage{luacensor}
10 \usepackage{fontspec}
11 \IfFontExistsTF{Palatine Parliamentary}{\setromanfont[RawFeature={+onum,+pnum}]{Palatine Parliamentary}
12 }{\setromanfont[RawFeature={+onum,+pnum}]{TeX Gyre PagellaX}}
13 \setmonofont[Scale=.9]{Deja Vu Sans Mono}
14 \usepackage{luacode}
15 %\usepackage[firstnumber=last]{fancyvrb}
16 \usepackage{minted}
17 \date{\today\\\smallskip\ttfamily Version \luacensorversionnumber}
18 \author{Elijah Z Granet\thanks{e-mail: \href{mailto:[email protected]}{\ttfamily [email protected]}}}
19
20 \title{\texttt{LuaCensor}:\\A package for redacting sensitive information}
21
22 \begin{document}
23 \maketitle
24 \tableofcontents
25 \section{Very Quick Guide}
26 \subsection{Purpose}
27 This package redacts sensitive information using \texttt{Lua}, and adds accessibility support.
28 \subsection{Usage}
29 The package is called with:
30 \begin{quote}
31 \begin{minted}{latex}
32 \usepackage{luacensor}
33 \end{minted}
34 \end{quote}
35
36 Sensitive information is enclosed within the command:
37 \begin{quote}
38 \begin{minted}{latex}
39 \cnsr{John Smith}
40 \end{minted}
41 \end{quote}
42
43 When the outputted document is intended for authorised readers who are supposed to see sensitive information, no further action is needed. When the outputted document is for general audiences, who are \textit{not} supposed to see sensitive information, add the following line to the preamble:
44 \begin{quote}
45 \begin{minted}{latex}
46 \cnsrtrue
47 \end{minted}
48 \end{quote}
49
50 This activates the censoring globally.
51 \subsection{The \texttt{\color{red}warning} option}
52 For many documents, the presence or absence of redaction in the document will be obvious by black bars in the first page. However, for other documents, particularly long reports or, for example, a court judgment with a title page, it is useful to give an indication. This can be done by calling the package with:
53 \begin{quote}
54 \begin{minted}{latex}
55 \usepackage[warning]{luacensor}
56 \end{minted}
57 \end{quote}
58 This prints automatically prints a warning at the top of the page indicating either that the text is redacted or unredacted. The default `safe' and `danger' warnings, below, are there mostly as a place holder, because it is anticipated that the precise wording of the warning will vary by jurisdiction.\clearpage
59
60 \begin{center}
61 \textit{The default danger warning:}\\
62 \color{red}\tworules\vskip 5pt\allwarning
63 \vskip5pt\tworules%
64 \end{center}%
65
66 \begin{center}
67 \textit{The default safe warning:}\\
68 \begin{center}
69 \color{forestgreen}
70 \tworules\vskip5pt
71 \normalsize\normalfont\sffamily\bfseries\textsafe
72 \vskip5pt\tworules
73 \end{center}
74 \end{center}
75
76 As I noted above, it is unlikely these default options will be suitable for most situations, and for this reason it is easy to change. To alter the text used in the `safe' option, simply use:
77
78 \noindent\begin{minted}{latex}
79
80 \renewcommand{\textsafe}{This is the text in safe mode}
81
82 \end{minted}
83
84 To change the warning heading option for the `danger' text, renew the command \verb+\warnword+ to change the word `warning', renew the command \verb+\dangerblock+ to alter or remove the warning triangles. The other commands for more custom changing of the warning are all in the source code and easily altered for even more custom work.
85
86 \noindent\begin{minted}{latex}
87 \renewcommand{\textwarn}{This is the text in danger mode}
88 \end{minted}
89 To alter the warning triangles,
90
91
92
93
94
95
96 \subsection{Requirements}
97 This package will \textbf{only} work in Lua\LaTeX. The package works out of the box with a standard \TeX\ distribution, but ideally, I would strongly suggest installing the free (\textit{libre} \& \textit{gratis}) `Redacted' font from Google Fonts, which gives a quite æsthetically pleasing black bar effect.\footnote{Available at: \url{https://fonts.google.com/specimen/Redacted}; a versioin is also available at the GitHub repo of this project: \url{https://github.com/ezgranet/luacensor}}
98 \subsection{\color{red}Limitations}
99 The package is completely effective at censoring text formatted with normal \LaTeX\ commands, by which I mean that it is impossible for someone to ascertain the original text (or even its precise length) from the outputted \MakeLowercase{\textsc{PDF}} when the \verb|\cnsrtrue| option has been activated.
100
101 However, math mode is used, it will censor numbers, but not operators or \TeX\ (as opposed to Unicode) operators. This is probably fine for most instances, but unacceptable where security is of the highest priority, and I would not really recommend using this package to censor highly secret formulæ; the \texttt{censor} package in your \TeX\ distribution will do a better job of that. The package is set to completely disappear the output (as opposed to black bar over) of the \texttt{math}, \texttt{align}, \texttt{equation}, \texttt{tabular}, and a few other environments, as disappearing these environments proved more secure than the piecemeal blacking out I saw. It is probable that there are packages and macros that will break the \texttt{cnsr} macro, and therefore, care should be taken to always examine output before public distribution.
102
103 Users should also be aware that many \TeX\ primitives confuse the package, in particular \verb+\vskip+, \verb+\hskip+ \textit{etc} that take arguments outside curly braces cause difficulties; the best solution is simply to either use the \LaTeX\ alternatives (\textit{eg}, \verb+\hspace+) or enclose the primitives in the \verb+\hddn+ command which simply disappears them.
104 \subsection{Demonstration}
105 \begin{quote}
106 \begin{minted}[fontsize=\footnotesize,breaklines]{latex}
107 %In the preamble: \usepackage{luacensor}
108 \begin{quote}
109 \footnotesize \cnsr{Whereas recognition} of the \cnsrtrue\cnsr{inherent dignity and of the equal and inalienable rights of all members of the human family} is the foundation of freedom, justice and peace in the world,
110
111 \cnsr{Whereas disregard and contempt for human rights have resulted in barbarous acts which have outraged the conscience of mankind, and the advent of a world in which human beings shall enjoy freedom of speech and belief and freedom from fear and want has been proclaimed as the highest aspiration of the common people,}
112 \end{quote}
113 \end{minted}
114 \end{quote}
115 \begin{quote}
116 \footnotesize \cnsr{Whereas recognition} of the \cnsrtrue\cnsr{inherent dignity and of the equal and inalienable rights of all members of the human family} is the foundation of freedom, justice and peace in the world,
117
118 \cnsr{Whereas disregard and contempt for human rights have resulted in barbarous acts which have outraged the conscience of mankind, and the advent of a world in which human beings shall enjoy freedom of speech and belief and freedom from fear and want has been proclaimed as the highest aspiration of the common people,}
119 \end{quote} \clearpage
120
121
122
123 \section{More detailed information}
124 \subsection{Purpose}
125 This package is a relatively lightweight and aesthetically pleasing censorship solution which includes accessibility features to allow screen readers to be aware that content has been redacted.
126 \subsection{The censoring mechanism}
127 The package uses Luas's \texttt{toks} filter to replace all \textsc{utf8} characters with a single glyph (• in the case of Redacted, and a Unicode black rectangle in the fallback \TeX\ default font Source Sans Pro). In both font options, these combine visually into a single line (though this can be deconstructed in a text editor).
128
129 However, while changing all characters into a single character is effective in \textit{most} cases, this alone would not be sufficiently secure for reliable usage. This is because knowing the length of a censored name could be combined with other information in, for example, a Family Court judgment, to allow for what lawyers call `jigsaw identification' (\textit{eg}, where there is only one person with an eight letter surname who meets the other details given in the judgment).
130
131 Therefore, the package adds an extra layer of security by randomly changing the length of strings during the censorship phase; censored strings can thus be either longer or shorter by a few characters. This means that while the area of the blacked out content will be \textit{approximately} similar to the length of the uncensored string (which means wireframing more or less works), it cannot be used to reverse engineer information about the censored content.
132
133 \subsection{The accessibility feature}
134 One concern about document redaction is ensuring that visually impaired readers of your document, who use screen reading software to listen to your text, may encounter problems with censored content. If the screen reading software skips over the censored text altogether, it will be a very confusing jump for the visually impaired user. If the screen reading software reads the replacement characters, it will be very annoying for the visually impaired reader to hear, in a censored paragraph, the same character being read out \textit{ad nauseam} (\textit{eg}, `Asterisk, asterisk, asterisk…').
135
136 To overcome this limitation, the package uses the \texttt{accsup} package to add an `actual text' feature which will lead screen readers (and utilities like \texttt{pdftotext}) to replace the string of replacement characters with the two words `TEXT REDACTED'. This also will be encountered by naïve users who try to outdo the package by copying and pasting the black blocks from Adobe™ Acrobat or Reader. (However, because other PDF readers, like Apple's Preview, do not implement accessibility features, this is \textbf{not} an additional security feature and is not on its own sufficient to work for redaction; if it were otherwise, the rest of the package would be unnecessary)
137
138
139
140 \subsection{Bugs and development}
141 All bugs, feature requests, or other technical points should be submitted to the package's official Github page.\footnote{\url{https://github.com/ezgranet/luacensor}}
142
143 \subsection{Licensing}
144 The software is free and open-sour ce software licensed under the Latex Public Project Licence, version 1.3\textit{c}.\footnote{\url{https://www.latex-project.org/lppl/}}
145
146
147 \subsection{Some useful advice}
148 This package is really good at some things, but if you find it breaks down on censoring complex \LaTeX\ code, the existing \texttt{censor} package on \textsc{ctan} is excellent (albeit less good with accessibility), and works with non-\texttt{Lua} versions of \TeX. Incidentally, you can use both this package and \texttt{censor} in the same file without trouble; this (\textit{not} a penchant for annoying tech-speak) is why the main command in this package is \texttt{cnsr} without vowels.
149
150 \clearpage
151 \section{Implementation}
152 \begin{minted}[
153 frame=lines,
154 framesep=2mm,
155 baselinestretch=1.2,
156 bgcolor=LightGray,
157 fontsize=\footnotesize,
158 linenos,
159 breaklines,
160 firstnumber=last
161 ]
162 {latex}
163 %luacensor.sty
164 \def\luacensorversionnumber{1.1.1}
165 \ProvidesPackage{luacensor}
166 [2024/04/06 \luacensorversionnumber\
167 Redact sensitive information using Lua]
168 % !TeX program = lualatex
169 % !TeX encoding = utf8
170 % This work may be distributed and/or modified under the
171 % conditions of the LaTeX Project Public License, either version 1.3
172 % of this license or (at your option) any later version.
173 % The latest version of this license is in
174 % http://www.latex-project.org/lppl.txt
175 % and version 1.3 or later is part of all distributions of LaTeX
176 % version 2005/12/01 or later.
177 %
178 % This work has the LPPL maintenance status `maintained'.
179 %
180 % The Current Maintainer of this work is Elijah Z Granet
181 %%%%%%%%%%%%%%%%%%%%%%%%%%%
182 %%%%%%%%%%%%%%%%%%%%%%%%%%%
183 % option (we'll come back
184 % to this later
185 %%%%%%%%%%%%%%%%%%%%%%%%%%%
186 %%%%%%%%%%%%%%%%%%%%%%%%%%%
187 \newif\ifwarning
188 \warningfalse
189 \DeclareOption{warning}{\warningtrue}
190 \ProcessOptions*
191 \end{minted}
192 \subsection{Dependencies}
193 \begin{minted}[
194 frame=lines,
195 framesep=2mm,
196 baselinestretch=1.2,
197 bgcolor=LightGray,
198 fontsize=\footnotesize,
199 linenos,
200 breaklines,
201 firstnumber=last
202 ]
203 {latex}
204 %%%%%%%%%%%%%%%%%%%%%%%%%%%
205 %%%%%%%%%%%%%%%%%%%%%%%%%%%
206 % DEPENDENCIES
207 %%%%%%%%%%%%%%%%%%%%%%%%%%%
208 %%%%%%%%%%%%%%%%%%%%%%%%%%%
209 \RequirePackage{luacode}
210 \RequirePackage{environ}% http://ctan.org/pkg/environ
211
212 \RequirePackage{verbatim}
213 % ^ for the censoring
214 \RequirePackage{accsupp}
215 %^for accessibility
216 \RequirePackage{fontspec}
217 %^for black lines
218 %in theory, you could do
219 %a lighter version of this
220 %package with just asterisks
221 %or `[TEXT-REDACTED]'
222 %And perhaps that would be better for
223 %the environment with printing
224 %BUT I MADE MY CHOICE!
225 \RequirePackage{xcolor}
226 \RequirePackage{graphicx}
227 \end{minted}
228 \subsection{fonts}
229 \begin{minted}[
230 frame=lines,
231 framesep=2mm,
232 baselinestretch=1.2,
233 bgcolor=LightGray,
234 fontsize=\footnotesize,
235 linenos,
236 breaklines,
237 firstnumber=last
238 ]
239 {latex}
240 %%%%%%%%%%%%%%%%%%%%%%%%%%%
241 %%%%%%%%%%%%%%%%%%%%%%%%%%%
242 % FONTS
243 %%%%%%%%%%%%%%%%%%%%%%%%%%%
244 %%%%%%%%%%%%%%%%%%%%%%%%%%%
245 %%%%%%%%%%%%%%%%%%%%%%%%%%%
246 %%%%%%%%%%%%%%%%%%%%%%%%%%%
247 % redacted is prettier and free to download
248 %%%%%%%%%%%%%%%%%%%%%%%%%%%
249 %%%%%%%%%%%%%%%%%%%%%%%%%%%
250 % Strongly recommended
251 %%%%%%%%%%%%%%%%%%%%%%%%%%%
252 %%%%%%%%%%%%%%%%%%%%%%%%%%%
253 %%%%%%%%%%%%%%%%%%%%%%%%%%%
254 %%%%%%%%%%%%%%%%%%%%%%%%%%%
255 \IfFontExistsTF{Redacted}{%
256 \newfontface\cnsrfnt[%%%%%%
257 %the scale is arbitrary, but kind of works
258 %Scale=1.1,
259 %%the below declarations are to prevent warnings about shapes not being available
260 %WordSpace=0,
261 ItalicFont={Redacted},%
262 BoldItalicFont={Redacted},%
263 BoldFont={Redacted},%
264 SmallCapsFont={Redacted}]{Redacted}
265 \newcommand{\onething}{\cnsrfnt\ • }
266 \newcommand{\twothings}{\cnsrfnt\ • •}
267 \newcommand{\donothing}{\cnsrfnt\ }
268 %%%%%%%%%%%%%%%%%%%%%%%%%%%
269 %%%%%%%%%%%%%%%%%%%%%%%%%%%
270 %The little spaces let justification happen
271 %%%%%%%%%%%%%%%%%%%%%%%%%%%
272 %%%%%%%%%%%%%%%%%%%%%%%%%%%
273 %%%%%%%%%%%%%%%%%%%%%%%%%%%
274 %%%%%%%%%%%%%%%%%%%%%%%%%%%
275 % • chosen as an arbitrary average width
276 %%%%%%%%%%%%%%%%%%%%%%%%%%%
277 %%%%%%%%%%%%%%%%%%%%%%%%%%%
278 }{
279 %%%%%%%%%%%%%%%%%%%%%%%%%%%
280 %%%%%%%%%%%%%%%%%%%%%%%%%%%
281 % This option works perfectly
282 %fine, it's just less pretty
283 %%but a good fallback because
284 % Source Sans is in TeX dists by default
285 %%%%%%%%%%%%%%%%%%%%%%%%%%%
286 %%%%%%%%%%%%%%%%%%%%%%%%%%%
287 \newfontface\cnsrfnt[Scale=1.01,%To allow for separate use of source sans in text
288 WordSpace=0,%To make it all one black line
289 %the below declarations are to prevent warnings about shapes not being available
290 ItalicFont={Source Sans Pro Black},BoldItalicFont={Source Sans Pro Black},BoldFont={Source Sans Pro Black},SmallCapsFont={Source Sans Pro Black}]{Source Sans Pro Black}
291 %%%%%%%%%%%%%%%%%%%%%%%%%%%
292 %%%%%%%%%%%%%%%%%%%%%%%%%%%
293 % Bit of unicode magic below to make the black line effect
294 %%%%%%%%%%%%%%%%%%%%%%%%%%%
295 %%%%%%%%%%%%%%%%%%%%%%%%%%%
296 \newcommand{\onething}{\cnsrfnt ▬ }
297 \newcommand{\twothings}{\cnsrfnt ▬ ▬ }
298 \newcommand{\donothing}{ }
299 }
300 \end{minted}
301 \subsection{Removing pesky environments}
302 \begin{minted}[
303 frame=lines,
304 framesep=2mm,
305 baselinestretch=1.2,
306 bgcolor=LightGray,
307 fontsize=\footnotesize,
308 linenos,
309 breaklines,
310 firstnumber=last
311 ]
312 {latex}
313 %%%%%%%%%%%%%%%%%%%%%%%%%%%
314 %%%%%%%%%%%%%%%%%%%%%%%%%%%
315 % A neat fallback for disappearing things…
316 %%%%%%%%%%%%%%%%%%%%%%%%%%%
317 %%%%%%%%%%%%%%%%%%%%%%%%%%%
318 %%%%%%%%%%%%%%%%%%%%%%%%%%%
319 %%%%%%%%%%%%%%%%%%%%%%%%%%%
320 % FULL CREDIT
321 % and FULSOME THANKS
322 % TO TEX.SE USER
323 % Werner for the code below
324 %%%%%%%%%%%%%%%%%%%%%%%%%%%
325 %%%%%%%%%%%%%%%%%%%%%%%%%%%
326 \makeatletter
327 \newcommand{\voidenvironment}[1]{%
328 \expandafter\providecommand\csname env@#1@save@env\endcsname{}%
329 \expandafter\providecommand\csname env@#1@process\endcsname{}%
330 \@ifundefined{#1}{}{\RenewEnviron{#1}{}}%
331 }
332 \makeatother
333 \newcommand{\hddn}[1]{%
334 \ifcnsr{}\else%
335 #1\fi}
336 \newenvironment*{hidden}{\begin{@empty}
337 }{\end{@empty}}
338 \voidenvironment{hidden}
339
340 %%%%%%%%%%%%%%%%%%%%%%%%%%%
341 %%%%%%%%%%%%%%%%%%%%%%%%%%%
342 \end{minted}
343 \subsection{The `\texttt{cnsr}' command}
344 \begin{minted}[
345 frame=lines,
346 framesep=2mm,
347 baselinestretch=1.2,
348 bgcolor=LightGray,
349 fontsize=\footnotesize,
350 linenos,
351 breaklines,
352 firstnumber=last
353 ]
354 {latex}
355 %%%%%%%%%%%%%%%%%%%%%%%%%%%
356 %%%%%%%%%%%%%%%%%%%%%%%%%%%
357 %%%%%%%%%%%%%%%%%%%%%%%%%%%
358 %%%%%%%%%%%%%%%%%%%%%%%%%%%
359 % the CENSOR COMMAND
360 %%%%%%%%%%%%%%%%%%%%%%%%%%%
361
362 \newif\ifcnsr\cnsrfalse
363 \newcommand{\cnsr}[1]{%
364 \ifcnsr{%
365 \voidenvironment{equation*}%
366 \voidenvironment{equation}%
367 \voidenvironment{table}%
368 \voidenvironment{table*}%
369 \voidenvironment{tabular}%
370 \voidenvironment{tabular*}%
371 \voidenvironment{}%
372 %%%%%%%%%%%%%%%%%%%%%%%%%%%
373 % I don't know how many
374 % people use TEX native accent commands
375 % in LuaTEX given that using Unicode is more
376 %people's style. But just in case, because these can lead to stray accent marks floating above censored letters.
377 %%%%%%%%%%%%%%%%%%%%%%%%%%%
378 %%%%%%%%%%%%%%%%%%%%%%%%%%%
379 %%%%%%%%%%%%%%%%%%%%%%%%%%%
380 \renewcommand{\`}[1]{}%
381 \renewcommand{\'}[1]{}%
382 \renewcommand{\^}[1]{}%
383 \renewcommand{\"}[1]{}%
384 \renewcommand{\H}[1]{}%
385 \renewcommand{\~}[1]{}%
386 \renewcommand{\c}[1]{}%
387 \renewcommand{\k}[1]{}%
388 \renewcommand{\l}[1]{}%
389 \renewcommand{\=}[1]{}%
390 \renewcommand{\b}[1]{}%
391 \renewcommand{\.}[1]{}%
392 \renewcommand{\d}[1]{}%
393 \renewcommand{\r}[1]{}%
394 \renewcommand{\u}[1]{}%
395 \renewcommand{\v}[1]{}%
396 \renewcommand{\t}[1]{}%
397 \renewcommand{\o}[1]{}%
398 \renewcommand{\i}[1]{}%
399 %%%%%%%%%%%%%%%%%%%%%%%%%%%d
400 %%%%%%%%%%%%%%%%%%%%%%%%%%%
401 %%%%%%%%%%%%%%%%%%%%%%%%%%%
402 %%%%%%%%%%%%%%%%%%%%%%%%%%%
403 % here we have the accsupp magic
404 % this operates by replacing the 'x's
405 % or unicode black squares as the case
406 % may be with an alt text
407 % this serves a dual purpose of both making
408 %pdftotext not break with huge strings of meaningless characters
409 %but more importantly
410 % it means screen readers don't subject
411 %. their users to the meaningless reading out of unicode black squares 50 times in a row!
412 %%%%%%%%%%%%%%%%%%%%%%%%%%%
413 %%%%%%%%%%%%%%%%%%%%%%%%%%%
414 %%%%%%%%%%%%%%%%%%%%%%%%%%%
415 %%%%%%%%%%%%%%%%%%%%%%%%%%%
416 \BeginAccSupp{method=plain,ActualText={TEXT REDACTED}}%
417 \rndstring{#1}%
418 \EndAccSupp{}}%
419 \else%
420 %%%%%%%%%%%%%%%%%%%%%%%%%%%
421 %%%%%%%%%%%%%%%%%%%%%%%%%%%
422 % if the conditional is off
423 % the command does absolutely nothing
424 %%%%%%%%%%%%%%%%%%%%%%%%%%%
425 %%%%%%%%%%%%%%%%%%%%%%%%%%%
426 #1%
427 \fi}
428 %%%%%%%%%%%%%%%%%%%%%%%%%%%
429 %%%%%%%%%%%%%%%%%%%%%%%%%%%
430 \end{minted}
431 \subsection{the Lua magic}
432 \begin{minted}[
433 frame=lines,
434 framesep=2mm,
435 baselinestretch=1.2,
436 bgcolor=LightGray,
437 fontsize=\footnotesize,
438 linenos,
439 breaklines,
440 firstnumber=last
441 ]
442 {latex}
443 % %%%%%%%%%%%%%%%%%%%%%%%%%%%
444 %%%%%%%%%%%%%%%%%%%%%%%%%%%
445 % The LUA MAGIC PART
446 %%%%%%%%%%%%%%%%%%%%%%%%%%%
447 %%%%%%%%%%%%%%%%%%%%%%%%%%%
448 %%%%%%%%%%%%%%%%%%%%%%%%%%%
449 %%%%%%%%%%%%%%%%%%%%%%%%%%%
450 \begin{luacode}
451 \end{minted}
452 \begin{minted}[
453 frame=lines,
454 framesep=2mm,
455 baselinestretch=1.2,
456 bgcolor=LightGray,
457 fontsize=\footnotesize,
458 linenos,
459 breaklines,
460 firstnumber=last
461 ]
462 {lua}
463 --fulsome thanks to TeX.SE users Henri Menke and David Carlisle, without whom none of this would be possible
464 local function rndstring()
465 local toks = token.scan_toks(s)
466 local on = true
467 for n, t in ipairs(toks) do
468 if t.csname == "begin" or t.csname == "end" then
469 on = false
470 -- The below is necessary as TeX primitives can break the code otherwise because they do not use brackets
471 end
472
473 if not(on) and t.cmdname == "right_brace" then
474 on = true
475 -- This prevents needless errors about gibberish up commands
476 end
477 if on and t.csname == "&" then
478 local letter = token.create'donothing'
479 toks[n] = letter
480
481 elseif on and t.csname == "%" then
482 local letter = token.create'donothing'
483 toks[n] = letter
484
485 elseif on and t.csname == "$" then
486 local letter = token.create'donothing'
487 toks[n] = letter
488
489 elseif on and t.csname == "#" then
490 local letter = token.create'donothing'
491 toks[n] = letter
492
493 elseif on and t.csname == "_" then
494 local letter = token.create'donothing'
495 toks[n] = letter
496
497 elseif on and t.csname == "{" then
498 local letter = token.create'donothing'
499 toks[n] = letter
500
501 elseif on and t.csname == "}" then
502 local letter = token.create'donothing'
503 toks[n] = letter
504
505 elseif on and t.csname == "~" then
506 local letter = token.create'donothing'
507 toks[n] = letter
508
509 elseif on and t.csname == "^" then
510 local letter = token.create'donothing'
511 toks[n] = letter
512 elseif on and t.cmdname == "letter" then
513 -- The below is the randomness part of this, which I admit is fairly arbitrary, but will more often artificially shorten strings than lengthen them, as testing found if lengthening was too frequent, it led to really unsightly long strings.
514 local f = math.random (1,20)
515 if f == 1 then
516 local letter = token.create'donothing'
517 toks[n] = letter
518
519 elseif f == 2 then
520 local letter = token.create'donothing'
521 toks[n] = letter
522 elseif f == 3 then
523 local letter = token.create'donothing' toks[n] = letter
524 elseif f == 4 then
525 local letter = token.create'twothings'
526 toks[n] = letter
527 elseif f == 5 then
528 local letter = token.create'donothing' toks[n] = letter
529
530 else
531 local letter = token.create'onething'
532 toks[n] = letter
533 end
534 elseif
535 on and t.cmdname == "spacer" then
536 local f = math.random (1,20)
537 if f == 2 then
538 local letter = token.create'donothing'
539 toks[n] = letter
540 elseif f == 3 then
541
542 local letter = token.create'donothing' toks[n] = letter
543 elseif f == 4 then
544 local letter = token.create'donothing'
545 toks[n] = letter
546 elseif f == 5 then
547
548
549 local letter = token.create'twothings' toks[n] = letter
550 elseif f == 6 then
551
552
553 local letter = token.create'donothing' toks[n] = letter
554 elseif f == 7 then
555 local letter = token.create'donothing' toks[n] = letter
556
557
558 else
559 local letter = token.create'onething'
560 toks[n] = letter
561
562 end
563
564 elseif
565 on and t.cmdname == "other_char" then
566 local f = math.random (1,20)
567 if f == 2 then
568 local letter = token.create'donothing'
569 toks[n] = letter
570 elseif f == 3 then
571
572 local letter = token.create'donothing' toks[n] = letter
573 elseif f == 4 then
574 local letter = token.create'donothing'
575 toks[n] = letter
576 elseif f == 5 then
577
578
579 local letter = token.create'twothings' toks[n] = letter
580 elseif f == 6 then
581
582
583 local letter = token.create'donothing' toks[n] = letter
584 elseif f == 7 then
585 local letter = token.create'donothing' toks[n] = letter
586
587
588 else
589 local letter = token.create'onething'
590 toks[n] = letter
591
592 end
593 end
594 end
595 --Drop the token in and move on
596 token.put_next(toks)
597 end
598 local lft = lua.get_functions_table()
599 --make a global command
600 lft[#lft + 1] = rndstring
601 token.set_lua("rndstring", #lft, "global")
602 \end{minted}
603 \begin{minted}[
604 frame=lines,
605 framesep=2mm,
606 baselinestretch=1.2,
607 bgcolor=LightGray,
608 fontsize=\footnotesize,
609 linenos,
610 breaklines,
611 firstnumber=last
612 ]
613 {latex}
614 \end{luacode}
615 \end{minted}
616 \subsection{The `{\ttfamily\color{red}warning}' option}
617 \begin{minted}[
618 frame=lines,
619 framesep=2mm,
620 baselinestretch=1.2,
621 bgcolor=LightGray,
622 fontsize=\footnotesize,
623 linenos,
624 breaklines,
625 firstnumber=last
626 ]
627 {latex}
628 %%%%%%%%%%%%%%%%%%%%%%%%%%%
629 %%%%%%%%%%%%%%%%%%%%%%%%%%%
630 % WARNING FUN YAY
631 %%%%%%%%%%%%%%%%%%%%%%%%%%%
632 %%%%%%%%%%%%%%%%%%%%%%%%%%%
633 %%%%%%%%%%%%%%%%%%%%%%%%%%%
634 %%%%%%%%%%%%%%%%%%%%%%%%%%%
635 % Definitely this whole section
636 %is there to be user modified, because
637 % depending on language, jurisdiction
638 %type of document etc, everyone will need
639 %a specific warning style. So the important
640 % part of the code here is the
641 % conditional and global [warning]
642 % option, because that's the magic value added
643 %%%%%%%%%%%%%%%%%%%%%%%%%%%
644 %%%%%%%%%%%%%%%%%%%%%%%%%%%
645 %%%%%%%%%%%%%%%%%%%%%%%%%%%
646 %%%%%%%%%%%%%%%%%%%%%%%%%%%
647 %%%%%%%%%%%%%%%%%%%%%%%%%%%
648 %%%%%%%%%%%%%%%%%%%%%%%%%%%
649 % fonts for the warning:
650 %I chose default LaTeX fonts
651 % here to be changed as users wish
652 %%%%%%%%%%%%%%%%%%%%%%%%%%%
653 %%%%%%%%%%%%%%%%%%%%%%%%%%%
654 \newfontface\wrnstncl{QT Military}
655 \newcommand{\warnword}{WARNING}
656 \newfontface\smbl{DejaVuSans-Bold}
657 \newcommand{\danger}{\smbl ⚠︎\normalfont}
658 \newcommand{\warnformat}{\sffamily\bfseries \color{red}}
659 \newcommand{\textwarn}{This document is {\underline{NOT}} redacted. It contains private and confidential personal data, and may {\underline{NOT}} be distributed, published, or shown to those without the right to view such information. The publication of the information in this document may constitute a contempt of court, punishable by a term of imprisonment.}
660 \newcommand{\textsafe}{This document has been altered to remove sensitive personal data. It is cleared for publication and dissemination.
661 }
662 \definecolor{darkgreen}{rgb}{0.0, 0.2, 0.13}
663 \definecolor{darkspringgreen}{rgb}{0.09, 0.45, 0.27}
664 \definecolor{forestgreen}{rgb}{0.13, 0.55, 0.13}
665 \newcommand{\dquad}{\danger\danger\danger\danger}
666 \newcommand{\dangersign}[1]{\scalebox{2}{\huge\danger}}
667 \newcommand{\dangerblock}{\scalebox{2}{\huge\danger\quad\danger\quad\danger}}
668 \newcommand{\warnblock}{{\Large\wrnstncl\warnword\quad\warnword\quad\warnword}}
669 \newcommand{\tworules}{\hrule width \hsize height .7pt\vskip2pt\hrule width \hsize height .7pt}
670 \newcommand{\allwarning}{\dangerblock\\\warnblock\\\normalfont\smallskip\warnformat\textwarn }
671 \newcommand{\confwarning}{%
672 %%%%%%%%%%%%%%%%%%%%%%%%%%%
673 %%%%%%%%%%%%%%%%%%%%%%%%%%%
674 % The warning option
675 %%%%%%%%%%%%%%%%%%%%%%%%%%%
676 %%%%%%%%%%%%%%%%%%%%%%%%%%%
677 \ifwarning
678 \ifcnsr
679 %%%%%%%%%%%%%%%%%%%%%%%%%%%
680 %%%%%%%%%%%%%%%%%%%%%%%%%%%
681 % a note saying document is redacted
682 %%%%%%%%%%%%%%%%%%%%%%%%%%%
683 %%%%%%%%%%%%%%%%%%%%%%%%%%%
684 \begin{center}
685 \color{forestgreen}
686 \tworules\vskip5pt
687 \normalsize\normalfont\sffamily\bfseries\textsafe
688 \vskip5pt\tworules
689 \end{center}
690 \else
691 %%%%%%%%%%%%%%%%%%%%%%%%%%%
692 %%%%%%%%%%%%%%%%%%%%%%%%%%%
693 % The WARNING for un-redacted docs
694 %%%%%%%%%%%%%%%%%%%%%%%%%%%
695 %%%%%%%%%%%%%%%%%%%%%%%%%%%
696 \begin{center}\color{red}\tworules\vskip 5pt\allwarning
697 \vskip5pt\tworules%
698 \end{center}%
699 \fi%
700 \else\fi}
701 %%%%%%%%%%%%%%%%%%%%%%%%%%%
702 %%%%%%%%%%%%%%%%%%%%%%%%%%%
703 % Allow \maketitle
704 % on same page
705 % yay
706 %
707 %%%%%%%%%%%%%%%%%%%%%%%%%%%
708 %%%%%%%%%%%%%%%%%%%%%%%%%%%
709 \ifwarning\let\oldmaketitle\maketitle\renewcommand{\maketitle}{{\let\newpage\relax\maketitle}}\else\fi
710 %%%%%%%%%%%%%%%%%%%%%%%%%%%
711 %%%%%%%%%%%%%%%%%%%%%%%%%%%
712 % print the warning at the start of the document
713 %%%%%%%%%%%%%%%%%%%%%%%%%%%
714 %%%%%%%%%%%%%%%%%%%%%%%%%%%
715 \AtBeginDocument{\confwarning}
716 \end{minted}
717 \section{Version History}
718 \subsection{\texttt{1.1.1}}
719 \ttfamily 6 April 2024: Fixed an issue with OTF for dejavusans not loading by using the postscript name.
720
721 \subsection{\texttt{1.1.0}}
722 \ttfamily 22 February 2022: Added the `warning' option and fixed a few errors in the code resulting from \TeX\ primitives causing issues.
723 \subsection{\texttt{1.0.0}}
724 \ttfamily 18 February 2022: Package creation
725
726
727 \end{document}