% isomath.sty: Math for scientists
% ********************************
% 
% :Abstract:  The `isomath` package enables formatting Greek and Latin
%             letters as symbols for vectors, matrices, and tensors
%             in the typefaces recommended for scientific papers
%             by the International Standard ISO 80000-2.
% 
% :Copyright: © 2008, 2010 Günter Milde
% :Licence:   This work may be distributed and/or modified under the
%             conditions of the `LaTeX Project Public License`_, either
%             version 1.3 of this license or (at your option) any later version.
% 
% :Identification:
%  ::

\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{isomath}
[2011/02/01 v0.5 ISO math style]

% .. contents::
%   
% History
% =======
% 
% .. class:: borderless
% 
% ===  ============  ========================================================
% 0.1    2008-09-25  first public version.
% 0.2    2008-10-02  bugfix: a usage example was uncommented;
% \                  updated documentation;
% \                  define \mathsans only if OMLmathsans is true;
% \                  option reuseMathalphabets -> reuseMathAlphabets.
% 0.3    2009-06-19  documentation update;
% \                  fix OMLmathrm and OMLmathsans definitions;
% \                  switch license to LPP.
% 0.4    2010-08-23  split user documentation from literate source;
% \                  option ``scaled``;
% \                  documentation update.
% 0.5    2011-01-04  math alphabet names matching Unicode;
% \                  documentation review and extension;
% \                  bold alphabet variants in ``bold`` math version;
% \                  upright numbers with ``\vectorsym``.
% ===  ============  ========================================================
% 
% 
% Requirements
% ============
% 
% fixmath.sty
% -----------
% The package fixmath_ by Walter Schmidt defines Greek letters as symbols
% of type ``\mathalpha`` and takes them from the ``letters`` symbol font in
% ``\mathnormal`` (as opposed to ``operators`` in ``fontmath.ltx``).
% 
% fixmath_ also defines the ``\mathbold`` alphabet, setting it to ``cmm``.
% This definition is be overwritten with a configurable value for
% the font family below. ::

\RequirePackage{fixmath}


% kvoptions.sty
% -------------
% The kvoptions_ package in the oberdiek_ bundle facilitates the setup of
% package options and provides a key=value interface (based on keyval_)::

\RequirePackage{kvoptions}


% Options
% =======
% 
% rmdefault
% ---------
% Family for roman math fonts. Must be available in OML
% encoding. The default is to use the corresponding text font family
% (``\rmdefault``).
% ::

\DeclareStringOption[\rmdefault]{rmdefault}

% sfdefault
% ---------
% Family for sans-serif math fonts. The default selects `CM Bright`, as
% most sans serif fonts are not available in OML encoding::

\DeclareStringOption[cmbr]{sfdefault}

% scaled
% ------
% The sans-serif fonts, ``fav`` (Arev), ``llcmss`` (LX Fonts), and
% ``iwona`` can be scaled with the ``scaled`` option.
% ::

\DeclareStringOption[1.0]{scaled}

% reuseMathAlphabets
% ------------------
% The definition of new `math alphabets`_ can lead to a “too many math
% alphabets used in version normal” error.
% 
% As a workaround, this option tells `isomath` to re-use the existing
% ``\mathbf`` and ``\mathsf`` alphabets for *italic* bold and sans-serif
% bold.
% ::

\DeclareBoolOption{reuseMathAlphabets}

% OMLmath*
% --------
% The following options cause `isomath` to (re)define the corresponding
% `math alphabets`_ in OML encoding::

\DeclareBoolOption{OMLmathrm}
\DeclareBoolOption{OMLmathbf}
\DeclareBoolOption{OMLmathsf}
\DeclareBoolOption{OMLmathsfit}
\DeclareBoolOption{OMLmathtt}
% backwards compatibility option alias
\DeclareVoidOption{OMLmathsans}{\isomath@OMLmathsfittrue}

% Setting these options enables access to small Greek letters in
% different shapes with e.g. ``\mathrm{\pi}`` *if an OML encoded font
% is available*. Currently, only the mathdesign_ fonts support roman in
% OML encoding.
% 
% With some packages, these options can result in a “too many math alphabets
% used in version normal” error.
% 
% --------------------------------------------------------
% 
% Process the options with ``kvoptions`` extensions::

\ProcessKeyvalOptions*


% Declarations
% ============
% 
% Math alphabets
% --------------
% 
% In math, LaTeX uses “absolute” fontnames instead of a selection by
% family, shape, and weight because typefaces have a semantic meaning
% [fntguide]_.
% 
% `isomath` defines a math alphabet for every required font variant and
% optionally re-defines the standard math alphabets in `OML` font encoding.
% 
% Unfortunately, the number of math alphabets in one math version is
% limited to 16, so we have to be careful not to exceed this. The
% ``reuseMathAlphabets`` option reduces the number of math alphabet
% definitions by two, with the side effect of italic shape with
% ``\mathbf`` and ``\mathsf`` commands::

