further documentation

3 files changed, 115 insertions, 33 deletions

diff --git a/tex/context/third/cyrillicnumbers/cyrillicnumbers.lua b/tex/context/third/cyrillicnumbers/cyrillicnumbers.lua
index 62c634d..f8f745b 100644
--- a/tex/context/third/cyrillicnumbers/cyrillicnumbers.lua
+++ b/tex/context/third/cyrillicnumbers/cyrillicnumbers.lua
@@ -10,20 +10,27 @@
 --------------------------------------------------------------------------------
 --
 
---- read this first:
----
---- Жолобов, О. Ф.: *Числительные*. In: *Историческая грамматика древнерусского
----                 языка*, vol. 4, Moskva 2006, pp. 58--63
----
---- Trunte, Nikolaos H.: *Altkirchenslavisch*. In: *Словѣньскъи ѩꙁъікъ.
----                      Ein praktisches Lehrbuch des Kirchenslavischen in 30
----                      Lektionen. Zugleich eine Einführung in die slavische
----                      Philologie*, vol. 1, München ⁵2005, pp. 161ff.
+--[[ldx--
+<p>read this first:</p>
+
+<p>Жолобов, О. Ф.: <key>Числительные</key>. In: <key>Историческая
+                   грамматика древнерусского языка</key>, vol. 4, Moskva
+                   2006, pp. 58--63</p>
+
+<p>Trunte, Nikolaos H.: <key>Altkirchenslavisch</key>. In:
+                        <key>Словѣньскъи ѩꙁъікъ.  Ein praktisches Lehrbuch
+                        des Kirchenslavischen in 30 Lektionen. Zugleich eine
+                        Einführung in die slavische Philologie</key>, vol.
+                        1, München ⁵2005, pp. 161ff.</p>
 
---- or have a glance at these:
---- http://www.pravpiter.ru/zads/n018/ta013.htm
---- http://www.uni-giessen.de/partosch/eurotex99/berdnikov2.pdf
---- <http://ru.wikipedia.org/wiki/Кириллическая_система_счисления>
+<p>or have a glance at these:</p>
+
+<typing>
+http://www.pravpiter.ru/zads/n018/ta013.htm
+http://www.uni-giessen.de/partosch/eurotex99/berdnikov2.pdf
+http://ru.wikipedia.org/wiki/Кириллическая_система_счисления
+</typing>
+--ldx]]--
 
 local iowrite     = io.write
 local mathceil    = math.ceil
diff --git a/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkii b/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkii
new file mode 100644
index 0000000..c3b955b
--- /dev/null
+++ b/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkii
@@ -0,0 +1,3 @@
+\writestatus{loading}{Cyrillic Number Support for ConTeXt}
+\writestatus{ERROR}  {The module “Cyrillic Numbers” does not support ConTeXt MkII.}
+\bye \endinput
diff --git a/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv b/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv
index 24e7b56..e187c66 100644
--- a/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv
+++ b/tex/context/third/cyrillicnumbers/t-cyrillicnumbers.mkiv
@@ -1,8 +1,8 @@
 %D \module
 %D   [     file=t-cyrillicnumbers,
-%D      version=2011-11-29 09:58:48+0100,
+%D      version=2012-01-27 14:04:10+0100,
 %D        title=\CONTEXT\ User Module,
-%D     subtitle=Cyrillic Number Module,
+%D     subtitle=Cyrillic Numbers,
 %D       author=Philipp Gesang,
 %D         date=\currentdate,
 %D    copyright=Philipp Gesang,
@@ -12,6 +12,17 @@
 %D two clauses. There is a copy in a file named "COPYING" in the
 %D t-cyrillicnumbers source tree.
 
+%M \definehead[docsection] [chapter]
+%M \setuphead [docsection] [page=no,style=\tf\bold\WORD,color=darkmagenta,alternative=inmargin,before={\blank[3*line]}]
+%M \definehead[doctitle]   [coupling=docsection,default=docsection,incrementnumber=no,page=no]
+%M \setuplist [docsection] [alternative=b,textstyle=\tf]
+%M \setupinteraction[focus=standard,color=darkmagenta]
+
+%D \doctitle{Overview}\placelist[docsection][criterium=all]\page[yes]
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%D \docsection{Global strings and namespace initialization}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \writestatus{loading}{Cyrillic Number Support for ConTeXt}
 
 \unprotect
@@ -41,8 +52,16 @@
     version=hg-tip,
 ]
 
