man: setup and define letterspacing macros

3 files changed, 158 insertions, 21 deletions

diff --git a/letterspace.tex b/letterspace.tex
index 6e80459..0e9d472 100644
--- a/letterspace.tex
+++ b/letterspace.tex
@@ -2,28 +2,35 @@
 
 \defineletterspace [largecaps]
 \setupletterspace  [largecaps] [
-  spacefactor=.2,
+  factor=.2,
   spaceskip=.3em,
   suppresskern=yes,
 ]
 
 \defineletterspace [mediumcaps]
 \setupletterspace  [mediumcaps] [
-  spacefactor=.25,
+  factor=.25,
   spaceskip=.5em,
   suppresskern=yes,
 ]
 
 \defineletterspace [smallcaps]
 \setupletterspace  [smallcaps] [
-  spacefactor=.05,
+  factor=.05,
   spaceskip=.25em,
-  suppresskern=no,
+  suppresskern=yes,
 ]
 
 \defineletterspace [textemph]
 \setupletterspace  [textemph] [
-  spacefactor=.125,
+  factor=.125,
+  spaceskip=.33em,
+  suppresskern=no,
+]
+
+\defineletterspace [slightly]
+\setupletterspace  [slightly] [
+  factor=.075,
   spaceskip=.33em,
   suppresskern=no,
 ]
@@ -33,7 +40,7 @@
 
 \defineletterspace [ugly]
 \setupletterspace  [ugly] [
-  spacefactor=.4,
+  factor=.4,
   spaceskip=1em,
   suppresskern=no,
 ]
@@ -51,8 +58,11 @@
   onum=yes,
   dlig=yes,
   liga=yes,
+  kern=yes,
 ]
 
+\definefontfeature [kerning] [kern=yes]%
+
 \usetypescript [modern]
 \usetypescript [antykwa-poltawskiego]
 \setupbodyfont [antykwa-poltawskiego,10pt]
@@ -173,9 +183,9 @@
 \defineletterspace [LSchapter]
 \defineletterspace [LSsection]
 \defineletterspace [LSsubsection]
-\setupletterspace  [LSchapter]    [spacefactor=.1,  spaceskip=.33em]
-\setupletterspace  [LSsection]    [spacefactor=.15, spaceskip=.40em]
-\setupletterspace  [LSsubsection] [spacefactor=.125,spaceskip=.33em]
+\setupletterspace  [LSchapter]    [factor=.1,  spaceskip=.33em]
+\setupletterspace  [LSsection]    [factor=.15, spaceskip=.40em]
+\setupletterspace  [LSsubsection] [factor=.125,spaceskip=.33em]
 
 \def   \fontchapter#1{\setupbodyfont[11pt]\WORD\LSchapter{#1}}
 \def   \fontsection#1{\setupbodyfont[11pt]\word\sc\LSsection{#1}}
