%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Documentation for the cistercian package
% A package to display cistercian numerals
% Maintained by samcarter
%
% Project repository and bug tracker:
% https://github.com/samcarter/cistercian
%
% Released under the LaTeX Project Public License v1.3c or later
% See https://www.latex-project.org/lppl.txt
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% arara: latexmk
\documentclass{scrartcl}

\usepackage[
  themecolor=samlgray,
]{\jobname-settings}
\colorlet{red}{samred}

\usepackage{cistercian}

\setlength{\footheight}{21pt}
\cfoot{%
  \cistercian[stroke=0.1ex,scale=2]{\value{page}}
}
\pagestyle{scrheadings}

% meta %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{The cistercian package}
\subtitle{A package to display Cistercian numerals}
\author{%
  \texorpdfstring{
    \texttt{samcarter}\\
    \url{https://github.com/samcarter/cistercian}\\
    \url{https://ctan.org/pkg/cistercian}
  }{samcarter}}
\date{Version v0.3 \textendash{} 2025/04/15}
\packagename{cistercian}

\begin{document}
\maketitle
\thispagestyle{scrheadings}

\begin{tcolorbox}[width=.8\textwidth,center,sidebyside=false,title={Note}]
Users, for whom compilation speed is important and who do not need the possibility to modify the appearance of the numerals via Ti\emph{k}Z options, should have a look at the amazingly fast and very versatile \href{https://ctan.org/pkg/xistercian}{xistercian} package instead.

The two packages are not meant to be combined.
\end{tcolorbox}

\section{Introduction}

The \saminline|cistercian| package is meant for displaying Cistercian numerals in \LaTeX{}.
It was inspired by the Numberphile video ``The Forgotten Number System''\footnote{\url{https://www.youtube.com/watch?v=9p55Qgt7Ciw}}. Many thanks to Paulo Cereda for bringing this video to my attention!

\blurb

\section{Cistercian numerals}

Cistercian numerals are a nearly forgotten number system which was invented in the late Middle Ages by Cistercian monks who were, at that time, one of the most influential congregations with monasteries spreading over most of Europe.

Cistercian numerals are a base-10 system for natural numbers up to 9999.
They are formed by a vertical stem for zero \cistercian{0}.
Onto this stem, additional markings are added to denote individual digits, e.g.\ 1 is \cistercian{1}, 2 is \cistercian{2}, etc.
The markings for ones are added at the top right, the ones for tens are mirrored to the top left (e.g.\ 10 is \cistercian{10}), hundreds at the bottom right (e.g.\ 100 is \cistercian{100}) and thousands at the bottom left (e.g.\ \cistercian{1000}).
To form the complete number, the digits are superimposed on top of each other, e.g.\ 1111 is \cistercian{1111}.

While arithmetic calculations are hard with such a numeral system, it provides a compact and uniform way to denote natural numbers, making it well suited for year numbers or sequences like page numbers and footnotes. 

Several variants were in use, in this package we are adopting the glyph shapes as shown in \url{https://commons.wikimedia.org/wiki/File:Cistercian_digits_(vertical).svg}.

\section{Overview numerals}

\begin{center}
\cistercianset{
  height=4.5ex,
  stroke=0.3ex
}
\begin{tabular}{*{9}{c}}
\cistercian{1} & \cistercian{2} & \cistercian{3} & \cistercian{4} & \cistercian{5} & \cistercian{6} & \cistercian{7} & \cistercian{8} & \cistercian{9} \\
1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9\\
\cistercian{10} & \cistercian{20} & \cistercian{30} & \cistercian{40} & \cistercian{50} & \cistercian{60} & \cistercian{70} & \cistercian{80} & \cistercian{90} \\
10 & 20 & 30 & 40 & 50 & 60 & 70 & 80 & 90\\
\cistercian{100} & \cistercian{200} & \cistercian{300} & \cistercian{400} & \cistercian{500} & \cistercian{600} & \cistercian{700} & \cistercian{800} & \cistercian{900} \\
100 & 200 & 300 & 400 & 500 & 600 & 700 & 800 & 900\\
\cistercian{1000} & \cistercian{2000} & \cistercian{3000} & \cistercian{4000} & \cistercian{5000} & \cistercian{6000} & \cistercian{7000} & \cistercian{8000} & \cistercian{9000} \\
1000 & 2000 & 3000 & 4000 & 5000 & 6000 & 7000 & 8000 & 9000\\
\end{tabular}
\end{center}

\section{Basic usage}

The \saminline|cistercian| package provides the macro \saminline|\cistercian{<number>}| to show a given number as Cistercian numeral.
\begin{tcblisting}{title={Basic macro},environment lower args={scalebox}{5}}
\cistercian{42}
\end{tcblisting}

To change the page numbering of a document to Cistercian numerals, the following macro can be used:
\begin{tcblisting}{title={Page numbering},listing only}
\pagenumbering{cistercian}
\end{tcblisting}

\section{Options}

By default, the Cistercian numerals will scale with the surrounding font:
\begin{tcblisting}{title={Font scaling}}
\cistercian{2} Text

\Huge \cistercian{5} Text
\end{tcblisting}

However the height, width and stroke can also be controlled individually (values in parenthesis denote the default value):
\begin{tcblisting}{title={Height (height of ``I'')},environment lower args={scalebox}{5}}
\cistercian{9}
\cistercian[height=2ex]{9}
\end{tcblisting}
\begin{tcblisting}{title={Width (height/3)},environment lower args={scalebox}{5}}
\cistercian{5}
\cistercian[width=0.7ex]{5}
\end{tcblisting}
\begin{tcblisting}{title={Stroke (height/10)},environment lower args={scalebox}{5}}
\cistercian{7}
\cistercian[stroke=0.5mm]{7}
\end{tcblisting}

Internally the package uses a \saminline|tikzpicture| to draw the numeral and also accepts all options, which can normally be passed to the \saminline|tikzpicture| environment, in its optional argument. This can for example be used to change the colour or scale the numeral:
\begin{tcblisting}{title={\TikZ\ options},environment lower args={scalebox}{5}}
\cistercian[scale=2,draw=red]{3141}
\end{tcblisting}

Another \TikZ\ option which might be useful for the Cistercian numerals is \saminline|line join|, which changes how the lines connect to each other. This alters the appearance of the numbers quite a bit and can help to blend them in with the surrounding font.
\begin{tcblisting}{title={Line join (miter)},environment lower args={scalebox}{5}}
\cistercian[line join=round]{53}
\cistercian[line join=bevel]{53}
\cistercian[line join=miter]{53}
\end{tcblisting}

Besides using these option as optional argument, they can also be set globally using the macro \saminline|\cistercianset|:
\begin{tcblisting}{title={Global options},listing only}
\cistercianset{%
  height=1cm,
  width=0.2cm,
  stroke=0.1cm,
  draw=red,
}
\end{tcblisting}

These global options can be reset:
\begin{tcblisting}{title={Reset global options},listing only}
\cistercianreset
\end{tcblisting}

\end{document}