+%D Loading the \LUA\ conversion routines.
+
 \registerctxluafile{cyrillicnumbers}
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%D \docsection{Setup command}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%D The\reference[setupdef]{} autogenerated setup command needs to
+%D be extended to pass values on to the \LUA\ end.
+
 \def\cyrnumsetvariables{%
   \startluacode
     local tc = thirddata.cyrnum
@@ -66,10 +85,40 @@
 \appendtoks \setuevalue{\currentcyrnum}{\do_cyrnum[\currentcyrnum]} \to \everydefinecyrnum
 \appendtoks \cyrnumsetvariables                                     \to \everysetupcyrnum
 
+%D This allows the module to be loaded with a second set of
+%D key-value arguments. If initialized as follows, additional debug
+%D information will be output on the terminal.
+%D
+%D \starttyping
+%D \usemodule[cyrillicnumbers][test=yes]
+%D \stoptyping
+
 \startmoduletestsection
   \ctxlua{thirddata.cyrnum.debug = true}
 \stopmoduletestsection
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%D \docsection{Titlo variants}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%D The {\em Cyrillic Numbers} module allows the titlo, if requested,
+%D to be drawn in two different ways. If the setup parameter
+%D \type{titlo} has the value {\em mp}, then the variant employing
+%D \METAPOST\ is selected. As there are a couple of different
+%D styles, it will be necessary that the user determine one by
+%D setting the parameter \type{titlomode} to an integer.
+%D Additionally it is possible to manipulate the pen width that
+%D \METAPOST\ uses when executing the titlo code. {\em NB} as the
+%D drawing routines differ, the \type{penwidth} parameter lead to
+%D different results with different modes as well, ymmv.
+%D 
+%D \starttyping
+%D \setupcyrnum[
+%D   titlo=mp,
+%D   titlomode=4,
+%D   penwidth=4,
+%D ]
+%D \stoptyping
+
 \startuniqueMPgraphic{cyrnum-titlo1}
   path titlo ;
   save High, Low ;
@@ -263,6 +312,12 @@
   setbounds currentpicture to boundingbox OverlayBox ;
 \stopuniqueMPgraphic
 
+%D The \METAPOST\ titlo is drawn as an overlay which in turn
+%D serves as the background for a dedicated \type{\framed} macro.
+%D This titlo command is accessible in protected mode as
+%D \type{\cyrnumdrawtitlo}, which is also called by the
+%D \LUA\ functions.
+
 \defineoverlay[cyrnum-titlo-overlay1][\uniqueMPgraphic{cyrnum-titlo1}]
 \defineoverlay[cyrnum-titlo-overlay2][\uniqueMPgraphic{cyrnum-titlo2}]
 \defineoverlay[cyrnum-titlo-overlay3][\uniqueMPgraphic{cyrnum-titlo3}]
@@ -279,22 +334,27 @@
   background=cyrnum-titlo-overlay\cyrnumparameter{titlomode},
 ]
 
-\def\Titlo{\dontleavehmode\cyrnum_titloframe}
+%D \macros
+%D   {cyrnumdrawtitlo}
+%D
+%D The macro \type{\cyrnumdrawtitlo} allows for arbitrary titlo
+%D placement which might be useful for other text elements besides
+%D plain numbers, e.~g. abbreviations {\italic\letterampersand}c.
 
-\let\cyrnumdrawtitlo\cyrnum_titloframe %% for protected context
+\let\cyrnumdrawtitlo\cyrnum_titloframe
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%D \subject{Interfacing with the Lua functions}
+%D \docsection{User level interface}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 %D \macros
 %D   {definecyrnum}
-%D 
+%D
 %D User interface to the main conversion routines. The definition
 %D macro autogenerates the primary user-level macro, which in turn
 %D relies \type{\setupcyrnum} for argument processing (see above on
-%D \at{Page}[setupdef]).
-%D 
+%D \at{page}[setupdef]).
+%D
 %D Example usage:
 %D
 %D \starttyping
@@ -325,7 +385,7 @@
 
 %D \macros
 %D    {setupcyrnum}
-%D 
+%D
 %D The \type{\setupcyrnum} and \type{\definecyrnum} macros are
 %D autogenerated via the namespace.
 
@@ -341,17 +401,36 @@
 ]
 
 %D \macros
+%D   {cyrnum}
+%D
+%D The default user macro is defined as \type{\cyrnum}.
+
+\definecyrnum[\v!cyrnum]
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%D \docsection{Conversion routines}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%D \macros
 %D   {cyrillicnumerals,Cyrillicnumerals}
-%D 
+%D
 %D Conforming to the standard \CONTEXT\ naming scheme as employed
 %D with number conversion macros, we define two macros for use with
 %D conversions. As there is no definition for uppercase conversion,
 %D the macro \type{\Cyrillicnumerals} exists only for compatibility
 %D reasons.
-%D 
+%D
 %D Also, we setup two corresponding conversions \type{cyr} and
-%D \type{Cyr} for use with e.g.  enumerations, headings, counters
-%D {\italic\letterampersand}c.
+%D \type{Cyr} for use with e.g. enumerations, headings, counters
+%D {\italic\letterampersand}c. Instead of these predefined ones
+%D the user may consider defining a dedicated conversion routine
+%D for each purpose:
+
+%D \starttyping
+%D \definecyrnum    [mycyrnum] [titlo=mp,titlomode=7,titlospan=all,penwidth=2]
+%D \defineconversion[myconversion][\mycyrnum]
+%D
+%D \setuphead[section][conversion=myconversion]
+%D \stoptyping
 
 \definecyrnum[\v!cyrillicnumerals]
 \definecyrnum[\v!Cyrillicnumerals]
@@ -361,13 +440,6 @@
 \defineconversion[cyr]             [\cyrillicnumerals]
 \defineconversion[Cyr]             [\Cyrillicnumerals]
 
-%D \macros
-%D   {cyrnum}
-%D 
-%D The default user macro is defined as \type{\cyrnum}.
-
-\definecyrnum[\v!cyrnum]
-
 \unprotect \endinput
 
 %   vi:ft=context:fo=co:ts=2:expandtab:sw=2