diff options
| -rw-r--r-- | doc/context/third/enigma/enigma_manual.tex | 108 | ||||
| -rw-r--r-- | doc/context/third/enigma/examples/enigma-example-context.tex | 1 | ||||
| -rw-r--r-- | doc/context/third/enigma/examples/enigma-example-latex.tex | 34 | ||||
| -rw-r--r-- | doc/context/third/enigma/examples/enigma-example-plain.tex | 31 | ||||
| -rw-r--r-- | tex/context/third/enigma/enigma.lua | 258 | ||||
| -rw-r--r-- | tex/context/third/enigma/t-enigma.mkvi | 23 | ||||
| -rw-r--r-- | tex/latex/enigma/enigma.sty | 2 | ||||
| -rw-r--r-- | tex/plain/enigma/enigma.tex | 24 |
8 files changed, 260 insertions, 221 deletions
diff --git a/doc/context/third/enigma/enigma_manual.tex b/doc/context/third/enigma/enigma_manual.tex index bbd3ba3..34dee9b 100644 --- a/doc/context/third/enigma/enigma_manual.tex +++ b/doc/context/third/enigma/enigma_manual.tex @@ -62,17 +62,17 @@ intuitions are for the most part informed by \CONTEXT. For this reason, a couple words concerning the interfaces will be necessary. - The examples in this manual will be cycling through all three formats, - but once you get the general idea of how it works, you will have no - problem translating between coding styles. + The examples in this manual will be cycling through all three + formats, but once you get the general idea of how it works, you will + have no problem translating between coding styles. Those familiar with \CONTEXT\ might, therefore, skip the following paragraphs and continue directly with the next section on \at{page}[sec:opts].% - + The package is loaded as usual. For \PLAIN, issue a \type{\input{enigma}}. - \LATEX-users need to place \type{\usepackage{enigma}} somewhere inside - the preamble. + \LATEX-users need to place \type{\usepackage{enigma}} somewhere + inside the preamble. (There are no package options.) From this point on, instructions for both formats are the same. @@ -80,9 +80,10 @@ will be derived: \texmacro{defineenigma} and \texmacro{setupenigma}. Both are a kind of \emph{meta-macros}, meaning that they generate - other macros which may then be employed to access the functionality of - the package. - As such they naturally belong inside the preamble (if you chose to use + other macros which may then be employed to access the functionality + of the package. + As such they naturally belong inside the preamble (if you chose to + use \modulename{Enigma} with \LATEX, that is). It follows that the correct and only meaningful order is to \texmacro{defineenigma} an enigma machine first and then @@ -99,8 +100,8 @@ have to process entire paragraphs. As encrypted passages are supposed to stand on their own, this small limitation should not have a severe impact on functionality. - If you should, however, need a macro that works for smaller portions - of text, please send a feature request to the maintainer + If you should, however, need a macro that works for smaller + portions of text, please send a feature request to the maintainer (\ichdparameter{email}). } However, these are not usable right away, as we still have to set the @@ -114,10 +115,10 @@ examples of their effects will be given further below in the section on functionality (see \at{page}[sec:fun]).% \footnote{% - If you grasp the concept of paired \type{\define<foo>} \endash\space - \type{\setup<foo>} macros, then congratulations are in order: - you qualify for migration from your current macro package to - \CONTEXT. + If you grasp the concept of paired \type{\define<foo>} + \endash\space \type{\setup<foo>} macros, then congratulations are + in order: you qualify for migration from your current macro package + to \CONTEXT. } \stopdocsection \startdocsection[title=Options Explained,reference=sec:opts] @@ -144,7 +145,7 @@ the following parameters. %% Usage ················ %% \startencryption aaaaa aaaaa aaaaa - aaaaa aaaaa aaaaa + aaaaa aaaaa aaaaa \stopencryption \startencryption Nobody in Poland is going @@ -168,16 +169,17 @@ the following parameters. <\emph{#2}>% \hskip1em% } - \item{other_chars}{boolean} How to handle non-encodable characters, i.\,e. - glyphs outside the bare set of Latin letters; see below on + \item{other_chars}{boolean} How to handle non-encodable characters, + i.\,e. glyphs outside the bare set of Latin letters; see below on \at{page}[explained:other_chars]. - \item{day_key}{string} Encryption key, i.\,e. a description of the initial - setup of an Enigma machine: the reflector used, the choice and - positions of the three rotors, the ring settings, and the plugboard - wiring. + \item{day_key}{string} Encryption key, i.\,e. a description of the + initial setup of an Enigma machine: the reflector used, the choice + and positions of the three rotors, the ring settings, and the + plugboard wiring. \item{rotor_setting}{string} The initial rotor advancement. \item{spacing}{boolean} Auto-space output? - \item{verbose}{integer} Controls overall verbosity level (\emph{global}!). + \item{verbose}{integer} Controls overall verbosity level + (\emph{global}\/!). \stopitemize %% day key @@ -190,8 +192,8 @@ To state the obvious, the value of \identifier{day_key} serves as the \from[initialization]. } Together these have the denotation \emph{day key}, because they are -meant to be supplied in special code books by central authority, one for -each day.\footnote{% +meant to be supplied in special code books by central authority, one +for each day.\footnote{% Read about the historical directives for daily key renewal at \from[key_procedure]. there are some {\sc pdf}s with images of \emph{Kenngruppenbücher} at @@ -221,15 +223,16 @@ of this section is entirely optional. Also part of the \identifier{day_key}, but not mentioned yet, is the choice of the \emph{reflector}. It may be specified as one of the three letters \type{A}, \type{B} and -\type{C} as the first item. If no reflector is requested explicitly, the -machine defaults to \type{B}, which is actually the only one of the +\type{C} as the first item. If no reflector is requested explicitly, +the machine defaults to \type{B}, which is actually the only one of the three models that had been in widespread use (see below on \at{page}[listing:reflector] for the wirings). Initialization is not complete without a \identifier{rotor_setting}. -This is a triple of letters, each representing the initial state of -one rotor (e.\,g. \type{fkd}). Historically this was not part of the day -key but supposed to be chosen at random by the operating signal officer. +This is a triple of letters, each representing the initial state of one +rotor (e.\,g. \type{fkd}). Historically this was not part of the day +key but supposed to be chosen at random by the operating signal +officer. The output can be automatically grouped into sequences of five characters, delimited by spaces. This does not only conform with @@ -237,21 +240,22 @@ traditional crypto-style, but also allows for the resulting text to be sanely broken into lines by \TEX. %%% other_chars -% The option \identifier{other_chars} determines how the machine -- in our -% Unicode-aware times -- should behave when it encounters a non-Latin -% letter. For the time being it can either remove them from the input -% (value \emph{no}) or pass them through unmodified (\emph{yes}). Note -% that this is independent of the \emph{preprocessing} of characters like -% punctuation and umlauts, which is done automatically. +% The option \identifier{other_chars} determines how the machine -- in +% our Unicode-aware times -- should behave when it encounters a +% non-Latin letter. For the time being it can either remove them from +% the input (value \emph{no}) or pass them through unmodified +% (\emph{yes}). Note that this is independent of the +% \emph{preprocessing} of characters like punctuation and umlauts, +% which is done automatically. % (See below \at{page}[listing:preproc] for the internal substitution % list.) -Most documents don’t naturally adhere to the machine-imposed restriction -to the 26 letters of the Latin alphabet. The original encipherment -directives comprised substitution tables to compensate for a set of -intrinsic peculiarities of the German language, like umlauts and common -digraphs. The \modulename{Enigma} simulation module strives to apply -these automatically but there is no guarantee of completeness. +Most documents don’t naturally adhere to the machine-imposed +restriction to the 26 letters of the Latin alphabet. The original +encipherment directives comprised substitution tables to compensate for +a set of intrinsic peculiarities of the German language, like umlauts +and common digraphs. The \modulename{Enigma} simulation module strives +to apply these automatically but there is no guarantee of completeness. However,\reference[explained:other_chars]{} the Enigma lacks means of handling languages other than German. When the substitution lookup @@ -262,8 +266,8 @@ intends to keep these foreign characters instead, E can achieve this by setting the \identifier{other_chars} key in the \modulename{Enigma} setup to the value \emph{true}. An example of how the result of both methods may look, other things being equal, is given in below listing -(example for \CONTEXT; see the file \type{enigma-example-context.tex} in -the \type{doc/} subtree of your installation path). +(example for \CONTEXT; see the file \type{enigma-example-context.tex} +in the \type{doc/} subtree of your installation path). \startcontexttyping \usemodule [enigma] @@ -341,8 +345,8 @@ encryption and that spaces are omitted. \useURL[kgbuch] [http://de.wikipedia.org/wiki/Kenngruppenbuch] [] [code book] Now it’s certainly not wise to carry around the key to encrypted -documents as plain text within those documents. The keys will have to be -distributed via an independent channel, e.\,g. a \from[kgbuch]. +documents as plain text within those documents. The keys will have to +be distributed via an independent channel, e.\,g. a \from[kgbuch]. Keys in general don’t have to be supplied inside the document. If there is none specified, the module will interrupt the \TEX\ run and \emph{ask} for user input. Suppose Alice wanted to send an encrypted @@ -356,8 +360,8 @@ mtxrun --script mtx-t-enigma \ --text="I have nothing to hide. From the NSA, that is." \stoptyping -Alice would then include the result of this line in her \LATEX\ document -as follows: +Alice would then include the result of this line in her \LATEX\ +document as follows: \startlatextyping \documentclass{scrartcl} @@ -461,11 +465,11 @@ conditions are met: \startdocsection[title=Acknowledgements] \startcredits - \item The idea to implement the \emph{Enigma} cipher for \TEX\ came up - while I was reading \emph{The Code Book} by Simon Singh. + \item The idea to implement the \emph{Enigma} cipher for \TEX\ came + up while I was reading \emph{The Code Book} by Simon Singh. This work contains an excellent portrayal of the history of - German military cryptography and Allied cryptanalysis before and - during the Second World War.\par + German military cryptography and Allied cryptanalysis before + and during the Second World War.\par \from[codebook] \item A more detailed account from a historical-cryptological perspective is provided by Ulrich Heinz in his Dissertation (in diff --git a/doc/context/third/enigma/examples/enigma-example-context.tex b/doc/context/third/enigma/examples/enigma-example-context.tex index 769c608..11e1386 100644 --- a/doc/context/third/enigma/examples/enigma-example-context.tex +++ b/doc/context/third/enigma/examples/enigma-example-context.tex @@ -52,3 +52,4 @@ \stopothermessage \stoptext +% vim:ft=context:tw=71:ts=2:sw=2:expandtab diff --git a/doc/context/third/enigma/examples/enigma-example-latex.tex b/doc/context/third/enigma/examples/enigma-example-latex.tex index 66d84d1..f2113c1 100644 --- a/doc/context/third/enigma/examples/enigma-example-latex.tex +++ b/doc/context/third/enigma/examples/enigma-example-latex.tex @@ -1,41 +1,42 @@ \documentclass[a5paper]{scrartcl} \parindent0pt -%······································································% +%%····································································% \usepackage {enigma} -%%·····································································% +%%····································································% %% The first machine will be used for encryption of our plain text. \defineenigma {encryption} \setupenigma {encryption} { - other_chars = yes, - day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, + other_chars = yes, + day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, rotor_setting = ben, - spacing = yes, - verbose = 3, + spacing = yes, + verbose = 2, } -%%·····································································% +%%····································································% %% This second machine below will be used to decrypt the string. It is %% initialized with exactly the same settings as the first one. The -%% reason for this is that we can’t reuse the “encryption” machine as it -%% will already have progressed to some later state after the +%% reason for this is that we can’t reuse the “encryption” machine as +%% it will already have progressed to some later state after the %% encryption. Applying it on the ciphertext would yield a totally %% different string. Hence the need for another machine. \defineenigma{decryption} \setupenigma{decryption}{ - other_chars = yes, - day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, + other_chars = yes, + day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, rotor_setting = ben, } -%%·····································································% +%%····································································% \begin{document} -%%·····································································% +%%····································································% %% Ciphertext in the PDF. Rely on the addressee to decrypt the document %% externally. \startencryption - Never underestimate the amount of money, time, and effort someone will expend to thwart a security system. + Never underestimate the amount of money, time, and effort someone + will expend to thwart a security system. \stopencryption -%%·····································································% +%%····································································% %% Input string generated with: %% mtxrun --script t-enigma \ %% --setup="day_key=B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL,\ @@ -47,5 +48,6 @@ \startdecryption aqsnwyxgqarpuzrdktscbslaqmdhyonywxkwhcdgphvuqsspfjwhlszahygjbzmfpcpbniahvfcuradntepxsfchnn \stopdecryption -%%·····································································% +%%····································································% \end{document} +% vim:ft=tex:tw=71:expandtab:ts=2:sw=2 diff --git a/doc/context/third/enigma/examples/enigma-example-plain.tex b/doc/context/third/enigma/examples/enigma-example-plain.tex index 87ce9b1..ba2157d 100644 --- a/doc/context/third/enigma/examples/enigma-example-plain.tex +++ b/doc/context/third/enigma/examples/enigma-example-plain.tex @@ -1,37 +1,40 @@ \parindent0pt -%%·····································································% +%%····································································% \input {enigma} -%%·····································································% +%%····································································% %% The first machine will be used for encryption of our plain text. \defineenigma {encryption} \setupenigma {encryption} { - other_chars = yes, - day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, + other_chars = yes, + day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, rotor_setting = ben, + spacing = yes, + verbose = 1, } -%%·····································································% +%%····································································% %% This second machine below will be used to decrypt the string. \defineenigma{decryption} \setupenigma{decryption}{ - other_chars = yes, - day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, + other_chars = yes, + day_key = B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL, rotor_setting = ben, } -%%·····································································% +%%····································································% %% main -%%·····································································% +%%····································································% %% Ciphertext in the PDF. Rely on the addressee to decrypt the document %% externally. -%%·····································································% +%%····································································% %% encryption of plain text -%%·····································································% +%%····································································% \startencryption - Never underestimate the amount of money, time, and effort someone will expend to thwart a security system. + Never underestimate the amount of money, time, and effort someone + will expend to thwart a security system. \stopencryption -%%·····································································% +%%····································································% %% decryption of ciphertext -%%·····································································% +%%····································································% %% Input string generated with: %% mtxrun --script t-enigma \ %% --setup="day_key=B V III II 12 03 01 GI JV KZ WM PU QY AD CN ET FL,\ diff --git a/tex/context/third/enigma/enigma.lua b/tex/context/third/enigma/enigma.lua index ed227b7..12ac424 100644 --- a/tex/context/third/enigma/enigma.lua +++ b/tex/context/third/enigma/enigma.lua @@ -1,5 +1,5 @@ #!/usr/bin/env texlua ------------------------------------------------------------------------- +----------------------------------------------------------------------- -- FILE: enigma.lua -- USAGE: Call via interface from within a TeX session. -- DESCRIPTION: Enigma logic. @@ -7,13 +7,13 @@ -- AUTHOR: Philipp Gesang (Phg), <megas.kapaneus@gmail.com> -- VERSION: hg tip -- CREATED: 2012-02-19 21:44:22+0100 ------------------------------------------------------------------------- +----------------------------------------------------------------------- -- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Format Dependent Code] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph Exported functionality will be collected in the table @@ -26,22 +26,23 @@ local format_is_context_p = false --[[ichd-- \startparagraph -Afaict, \LATEX\ for \LUATEX\ still lacks a globally accepted namespacing -convention. This is more than bad, but we’ll have to cope with that. For -this reason we brazenly introduce \identifier{packagedata} (in analogy -to \CONTEXT’s \identifier{thirddata}) table as a package namespace -proposal. If this module is called from a \LATEX\ or plain session, the -table \identifier{packagedata} will already have been created so we will +Afaict, \LATEX\ for \LUATEX\ still lacks a globally accepted +namespacing convention. This is more than bad, but we’ll have to cope +with that. For this reason we brazenly introduce +\identifier{packagedata} (in analogy to \CONTEXT’s +\identifier{thirddata}) table as a package namespace proposal. If this +module is called from a \LATEX\ or plain session, the table +\identifier{packagedata} will already have been created so we will identify the format according to its presence or absence, respectively. \stopparagraph --ichd]]-- -if packagedata then -- latex or plain +if packagedata then -- latex or plain packagedata.enigma = enigma -elseif thirddata then -- context +elseif thirddata then -- context format_is_context_p = true thirddata.enigma = enigma -else -- external call, mtx-script or whatever +else -- external call, mtx-script or whatever _G.enigma = enigma end --[[ichd-- @@ -49,9 +50,9 @@ end --ichd]]-- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Prerequisites] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph First of all, we generate local copies of all those library functions that are expected to be referenced frequently. @@ -81,8 +82,10 @@ local noderemove = node and node.remove local nodeslide = node and node.slide local nodetraverse = node and node.traverse local nodetraverse_id = node and node.traverse_id -local nodesinstallattributehandler = format_is_context_p and nodes.installattributehandler -local nodestasksappendaction = format_is_context_p and nodes.tasks.appendaction +local nodesinstallattributehandler = format_is_context_p + and nodes.installattributehandler +local nodestasksappendaction = format_is_context_p + and nodes.tasks.appendaction local stringfind = string.find local stringformat = string.format local stringlower = string.lower @@ -150,8 +153,8 @@ local P, R, S, V, lpegmatch --[[ichd-- \startparagraph -By default the output to \type{stdout} will be zero. The verbosity level -can be adjusted in order to alleviate debugging. +By default the output to \type{stdout} will be zero. The verbosity +level can be adjusted in order to alleviate debugging. \stopparagraph --ichd]]-- --local verbose_level = 42 @@ -171,9 +174,9 @@ local max_msg_length = 250 --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Globals] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph The following mappings are used all over the place as we convert back and forth between the characters (unicode) and their numerical @@ -239,8 +242,8 @@ mnemonic. end --[[ichd-- -\placetable[here][listing:reflector]{The three reflectors and their substitution - rules.}{% +\placetable[here][listing:reflector]% + {The three reflectors and their substitution rules.}{% \starttabulate[|r|l|] \NC UKW a \NC AE BJ CM DZ FL GY HX IV KW NR OQ PU ST \NC \NR \NC UKW b \NC AY BR CU DH EQ FS GL IP JX KN MO TZ VW \NC \NR @@ -276,9 +279,9 @@ end --ichd]]-- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Pretty printing for debug purposes] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph The functions below allow for formatting of the terminal output; they have no effect on the workings of the enigma simulator. @@ -374,7 +377,8 @@ do return tableconcat(result) end - local init_announcement = colorize("\n" .. [[Initial position of rotors: ]], + local init_announcement + = colorize("\n" .. [[Initial position of rotors: ]], 37) pprint_init = function (init) local result = "" @@ -477,9 +481,9 @@ do --[[ichd-- \startparagraph -\luafunction{emit} is the main wrapper function for \identifier{stdout}. -Checks if the global verbosity setting exceeds the specified threshold, -and only then pushes the output. +\luafunction{emit} is the main wrapper function for +\identifier{stdout}. Checks if the global verbosity setting exceeds +the specified threshold, and only then pushes the output. \stopparagraph --ichd]]-- emit = function (v, f, ...) @@ -535,12 +539,12 @@ do --ichd]]-- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Rotation] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph -The following function \luafunction{do_rotate} increments the rotational -state of a single rotor. There are two tests for notches: +The following function \luafunction{do_rotate} increments the +rotational state of a single rotor. There are two tests for notches: \startitemize[n] \item whether it’s at the current character, and \item whether it’s at the next character. @@ -586,9 +590,9 @@ has been reached and covers the corner case \emph{double stepping}. --ichd]]-- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Input Preprocessing] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph Internally, we will use lowercase strings as they are a lot more readable than uppercase. Lowercasing happens prior to any further @@ -660,11 +664,11 @@ solution is to write out numbers above ten. --ichd]]-- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[ title={Main function chain to be applied to single characters}, ] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph As far as the Enigma is concerned, there is no difference between @@ -684,8 +688,8 @@ each rotor to the letter value (its position on the ingoing end). } \startparagraph The function \luafunction{do_do_encode_char} returns the character -substitution for one rotor. As a letter passes through each rotor twice, -the argument \identifier{direction} determines which way the +substitution for one rotor. As a letter passes through each rotor +twice, the argument \identifier{direction} determines which way the substitution is applied. \stopparagraph --ichd]]-- @@ -707,12 +711,12 @@ substitution is applied. --[[ichd-- \startparagraph -Behind the plugboard, every character undergoes seven substitutions: two -for each rotor plus the central one through the reflector. The function -\luafunction{do_encode_char}, although it returns the final result only, -keeps every intermediary step inside a table for debugging purposes. -This may look inefficient but is actually a great advantage whenever -something goes wrong. +Behind the plugboard, every character undergoes seven substitutions: +two for each rotor plus the central one through the reflector. The +function \luafunction{do_encode_char}, although it returns the final +result only, keeps every intermediary step inside a table for debugging +purposes. This may look inefficient but is actually a great advantage +whenever something goes wrong. \stopparagraph --ichd]]-- --- ra -> rb -> rc -> ukw -> rc -> rb -> ra @@ -740,8 +744,8 @@ alphabet. Characters that fail this check are, at the moment, returned as they were. \TODO{Make behaviour of \luafunction{encode_char} in case of invalid input configurable.} -Also, the counter of encoded characters is incremented at this stage and -some pretty printer hooks reside here. +Also, the counter of encoded characters is incremented at this stage +and some pretty printer hooks reside here. \stopparagraph \startparagraph @@ -760,7 +764,7 @@ local variable, \identifier{pb_char}. machine:rotate() local pb = machine.plugboard char = letter_to_value[char] - local pb_char = pb[char] -- first plugboard substitution + local pb_char = pb[char] -- first plugboard substitution emit(2, pprint_step, machine.step, char, pb_char) emit(3, pprint_rotor_scheme) emit(3, pprint_rotor, machine.rotors[1]) @@ -769,11 +773,12 @@ local variable, \identifier{pb_char}. char = do_encode_char(machine.rotors, machine.reflector, pb_char) - return value_to_letter[pb[char]] -- second plugboard substitution + return value_to_letter[pb[char]] -- second plugboard substitution end local get_random_pattern = function () - local a, b, c = mathrandom(1,26), mathrandom(1,26), mathrandom(1,26) + local a, b, c + = mathrandom(1,26), mathrandom(1,26), mathrandom(1,26) return value_to_letter[a] .. value_to_letter[b] .. value_to_letter[c] @@ -796,8 +801,8 @@ local variable, \identifier{pb_char}. --[[ichd-- \startparagraph -As the actual encoding proceeds character-wise, the processing of entire -strings needs to be managed externally. This is where +As the actual encoding proceeds character-wise, the processing of +entire strings needs to be managed externally. This is where \luafunction{encode_string} comes into play: It handles iteration and extraction of successive characters from the sequence. \TODO{Make \luafunction{encode_string} preprocess characters.} @@ -824,9 +829,9 @@ extraction of successive characters from the sequence. --ichd]]-- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Initialization string parser] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \placetable[here][]{Initialization strings}{% \bTABLE @@ -877,7 +882,8 @@ extraction of successive characters from the sequence. * V"ring" * (V"whitespace" * V"plugboard")^-1 , - reflector = Cg(C(R("ac","AC")) / stringlower, "reflector"), + reflector = Cg(C(R("ac","AC")) / stringlower, "reflector") + , rotors = Cg(Ct(V"rotor" * V"whitespace" * V"rotor" * V"whitespace" @@ -929,17 +935,17 @@ extraction of successive characters from the sequence. --ichd]]-- --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Initialization routines] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startparagraph The plugboard is implemented as a pair of hash tables. \stopparagraph --ichd]]-- local get_plugboard_substitution = function (p) - -- Plugboard wirings are symmetrical, thus we have one table for each - -- direction. + --- Plugboard wirings are symmetrical, thus we have one table for + --- each direction. local tmp, result = { }, { } for _, str in next, p do local one, two = stringlower(stringsub(str, 1, 1)), @@ -962,8 +968,8 @@ The plugboard is implemented as a pair of hash tables. --[[ichd-- \startparagraph Initialization of the rotors requires some precautions to be taken. -The most obvious of which is adjusting the displacement of its wiring by -the ring setting. +The most obvious of which is adjusting the displacement of its wiring +by the ring setting. \stopparagraph \startparagraph Another important task is to store the notch position in order for it @@ -972,20 +978,20 @@ to be retrievable by the rotation subroutine at a later point. \startparagraph The actual bidirectional mapping is implemented as a pair of tables. The initial order of letters, before the ring shift is applied, is -alphabetical on the input (right, “from”) side and, on the output (left, -“to”) side taken by the hard wired correspondence as specified in the -rotor wirings above. +alphabetical on the input (right, “from”) side and, on the output +(left, “to”) side taken by the hard wired correspondence as specified +in the rotor wirings above. NB the descriptions in terms of “output” and “input” directions is misleading in so far as during any encoding step the electricity will pass through every rotor in both ways. -Hence, the “input” (right, from) direction literally applies only to the -first half of the encoding process between plugboard and reflector. +Hence, the “input” (right, from) direction literally applies only to +the first half of the encoding process between plugboard and reflector. \stopparagraph \startparagraph -The function \luafunction{do_get_rotor} creates a single rotor -instance and populates it with character mappings. The \identifier{from} -and \identifier{to} subfields of its \identifier{wiring} field represent the -wiring in the respective directions. +The function \luafunction{do_get_rotor} creates a single rotor instance +and populates it with character mappings. The \identifier{from} and +\identifier{to} subfields of its \identifier{wiring} field represent +the wiring in the respective directions. This initital wiring was specified in the corresponding \identifier{raw_rotor_wiring} table; the ringshift is added modulo the alphabet size in order to get the correctly initialized rotor. @@ -1018,8 +1024,8 @@ alphabet size in order to get the correctly initialized rotor. Rotors are initialized sequentially accordings to the initialization request. The function \luafunction{get_rotors} walks over the list of -initialization instructions and calls \luafunction{do_get_rotor} for the -actual generation of the rotor table. Each rotor generation request +initialization instructions and calls \luafunction{do_get_rotor} for +the actual generation of the rotor table. Each rotor generation request consists of three elements: \stopparagraph \startitemize[n] @@ -1058,7 +1064,8 @@ character, each one will be encoded successively, yielding a list. --ichd]]-- local encode_general = function (machine, chr) local chr = stringlower(chr) - local replacement = pp_substitutions[chr] or valid_char_p[chr] and chr + local replacement + = pp_substitutions[chr] or valid_char_p[chr] and chr if not replacement then return false end if utf8len(replacement) == 1 then @@ -1137,14 +1144,15 @@ placeholders (“X”) from the encodable spectrum. See above The above mentioned preprocessing, however, does not even nearly extend to the whole unicode range that modern day typesetting is expected to handle. Thus, sooner or later an Enigma machine will encounter -non-preprocessable characters and it will have to decide what to do with -them. The Enigma module offers two ways to handle this kind of +non-preprocessable characters and it will have to decide what to do +with them. The Enigma module offers two ways to handle this kind of situation: \emph{drop} those characters, possibly distorting the deciphered plain text, or to leave them in, leaving hints behind as to -the structure of the encrypted text. None of these is optional, so it is -nevertheless advisable to not include non-latin characters in the plain -text in the first place. The settings key \identifier{other_chars} (type -boolean) determines whether we will keep or drop offending characters. +the structure of the encrypted text. None of these is optional, so it +is nevertheless advisable to not include non-latin characters in the +plain text in the first place. The settings key +\identifier{other_chars} (type boolean) determines whether we will keep +or drop offending characters. \stopparagraph --ichd]]-- @@ -1182,11 +1190,12 @@ boolean) determines whether we will keep or drop offending characters. decode_char = decode_char, set_state = set_state, processed_chars = processed_chars, - --- <badcodingstyle> - __raw = raw_settings -- hackish but occasionally useful + --- <badcodingstyle> -- hackish but occasionally useful + __raw = raw_settings --- </badcodingstyle> } --- machine - local init_state = pattern_to_state(pattern or get_random_pattern()) + local init_state + = pattern_to_state(pattern or get_random_pattern()) emit(1, pprint_init, init_state) machine:set_state(init_state) @@ -1202,9 +1211,9 @@ end --[[ichd-- -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \startdocsection[title=Setup Argument Handling] -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --ichd]]-- do --[[ichd-- @@ -1233,7 +1242,11 @@ as all the functionality resides in Lua. , value = C((V"balanced" + (1 - V"final"))^1), final = V"whitespace"^0 * V"comma" + V"rest_of_string", - rest_of_string = V"whitespace"^0 * V"eol_comment"^-1 * V"eol"^0 * V"eof", + rest_of_string = V"whitespace"^0 + * V"eol_comment"^-1 + * V"eol"^0 + * V"eof" + , rest_of_line = V"whitespace"^0 * V"eol_comment"^-1 * V"eol", eol_comment = V"comment_string" * (1 - (V"eol" + V"eof"))^0, comment_string = V"lua_comment" + V"TeX_comment", @@ -1242,11 +1255,16 @@ as all the functionality resides in Lua. emptyline = V"rest_of_line", balanced = V"balanced_brk" + V"balanced_brc", - balanced_brk = V"lbrk" * (V"balanced" + (1 - V"rbrk"))^0 * V"rbrk", - balanced_brc = V"lbrc" * (V"balanced" + (1 - V"rbrc"))^0 * V"rbrc", - + balanced_brk = V"lbrk" + * (V"balanced" + (1 - V"rbrk"))^0 + * V"rbrk" + , + balanced_brc = V"lbrc" + * (V"balanced" + (1 - V"rbrc"))^0 + * V"rbrc" + , -- Terminals - eol = P"\n\r" + P"\r\n" + P"\n" + P"\r", -- users do strange things + eol = P"\n\r" + P"\r\n" + P"\n" + P"\r", eof = -P(1), whitespace = S" \t\v", equals = P"=", @@ -1262,8 +1280,8 @@ as all the functionality resides in Lua. --[[ichd-- \startparagraph In the next step we process the arguments, check the input for sanity -etc. The function \luafunction{parse_args} will test whether a value has -a sanitizer routine and, if so, apply it to its value. +etc. The function \luafunction{parse_args} will test whether a value +has a sanitizer routine and, if so, apply it to its value. \stopparagraph --ichd]]-- @@ -1276,7 +1294,8 @@ a sanitizer routine and, if so, apply it to its value. ["true"] = true, yes = true, } - local toboolean = function (value) return boolean_synonyms[value] or false end + local toboolean + = function (value) return boolean_synonyms[value] or false end local alpha = R("az", "AZ") local digit = R"09" local space = S" \t\v" @@ -1360,9 +1379,10 @@ shuffling on the function side. \startparagraph When grouping output into the traditional blocks of five letters we insert space nodes. As their properties depend on the font we need to -recreate the space item for every paragraph. Also, as \CONTEXT\ does not -preload a font we lack access to font metrics before \type{\starttext}. -Thus creating the space earlier will result in an error. +recreate the space item for every paragraph. Also, as \CONTEXT\ does +not preload a font we lack access to font metrics before +\type{\starttext}. Thus creating the space earlier will result in an +error. The function \luafunction{generate_space} will be called inside the callback in order to get an appropriate space glue. \stopparagraph @@ -1382,11 +1402,11 @@ end \startparagraph \useURL[khaled_hosny_texsx] [http://tex.stackexchange.com/a/11970] [] [tex.sx] -Registering a callback (“node attribute”?, “node task”?, “task action”?) -in \CONTEXT\ is not straightforward, let alone documented. The trick is -to create, install and register a handler first in order to use it later -on \dots\ many thanks to Khaled Hosny, who posted an answer to -\from[khaled_hosny_texsx]. +Registering a callback (“node attribute”?, “node task”?, “task +action”?) in \CONTEXT\ is not straightforward, let alone documented. +The trick is to create, install and register a handler first in order +to use it later on \dots\ many thanks to Khaled Hosny, who posted an +answer to \from[khaled_hosny_texsx]. \stopparagraph --ichd]]-- @@ -1396,10 +1416,10 @@ local new_callback = function (machine, name) local mod_5 = 0 local insert_encoded --- First we need to choose an insertion method. If autospacing is - --- requested, a space will have to be inserted every five characters. - --- The rationale behind using differend functions to implement each - --- method is that it should be faster than branching for each - --- character. + --- requested, a space will have to be inserted every five + --- characters. The rationale behind using differend functions to + --- implement each method is that it should be faster than branching + --- for each character. if machine.spacing then -- auto-group output insert_encoded = function (head, n, replacement) local insertion = nodecopy(n) @@ -1453,7 +1473,7 @@ local new_callback = function (machine, name) end end elseif nid == GLUE_NODE then - if n.subtype ~= 15 then -- keeping the parfillskip is convenient + if n.subtype ~= 15 then -- keeping the parfillskip noderemove(head, n) end elseif IGNORE_NODES[nid] then @@ -1486,7 +1506,8 @@ local new_callback = function (machine, name) } nodestasksappendaction("processors", --"characters", - -- this one is “for users” (cf. node-tsk.lua) + --- this one is tagged “for users” + --- (cf. node-tsk.lua) "before", "thirddata.enigma.callbacks." .. name) nodes.tasks.disableaction("processors", @@ -1502,10 +1523,11 @@ Enigma\reference[listing:retrieve]{} machines can be copied and derived from one another at will, cf. the \texmacro{defineenigma} on \at{page}[listing:define]. Two helper functions residing inside the \identifier{thirddata.enigma} namespace take care of these actions: -\luafunction{save_raw_args} and \luafunction{retrieve_raw_args}. As soon -as a machine is defined, we store its parsed options inside the table -\identifier{configurations} for later reference. For further details on -the machine derivation mechanism see \at{page}[listing:inherit]. +\luafunction{save_raw_args} and \luafunction{retrieve_raw_args}. As +soon as a machine is defined, we store its parsed options inside the +table \identifier{configurations} for later reference. For further +details on the machine derivation mechanism see +\at{page}[listing:inherit]. \stopparagraph --ichd]]-- local configurations = { } @@ -1527,13 +1549,13 @@ enigma.retrieve_raw_args = retrieve_raw_args --[[ichd-- \startparagraph The function \luafunction{new_machine} instantiates a table containing -the complete specification of a workable \emph{Enigma} machine and other -metadata. The result is intended to be handed over to the callback -creation mechanism (\luafunction{new_callback}). However, the arguments -table is usally stored away in the \identifier{thirddata.enigma} -namespace anyway (\luafunction{save_raw_args}), so that the -specification of any machine can be inherited by some new setup later -on. +the complete specification of a workable \emph{Enigma} machine and +other metadata. The result is intended to be handed over to the +callback creation mechanism (\luafunction{new_callback}). However, the +arguments table is usally stored away in the +\identifier{thirddata.enigma} namespace anyway +(\luafunction{save_raw_args}), so that the specification of any machine +can be inherited by some new setup later on. \stopparagraph --ichd]]-- local new_machine = function (name) @@ -1551,4 +1573,4 @@ enigma.new_callback = new_callback \stopdocsection --ichd]]-- --- vim:ft=lua:sw=2:ts=2:tw=72 +-- vim:ft=lua:sw=2:ts=2:tw=71 diff --git a/tex/context/third/enigma/t-enigma.mkvi b/tex/context/third/enigma/t-enigma.mkvi index 267485f..ffade50 100644 --- a/tex/context/third/enigma/t-enigma.mkvi +++ b/tex/context/third/enigma/t-enigma.mkvi @@ -41,12 +41,13 @@ thirddata = thirddata or { } %D \startdocsection[title=Macro Generator] %D \startparagraph -%D The main setup.\reference[listing:define]{} The \texmacro{defineenigma} macro does not adhere to -%D the reommended practis of automatical macro derivation. Rather, we -%D have our own parser do the job of setting globals. This is a -%D consequence of the intention to offer the same behavior in any of the -%D three main formats, \PLAIN, \CONTEXT and \LATEX. Hence, we don’t rely -%D on the internal mechanisms but implement our own macro generator. +%D The main setup.\reference[listing:define]{} The +%D \texmacro{defineenigma} macro does not adhere to the reommended +%D practis of automatical macro derivation. Rather, we have our own +%D parser do the job of setting globals. This is a consequence of the +%D intention to offer the same behavior in any of the three main +%D formats, \PLAIN, \CONTEXT and \LATEX. Hence, we don’t rely on the +%D internal mechanisms but implement our own macro generator. %D \stopparagraph \def\enigma_define_indeed#id{% @@ -77,10 +78,10 @@ thirddata = thirddata or { } } %D \startparagraph -%D The \texmacro{enigma_inherit}\reference[listing:inherit]{} is called as -%D an intermediate step when deriving one machine from an already existing -%D one. It gets the stored configuration of its ancestor, relying on the -%D \luafunction{retrieve_raw_args} function (see +%D The \texmacro{enigma_inherit}\reference[listing:inherit]{} is called +%D as an intermediate step when deriving one machine from an already +%D existing one. It gets the stored configuration of its ancestor, +%D relying on the \luafunction{retrieve_raw_args} function (see %D \at{page}[listing:retrieve]. %D \stopparagraph \def\enigma_inherit#to#from{% @@ -153,4 +154,4 @@ thirddata = thirddata or { } %D \stopdocsection \protect -% vim:ft=context:sw=2:ts=2:tw=72 +% vim:ft=context:sw=2:ts=2:tw=71 diff --git a/tex/latex/enigma/enigma.sty b/tex/latex/enigma/enigma.sty index e9ccee4..80b8b26 100644 --- a/tex/latex/enigma/enigma.sty +++ b/tex/latex/enigma/enigma.sty @@ -4,4 +4,4 @@ \RequirePackage{luatexbase} \input{enigma} \endinput -% vim:ft=tex:sw=2:ts=2:expandtab:tw=72 +% vim:ft=tex:sw=2:ts=2:expandtab:tw=71 diff --git a/tex/plain/enigma/enigma.tex b/tex/plain/enigma/enigma.tex index 0cd0e61..2b4fb8e 100644 --- a/tex/plain/enigma/enigma.tex +++ b/tex/plain/enigma/enigma.tex @@ -9,7 +9,8 @@ \catcode`\!=11 %D Nice tool from luat-ini.mkiv. This really helps with those annoying %D string separators of Lua’s that clutter the source. -\def\luastringsep{===} % this permits \typefile{self} otherwise nested b/e sep problems +% this permits \typefile{self} otherwise nested b/e sep problems +\def\luastringsep{===} \edef\!!bs{[\luastringsep[} \edef\!!es{]\luastringsep]} %D \startdocsection[title=Prerequisites] @@ -56,8 +57,9 @@ local enigma = packagedata.enigma local current_args = enigma.parse_args(\!!bs\detokenize{#1}\!!es) enigma.save_raw_args(current_args, \!!bs\current_enigma_id\!!es) - enigma.new_callback(enigma.new_machine(\!!bs\current_enigma_id\!!es), - \!!bs\current_enigma_id\!!es) + enigma.new_callback( + enigma.new_machine(\!!bs\current_enigma_id\!!es), + \!!bs\current_enigma_id\!!es) }% \egroup% } @@ -85,10 +87,12 @@ \endgraf \bgroup% \directlua{% - if packagedata.enigma and packagedata.enigma.machines[ \!!bs#1\!!es] then - luatexbase.add_to_callback(\!!bs\c!pre_linebreak_filter\!!es, - packagedata.enigma.callbacks[ \!!bs#1\!!es], - \!!bs#1\!!es) + if packagedata.enigma and + packagedata.enigma.machines[ \!!bs#1\!!es] then + luatexbase.add_to_callback( + \!!bs\c!pre_linebreak_filter\!!es, + packagedata.enigma.callbacks[ \!!bs#1\!!es], + \!!bs#1\!!es) else print\!!bs ENIGMA: No machine of that name: #1!\!!es os.exit() @@ -98,7 +102,9 @@ \@EA\gdef\csname stop\current_enigma_id\endcsname{% \endgraf \directlua{ - luatexbase.remove_from_callback(\!!bs\c!pre_linebreak_filter\!!es, \!!bs#1\!!es) + luatexbase.remove_from_callback( + \!!bs\c!pre_linebreak_filter\!!es, + \!!bs#1\!!es) packagedata.enigma.machines[ \!!bs#1\!!es]:processed_chars() }% \egroup% @@ -118,4 +124,4 @@ \catcode`\_=8 % \popcatcodes \catcode`\!=12 % reserved according to source2e \ifenigmaisrunningplain\catcode`\@=12\fi -% vim:ft=tex:sw=2:ts=2:expandtab:tw=72 +% vim:ft=tex:sw=2:ts=2:expandtab:tw=71 |