path: root/Master/texmf-dist/source/latex/stex/smultiling/smultiling.dtx

% \iffalse meta-comment
% A LaTeX Class and Package for the Smultiling Glossary
% Copyright (c) 2009 Michael Kohlhase, all rights reserved
%               this file is released under the
%               LaTeX Project Public License (LPPL)
%
% The original of this file is in the public repository at 
% http://github.com/KWARC/sTeX/
% \fi
%   
% \iffalse
%<sty>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<sty>\ProvidesPackage{smultiling}[2016/04/07 v0.1 Multilingual Support for sTeX]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{url,array,omdoc,omtext,float}
\usepackage[show]{ed}
\usepackage[hyperref=auto,style=alphabetic]{biblatex}
\addbibresource{kwarcpubs.bib}
\addbibresource{extpubs.bib}
\addbibresource{kwarccrossrefs.bib}
\addbibresource{extcrossrefs.bib}
\usepackage{stex-logo}
\usepackage{ctangit}
\usepackage{hyperref}
\makeindex
\floatstyle{boxed}
\newfloat{exfig}{thp}{lop}
\floatname{exfig}{Example}
\def\tracissue#1{\cite{sTeX:online}, \hyperlink{hstp://trac.kwarc.info/sTeX/ticket/#1}{issue #1}}
\def\smglom{\textsf{SMGloM}\xspace}
\def\omdoc{\textsf{OMDoc}\xspace}
\def\latexml{{\LaTeX}ML\xspace}
\def\lmh{\textsf{lmh}\xspace}
\begin{document}\DocInput{smultiling.dtx}\end{document}
%</driver>
% \fi
% 
%\CheckSum{189}
% 
% \changes{v0.1}{2014/04/19}{First Version}
%
% 
% \MakeShortVerb{\|}
%
% \def\omdoc{OMDoc}
% \def\latexml{{\LaTeX}ML}
% \title{{\texttt{smultiling.sty}}: Multilinguality Support for \protect\sTeX}
%    \author{Michael Kohlhase, Deyan Ginev\\
%            Jacobs University, Bremen\\
%            \url{http://kwarc.info/kohlhase}}
% \maketitle
%
% \begin{abstract}
%   The |smultiling| package is part of the \sTeX collection, a version of {\TeX/\LaTeX}
%   that allows to markup {\TeX/\LaTeX} documents semantically without leaving the
%   document format, essentially turning {\TeX/\LaTeX} into a document format for
%   mathematical knowledge management (MKM).
%
%   The |smultiling| package adds multilinguality support for \sTeX, the idea is that
%   multilingual modules in \sTeX consist of a module signature together with multiple
%   language bindings that inherit symbols from it, which also account for cross-language
%   coordination.
% \end{abstract}
%
%\tableofcontents\newpage
% 
%\begin{omgroup}[id=sec:STR]{Introduction}
%  We have been using \sTeX as the encoding for the Semantic Multilingual Glossary of
%  Mathematics (\smglom; see~\cite{IanJucKoh:sps14}). The \smglom data model has been
%  taxing the representational capabilities of \sTeX with respect to multilingual support
%  and verbalization definitions; see~\cite{Kohlhase:dmesmgm14}, which we assume as
%  background reading for this note.
% 
% \begin{omgroup}{\protect\sTeX Module Signatures}
%   (monolingual) \sTeX had the intuition that the symbol definitions (|\symdef| and
%   |\symvariant|) are interspersed with the text and we generate \sTeX module signatures
%   (SMS |*.sms| files) from the \sTeX files. The SMS duplicate ``formal'' information
%   from the ``narrative'' \sTeX files. In the \smglom, we extend this idea by making the
%   the SMS primary objects that contain the language-independent part of the formal
%   structure conveyed by the \sTeX documents and there may be multiple narrative
%   ``language bindings'' that are translations of each other -- and as we do not want to
%   duplicate the formal parts, those are inherited from the SMS rather than written down
%   in the language binding itself. So instead of the traditional monolingual markup in
%   Figure~\ref{fig:stex-monolingual}, we we now advocate the divided style in
%   Figure~\ref{fig:stex-multiling}. 
%
% \begin{exfig}
% \begin{verbatim}
% \begin{module}[id=foo]
% \symdef{bar}{BAR}
% \begin{definition}[for=bar]
%   A \defiii{big}{array}{raster} ($\bar$) is a\ldots, it is much bigger 
%   than a \defiii[sar]{small}{array}{raster}.
% \end{definition}
% \end{module}
% \end{verbatim}\vspace{-2em}
% \caption{A module with definition in monolingual \protect\sTeX}\label{fig:stex-monolingual}
% \end{exfig}
% 
% \begin{exfig}
% \begin{verbatim}
% \usepackage{multiling}
% \begin{modsig}{foo}
% \symdef{bar}{BAR}
% \symi{sar}
% \end{modsig}
%
% \begin{modnl}[creators=miko,primary]{foo}{en}
% \begin{definition}
%   A \defiii[bar]{big}{array}{raster} ($\bar$) is a\ldots, it is much bigger
%   than a \defiii[sar]{small}{array}{raster}. 
% \end{definition}
% \end{modnl}
%
% \begin{modnl}[creators=miko]{foo}{de}
% \begin{definition}
%   Ein \defiii[bar]{gro"ses}{Feld}{Raster} ($\bar$) ist ein\ldots, es
%   ist viel gr"o"ser als ein \defiii[sar]{kleines}{Feld}{Raster}. 
% \end{definition}
% \end{modnl}
% \end{verbatim}\vspace{-2em}
% \caption{Multilingual \protect\sTeX for Figure \protect\ref{fig:stex-monolingual}.}
% \label{fig:stex-multiling}
% \end{exfig}
% 
%   We retain the old |module| environment as an intermediate stage. It is still useful
%   for monolingual texts. Note that for files with a module, we still have to extract
%   |*.sms| files. It is not completely clear yet, how to adapt the workflows. We clearly
%   need a \lmh or editor command that transfers an old-style module into a new-style
%   signature/binding combo to prepare it for multilingual treatment.
% \end{omgroup}
% \end{omgroup}
% 
% \begin{omgroup}[id=sec:user]{The User Interface}
%   The |smultiling| package accepts the \DescribeMacro{langfiles}|langfiles| option that
%   specifies -- for a module \meta{mod} that the module signature file has the name
%   \meta{mod}|.tex| and the language bindings of language with the ISO 639 language
%   specifier \meta{lang} have the file name
%   \meta{mod}|.|\meta{lang}|.tex|.\ednote{implement other schemes, e.g. the onefile
%   scheme.}
% 
% \begin{omgroup}{Multilingual Modules}
%   There the \DescribeEnv{modsig}|modsig| environment works exactly like the old |module|
%   environment, only that the |id| attribute has moved into the required argument --
%   anonymous module signatures do not make sense.
%
%   The \DescribeEnv{modnl}|modnl| environment takes two arguments the first is the name
%   of the module signature it provides language bindings for and the second the ISO 639
%   language specifier of the content language. We add the |primary| key |modnl|, which
%   can specify the primary language binding (the one the others translate from; and which
%   serves as the reference in case of translation conflicts).\ednote{@DG: This needs to
%   be implemented in LaTeXML}
% 
%   There is another difference in the multilingual encoding: All symbols are introduced
%   in the module signature, either by a |\symdef| or the new \DescribeMacro{\symi}|\symi|
%   macro. |\symi{|\meta{name}|}| takes a symbol name \meta{name} as an argument and
%   reserves that name. The variant \DescribeMacro{\symi*}|\symi*{|\meta{name}|}| declares
%   \meta{name} to be a primary symbol; see~\cite{Kohlhase:dmesmgm14} for a
%   discussion. \sTeX provides variants \DescribeMacro{\symii}|\symii| and
%   \DescribeMacro{\symiii}|\symiii| -- and their starred versions -- for multi-part
%   names.
% \end{omgroup}
% 
% \begin{omgroup}{Multilingual Definitions and Crossreferencing Terms}
%   We do not need a new infrastructure for defining mathematical concepts, only the
%   realization that symbols are language-independent. So we can use symbols for the
%   coordination of corresponding verbalizations. As the example in
%   Figure~\ref{fig:stex-multiling} already shows, we can just specify the symbol name in
%   the optional argument of the |\defi| macro to establish that the language bindings
%   provide different verbalizations of the same symbol.
% 
%   For multilingual term references the situtation is more complex: For single-word
%   verbalizations we could use |\atrefi| for language bindigns. Say we have introduced a
%   symbol |foo| in English by |\defi{foo}| and in German by |\defi[foo]{Foo}|. Then we
%   can indeed reference it via |\trefi{foo}| and |\atrefi{Foo}{foo}|. But one the one
%   hand this blurs the distinction between translation and ``linguistic variants'' and on
%   the other hand does not scale to multi-word compounds as |bar| in
%   Figure~\ref{fig:stex-multiling}, which we would have to reference as
%   |\atrefiii{gro"ses Feld Raster}{bar}|. To avoid this, the |smultiling| package
%   provides the new macros \DescribeMacro{\mtref*}|\mtrefi|, |\mtrefii|, and |\mtrefiii|
%   for multilingual references. Using this, we can reference |bar| as
%   |\mtrefiii[?bar]{gro"ses}{Feld}{Raster}|, where we use the (up to three) mandatory
%   arguments to segment the lexical constituents.
% 
%   The first argument it syntactially optional to keep the parallelity to |\*def*|
%   |\*tref*| it specifies the symbol via its name \meta{name} and module name \meta{mod}
%   in a MMT URI \meta{mod}|?|\meta{name}. Note that MMT URIs can be relative:
%   \begin{compactenum}
%     \item |foo?bar| denotes the symbol |bar| from module |foo|
%     \item |foo| the module |foo| (the symbol name is induced from the remaining
%       arguments of |\mtref*|)
%     \item |?bar| specifies symbol |bar| from the current module
%     \end{compactenum}
%     Note that the number suffix |i|/|ii|/|iii| indicates the number of words in the
%     actual language binding, not in the symbol name as in |\atref*|.
% \end{omgroup}
% 
% \begin{omgroup}{Multilingual Views}
%   Views receive a similar treatment as modules in the |smultiling| package. A
%   multilingual view consists of a view signature marked up with the
%   \DescribeMacro{viewsig}|viewsig| environment. This takes three required arguments: a
%   view name, the source module, and the target module. The optional first argument is
%   for metadata (|display|, |title|, |creators|, and |contributors|) and load information
%   (|frompath|, |fromrepos|, |topath|, and |torepos|).\ednote{MK: that does not work yet,
%   what we describe here is \texttt{mhviewig}; we need to refactor further.}
% \begin{verbatim}
% \begin{viewsig}[creators=miko,]{norm-metric}{metric-space}{norm}
%   \vassign{base-set}{base-set}
%   \vassign{metric}{\funcdot{x,y}{\norm{x-y}}}
% \end{viewsig}
% \end{verbatim}
%   Views have language bindings just as modules do, in our case, we have 
% \begin{verbatim}
% \begin{gviewnl}[creators=miko]{norm-metric}{en}{norm}{metric-space}
%   \obligation{metric-space}{obl.norm-metric.en}
%   \begin{assertion}[type=obligation,id=obl.norm-metric.en]
%     $\defeq{d(x,y)}{\norm{x-y}}$ is a \trefii[metric-space]{distance}{function}
%   \end{assertion}
%   \begin{sproof}[for=obl.norm-metric.en]
%     {we prove the three conditions for a distance function:}
%     ...
%   \end{sproof}
% \end{gviewnl}
% \end{verbatim}
% 
% \end{omgroup}
% 
% \begin{omgroup}{Mathematical Keywords}
%   For translations of the mathemtical keywords, the |statements| and |sproofs| packages
%   in \sTeX define special language definition files,
%   e.g. |statements-ngerman.ldf|.\ednote{say more about this}\ednote{There is the
%   translator package which belongs to beamer, maybe we should switch to that.} There is
%   currently only very limited support for this.
% \end{omgroup}
% \end{omgroup}
%
% \begin{omgroup}{Limitations}
%
% We list the limitations of the |smultiling| package. 
%
% \begin{omgroup}{General \texttt{babel} Integration}
%   There is currently no integration with the |babel| package that handles
%   language-specific aspects in {\LaTeX}. In particular, selecting the right language
%   must be done manually. In particular, the example from Figure~\ref{fic:stex-multiling}
%   would really have the form given in Figure~\ref{fig:stex-multiling-babel} -- see the
%   |\usepackage[usenglish,ngerman]{babel}| in line 2, and the |\selectlanguage|
%   statements in lines 6 and 13.
% \begin{exfig}
% \begin{verbatim}
% \usepackage{multiling}
% \usepackage[usenglish,ngerman]{babel}% babel support
% \begin{modsig}{foo}
% \symdef{bar}{BAR}
% \symi{sar}
% \end{modsig}
% \selectlanguage{english}% english version follows
% \begin{modnl}[creators=miko,primary]{foo}{en}
% \begin{definition}
%   A \defiii[bar]{big}{array}{raster} ($\bar$) is a\ldots, it is much bigger
%   than a \defiii[sar]{small}{array}{raster}. 
% \end{definition}
% \end{modnl}
% \selectlanguage{german}% german umlauts please
% \begin{modnl}[creators=miko]{foo}{de}
% \begin{definition}
%   Ein \defiii[bar]{gro"ses}{Feld}{Raster} ($\bar$) ist ein\ldots, es
%   ist viel gr"o"ser als ein \defiii[sar]{kleines}{Feld}{Raster}. 
% \end{definition}
% \end{modnl}
% \end{verbatim}\vspace{-2em}
% \caption{Multilingual \protect\sTeX with \texttt{babel}}
% \label{fig:stex-multiling-babel}
% \end{exfig}
% 
% For the |langfiles| setup, which assumes that module signatures and langauge bindings
% are in separate files, |babel| integration can be simplified by providing a
% language-specific preamble file with |\usepackage{|\meta{language}|}{babel}| which is
% pre-pended to all language binding files when formatted. This preamble can also contain
% the other langauge-specific packages (e.g. for font encodings, etc.).
% \end{omgroup}
% 
% \begin{omgroup}{Language-Specific Limitations}
% Some languages have more problems than others
% \begin{description}
% \item[Turkish] makes \texttt{=} an active character (to give better spacing); this
%   interacts unfavorably with the |keyval| package which needs \texttt{=} as key/value
%   separator (and gives it a different catcode). Therefore we need to prohibit this by
%   restricting the |shorthands| option: use |\usepackage[turkish,shorthands=:!]{babel}|.
% \item[Chinese] needs special fonts and |xelatex|\ednote{get Jinbo to document this}.
% \end{description}
% \end{omgroup}
% \end{omgroup}
% 
% \StopEventually{\newpage\PrintIndex\newpage\PrintChanges\printbibliography}\newpage
%
% \begin{omgroup}[id=sec:impl:cls]{Implementation}
%
% \begin{omgroup}[id=sec:impl:cls:options]{Class Options}
%    \begin{macrocode}
%<*sty>
\newif\if@smultiling@mh@\@smultiling@mh@false
\DeclareOption{mh}{\@smultiling@mh@true}
\newif\if@langfiles\@langfilesfalse
\DeclareOption{langfiles}{\@langfilestrue}
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{modules}}
\ProcessOptions
%    \end{macrocode}
%
% We load the packages referenced here. 
%
%    \begin{macrocode}
\if@smultiling@mh@\RequirePackage{smultiling-mh}\fi
\RequirePackage{etoolbox}
\RequirePackage{structview}
%    \end{macrocode}
% \end{omgroup}
%
% \begin{omgroup}{Signatures}
% 
% \begin{environment}{modsig}
%   The |modsig| environment is just a layer over the |module| environment. We also
%   redefine macros that may occur in module signatures so that they do not create markup.
%    \begin{macrocode}
\newenvironment{modsig}[2][]{%
\def\@test{#1}\ifx\@test\@empty\begin{module}[id=#2]\else\begin{module}[id=#2,#1]\fi\ignorespacesandpars}
{\end{module}\ignorespacesandparsafterend}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{viewsig}
%   The |viewsig| environment is just a layer over the |view| environment with the keys
%   suitably adapted.
%    \begin{macrocode}
\newenvironment{viewsig}[4][]{\def\@test{#1}\ifx\@test\@empty%
  \begin{view}[id=#2,ext=tex]{#3}{#4}\else\begin{view}[id=#2,#1,ext=tex]{#3}{#4}\fi%
  \ignorespacesandpars}
  {\end{view}\ignorespacesandparsafterend}
%    \end{macrocode}
% \end{environment}
%
% \begin{macro}{\@sym*}
%   has a starred form for primary symbols.
%    \begin{macrocode}
\newcommand\symi{\@ifstar\@symi@star\@symi}
\newcommand\@symi[1]{\if@importing\else Symbol: \textsf{#1}\fi\ignorespacesandpars}
\newcommand\@symi@star[1]{\if@importing\else Primary Symbol: \textsf{#1}\fi\ignorespacesandpars}
\newcommand\symii{\@ifstar\@symii@star\@symii}
\newcommand\@symii[2]{\if@importing\else Symbol: \textsf{#1-#2}\fi\ignorespacesandpars}
\newcommand\@symii@star[2]{\if@importing\else Primary Symbol: \textsf{#1-#2}\fi\ignorespacesandpars}
\newcommand\symiii{\@ifstar\@symiii@star\@symiii}
\newcommand\@symiii[3]{\if@importing\else Symbol: \textsf{#1-#2-#3}\fi\ignorespacesandpars}
\newcommand\@symiii@star[3]{\if@importing\else Primary Symbol: \textsf{#1-#2-#3}\fi\ignorespacesandpars}
%    \end{macrocode}
% \end{macro}
% \end{omgroup}
% 
% \begin{omgroup}[id=sec:langbindings]{Language Bindings}
% 
% \begin{macro}{modnl:*}
%    \begin{macrocode}
\addmetakey{modnl}{load}
\addmetakey*{modnl}{title}
\addmetakey*{modnl}{creators}
\addmetakey*{modnl}{contributors}
\addmetakey{modnl}{srccite}
\addmetakey{modnl}{primary}[yes]
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{modnl}
%   The |modnl| environment is just a layer over the |module| environment and the
%   |\importmodule| macro with the keys and language suitably adapted.
%    \begin{macrocode}
\newenvironment{modnl}[3][]{\metasetkeys{modnl}{#1}%
  \def\@test{#1}\ifx\@test\@empty\begin{module}[id=#2.#3]\else\begin{module}[id=#2.#3,#1]\fi%
  \if@langfiles\importmodule[load=#2,ext=tex]{#2}\else
  \ifx\modnl@load\@empty\importmodule{#2}\else\importmodule[ext=tex,load=\modnl@load]{#2}\fi%
  \fi%
  \ignorespacesandpars}
{\end{module}\ignorespacesandparsafterend}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{viewnl}
%   The |viewnl| environment is just a layer over the |viewsketch| environment with the
%   keys and langauge suitably adapted.\ednote{MK: we have to do something about the
%   if@langfiles situation here. But this is non-trivial, since we do not know the current
%   path, to which we could append .\meta{lang}!}
%    \begin{macrocode}
\newenvironment{viewnl}[5][]{\def\@test{#1}\ifx\@test\@empty%
  \begin{viewsketch}[id=#2.#3,ext=tex]{#4}{#5}\else%
  \begin{viewsketch}[id=#2.#3,#1,ext=tex]{#4}{#5}\fi%
  \ignorespacesandpars}
  {\end{viewsketch}\ignorespacesandparsafterend}
%    \end{macrocode}
% \end{environment}
% \end{omgroup}
% 
% \begin{omgroup}{Multilingual Statements and Terms}
%
% \begin{macro}{\mtref*}
%   we first first define an auxiliary conditional |\@instring| that checks of |?| is in
%   the first argument.  |\mtrefi| uses it, if there is one, it just calls |\termref|,
%   otherwise it calls |\@mtrefi|, which assembles the |\termref| after splitting at the
%   |?|.
%    \begin{macrocode}
\def\@instring#1#2{TT\fi\begingroup\edef\x{\endgroup\noexpand\in@{#1}{#2}}\x\ifin@}
\newcommand\mtrefi[2][]{\if\@instring{?}{#1}\@mtref #1\relax{#2}\else\termref[cd=#1]{#2}\fi}
\def\@mtref#1?#2\relax{\termref[cd=#1,name=#2]}
\newcommand\mtrefis[2][]{\mtrefi[#1]{#2s}}
\newcommand\mtrefii[3][]{\mtrefi[#1]{#2 #3}}
\newcommand\mtrefiis[3][]{\mtrefi[#1]{#2 #3s}}
\newcommand\mtrefiii[4][]{\mtrefi[#1]{#2 #3 #4}}
\newcommand\mtrefiiis[4][]{\mtrefi[#1]{#2 #3 #4s}}
%    \end{macrocode}
% \end{macro}
% \end{omgroup}
% 
% \begin{omgroup}{Miscellaneneous}
%   the |\ttl| macro (to-translate) is used to mark untranslated stuff. We need a better
%   \latexml treatment of this eventually that is integrated with MathHub.info. 
% \begin{macro}{\ttl}
%    \begin{macrocode}
\newcommand\ttl[1]{\red{TTL: #1}}
%</sty>
%    \end{macrocode}
% \end{macro}
% \end{omgroup}
% \end{omgroup} 
% \Finale
% 
\endinput
% \iffalse
%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% End: 
% \fi

% LocalWords:  iffalse cls omdoc latexml texttt smlog.cls sref
% LocalWords:  maketitle newpage tableofcontents newpage omgroup ednote ltxml
% LocalWords:  printbibliography showmeta metakeys amstext ginput newcommand
% LocalWords:  module-defs gimport renewcommand langbindings gle newenvironment
% LocalWords:  doctex