\documentclass{article}

\usepackage[unicode,colorlinks=true,linkcolor=blue]{hyperref}
\usepackage{bookmark}
\hypersetup{colorlinks=true,linkcolor=blue,urlcolor=blue,pdfencoding=auto}
\usepackage{parskip}
\usepackage{amsmath}

\ifdefined\XeTeXrevision
  \usepackage[no-math]{fontspec}
  \setmainfont{Linux Libertine O}
  \setsansfont{Linux Biolinum O}
  \setmonofont{Inconsolata}[Scale=MatchLowercase]
  \usepackage[libertine,slantedGreek]{newtxmath}
  % \usepackage{unicode-math}
\else\ifdefined\luatexversion
  \usepackage{fontspec}
  \setmainfont{Linux Libertine O}
  \setsansfont{Linux Biolinum O}
  \setmonofont{Inconsolata}[Scale=MatchLowercase]
  \usepackage[libertine,slantedGreek]{newtxmath}
\else
  \usepackage[utf8]{inputenc}
  \usepackage[LGR,T1]{fontenc}
  \usepackage{textcomp}
  \usepackage{lmodern}
  % \usepackage{libertine}
  % \usepackage{gfsdidot}
  % \usepackage{kerkis}
  % \usepackage{newtxtext,newtxmath}
  % \usepackage{substitutefont}
  % \substitutefont{LGR}{\rmdefault}{artemisia}
  \usepackage{isomath}
\fi\fi

% No section numbers but PDF bookmarks for sections
% \setcounter{secnumdepth}{0}

% load alphabeta after math setup and encoding setup!
% \usepackage{alphabeta}
\usepackage[normalize-symbols]{alphabeta}

% Avoid warnigns with PDF string generation for "alphabeta" commands:

% let \TextOrMath (from fixltx2e) return the "text" argument:
\pdfstringdefDisableCommands{\let\TextOrMath\@firstoftwo}

% varstigma only defined with 8-bit LGR fonts
\providecommand*{\varstigma}{$\oslash$}

% varkappa, only defined with newtxmath, other var... only with unicode-math
\providecommand*{\varkappa}{\oslash}
\providecommand*{\varbeta}{\oslash}
\providecommand*{\varTheta}{\oslash}


\begin{document}

\title{The \emph{alphabeta} package}
\author{Günter Milde}
\maketitle

