expanded documentation

3 files changed, 219 insertions, 19 deletions

diff --git a/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex b/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex
index 3206522..86b1653 100644
--- a/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex
+++ b/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex
@@ -9,6 +9,10 @@
   titlo=no,
 ]
 
+\definecyrnum[rednum][
+  command={\switchtocolor[red]},
+]
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Letterspacing / emphases                                      %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -114,7 +118,14 @@
 \def\greek     #1{\begingroup\language[agr]\setupbodyfont[computer-modern-unicode]#1\endgroup}
 
 \usetypescript [modern]
-\setupbodyfont [modern]
+\starttypescript [mymodern]
+  \definetypeface [mymodern] [rm] [serif] [modern]                  [default]
+  \definetypeface [mymodern] [tt] [mono]  [computer-modern-unicode] [default]
+\stoptypescript %% this will do as lm and cmu are acceptably similar
+\usetypescript [mymodern]
+\setupbodyfont [mymodern]
+
+% \setupbodyfont [modern]
 % \usetypescript [antykwa-poltawskiego]
 % \setupbodyfont [antykwa-poltawskiego,10pt]
 
@@ -127,12 +138,15 @@
 \def\uprightslash{\bgroup\tf/\egroup}
 \def\uprightomiss{\bgroup\tf[\dots]\egroup}
 
+% \setuptyping[style=\tfx\sans]
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Presenting the Interface                                      %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \usemodule  [int-load]
 \loadsetups [t-cyrillicnumbers.xml]
