docstrings; interface redone

1 files changed, 28 insertions, 27 deletions

diff --git a/t-letterspace.mkiv b/t-letterspace.mkiv
index 4811ee5..ff90f06 100644
--- a/t-letterspace.mkiv
+++ b/t-letterspace.mkiv
@@ -15,6 +15,8 @@
 
 \startinterface all
   \setinterfacevariable {letterspace} {letterspace}
+  \setinterfacevariable {spacefactor} {spacefactor}
+  \setinterfacevariable {spaceskip}   {spaceskip}
 \stopinterface
 
 \unprotect
@@ -27,7 +29,7 @@
   setup=list,
   style=no,
   type=module,
-  version=hg,
+  version=hg-rev:3+,
 ]
 
 %D \macros
@@ -39,7 +41,7 @@
 %D You’ll have to thank him if it works and blame me if it doesn’t.
 
 \appendtoks
-  \setuevalue{\currentletterspace}{\doletterspace [\currentletterspace]}%
+  \setuevalue{\currentletterspace        }{\doletterspace[\currentletterspace]}%
   \setuevalue{\e!start\currentletterspace}{\dostartletterspace[\currentletterspace]}%
   \setuevalue{\e!stop \currentletterspace}{\dostopletterspace}%
 \to \everydefineletterspace
@@ -66,8 +68,8 @@
   \setupcharacterkerning[letterspace:current][factor=\letterspaceparameter{spacefactor}]%
   \def\letterspace_setstuff{%
     \setcharacterkerning[letterspace:current]%
-    \advance \spaceskip  \letterspaceparameter{textskip}%
-    \advance \xspaceskip \letterspaceparameter{textskip}%
+    \advance \spaceskip  \letterspaceparameter{spaceskip}%
+    \advance \xspaceskip \letterspaceparameter{spaceskip}%
   }%
   \ifhmode\ifnum\lastnodetype=\@@gluenode
       \unskip{\letterspace_setstuff\ }%
@@ -85,6 +87,14 @@
 %D \useURL [flet] [http://www.tug.org/TUGboat/Articles/tb09-3/tb22bechtolsheim.pdf] [] [\type{futurelet}]
 %D Very helpful for further understanding of what’s exactly going
 %D on: Stephan von Bechtolsheim’s tutorial on \from[flet].
+%D
+%D In short: the trick checking whether the token following the
+%D command is a space, that is: whether it expands to
+%D \type{\blankspace}. If the test succeeds, a space will be
+%D added that has the correct parameters and all space tokens
+%D following the command will be gobbled. Otherwise -- the next
+%D token being anything else -- \type{\letterspace} will proceed
+%D without changing anything.
 
 \def\doifnextspace#1{%
   \def\!!string{#1}%
@@ -102,6 +112,9 @@
 %D
 %D These rely even more shamelessly on \from[wschuster]’s code
 %D from the {\em fancybreak} module.
+%D
+%D The \type{\[start|stop]letterspace} environment is provided
+%D for sake of completeness.
 
 \unexpanded\def\dostartletterspace[#1]{%
   \edef\currentletterspace{#1}%
@@ -121,33 +134,21 @@
 %D    {setupletterspace}
 %D
 %D Initial setup.
-%D Setting the normal inline letterspacing factor
-%D \type{textfactor} and a separate factor for capital spacing
-%D \type{capfactor}.
-
-
-\setupletterspace [%
-  capfactor=.05,
-  capskip=.33em,
-  textfactor=.125,
-  textskip=.33em,
-  shortcommands=false, % “true” | “yes” | “yep” -- defaults to “false”
+%D The factor by which the {\em letter space} (i.e. space between
+%D glyphs) will be increased is specified via the
+%D \type{spacefactor} key.
+%D Additionally, it is wise with respect to legibility to enlarge
+%D the {\em interword space} as well. That is what the
+%D \type{spaceskip} key is for. The {\em spaceskip} should be an
+%D ordinary dimension.
+
+\setupletterspace [
+  \v!spacefactor=.125,
+  \v!spaceskip=.5em,
 ]
 
 \defineletterspace[\v!letterspace]
 
-\def\letterspace_truestrings{true,yep,yes}
-
-\def\letterspace_define_shortcommands{%
-  \doifinset{\letterspaceparameter{shortcommands}}{\letterspace_truestrings}{%
-    \writestatus{letterspace}{enabling short commands}%
-    %\global\let\CS\capitalspace%
-    \global\let\LS\letterspace%
-  }%
-}
-
-\appendtoks \letterspace_define_shortcommands \to \everystarttext
-
 \protect \stopmodule \endinput
 
 % vim:ft=context:sw=2:ts=2