\ifisomath@reuseMathAlphabets
  \PackageWarningNoLine{isomath}{%
    Re-using math alphabet `mathsf' for \protect \mathsfbfit
    \MessageBreak and `mathbf' for \protect \mathbfit
  }
\fi

% mathbfit
% ~~~~~~~~
% The *bold italic* math alphabet is named ``\mathbfit`` like in
% unicode-math_ (with an alias ``\mathbold`` like in fixmath_ and
% related packages). With the reuseMathAlphabets_ option, the roman bold
% math alphabet ``\mathbf`` is redefined and ``\mathbfit`` made an
% alias. The series selector ``bx`` (bold extended) is used, because it
% is better supported than ``b``. (Is there any LaTeX math font
% distinguishing between ``b`` and ``bx``?) ::

\ifisomath@reuseMathAlphabets
  \DeclareMathAlphabet{\mathbf}{OML}{\isomath@rmdefault}{bx}{it}
  \def\mathbfit{\mathbf}
\else
  \DeclareMathAlphabet{\mathbfit}{OML}{\isomath@rmdefault}{bx}{it}
\fi

% alias (overwriting the definition from fixmath)::

\renewcommand{\mathbold}{\mathbfit}

% mathsfit
% ~~~~~~~~
% For *sans-serif italic*, we define a new alphabet ``\mathsfit`` (with
% the alias ``\mathsans`` in analogy to ``\mathbold``). As this typeface
% is not required by ISO 80000-2 and TeX limits the number of math alphabets
% to 16 per math version, it is only defined if the ``OMLmathsfit`` or
% ``OMLmathsans`` option is set::

\ifisomath@OMLmathsfit
  \DeclareMathAlphabet{\mathsfit}{OML}{\isomath@sfdefault}{m}{it}
  \SetMathAlphabet{\mathsfit}{bold}{OML}{\isomath@sfdefault}{bx}{it}
  \def\mathsans{\mathsfit}
\fi

% mathsfbfit
% ~~~~~~~~~~~~
% The *sans serif bold italic* alphabet is used for tensor symbols.
% Following the Unicode math name scheme it is called
% ``\mathsfbfit``(with the backwards compatibility alias ``\mathboldsans``).
% With the reuseMathAlphabets_ option, the upright sans serif math
% alphabet ``\mathsf`` is redefined and ``\mathsfbfit`` made an
% alias to it::

\ifisomath@reuseMathAlphabets
  \DeclareMathAlphabet{\mathsf}{OML}{\isomath@sfdefault}{bx}{it}
  \def\mathsfbfit{\mathsf}
\else
  \DeclareMathAlphabet{\mathsfbfit}{OML}{\isomath@sfdefault}{bx}{it}
\fi
\def\mathboldsans{\mathsfbfit}

% Redefine standard alphabets
% ~~~~~~~~~~~~~~~~~~~~~~~~~~~
% 
% Redefine standard alphabets in `OML` font encoding
% if the corresponding `OMLmath*`_ option is true::

\ifisomath@OMLmathrm
  \SetMathAlphabet{\mathrm}{normal}{OML}{\isomath@rmdefault}{m}{n}
  \SetMathAlphabet{\mathrm}{bold}{OML}{\isomath@rmdefault}{bx}{n}
\fi
\ifisomath@OMLmathbf
  \SetMathAlphabet{\mathbf}{normal}{OML}{\isomath@rmdefault}{bx}{n}
\fi
\ifisomath@OMLmathsf
  \SetMathAlphabet{\mathsf}{normal}{OML}{\isomath@sfdefault}{m}{n}
  \SetMathAlphabet{\mathsf}{bold}{OML}{\isomath@sfdefault}{bx}{n}
\fi
\ifisomath@OMLmathtt
  \SetMathAlphabet{\mathtt}{normal}{OML}{\ttdefault}{m}{n}
  \SetMathAlphabet{\mathtt}{bold}{OML}{\ttdefault}{bx}{n}
\fi

% Command aliases
% ---------------
% 
% The following macros allow semantic markup of mathematical symbols.
% The argument is typeset as proposed by ISO 80000-2 and
% `Typefaces for Symbols in Scientific Manuscripts`_.
% 
% \\vectorsym
% ~~~~~~~~~~~
% Alphabetic vectors symbols are typeset *boldface italic* while numeric
% ones (e.g. zero vector) are typeset *boldface upright*. The number
% test is a simplified version from the LaTeX FAQ
% `Is the argument a number?
% <http://mail.tug.org/texlive/Contents/live/texmf-dist/doc/generic/FAQ-en/html/FAQ-isitanum.html>`__
% It fails if a number is followed by a non-number, e.g. ``\vectorsym{1a}``,
% but this is no valid vector symbol and would look strange with the
% ``\vec`` accent, too. ::

