\startmodule[type=mkiv]

\startdocumentation
\module
  [      file=t-transliterator,
       version=2010-12-23 22:10:09+0100,
         title=\CONTEXT\ User Module,
      subtitle=The Transliterator,
        author=Philipp Gesang,
          date=\currentdate,
     copyright=Philipp Gesang,
       license=2-clause BSD,
         email={pgesang at ix dot urz dot uni-heidelberg dot de}]
This module is licensed under the conditions of the BSD license with 
two clauses, there is a copy it in a file named "COPYING" in the
transliterator source tree.
\stopdocumentation

\startdefinition
\writestatus{loading}{Transliteration from non-Latin scripts}
\stopdefinition

\startdefinition
\unprotect
\stopdefinition

\startdefinition
\definenamespace [TRL] [
  name=transliterate,
  type=module,
  setup=list,
  parent=TRL,
  style=no,
  version=hg-r16,
  comment=Transliteration from non-Latin scripts.,
]
\stopdefinition

\startdefinition
\ctxlua{environment.loadluafile ("transliterator")}
\stopdefinition

\startdocumentation
Use the Transliterator by adding \type{\usemodule[transliterator]} somewhere
before \type{\starttext}.  Adjust the Transliterator through the
\type{\setuptransliterate} command.  As a first argument it accepts a set of
key-value options; at present you may configure \type{mode} and
\type{hyphenate}.
\stopdocumentation

\startdocumentation
At first we'll set some defaults:
\stopdocumentation

\startdefinition
\setuptransliterate[mode=ru_old,hyphenate=cz,debug=false]
\stopdefinition

\startdocumentation
Possible values for \type{mode} are by the time of this writing:
\type{ru}, \type{ru_transcript_de}, \type{ru_transcript_en}, \type{ru_old},
\type{all}, \type{iso9_ocs}, \type{ocs}, \type{ocs_gla}, \type{ru_cz},
\type{ocs_cz}, \type{gr} and \type{gr_n}.
As not all fonts, even the expensive ones, support some of the most frequent
unicode signs used in ISO~9 there are fallbacks for the transliterations of
the weak and hard sign: \type{iso9_ocs_hack}, which is essentially
\type{iso9_ocs}, and \type{ru_old_jer_hack}, which is essentially
\type{ru_old}.  These two transliterate {\em ь} and {\em ъ} (both upper and
lower case) to the more common, but non-ISO characters {\em '} and {\em ''}
respectively.
Possible values for \type{hyphenate} are all valid \CONTEXT\ language code, for an
overview see \type{http://wiki.contextgarden.net/Language_Codes}.
In praxi you may want to choose either Czech (the default) or Slovak
(\type{sk}) for most transliterations from cyrillic scripts.  I've not yet
made up my mind concerning Greek transliteration, any suggestions are
welcome.
\stopdocumentation

\startdocumentation
The following will help debugging and reviewing tables.  Make sure your
typescript can handle the characters, in general it's no use with Latin
Modern which unfortunately provides only a restricted set of the unicode
range.

The user-level command to output a single substitution table is
\type{\showOneTranslitTab{#1}}.
\stopdocumentation

\startdefinition
\define[1]\showOneTranslitTab{%
  \startluacode
    environment.loadluafile ("trans_tables_iso9")
    environment.loadluafile ("trans_tables_trsc")
    environment.loadluafile ("trans_tables_scntfc")
    environment.loadluafile ("trans_tables_trsc")
    environment.loadluafile ("trans_tables_glag")
    environment.loadluafile ("trans_tables_gr")
    translit.gen_rules_en()
    translit.gen_rules_de()
    translit.show_tab(translit["\luaescapestring{#1}"])
  \stopluacode
}
\stopdefinition

\startdocumentation
The user-level command to output all defined tables is
\type{\showTranslitTabs}.
\stopdocumentation

\startdefinition
\define\showTranslitTabs{%
  \ctxlua{translit.show_all_tabs()}%
}
\stopdefinition

\startdefinition
\def\translitDebug#1{%
  \doif{\transliterateparameter{debug}}{yes}{%
    {\ss\inmargin{\ctxlua{translit.debug_next()}} #1}%
  }%
}
\stopdefinition

\startdocumentation
The user-level command \type{\transliterate[#1]{#2}} does the job of
switching to a given language (for hyphenation) and adjusting the
substitution method locally.  It takes an optional list \type{[#1]} of
key-value arguments to allow ad-hoc specification of either two that deviate
from the defaults set initially by means of \type{\setuptransliterate}.

Internally, \type{\dotransliterate} is called according to the \CONTEXT\ 
coding style and in case the user provides \type{hyphenate=} or
\type{mode=} those will be used instead of the globals.  Note that this
leaves the latter unchanged.  Thus, in order to permanently switch to
another transliteration style the user would have to set it by calling
\type{\setuptransliterate} again.

\stopdocumentation

\startdefinition
\def\dotransliterate[#1]#2{%
  \bgroup\iffirstargument
    \setuptransliterate[#1]%
  \fi
    \language[\transliterateparameter{hyphenate}]%
    \ctxlua{translit.transliterate("\transliterateparameter{mode}","\luaescapestring{#2}")}%
  \egroup%
}
\stopdefinition

\startdefinition
\unexpanded\def\transliterate{\dosingleempty\dotransliterate}
\stopdefinition

\startdefinition
\unexpanded\def\starttransliterate{%
  \bgroup%
  \dosingleempty\dostarttransliterate%
}
\stopdefinition

\startdefinition
\let\stoptransliterate\relax
\stopdefinition

\startdefinition
\def\dostarttransliterate[#1]#2\stoptransliterate{%
  \iffirstargument
    \setuptransliterate[#1]%
  \fi
  \language[\transliterateparameter{hyphenate}]%
  \ctxlua{translit.transliterate("\transliterateparameter{mode}","\luaescapestring{#2}")}%
  \egroup%
}
\stopdefinition

\startdefinition
\protect \endinput
\stopdefinition
\stopmodule
