expanded documentation

1 files changed, 127 insertions, 29 deletions

diff --git a/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex b/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex
index 86b1653..7e56d9b 100644
--- a/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex
+++ b/doc/context/third/cyrillicnumbers/cyrillicnumbers.tex
@@ -186,7 +186,7 @@
 
 \setuppapersize[LHS][LHS]
 
-%\showframe
+% \showframe
 \setuplayout [
     width=122mm,
     %textheight=199mm, % ca. 47 rows * 12pt
@@ -209,8 +209,8 @@
     leftmargin=16mm,
     leftmargindistance=1em,
     %
-    rightmargin=20mm,
-    rightmargindistance=2mm,
+    rightmargin=15mm,
+    rightmargindistance=5mm,
     rightedge=0mm,
     rightedgedistance=0mm,
 ]
@@ -328,15 +328,17 @@
 
 %%% loosely based on: http://archive.contextgarden.net/message/20110804.141422.6e52d0bc.en.html
 \define[1]\marginhintbox{%
-  \toplinebox{\rotate{\tfx\tt #1}}%
+  \toplinebox{\rotate{#1}}%
+  % \toplinebox{\rotate{\framed{#1}}}%
 }
 
-\definemargindata[marginhint][inmargin][%
-  style={\ss\tfx},
-  location=inner,
+\definemargindata[marginhint][%
+  style={\tfx\tt},
+  location=outer,
   align=outer,
+  margin=margin,
   command=\marginhintbox,
-  % stack=yes,
+  stack=yes,
 ]
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -533,7 +535,69 @@
   context(table.concat(tab))
 \stopbuffer
 
-\starttext
+\defineframed[showcaseframed][
+  frame=off,
+  loffset=3pt,
+  roffset=\framedparameter{loffset},
+  toffset=\framedparameter{loffset},
+  boffset=\framedparameter{loffset},
+  background=color,
+  backgroundcolor=gray92,
+]
+\startbuffer[titloshowcase]%
+% \placefigure[right,2*hang][mptitlodemo]{Titlo as a matter of taste.}{%
+% \placefigure[][mptitlodemo]{Titlo as a matter of taste.}{%
+\placefigure[top][mptitlodemo]{Titlo as a matter of taste.}{%
+  \showcaseframed[
+    width=\hsize,
+    roffset=\framedparameter{loffset},
+    toffset=6pt,
+  ]{%
+    \tfc%
+    \dorecurse{9}{\normaltextcyrnum[titlo=mp,titlocolor=darkmagenta,titlomode=\recurselevel]{42}%
+                  \ifnum\recurselevel=9\else\hfill\fi}%
+  }%
+}%
+\stopbuffer
+
+\startbuffer[titlospanshowcase]%
+\placefigure[left][titlospandemo]{Different titlo spans.}{%
+  \showcaseframed[width=.333\hsize,align=left]{%
+    \type{titlospan}\hfill result\par
+    \dorecurse{6}{%
+      \recurselevel
+      \hfill
+      \normaltextcyrnum[titlo=mp,titlomode=1,titlocolor=darkmagenta,titlospan=\recurselevel]{424242}%
+      \ifnum\recurselevel<6\par\fi%
+    }
+  }%
+}%
+\stopbuffer
+
+\startbuffer[penwidthshowcase]%
+\start\setuptolerance[horizontal,tolerant,stretch]%
+% \placetable[left][penwidthdemo]{Comparison of different values for the parameter \type{penwidth}.}{%
+\placetable[bottom,left][penwidthdemo]{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%
+}%
+\stopbuffer
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\starttext                                                      %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \startfrontmatter
 \setuplayout [width=middle]
@@ -741,7 +805,7 @@ 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
+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
@@ -834,32 +898,66 @@ Normal text \cyrnum{42} \dots
 \stoptyping
 
 Naturally, the \type{command} may do anything that fits inside a
-one-argument macro, from coloring (\rednum{42}) to case
+one-argument macro, from coloring (\rednum[titlo=no]{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.
+The key \type{titlo} controls the placement and, if applicable,
+placement method of the
+\cyrnumdrawtitlo{\te{titlo}}.\marginhint{titlo}
+The two valid method identifiers are {\italic mp} and {\italic
+font}, everything else will be interpreted as {\italic no}, e.~g.
+the titlo will be omitted.
+The latter method, {\italic font}, takes the titlo glyph as
+supplied by the font file (code point U+483).
+The main drawback of this solution is that to my knowledge the
+font titla are designed to span a single char only.
+As the titlo belongs to the class of combining characters, in the
+stream of unicode glyphs it will be \te{appended} to the
+character above which it is placed.
+Thus, multi-digit Cyrillic numbers (i.~e. essentially any number
+with two or more non-zero digits) won’t be represented in an
+optimal way: \normaltextcyrnum[titlo=font]{42}.
+
+\getbuffer[titloshowcase]
+\getbuffer[titlospanshowcase]\indentation An alternative to the
+font titlo is provided by the {\italic mp} variant which uses
+\METAPOST\ to actually \te{draw} a titlo above the string of
+digits.
+Not only does this titlo cover the entire numeral, it also comes
+in a variety of drawing routines.
+At the moment there are nine more or less different titlos you
+may choose from as demonstrated in \in{figure}[mptitlodemo].\marginhint{titlomode,titlospan}
+These can be enabled on via the \type{titlomode} key.
+The range of digits to be covered by the titlo can be customized
+by passing the parameter \type{titlospan} an integer.
+The default value of 3 results in the titlo spanning at maximum the
+least significant three digits, because these won’t be prefixed
+by a thousands sign.
+If the user wants the numeral to be covered as a whole, E can
+simply pass the value {\italic all}.
+Beware that the dimensions of the titlo are proportional to the
+width of the numeral.
+Therefore, sufficiently wide (in terms of non-zero digits)
+numbers will cause the titlo to shrink horizontally as seen in
+\in{figure}[titlospandemo].
+E.~g. for the single digit number
+\normaltextcyrnum[titlo=mp,titlomode=5]{1} the titlo even exceeds
+the character it sits on, while it does not entirely cover the
+five digits plus two thousand signs of
+\normaltextcyrnum[titlo=mp,titlospan=all,titlomode=5]{54321}.
+When using the {\italic mp} titlo the color of this element can
+be chosen separately by passing a valid color identifier to the
+\type{titlocolor} key.\marginhint{titlocolor}
+
+\indentation The \METAPOST\ drawing options have separate keys.\marginhint{penwidth}
 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.
+See the table \about[penwidthdemo] for a demonstration of
+different values for this parameter.
+\getbuffer[penwidthshowcase]
 
 \stop