@@ -225,7 +235,8 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \def   \tocfontchapter#1{\WORD\LSchapter{#1}}
-\def   \tocfontsection#1{\word\sc\LSsection{#1}}
+%\def   \tocfontsection#1{\word\sc\LSsection{#1}}
+\def   \tocfontsection#1{\slightly{#1}}
 \def\tocfontsubsection#1{\LSsubsection{#1}}
 
 \setuplist [chapter] [
@@ -367,6 +378,9 @@
 
 \setupindenting [yes,next,medium]
 
+\useURL [leibnizausgabe] [http://www.leibniz-edition.de/Baende/] [] [Leibniz-Edition]
+\useURL [soulpackage] [http://ctan.larsko.net/macros/latex/contrib/soul/] [] [soul]
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Makeup for Front Matter                                       %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -446,17 +460,123 @@ This module is partly a reaction on the excellent article the
 last quotation was taken from, and partly the endeavour of a
 convinced \CONTEXT\ user and letter spacer to replace a number of
 kludges already in use with something more consistent.
+To be sure, those warnings are grounded in facts and they should
+seriously be taken into account before one resorts to
+letterspacing.
+
+Before the advent of \LUATEX\ the implementation of proper letter
+spacing in *\TEX\ proved to be extremely difficult.
+For instance, the \from [soulpackage] package provides some means
+but at the same time severely limits the content passed to
+macros.
+Nevertheless there are magnificent examples of letterspacing done
+right, like the \from [leibnizausgabe] by the Leibniz-Archiv in
+Hanover that has been typeset with \smallcaps{EDMAC} and \PDFTEX.
+Nowadays the Lua node library removes the technical restrictions
+and thus leaves the task of correct letterspacing to the user.
+The \te{Letterspace} module for \CONTEXT\ was designed to collect
+everything necessary to achieve this and to make it accessible
+from one place.
 
 \chapter{Commands}
 
+Technically, the \te{Letterspace} module doesn’t do anything
+fancy; it just maps some existing \CONTEXT\ macros into a single
+setup and lets you define and configure your own derivatives of
+it.
+The module is supposed to be loaded the regular way: somewhere
+before \type{\starttext} should be the line
+\starttyping
+\usemodule [letterspace]
+\stoptyping
+\noindentation-- That’s all.
+
 \section{Default Letterspace Command}
+Initially one letterspace command is already defined and
+configured, as well as a letterspacing environment.
+They are now ready for use in running text.
+
+%\definecolor [prettyone]   [r=.6,g=.6,b=.6]  % red
+%\definecolor [prettytwo]   [r=.0,g=.6,b=.6]  % green
+%\definecolor [prettythree] [r=.6,g=.6,b=.6]  % blue
+%\definecolor [prettyfour]  [r=.6,g=.6,b=.6]  % yellow
+
+%\startTEX
+\starttyping
+\usemodule [letterspace]
+\starttext
+
+\startlines
+  uides ut \letterspace{alta} stet \letterspace{niue} candidum
+  Soracte
+\stoplines
+
+\startletterspace
+  \startlines
+    hac {\italic ait} in Thebas, hac me iubet ardua uirtus
+    ire, Menoeceo qua lubrica sanguine turris.
+    experiar quid sacra iuuent, an falsus Apollo.
+  \stoplines
+\stopletterspace
+
+\stoptext
+\stoptyping
+%\stopTEX
 
 \showsetup{letterspace}
 \showsetup{startletterspace}
 
 \section{Defining and Customizing Letterspace Commands}
 
+The \te{Letterspace} module allows the letterspacing to be
+adjusted via \te{three} parameters.
+The \type{factor} determines the value by which the
+\te{intra}word spacing (between letters) will be extended.
+\type{spaceskip} specifies a dimension for the \te{inter}word
+spacing and, if applicable, the surrounding spaces.
+\type{suppresskern} allows for disabling the letter kerning which
+can improve the spacing of capitals (see below,
+\at{p.}[suppresskern]).
+
+The following lines reconfigure the predefined
+\type{\letterspace} macro to behave in an extreme fashion.
+\starttyping
+\setupletterspace [
+  factor=2,       % default: 0.125
+  spaceskip=2em,  % default: 0.5em
+]
+
+\letterspace{vapula!}
+\stoptyping
 \showsetup{setupletterspace}
+
+The recommended alternative to constantly readjusting the base
+command is to define separate macros for different purposes.
+
+\starttyping
+\defineletterspace [LSbighead]
+\defineletterspace [LSemphasis]
+\defineletterspace [LSsmcp]
+
+\setupletterspace [LSbighead]  [factor=.2,   spaceskip=.7em, suppresskern=yes]
+\setupletterspace [LSemphasis] [factor=.111, spaceskip=.4em, suppresskern=no,]
+\setupletterspace [LSsmcp]     [factor=.06,  spaceskip=.4em, suppresskern=no,]
+
+\LSbighead{\bf\WORD This is a candidate for sectioning, innit?}
+\blank [line]
+
+\startlines
+  terrarum delicta nec exsaturabile \LSsmcp{\sc Diris}
+  \LSemphasis{ingenium mortale} queror, quonam usque nocentum
+  exigar in poenas! taedet saeuire corusco
+  fulmine.
+\stoplines
+\stoptyping
+
+These macros can subsequently accessed from whatever markup
+element requires letterspacing: section titles, front matter
+makeup, emphasis etc.
+
 \showsetup{defineletterspace}
 
 \chapter{Applications}
@@ -573,7 +693,7 @@ It follows, that in the foregoing mapping, parts of longer
 However, substituting rule {\it2} for {\it3}, the resulting
 mapping will be less satisfactory.
 As quotations are prone to extending over multiple lines, whereas
-normal emphasis rarely spans more than two words, letter spacing
+normal emphasis rarely spans more than two words, spacing out
 the former might lead to the unbalanced appearance of paragraphs.
 So best avoid letterspacing in cases where the object possibly
 encompasses entire sentences.
@@ -594,17 +714,17 @@ good: \te{O Tite,} tute, \te{Tati,} tibi tanta, \te{tyranne,} tulisti.)
 \section{Capital Spacing}
 \startbuffer [display:capitals]
   \start%
-  \setupbodyfont [modern,12pt]%
+  %\setupbodyfont [modern,11pt]%
+  \setupbodyfont [11pt]%
   \framed[
     align=middle,
     background=color,
-    backgroundcolor=gray:1,
+    backgroundcolor=gray:2,
     offset=1em,
     frame=off,
   ]{%
-      \def\teststring{pavaway}%
+      \def\teststring{mispavayatsim}%
       %\definefontfeature [capitals] [cpsp=yes,kern=yes]% how’s this supposed to work?
-      \definefontfeature [kerning] [kern=yes]%
       \bf%
       {\color[gray:7]\WORD\teststring}\par
       %{\setff{capitals}\WORD\teststring}\par % why doesn’t this have
@@ -616,7 +736,7 @@ good: \te{O Tite,} tute, \te{Tati,} tibi tanta, \te{tyranne,} tulisti.)
 \stopbuffer
 
 \starthangaround{\getbuffer [display:capitals]}
-Another natural use of letter spacing is to even out capitals and
+Another natural use of letter spacing is to space out capitals and
 small caps, whose legibility suffers with increasing markup
 length.
 The appearance of capitals can be influenced in various ways, as
@@ -629,6 +749,23 @@ The final row, as the second, lacks kerning and adds
 20\,\letterpercent\ letter spacing.
 \stophangaround
 
+As is apparent from the example, the difference in spacing
+particularly influences the outcome.
+The {\WORD unmodified text} in the first row is packed too
+tightly, whereas disabling the kerning results in irregular
+widening of the {\subff{kerning}\WORD previously kerned} letters
+near the center.
+In the third row the sequence looks much better because of
+additional \mediumcaps{\WORD letterspacing.}
+With some fonts \smallcaps{\sc small capitals} profit from additional
+spacing as well, as employed in the section headings of this
+document.\reference[suppresskern]{}
+The \te{Letterspace} module provides a switch \type{suppresskern}
+that, if set to {\it yes}, will disable kerning during
+letterspacing.
+This option is meant for the special treatment of capitalization
+but depending on the font it might equally help when dealing with
+emphasis as well.
 
 \title{References}
 
diff --git a/t-letterspace.mkiv b/t-letterspace.mkiv
index 0cdc7ac..ce3f026 100644
--- a/t-letterspace.mkiv
+++ b/t-letterspace.mkiv
@@ -19,7 +19,7 @@
 
 \startinterface all
   \setinterfacevariable {letterspace} {letterspace}
-  \setinterfacevariable {spacefactor} {spacefactor}
+  \setinterfacevariable {factor}      {factor}
   \setinterfacevariable {spaceskip}   {spaceskip}
   \setinterfacevariable {suppresskern}{suppresskern}
 \stopinterface
@@ -73,7 +73,7 @@
 \def\dododoletterspace#1{%
   \def\currentobject{#1}%
   \dontleavehmode
-  \setupcharacterkerning[letterspace:current][factor=\letterspaceparameter{spacefactor}]%
+  \setupcharacterkerning[letterspace:current][factor=\letterspaceparameter{factor}]%
   \def\letterspace_setstuff{%
     \setcharacterkerning[letterspace:current]%
     \advance \spaceskip  \letterspaceparameter{spaceskip}%
@@ -147,14 +147,14 @@
 %D Initial setup.
 %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 \type{factor} 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!factor=.125,
   \v!spaceskip=.5em,
   \v!suppresskern=false,
 ]
diff --git a/t-letterspace.xml b/t-letterspace.xml
index 955ebba..bac1f3f 100644
--- a/t-letterspace.xml
+++ b/t-letterspace.xml
@@ -14,7 +14,7 @@
         <cd:constant type="cd:name"/>
       </cd:keywords>
       <cd:assignments n="2" list="yes" optional="no">
-        <cd:parameter name="spacefactor">
+        <cd:parameter name="factor">
           <!-- Can’t inherit from “\setupcharacterkerning” because cont-en.xml
             still lacks that entry. -->
           <cd:constant type="cd:number" default=".125"/>