%%
%% `numspell.tex' documentation of the numspell package
%%
%% Copyright 2017- by Tibor Tomacs
%%
%% 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.
%% The latest version of this license is in
%%   http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Tibor Tomacs.
%%
\documentclass{article}
\usepackage[a4paper,margin=25mm]{geometry}
\usepackage[pdfstartview=FitH,colorlinks,allcolors=black,bookmarksnumbered]{hyperref}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{numspell}
\usepackage[magyar,german,french,english]{babel}
\usepackage{listings,xcolor,amsmath,upquote}
\usepackage[group-separator={,}]{siunitx}
\flushbottom
\setlength{\labelsep}{0pt}
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt}

\lstnewenvironment{examplelst}{\lstset{
belowskip=\bigskipamount,
basicstyle=\ttfamily,
backgroundcolor=\color{black!10},
columns=fullflexible,
keepspaces}}{}

\newcommand{\commandinline}{\lstinline[
literate={<}{{$\langle$}}1{>}{{$\rangle$}}1,
delim={[is][\color{green!50!black}\normalfont\itshape]{!}{!}},
basicstyle=\color{blue!80!black}\ttfamily,
columns=fullflexible,
keepspaces]}

\newcommand{\verbinline}{\lstinline[
literate={<}{{$\langle$}}1{>}{{$\rangle$}}1,
delim={[is][\color{green!50!black}\normalfont\itshape]{!}{!}},
basicstyle=\ttfamily,
columns=fullflexible,
keepspaces]}

\begin{document}

\title{The {\bfseries\sffamily numspell} package\\{\large v1.0 (2017/02/09)}}
\author{Tibor Tómács\\{\normalsize\url{tomacs.tibor@uni-eszterhazy.hu}}}
\date{}
\maketitle

\section{Introduction}
The aim of the \texttt{numspell} package is to spell the cardinal and ordinal numbers from 0 to $10^{67}-1$ (i.e.~maximum 66 digits).

Currently, the supported languages are English, German, French and Hungarian.
The spelling will happen in the current language.

The \texttt{numspell} package requires the services of the following packages: \texttt{xstring}, \texttt{etoolbox}, \texttt{pdftexcmds}.

Load the package as usual, with
\begin{flushleft}
\commandinline|\usepackage{numspell}|
\end{flushleft}

\section{Commands}
\begin{description}
\item\commandinline|\numspell[!<zeros>!]{!<num>!}|\\
Spelling the cardinal number $n=\text{\color{green!50!black}\itshape$\langle$num$\rangle$}\cdot10^{\text{\color{green!50!black}\itshape$\langle$zeros$\rangle$}}$, where $0\leq n\leq 10^{67}-1$. The default value of \commandinline|!<zeros>!| is \texttt{0}. For example
\begin{flushleft}
\verb|\numspell{12000}| $\to$ \numspell{12000}\\
\verb|\numspell[3]{12}| $\to$ \numspell[3]{12}\\
\verb|\numspell[6]{12}| $\to$ \numspell[6]{12}\\
\verb|\numspell[63]{1}| $\to$ \numspell[63]{1}
\end{flushleft}

\item\commandinline|\thenumspell|\\
The \verb|\numspell| stores the result in this command. For example
\begin{flushleft}
\verb|\numspell{12000}; \thenumspell| $\to$ \numspell{12000}; \thenumspell\\
\verb|\numspell{1}; \numspell{2}; \thenumspell| $\to$ \numspell{1}; \numspell{2}; \thenumspell
\end{flushleft}

\item\commandinline|\numspellsave{!<name>!}|\\
It generates the \commandinline|\thenumspell!<name>!| command, which saves the current \verb|\thenumspell|. For example
\begin{verbatim}
\numspell{1};
\numspellsave{MyNum}
\numspell{2};
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\numspell{1};
\numspellsave{MyNum}
\numspell{2};
\thenumspell;
\thenumspellMyNum

\item\commandinline|\numspelldashspace{!<length>!}|\\
In the number spelling, the spaces around the dashes are flexibility for the optimal hyphenation. Its value is \texttt{0pt plus} \commandinline|!<length>!|.
The default value of \commandinline|!<length>!| is \texttt{2pt}. For example
\begin{verbatim}
\selectlanguage{magyar}
\numspell{6512312354762547162546254756}\\[2mm]
\numspelldashspace{10pt}
\numspell{6512312354762547162546254756}
\end{verbatim}
{\selectlanguage{magyar}
\numspell{6512312354762547162546254756}\\[2mm]
\numspelldashspace{10pt}
\numspell{6512312354762547162546254756}}

\item\commandinline|\numspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\numspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\numspell[!<zeros>!]{!<num>!}|\\
\verbinline|\numspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\numspell*{1}
\numspellsave{MyNum}
\numspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\numspell*{1}
\numspellsave{MyNum}
\numspell*{2}
\thenumspell;
\thenumspellMyNum

\item\commandinline|\Numspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\numspell|, but the first letter will be capital. For example
\begin{flushleft}
\verb|\Numspell{12000}| $\to$ \Numspell{12000}\\
\verb|\Numspell[3]{12}| $\to$ \Numspell[3]{12}\\
\verb|\Numspell[6]{12}| $\to$ \Numspell[6]{12}\\
\verb|\Numspell[63]{1}| $\to$ \Numspell[63]{1}
\end{flushleft}

\item\commandinline|\Numspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\Numspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\Numspell[!<zeros>!]{!<num>!}|\\
\verbinline|\Numspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\Numspell*{1}
\numspellsave{MyNum}
\Numspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\Numspell*{1}
\numspellsave{MyNum}
\Numspell*{2}
\thenumspell;
\thenumspellMyNum

\item\commandinline|\ordnumspell[!<zeros>!]{!<num>!}|\\
Spelling the ordinal number
$n=\text{\color{green!50!black}\itshape$\langle$num$\rangle$}\cdot10^{\text{\color{green!50!black}\itshape$\langle$zeros$\rangle$}}$,
where $0\leq n\leq 10^{67}-1$. The default value of \commandinline|!<zeros>!| is \texttt{0}. For example
\begin{flushleft}
\verb|\ordnumspell{12000}| $\to$ \ordnumspell{12000}\\
\verb|\ordnumspell[3]{12}| $\to$ \ordnumspell[3]{12}\\
\verb|\ordnumspell[6]{12}| $\to$ \ordnumspell[6]{12}\\
\verb|\ordnumspell[63]{1}| $\to$ \ordnumspell[63]{1}
\end{flushleft}

\item\commandinline|\ordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\ordnumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\ordnumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\ordnumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\ordnumspell*{1}
\numspellsave{MyNum}
\ordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\ordnumspell*{1}
\numspellsave{MyNum}
\ordnumspell*{2}
\thenumspell;
\thenumspellMyNum

\item\commandinline|\Ordnumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\ordnumspell|, but the first letter will be capital. For example
\begin{flushleft}
\verb|\Ordnumspell{12000}| $\to$ \Ordnumspell{12000}\\
\verb|\Ordnumspell[3]{12}| $\to$ \Ordnumspell[3]{12}\\
\verb|\Ordnumspell[6]{12}| $\to$ \Ordnumspell[6]{12}\\
\verb|\Ordnumspell[63]{1}| $\to$ \Ordnumspell[63]{1}
\end{flushleft}

\item\commandinline|\Ordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\Ordnumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\Ordnumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\Ordnumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\Ordnumspell*{1}
\numspellsave{MyNum}
\Ordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
\Ordnumspell*{1}
\numspellsave{MyNum}
\Ordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{description}

\section{Commands for English language}
\begin{description}
\item\commandinline|\numspellUS|\\
By default, the number spelling will happen in British English, if the \texttt{english} language is active.
This command changes it to American English. For example
\begin{flushleft}
\verb|\numspellUS\numspell{1012345}| $\to$ \numspellUS\numspell{1012345}\numspellGB
\end{flushleft}

\item\commandinline|\numspellGB|\\
Using the \verb|\numspellUS| command, you can rechange it to British English by this command. For example
\begin{verbatim}
\numspellUS\numspell{1012345}\\
\numspellGB\numspell{1012345}
\end{verbatim}
\numspellUS\numspell{1012345}\\
\numspellGB\numspell{1012345}
\end{description}

\section{Commands for French language}
The following commands only work, if \texttt{french} language is active.
\begin{description}
\selectlanguage{french}
\item\commandinline|\numspellpremiere|\\
By default, \verb|\ordnumspell{1}| $\to$ \ordnumspell{1},\\
but \verb|\numspellpremiere\ordnumspell{1}| $\to$ {\numspellpremiere\ordnumspell{1}}

\item\commandinline|\numspellpremier| (default)\\
\verb|\numspellpremiere\ordnumspell{1};|\\
\verb|\numspellpremier\ordnumspell{1}|\\[2mm]
{\numspellpremiere\ordnumspell{1}}; {\numspellpremier\ordnumspell{1}}
\end{description}

\section{Commands for Hungarian language}
The following commands only work, if \texttt{magyar} language is active.
\begin{description}
\item\commandinline|\anumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\numspell|, but the number spelling will start with Hungarian definite article. For example
\begin{flushleft}
{\selectlanguage{magyar}
\verb|\anumspell{1}| $\to$ \anumspell{1}\\
\verb|\anumspell{2}| $\to$ \anumspell{2}}
\end{flushleft}

\item\commandinline|\anumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\anumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\anumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\anumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\anumspell*{1}
\numspellsave{MyNum}
\anumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
{\selectlanguage{magyar}
\anumspell*{1}
\numspellsave{MyNum}
\anumspell*{2}
\thenumspell;
\thenumspellMyNum}

\item\commandinline|\Anumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\anumspell|, but the first letter will be capital. For example
\begin{flushleft}
{\selectlanguage{magyar}
\verb|\Anumspell{1}| $\to$ \Anumspell{1}\\
\verb|\Anumspell{2}| $\to$ \Anumspell{2}}
\end{flushleft}

\item\commandinline|\Anumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\Anumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\Anumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\Anumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\Anumspell*{1}
\numspellsave{MyNum}
\Anumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
{\selectlanguage{magyar}
\Anumspell*{1}
\numspellsave{MyNum}
\Anumspell*{2}
\thenumspell;
\thenumspellMyNum}

\item\commandinline|\aordnumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\ordnumspell|, but the number spelling will start with Hungarian definite article. For example
\begin{flushleft}
{\selectlanguage{magyar}
\verb|\aordnumspell{1}| $\to$ \aordnumspell{1}\\
\verb|\aordnumspell{2}| $\to$ \aordnumspell{2}}
\end{flushleft}

\item\commandinline|\aordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\aordnumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\aordnumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\aordnumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\aordnumspell*{1}
\numspellsave{MyNum}
\aordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
{\selectlanguage{magyar}
\aordnumspell*{1}
\numspellsave{MyNum}
\aordnumspell*{2}
\thenumspell;
\thenumspellMyNum}

\item\commandinline|\Aordnumspell[!<zeros>!]{!<num>!}|\\
It works like \verb|\aordnumspell|, but the first letter will be capital. For example
\begin{flushleft}
{\selectlanguage{magyar}
\verb|\Aordnumspell{1}| $\to$ \Aordnumspell{1}\\
\verb|\Aordnumspell{2}| $\to$ \Aordnumspell{2}}
\end{flushleft}

\item\commandinline|\Aordnumspell*[!<zeros>!]{!<num>!}|\\
It works like \verb|\Aordnumspell|, but the number spelling will not be printed.
In other words, the following two lines are equivalent:
\begin{flushleft}
\verbinline|\Aordnumspell[!<zeros>!]{!<num>!}|\\
\verbinline|\Aordnumspell*[!<zeros>!]{!<num>!}\thenumspell|
\end{flushleft}
For example
\begin{verbatim}
\Aordnumspell*{1}
\numspellsave{MyNum}
\Aordnumspell*{2}
\thenumspell;
\thenumspellMyNum
\end{verbatim}
{\selectlanguage{magyar}
\Aordnumspell*{1}
\numspellsave{MyNum}
\Aordnumspell*{2}
\thenumspell;
\thenumspellMyNum}
\end{description}

\section{Examples}
\subsection*{Example \stepcounter{subsection}\arabic{subsection}}
\begin{examplelst}
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[magyar,german,french,english]{babel}
\usepackage{numspell}
\usepackage[group-separator={,}]{siunitx}
\begin{document}

\def\mynum{123456789}

\noindent
In British English the spelling of \num{\mynum} is
\emph{``\numspell{\mynum}''}.

\smallskip\noindent
In American English the spelling of \num{\mynum} is
{\numspellUS\emph{``\numspell{\mynum}''}}.

\smallskip\noindent
In German the spelling of \num{\mynum} is
{\selectlanguage{german}\emph{``\numspell{\mynum}''}}.

\smallskip\noindent
In French the spelling of \num{\mynum} is
{\selectlanguage{french}\emph{``\numspell{\mynum}''}}.

\smallskip\noindent
In Hungarian the spelling of \num{\mynum} is
{\selectlanguage{magyar}\emph{`'\numspell{\mynum}''}}.