\providecommand*{\vectorsym}[1]{%
  \ifnum9<1#1%
    \mathbf{#1}%
  \else%
    \mathbfit{#1}%
  \fi}

% For easier writing or to make existing documents conform to the standard,
% you might want to re-define the standard ``\vec`` command after loading this
% package.
% 
% \\matrixsym
% ~~~~~~~~~~~
% Symbols for matrices are typeset *boldface italic*, i. e. in the same face
% as vectors. ::

\providecommand*{\matrixsym}{\vectorsym}

% \\tensorsym
% ~~~~~~~~~~~
% Symbols for tensors are *sans-serif bold italic*::

\providecommand*{\tensorsym}{\mathsfbfit}


% Font mappings
% -------------
% 
% Substitutions needed for the math alphabet definitions and setup for
% scaled fonts. For details about the font definition macros see
% [fntguide]_.
% 
% Common family name for text and math
% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
% 
% Some font packages provide matching text and math font but do not
% define a substitution in their ``*.fd`` files. Ideally, the following
% mappings should be moved there.
% 
% Mathpazo (Palatino) ppl ↔ zplm ::

\DeclareFontFamily{OML}{ppl}{\skewchar\font127}
\DeclareFontShape{OML}{ppl}{m}{it}{<-> ssub * zplm/m/it}{}
\DeclareFontShape{OML}{ppl}{bx}{it}{<-> ssub * zplm/b/it}{}


% Scaling
% ~~~~~~~
% Scale the ``fav`` (Arev), ``llcmss`` (LX Fonts), and ``iwona`` fonts
% by the value of the scaled_ option.
% 
% To get scaled versions of a font, you cannot use the ``ssub``
% `size function`, but must use the empty function or ``s`` with the font
% file as argument [found by experiment, GM 2010-01-28].
% 
% Arev (see omlzavm.fd): fav ↔ zavm ::

\DeclareFontFamily{OML}{fav}{\skewchar\font127}
\DeclareFontShape{OML}{fav}{m}{it}{<-> s * [\isomath@scaled] zavmri7m}{}
\DeclareFontShape{OML}{fav}{bx}{it}{<-> s * [\isomath@scaled] zavmbi7m}{}

% LX Fonts (see lxfonts.sty): llcmss ↔ llcmm ::

\DeclareFontFamily{OML}{llcmss}{\skewchar\font'177}
\DeclareFontShape{OML}{llcmss}{m}{it}{<-> s * [\isomath@scaled] lcmmi8}{}
\DeclareFontShape{OML}{llcmss}{bx}{it}{<-> s * [\isomath@scaled] lcmmib8}{}

% Iwona (see ``omliwona.fd``) iwona ↔ mi-iwona::

\DeclareFontFamily{OML}{iwona}{}
\DeclareFontShape{OML}{iwona}{m}{it}{<-> s * [\isomath@scaled] mi-iwonari}{}
\DeclareFontShape{OML}{iwona}{bx}{it}{<-> s * [\isomath@scaled] mi-iwonabi}{}


% References
% ==========
% 
% .. [fntguide] `LaTeX 2e font selection`:
%    http://mirror.ctan.org/macros/latex/doc/fntguide.pdf.
% 
% .. _LaTeX Project Public License: http://www.latex-project.org/lppl.txt
% .. _arev: http://mirror.ctan.org/help/Catalogue/entries/arev.html
% .. _cmbright: http://mirror.ctan.org/help/Catalogue/entries/cmbright.html
% .. _fixmath: http://mirror.ctan.org/help/Catalogue/entries/fixmath.html
% .. _hvmath: http://mirror.ctan.org/help/Catalogue/entries/hvmath.html
% .. _iwona: http://mirror.ctan.org/help/Catalogue/entries/iwona.html
% .. _keyval: http://mirror.ctan.org/help/Catalogue/entries/keyval.html
% .. _kvoptions: http://mirror.ctan.org/help/Catalogue/entries/kvoptions.html
% .. _lxfonts: http://mirror.ctan.org/help/Catalogue/entries/lxfonts.html
% .. _mathdesign: http://mirror.ctan.org/help/Catalogue/entries/mathdesign.html
% .. _mathematical alphanumeric symbols:
%     http://www.unicode.org/charts/PDF/U1D400.pdf
% .. _oberdiek: http://mirror.ctan.org/help/Catalogue/entries/oberdiek.html
% .. _`Typefaces for Symbols in Scientific Manuscripts`:
%    http://physics.nist.gov/cuu/pdf/typefaces.pdf
% .. _unicode-math:
%    http://mirror.ctan.org/help/Catalogue/entries/unicode-math.html