+\setupcolor [x11]
 
 \define\beautifyshowsetups{%
   \unexpanded\def\setupnumfont  {\rm}%
@@ -145,7 +159,7 @@
   \defineframedtext [setuptext] [
     frame=off,
     background=color,
-    backgroundcolor=gray:2,
+    backgroundcolor=gray92,
     width=\hsize,
     height=fit,
     align=right,
@@ -301,7 +315,7 @@
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% header and footers                                            %
+% Header and Footers                                            %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \setupfooter[text][% handy for occasional pagenumbers in footnotes at chapters
@@ -309,6 +323,23 @@
 ]
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Margins                                                       %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%% loosely based on: http://archive.contextgarden.net/message/20110804.141422.6e52d0bc.en.html
+\define[1]\marginhintbox{%
+  \toplinebox{\rotate{\tfx\tt #1}}%
+}
+
+\definemargindata[marginhint][inmargin][%
+  style={\ss\tfx},
+  location=inner,
+  align=outer,
+  command=\marginhintbox,
+  % stack=yes,
+]
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % ToC                                                           %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -395,18 +426,33 @@
   after=\stopnarrower,
 ]
 
-\unexpanded\def\ctay#1{\cite[authoryear][#1]}
+\def\ctay#1{\cite[authoryear][#1]}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Bib: Entries                                                  %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \startpublication [
+  k=fonts,
+  t=book, % bibtex go to hell
+  a={Hagen/Hoekwater},
+  y=2011,
+  n=1,
+  s={Fonts},
+]
+  \author[]{Hans}[]{}{Hagen}
+  \author[]{Taco}[]{}{Hoekwater}
+  \pubyear{2011}
+  \title{Fonts in \CONTEXT}
+  \city{Hasselt}
+\stoppublication
+
+\startpublication [
   k=trunte,
   t=inproceedings, % bibtex go to hell
   a={Trunte},
   y=2005,
-  n=1,
+  n=2,
   s={Altkirchenslavisch},
 ]
   \author[]{Nikolaos H.}[]{}{Trunte}
@@ -424,7 +470,7 @@
   t=inproceedings,
   a={Žolobov},
   y=2006,
-  n=2,
+  n=3,
   s={Čislitelʹnye},
 ]
   \author[]{O. F.}[]{}{Žolobov}
@@ -447,8 +493,14 @@
 
 \setupindenting [yes,next,medium]
 
-\useURL [leibnizausgabe] [http://www.leibniz-edition.de/Baende/] [] [\name{Leibniz}-Edition]
-\useURL [soulpackage] [http://ctan.larsko.net/macros/latex/contrib/soul/] [] [soul]
+\useURL [petr]         [http://www.paratype.ru/e-zine/issue04/peter1/peter1a.htm] [] [\hyphenatedurl{http://www.paratype.ru/e-zine/issue04/peter1/peter1a.htm}]
+\useURL [reform1917]   [http://ru.wikipedia.org/wiki/Реформа_русской_орфографии_1918_года] [] [\hyphenatedurl{http://ru.wikipedia.org/wiki/Реформа_русской_орфографии_1918_года}]
+
+\useURL [pttypescript] [http://archive.contextgarden.net/message/20110105.204326.d0228ca7.en.html]
+
+\useURL [phg-mail]     [mailto:gesang@stud.uni-heidelberg.de] [] [\hyphenatedurl{gesang@stud.uni-heidelberg.de}]
+\useURL [phg-bibu]     [https://bitbucket.org/phg/]    [] []
+
 
 \pdfcompresslevel9
 
@@ -502,9 +554,6 @@
 
 \page
 
-\useURL [phg-mail] [mailto:gesang@stud.uni-heidelberg.de] [] [\hyphenatedurl{gesang@stud.uni-heidelberg.de}]
-\useURL [phg-bibu] [https://bitbucket.org/phg/]    [] []
-
 % \def\cyrillicalphabet{%
 %   А,Б,В,Г,Д,Е,Ж,Ѕ,ʐ,И,І,К,Л,М,Н,О,П,Р,С,Т,ОУ,Ф,%
 %   Х,Ѡ,Ц,Ч,Ш,Щ,Ъ,Ы,Ь,Ѣ,Ю,Ι,Ѥ,Ѧ,Ѫ,Ѩ,Ѭ,Ѯ,Ѱ,Ѳ,Ѵ,%
@@ -674,27 +723,175 @@ maintain different conversion settings for different purposes.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \startchapter[reference=functionality,title=Functionality]
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Default Command}
+\startsection[title=Setup]
+
+The module is initialized as any other:
+
+\starttyping
+\usemodule[cyrillicnumbers]
+\stoptyping
+
+Once the module code is loaded, the \te{setup} command provides
+means to configure all the functionality it offers.
+
+\showsetup{setupcyrnum}
+
+Let’s walk through the options one by one.\marginhint{dots}
+As was hinted in the introduction a common praxis is to delimit
+Cyrillic numbers with dots.
+Dot placement is enabled or disabled by setting the \type{dots}
+key to {\italic yes} or {\italic no} respectively.
+The \type{dotsymbol} key allows the user to supply a delimiter of eir
+own choice; it defaults to the character “·” (unicode
+U+00B7).\marginhint{dotsymbol}
+If a font doesn’t contain a glyph for this code point or for
+whatever reason another symbol is required, the solution will
+look like this: \type{\setupcyrnum[dots=yes,dotsymbol=\cdot]}.
+The result of this modification looks as follows:
+\normaltextcyrnum[dots=yes,dotsymbol=\cdot]{42}.
+As the dot can be an arbitrary symbol, it could be replaced by
+the asterisk: \normaltextcyrnum[dots=yes,dotsymbol=*]{42}, or --
+even weirder -- the hash character (“Gartenzaun”):
+\normaltextcyrnum[dots=yes,dotsymbol=\#]{42}.
+
+In order to notate the sixth decimal digit (for multiples of one
+hundred million) there are two mutually excluding
+options\marginhint{preferhundredk}: either the hundred thousands
+sign or the thousands prefix may be employed.
+Thus, the setup key \type{preferhundredk} determines which one
+will be chosen. If set to {\italic yes}, then it’s going to be
+the houndred thousands sign, else the regular thousands sign:
+\normaltextcyrnum[preferhundredk=yes]{900000} $=$
+\normaltextcyrnum[preferhundredk=no] {200000} $+$
+\normaltextcyrnum[preferhundredk=no] {700000}.
+(As is obvious from this example, the visual quality of the
+houndred thousands sign, which is a separate glyph, depends on
+the font used.)
+
+Not every font contains proper glyphs for the entire Cyrillic
+unicode range, in fact every dedicated font for one Cyrillic
+alphabet -- Russian, say -- might not contain all the characters
+needed to represent every Cyrillic numeral.\marginhint{command}
+This is the result of the historical development the respective
+scripts went through.
+This process usually lead to the elimination of several glyphs at
+different stages of the development.
+For example the Russian alphabet experienced one significant
+reduction of letters at the hand of emperor Peter~I\footnote{%
+  For an overview cf. \from[petr] or just google
+  \quotation{\russian{гражданский шрифт}}.
+}
+and another one later in 1917 as a consequence of -- not only --
+the revolution.\footnote{%
+  Cf. \from[reform1917].
+}
+Thus, chances are that in order to represent Cyrillic numbers,
+which rely on a superset of the modern Russian alphabet, another
+font needs to be chosen.\footnote{%
+  Font fallbacks are another option if the substitutes match the
+  main font typographically; see \ctay{fonts}, pp. 97--99.
+}
+The Cyrillic Numbers module provides a hook for this kind of
+customization: you may define your own font switching macro and
+assign it to the \type{command} key of the setup.
+Suppose you decide to typeset your numbers using the Paratype
+Serif font.\footnote{%
+  A typescript can be found on the \CONTEXT\ mailing list:
+  \from[pttypescript]. Keep in mind that ParaType Serif itself is
+  not a particularly suitable number font as it does not contain
+  all required glyphs.
+}
+
+\starttyping
+
+%%% 1. Load the module and the font.
+\usemodule         [cyrillicnumbers]
+\usetypescriptfile [type-paratype.mkiv]
+
+%%% 2. Define the font and a command that switches to it.
+\definetypeface [numberfont] [rm]      [serif]
+                [paratype]   [default] []
+\unexpanded\define[1]\numbercommand{%
+  \begingroup
+    \language[ru]%
+    \setupbodyfont[numberfont]%
+    #1%
+  \endgroup%
+}
+
+%%% 3. Hook the command into our converter.
+\setupcyrnum [dots=yes,command=\numbercommand]
+
+%%% 4. Use as needed.
+\starttext
+Normal text \cyrnum{42} \dots
+\stoptext
+
+%%% 5. ????
+
+%%% 6. Profit!!!!!
+
+\stoptyping
+
+Naturally, the \type{command} may do anything that fits inside a
+one-argument macro, from coloring (\rednum{42}) to case
+manipulation
+(\normaltextcyrnum[command=\WORD\oldrussian]{42}).
+
+\start\setuptolerance[horizontal,tolerant,stretch]
+\placetable[left][]{Comparison of different values for the parameter \type{penwidth}.}{%
+  \starttabulate[|r|r|l|r|r|l|]%% tabulate sucks hard, just try to use it with a macro that contains a numberconversion and you’ll know why
+    \let\lp\letterpercent
+    \startluacode
+      local max      = 10
+      local step     = .2
+      local dimleft  = .4
+      local f_row = [[\NC \lp d \NC \lp .3fpt \NC \cyrnum[penwidth=\lp dpt]{\lp d} \NC \lp d \NC \lp .3fpt \NC \cyrnum[penwidth=\lp dpt]{\lp d} \AR]]
+      for i=1, max do
+        dimleft = dimleft + step
+        local dimright = dimleft + max * step
+        context(string.format(f_row, i, dimleft, dimleft, i, i+4200, dimright, dimright, i+4200))
+      end
+    \stopluacode
+  \stoptabulate
+}
+The \METAPOST\ drawing options have separate keys.
+Of these, \type{penwidth} rather obviously determines the width
+of the pen that is used when drawing a titlo.
+Finding the optimal width can involve a lot of testing;
+as a rule, the bigger the font, the wider the pen should be.
+
+\stop
+
+\stopsection
+
+\startsection[title=Predefined Commands]
+
 \showsetup{cyrnum}
 \showsetup{cyrnumdrawtitlo}
 
 % \cyrnumdrawtitlo{foobar}
+\stopsection
 
-\section{Customized Commands}
-\showsetup{setupcyrnum}
+\startsection[title=Command Derivation]
 \showsetup{definecyrnum}
 
+\stopsection
+
 \stopchapter
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \startchapter[reference=usage,title=Usage and Precautions]
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{Counters}
+\startsection[title=Counters]
+\stopsection
 
-\section{The Titlo}
+\startsection[title=The Titlo]
+\stopsection
 
-\section{Font Issues}
+\startsection[title=Font Issues]
+\stopsection
 
 \stopchapter
 
diff --git a/tex/context/interface/third/t-cyrillicnumbers.xml b/tex/context/interface/third/t-cyrillicnumbers.xml
index b94befc..71d79af 100644
--- a/tex/context/interface/third/t-cyrillicnumbers.xml
+++ b/tex/context/interface/third/t-cyrillicnumbers.xml
@@ -24,6 +24,9 @@
         <cd:constant type="cd:name"/>
       </cd:keywords>
       <cd:assignments n="2" list="yes" optional="no">
+        <cd:parameter name="command">
+          <cd:constant type="cd:oneargument"/>
+        </cd:parameter>
         <cd:parameter name="dots">
           <cd:constant type="no"/>
           <cd:constant type="yes" default="yes"/>
diff --git a/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv b/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv
index c13b00d..e087a43 100644
--- a/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv
+++ b/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv
@@ -70,7 +70,7 @@
     tc.titlolocation = tc.position_synonyms["\cyrnumparameter{\v!titlolocation}"]   or "f"
     tc.prefer100k    = tc.     yes_synonyms["\cyrnumparameter{\v!preferhundredk}"]  or false
     tc.drawdots      = tc.     yes_synonyms["\cyrnumparameter{\v!dots}"]            or false
-    tc.dotsymbol     = "\cyrnumparameter{\v!dotsymbol}"
+    tc.dotsymbol     = "\luaescapestring{\cyrnumparameter{\v!dotsymbol}}"
 
     local span   = "\cyrnumparameter{\v!titlospan}"
     local num = tonumber(span)
@@ -383,7 +383,7 @@
 }
 
 \def\dodo_cyrnum[#1]{%
-  \begingroup%
+  \begingroup
   \setupcyrnum[\currentcyrnum][#1]%
   \cyrnumparameter{command}\begingroup%
   \dododo_cyrnum%