\end{document}
\end{examplelst}

\def\mynum{123456789}

\noindent
In British English the spelling of \num{\mynum} is \emph{``\numspell{\mynum}''}.

\smallskip\noindent
In American English the spelling of \num{\mynum} is
{\numspellUS\emph{``\numspell{\mynum}''}}.

\smallskip\noindent
In German the spelling of \num{\mynum} is
{\selectlanguage{german}\emph{``\numspell{\mynum}''}}.

\smallskip\noindent
In French the spelling of \num{\mynum} is
{\selectlanguage{french}\emph{``\numspell{\mynum}''}}.

\smallskip\noindent
In Hungarian the spelling of \num{\mynum} is
{\selectlanguage{magyar}\emph{`'\numspell{\mynum}''}}.

\bigskip
\subsection*{Example \stepcounter{subsection}\arabic{subsection}}
\begin{examplelst}
\documentclass{article}
\usepackage{numspell}
\usepackage[group-separator={,}]{siunitx}
\begin{document}

\def\mynum{123456789012345678901234567890123456789012345678901234567890123456}
\Numspell{\mynum}, that is \num{\mynum}.

\end{document}
\end{examplelst}

\def\mynum{123456789012345678901234567890123456789012345678901234567890123456}
\Numspell{\mynum}, that is \num{\mynum}.

\bigskip
\subsection*{Example \stepcounter{subsection}\arabic{subsection}}
\begin{examplelst}
\documentclass{article}
\usepackage{numspell}
\newcounter{mycount}
\makeatletter
\begin{document}

The
\@whilenum\value{mycount}<31
\do{\ordnumspell{\themycount}\stepcounter{mycount},\ }\dots

\end{document}
\end{examplelst}

\makeatletter
\newcounter{mycount}
The
\@whilenum\value{mycount}<31
\do{\ordnumspell{\themycount}\stepcounter{mycount},\ }\dots
\makeatother

\bigskip
\subsection*{Example \stepcounter{subsection}\arabic{subsection}}
\begin{examplelst}
\documentclass{article}
\usepackage{numspell}
\newcounter{mycount}
\def\themycount{\numspell{\arabic{mycount}}}
\makeatletter
\begin{document}

\Numspell{0},
\@whilenum\value{mycount}<30
\do{\stepcounter{mycount}\themycount,\ }\dots

\end{document}
\end{examplelst}

\def\themycount{\numspell{\arabic{mycount}}}
\setcounter{mycount}{0}
\makeatletter
\Numspell{0},
\@whilenum\value{mycount}<30
\do{\stepcounter{mycount}\themycount,\ }\dots
\makeatother

\bigskip
\section{Limitations}
Do not use the \verb|\numspell|, \verb|\numspell*|, \verb|\Numspell|, \verb|\Numspell*|, etc.\ commands inside \verb|\MakeUppercase| and sectioning commands.
An example for the illustration of the problem:
\begin{examplelst}
\documentclass{article}
\usepackage{hyperref,numspell}
\pagestyle{headings}
\begin{document}

\section{The \ordnumspell{123} factor}
\MakeUppercase{\numspell{123}}
\newpage
Text

\end{document}
\end{examplelst}
\noindent
The bugs:
\begin{enumerate}
\setlength{\labelsep}{5pt}
\item
You can see it on the page 1: ``\numspell{123}''\\
Required: \numspell*{123}\MakeUppercase{``\thenumspell''}

\item
You can see it on the heading: \emph{``THE \ordnumspell{123} FACTOR''}\\
Required: \ordnumspell*{123}\MakeUppercase{\em``The \thenumspell\ factor''}

\item
You can see it on the pdf bookmark: ``The 123 factor''\\
Required: ``The \ordnumspell{123} factor''
\end{enumerate}
\noindent
The solution is very easy:
\begin{examplelst}
\ordnumspell*{123}
\section{The \thenumspell\ factor}
\numspell*{123}
\MakeUppercase{\thenumspell}
\end{examplelst}

\end{document}