summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilipp Gesang <gesang@stud.uni-heidelberg.de>2012-06-08 11:50:01 +0200
committerPhilipp Gesang <gesang@stud.uni-heidelberg.de>2012-06-08 11:50:01 +0200
commita907ca78f3043cc3eb450d8062ea60d0abd05a10 (patch)
tree7115875064c94b041fa4fdf206a896c0b4fbf9ab
parentb270c9e7f3e23feee7d152afbf5f9ac04cc5acfd (diff)
downloadenigma-a907ca78f3043cc3eb450d8062ea60d0abd05a10.tar.gz
[doc] setups for n00bs
-rw-r--r--doc/context/third/enigma/enigma_manual.tex77
-rw-r--r--doc/context/third/enigma/examples/enigma-example-plain.tex2
2 files changed, 73 insertions, 6 deletions
diff --git a/doc/context/third/enigma/enigma_manual.tex b/doc/context/third/enigma/enigma_manual.tex
index f088867..2add2d1 100644
--- a/doc/context/third/enigma/enigma_manual.tex
+++ b/doc/context/third/enigma/enigma_manual.tex
@@ -19,11 +19,77 @@
\startdocsection[title=Loading the Module/Package]
\startdocsubsection
\TODO{instuctions for plain, latex + ctx}
- The
+ The intention is for the \modulename{Enigma} codebase to integrate
+ with the three most popular (as of 2012) \TEX\ formats:
+ \CONTEXT,
+ \PLAIN, and
+ \LATEX.
+ If the user interface does not fully conform with the common practise
+ of the latter two, please be lenient toward the author whose
+ 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.
+ 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.
+ (There are no package options.)
+ From this point on, instructions for both formats are the same.
+
+ The interface provides two basic macros from which all functionality
+ 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
+ \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
+ \texmacro{setupenigma} it.
+ The former takes a single, the latter a double argument.
+ Thus, \type{\defineenigma{encrypt}} creates a new environment
+ consisting of the macros \texmacro{startencrypt} and
+ \texmacro{stopencrypt}.%
+ \footnote{%
+ \CONTEXT-users will have noticed that there is no simple macro
+ \type{\encrypt{foo}}. The reason for this is that the callback
+ which the module relies on operates on node-level.
+ This means that for the Enigma encryption to have an effect it will
+ 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
+ (\ichdparameter{email}).
+ }
+ However, these are not usable right away, as we still have to set the
+ initial state of the machine.
+ This is achieved by the second meta-macro,
+ \type{\setupenigma{encrypt}{<args>}}, where \type{<args>} is a
+ placeholder for a list of \emph{assignments}, i.\,e. pairs of
+ \emph{key=value} statements by means of which all further parameters
+ are specified.
+ A list of possible parameters can be found in the next section,
+ 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>} --
+ \type{\setup<foo>} macros, then congratulations are in order:
+ you qualify for migration from your current macro package to
+ \CONTEXT.
+ }
\stopdocsubsection
\stopdocsection
-\startdocsection[title=Options Explained]
+\startdocsection[title=Options Explained,reference=sec:opts]
\startitemize
\let\olditem\item
@@ -65,8 +131,9 @@ default behaviour is to drop alien letters and move on. If the user
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 thing being equal, is given in below listing
-(example for \CONTEXT).
+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).
\startcontexttyping
\usemodule [enigma]
@@ -100,7 +167,7 @@ information about the structure of the plain text.
\stopdocsection
-\startdocsection[title=Basic Functionality]
+\startdocsection[title=Basic Functionality,reference=sec:fun]
Encrypt the text of your document using the script interface. For
a start try out the settings as given in below listing.
diff --git a/doc/context/third/enigma/examples/enigma-example-plain.tex b/doc/context/third/enigma/examples/enigma-example-plain.tex
index d731c7d..87ce9b1 100644
--- a/doc/context/third/enigma/examples/enigma-example-plain.tex
+++ b/doc/context/third/enigma/examples/enigma-example-plain.tex
@@ -1,5 +1,5 @@
\parindent0pt
-%······································································%
+%%·····································································%
\input {enigma}
%%·····································································%
%% The first machine will be used for encryption of our plain text.