With the \emph{alphabeta} package, you can write Greek letters ``by name''
or as literal Unicode characters in both, ``text'' and ``math'' mode. The
mode determines whether the letters are taken from the text or math font.
Just like Latin letters, the Greek counterparts are by default italic in
math mode (capital letters upright without \emph{fixmath} or
\emph{\href{http://www.ctan.org/pkg/isomath}{isomath}}) and upright in text:


\begin{quote}
  Text: L \Gamma{} l \gamma,
  emphasized text: \emph{L \Gamma{} l \gamma},
  mathematics: $ L \ \Gamma \ l \ \gamma $
\end{quote}

This makes it easy to write a single Greek symbol (like \Psi{} or \mu{}) or
a \lambda\omicron\gamma\omicron\varsigma{} in non-Greek text as well as
ISO-conforming formulas with upright symbols for constants like $A =
\text{\pi} r^2$ (instead of $A = \pi r^2$).\footnote{%
  The \emph{\href{http://www.ctan.org/pkg/isomath}{isomath}} package
  documentation describes more alternatives for upright Greek symbols in
  math mode.}

\section{Usage}

Load this package in the preamble of your document (after font and math
setup) with
\begin{verbatim}
  \usepackage{alphabeta}
\end{verbatim}
or, if you want to merge symbol variants, with the
\texttt{normalize-symbols} option:
\begin{verbatim}
  \usepackage[normalize-symbols]{alphabeta}
\end{verbatim}

See the source of this document \url{alphabeta-doc.tex} for a setup and
usage example.

\subsection{option normalize-symbols}

The \texttt{normalize-symbols} option is passed to the
\href{alphabeta-doc.pdf}{\emph{alphabeta}} package. It
merges ``letters'' and ``symbol`` variants of some Greek
letters to the ``letter'' character (but is ignored with Unicode fonts):
\begin{quote}
  This text uses both variants for beta (β|ϐ), theta (θ|ϑ), phi (φ|ϕ), pi
  (π|ϖ), kappa (κ|ϰ), rho (ρ|ϱ), Theta (Θ|ϴ), and epsilon (ε|ϵ) in the LaTeX
  source.
\end{quote}

\textbf{Attention}: Be careful in cases where the distinction between the
symbol variants may be important (e.g. in a mathematical or scientific
context). Use XeTeX/LuaTeX with Unicode fonts or the respective characters
in math mode (e.g. $π$ vs. $ϖ$).

\section{Tests and examples}

\subsection{Greek alphabet}

Greek letters via generic ``name'' macros without language/font-encoding
switch:

\begin{quote}
  \Alpha{} \Beta{} \Gamma{} \Delta{} \Epsilon{} \Zeta{} \Eta{} \Theta{}
  \Iota{} \Kappa{} \Lambda{} \Mu{} \Nu{} \Xi{} \Omicron{} \Pi{} \Rho{}
  \Sigma{} \Tau{} \Upsilon{} \Phi{} \Chi{} \Psi{} \Omega{}
  \\
  \alpha{} \beta{} \gamma{} \delta{} \epsilon{} \zeta{} \eta{} \theta{}
  \iota{} \kappa{} \lambda{} \mu{} \nu{} \xi{} \omicron{} \pi{} \rho{}
  \sigma{} \varsigma{} \tau{} \upsilon{} \phi{} \chi{} \psi{} \omega{}
  \\
  \digamma{} \Digamma{} \stigma{} \varstigma{}%
     \footnote{\texttt{\textbackslash varstigma} is not defined with
       Xe/LuaTeX and similar to \texttt{\textbackslash stigma} in some fonts.}
  \koppa{} \qoppa{} \Qoppa{}
  \Stigma{} \Sampi{} \sampi{}
\end{quote}

Greek letters via Unicode input without language/font-encoding switch:

\begin{quote}
  Α Β Γ Δ Ε Ζ Η Θ Ι Κ Λ Μ Ν Ξ Ο Π Ρ Σ Τ Υ Φ Χ Ψ Ω\\
  α β γ δ ε ζ η θ ι κ λ μ ν ξ ο π ρ σ ς τ υ φ χ ψ ω\\
  ϝ Ϝ ϛ ϟ ϙ Ϙ Ϛ Ϡ ϡ
\end{quote}

\subsubsection{symbol variants}

Mathematical notation uses variant shapes of some Greek letters as
additional symbols. The variations have no syntactic meaning in Greek text
and text fonts may use the variant shapes in place of the “regular” ones as
a stylistic choice.

Unicode defines separate code points for the symbol variants. TeX supports
some of the variant shape symbols in mathematical mode, but its concept of
“standard” vs. “variant” symbols differs from the distinction between
“GREEK LETTER ...” vs. “GREEK ... SYMBOL” in the Unicode standard
See \href{greek-euenc-doc.pdf}{greek-euenc-doc}.

The \emph{alphabeta} package defines generic macros for these variants that
are short forms of the set defined in \texttt{greek-euenc.def}:
\begin{quote}
  \verb|\<name>| selects the Unicode GREEK LETTER ... variant,

  \verb|\<name>symbol| selects the Unicode
     GREEK ... SYMBOL variant,

  \verb|\var<name>| selects the variant
    shape according to TeX' mathematical mode
\end{quote}
See Table \ref{tab:symbol-variant-macros} for the full list. 
\begin{table}[tbp]
  \centering
  \begin{tabular}{lcc}
  \hline
  macro & text & math \\
  \hline
  \verb$\pi$            & \pi            & $\pi$         \\
  \verb$\varpi$         & \varpi         & $\varpi$      \\
  \verb$\pisymbol$      & \pisymbol      & $\pisymbol$   \\
  \hline
  \verb$\rho$           & \rho           & $\rho$        \\
  \verb$\varrho$        & \varrho        & $\varrho$     \\
  \verb$\rhosymbol$     & \rhosymbol     & $\rhosymbol$  \\
  \hline
  \verb$\theta$         & \theta         & $\theta$      \\
  \verb$\vartheta$      & \vartheta      & $\vartheta$   \\
  \verb$\thetasymbol$   & \thetasymbol   & $\thetasymbol$ \\
  \hline
  \verb$\epsilon$       & \epsilon       & $\epsilon$    \\
  \verb$\varepsilon$    & \varepsilon    & $\varepsilon$ \\
  \verb$\epsilonsymbol$ & \epsilonsymbol & $\epsilonsymbol$ \\
  \hline
  \verb$\phi$           & \phi           & $\phi$        \\
  \verb$\varphi$        & \varphi        & $\varphi$     \\
  \verb$\phisymbol$     & \phisymbol     & $\phisymbol$  \\
  \hline
  \verb$\beta$          & \beta          & $\beta$       \\
  \verb$\varbeta$       & \varbeta       & $\varbeta$    \\
  \verb$\betasymbol$    & \betasymbol    & $\betasymbol$ \\
  \hline
  \verb$\kappa$         & \kappa         & $\kappa$      \\
  \verb$\varkappa$      & \varkappa      & $\varkappa$   \\
  \verb$\kappasymbol$   & \kappasymbol   & $\kappasymbol$\\
  \hline
  \verb$\Theta$         & \Theta         & $\Theta$      \\
  \verb$\varTheta$      & 		 & $\varTheta$   \\
  \verb$\Thetasymbol$   & \Thetasymbol   & \\
  \hline
  \end{tabular}
  \caption{Macros for Greek symbol variants. With 8-bit TeX and the
  \texttt{normalize-symbols} option, the output for both variants in text
  mode is the same, as 8-bit Greek text fonts contain only one symbol
  variant.} \label{tab:symbol-variant-macros}
\end{table}



\subsection{\ensuregreek{%
    Ἑλληνικά (\<\Epsilon\lambda\lambda\eta\nu\iota\kappa\'\alpha{})}
  in PDF strings}

With the alphabeta package, you get Greek letters in both, the document body
and PDF metadata generated by hyperref if the input uses Unicode literals or
macros. Wrapping in \verb+\ensuregreek+ ensures the right placement of the
accents and breathings (before, not above capital letters). With LICR input
(accent macros + symbol macros), non-standard diacritics are missing in the
PDF data, as hyperref's PU encoding currently does not support polytonic
Greek. (Here, the dasia is dropped at the start of the word in parentheses in
the PDF toc. The warning ``\texttt{Glyph not defined in PU encoding,
removing `\textbackslash<' on input line 145.}'' is written to the log.)

Warnings like \texttt{Token not allowed in a PDF string
(Unicode): removing `\textbackslash TextOrMath ' on input line 145.}
can be ignored or avoided with the preamble code:

\begin{verbatim}
  \pdfstringdefDisableCommands{\let\TextOrMath\@firstoftwo}
\end{verbatim}


\subsection{Greek in math $\Gamma = \sin\alpha / \cos{\beta}$}

In the main document, Greek in math mode should work as usual:

\[\Gamma = \frac{\sin\alpha}{\cos{\beta}}.
\]

With 8-bit TeX, literal Greek Unicode characters are supported also in
mathematical mode (for XeTeX/LuaTeX use unicode-math):

\[  Γ = \frac{\sin α}{\cos{β}}.
\]

Greek letters and symbols in math (there are no math macros for Greek letters wich exist
with similar shape in the Latin alphabet):

Input as macro:

\begin{align*}
  &
  % \Alpha{} \Beta{}
  \Gamma{} \Delta{}
  % \Epsilon{} \Zeta{} \Eta{}
  \Theta{}
  % \Iota{} \Kappa{}
  \Lambda{}
  % \Mu{} \Nu{}
  \Xi{}
  % \Omicron{}
  \Pi{}
  % \Rho{}
  \Sigma{}
  % \Tau{}
  \Upsilon{} \Phi{}
  % \Chi{}
  \Psi{} \Omega{}
\\&
  \alpha{} \beta{} \gamma{} \delta{} \epsilon{} \zeta{} \eta{} \theta{}
  \iota{} \kappa{} \lambda{} \mu{} \nu{} \xi{}
  % \omicron{}
  \pi{} \rho{}
  \sigma{} \varsigma{} \tau{} \upsilon{} \phi{} \chi{} \psi{} \omega{}
\\&
  \vartheta \varphi \varpi \digamma{} \varrho \varepsilon
\end{align*}

Input as Unicode literals (with XeTeX/LuaTeX, this requires the unicode-math
package):

\begin{align*} & Γ ΔΘΛΞΠΣΥ ΦΨ Ω \\
               & αβγδεζηθικλμνξπρσςτυφχψω \\
	       & ϑϕϖϝϱϵ
\end{align*}

The "normal" vs. "variant" shape of phi and epsilon is inverted when using
traditional makros or Unicode letter vs. symbol characters respectively.
This is to keep backwards compatibility of the math macros as well
as consistent input-output mapping for Unicode in text and math.

PDF strings do not know math mode. The content of a formula or equation is
evaluated in text mode with non-valid commands discarded (and warnings
written to the log). This works resonably well for simple formulas (but not,
e.g., for super-/subscripts). With the \emph{alphabeta} package, it works
also for Greek letters.


\subsection{Diacritics}

Accent macros are set up for use with the generic macros by definition of
``TextComposite'' commands.

Diacritics (except the dialytika) should placed
before capital letters and dropped with MakeUppercase:

\begin{quote}
\ensuregreek{
\<{\alpha} \>{\epsilon} \"'{\iota} \>`{\eta}
\'<{\omicron} \~<{\upsilon} \~>{\omega}
\\
\<{\Alpha} \>{\Epsilon} \'{\Iota} \>`{\Eta}
\'<{\Omicron} \~<{\Upsilon} \~>{\Omega}
\\
\MakeUppercase{%
 \<{\alpha} \>{\epsilon} \"'{\iota} \>`\eta{}
 \'<{\omicron} \~<{\upsilon} \~>{\omega}
}}
\end{quote}

\subsection{Limitations}

With 8-bit TeX, the following limitations known from
\emph{\href{textalpha-doc.pdf}{textalpha}} apply if the current font
encoding is not LGR:

\begin{itemize}

\item Composition of diacritics (like \verb+\>\'+) fails:

      \<{\alpha} \>{\epsilon} \"'{\iota} \>`\eta{}
      \'<{\omicron} \~<{\upsilon} \~>{\omega}

      Long names (like \verb+\accdasiaoxia+) work in any font encoding,
      however they do not select precomposed characters (the difference
      becomes obvious if you drag-and-drop text from the PDF version of this
      document):
      %
      \ensuregreek{\<'\alpha{} \accdasia\acctonos\alpha{} \accdasiaoxia\alpha{}}
      (LGR) vs. \accdasiaoxia\alpha{} (T1)

\item MakeUppercase fails with composite diacritics in other font encodings.
      % \MakeUppercase{%
      %  \<\alpha{} \>\epsilon{} \'\iota{} \`\eta{} \~\upsilon{}
      % }

\item There is no kerning between Greek letters, if the font encoding is not
      LGR: compare \ensuregreek{\Alpha\Upsilon\Alpha} (LGR) to \Alpha\Upsilon\Alpha (T1).
      Because of this (and for proper hyphenation), use of the Babel package
      and correct language setting is recommended for Greek quotes.

\end{itemize}

The \verb+\ensuregreek+ macro ensures that the argument is typeset with a
font encoding supporting Greek. This keeps kerning (if the kerning pair is
inside the argument, \ensuregreek{\Alpha\"\Upsilon\Alpha}), and allows
combining of accent macros where pre-composed characters are selected
(\ensuregreek{\<'\alpha}).

\end{document}
