\documentclass[11pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{hyperref}
\usepackage{geometry}
\geometry{margin=2.6cm}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{microtype}
\microtypesetup{expansion=false}
\usepackage{booktabs}
\usepackage{enumitem}

\lstdefinelanguage{malagasyshell}{
  morekeywords={},
  sensitive=false,
  morecomment=[l]{\#},
}
\lstset{
  basicstyle=\ttfamily\small,
  breaklines=true,
  frame=single,
  backgroundcolor=\color{gray!8},
  columns=fullflexible,
}

\title{Guide d'utilisation\\\texttt{malagasy-numberwords}}
\author{RALAHADY Bruno Bakys\thanks{ralahadybru@yahoo.fr}}
\date{Septembre 2026 --- version 0.1.0}

\begin{document}
\maketitle
\tableofcontents

\section{Présentation}

\texttt{malagasy-numberwords} convertit des nombres en leur forme écrite en
malgache~: cardinaux, ordinaux, décimaux, pourcentages, montants en ariary et
dates. Le paquet est disponible en trois formes~: une bibliothèque Python,
une commande en ligne, et un paquet LaTeX (avec une passerelle vers
\texttt{fmtcount}).

Chaque règle de composition est sourcée et documentée (voir le dossier
\texttt{docs/}) ; les limites connues sont signalées explicitement dans ce
guide plutôt que passées sous silence.

\section{Installation}

\subsection{Python et ligne de commande}

\begin{lstlisting}
pip install -e .
\end{lstlisting}

{\sloppy
Ceci installe la bibliothèque Python du paquet ainsi que la commande
\path{malagasy-numberwords}.
\par}

\subsection{LaTeX}

Placez \texttt{malagasy-numberwords.sty} (et, si besoin,
\path{fc-malagasy-numberwords.def}) dans le même dossier que votre document, ou dans un
chemin connu de TeX, puis~:

\begin{lstlisting}
\usepackage{malagasy-numberwords}
\end{lstlisting}

\section{Utilisation en Python}

\begin{lstlisting}[language=Python]
from malagasy_numberwords import (
    number_to_words, ordinal_to_words, decimal_to_words,
    percentage_to_words, currency_to_words, date_to_words,
)

number_to_words(2026)
# 'enina amby roapolo sy roa arivo'

ordinal_to_words(59)
# 'faha sivy amby dimampolo'

decimal_to_words("3.14")
# "telo faingo efatra ambin'ny folo"

percentage_to_words(25)
# 'dimy amby roapolo isan-jato'

currency_to_words(100000)
# 'iray hetsy ariary'

date_to_words(11, 10, 2003)
# "faha iraika ambin'ny folo ny volana Oktobra telo sy roa arivo"
\end{lstlisting}

\subsection{Domaines de validité et erreurs}

\begin{center}
\begin{tabular}{@{}p{4.3cm}p{4.3cm}p{5.5cm}@{}}
\toprule
Fonction & Domaine valide & En cas d'entrée invalide \\
\midrule
\texttt{number\_to\_words} & $0 \le n \le 999\,999{\times}10^6{+}999\,999$ & \texttt{NotImplementedError} \\
\texttt{ordinal\_to\_words} & $n \ge 1$ & \texttt{NotImplementedError} \\
\texttt{decimal\_to\_words} & chaîne \texttt{"X.Y"} ou \texttt{"X,Y"} & \texttt{ValueError} si mal formée \\
\texttt{percentage\_to\_words} & comme \texttt{number\_to\_words} & idem \\
\texttt{currency\_to\_words} & \texttt{currency="MGA"} uniquement & \texttt{NotImplementedError} sinon \\
\texttt{date\_to\_words} & mois entre 1 et 12 & \texttt{ValueError} sinon \\
\bottomrule
\end{tabular}
\end{center}

Aucune fonction ne renvoie silencieusement une forme approximative~: une
entrée hors du domaine sourcé déclenche toujours une erreur explicite.

\section{Utilisation en ligne de commande}

\begin{lstlisting}
malagasy-numberwords 2026
malagasy-numberwords 59 --ordinal
malagasy-numberwords 3.14 --decimal
malagasy-numberwords 50 --percentage
malagasy-numberwords 100000 --currency MGA
malagasy-numberwords 11 --date 10 2003
malagasy-numberwords --help
\end{lstlisting}

En cas d'erreur, la commande affiche un message sur la sortie d'erreur et
retourne un code de sortie non nul (utile dans un script).

\section{Utilisation en LaTeX}

\begin{lstlisting}
\usepackage{malagasy-numberwords}

\MalagasyNumberToWords{2026}
\MalagasyOrdinalToWords{59}
\MalagasyDecimalToWords{3}{14}
\MalagasyPercentageToWords{25}
\MalagasyCurrencyToWords{100000}
\MalagasyDateToWords{11}{10}{2003}
\end{lstlisting}

\subsection{Limite propre au port LaTeX}

Contrairement à la bibliothèque Python (entiers illimités), le port LaTeX
utilise les compteurs natifs de TeX, limités à environ
$\pm 2\,147\,483\,647$. Au-delà, une erreur de paquet explicite est levée
(\texttt{\textbackslash PackageError}) plutôt qu'un résultat silencieusement
faux.

\subsection{Intégration avec \texttt{fmtcount}}

\begin{lstlisting}
\usepackage{malagasy-numberwords}
\usepackage{fmtcount}
\MalagasyLoadFmtcountSupport

\numberstringnum{2026}
\ordinalstringnum{59}
\end{lstlisting}

{\sloppy
\textbf{Point important~:} le malgache n'étant pas reconnu par
\texttt{babel}/\texttt{polyglossia}, et le fichier d'interopérabilité étant
nommé \path{fc-malagasy-numberwords.def} (et non \path{fc-malagasy.def},
pour rester facilement identifiable comme appartenant à ce paquet), la
commande standard de chargement de langue de \texttt{fmtcount} ne le
trouverait pas. La macro \path{\MalagasyLoadFmtcountSupport} reproduit le
mécanisme interne nécessaire (activation du mode multilingue, réglage de
\texttt{languagename}, chargement du fichier sous son nom
réel) en une seule commande. \texttt{fmtcount} lui-même limite
\texttt{numberstringnum} et \texttt{ordinalstringnum} à la plage 0--99999
(limite de \texttt{fmtcount}, pas de \texttt{malagasy-numberwords}).
\par}

\section{Limites connues (toutes langues confondues)}

\begin{itemize}[leftmargin=1.4em]
  \item \textbf{Cardinal} — au-delà de $999\,999{\times}10^6{+}999\,999$,
    comportement non sourcé.
  \item \textbf{Décimal} — un zéro non significatif dans la partie décimale
    (ex. « 3,05 ») peut être mal interprété (lu comme « 5 », pas « zéro
    cinq »).
  \item \textbf{Date} — le jour et l'année épelés en toutes lettres sont une
    extrapolation~: les sources réelles observées gardent ces deux éléments
    en chiffres.
  \item \textbf{Monnaie} — seul l'ariary (MGA) est pris en charge ; la
    sous-unité \emph{iraimbilanja} (1/5 ariary) n'est pas gérée.
  \item \textbf{LaTeX} — plafond des compteurs 32 bits de TeX (voir
    ci-dessus).
\end{itemize}

\section{Où trouver plus de détails}

\begin{center}
\begin{tabular}{@{}p{4.2cm}p{9.5cm}@{}}
\toprule
Document & Contenu \\
\midrule
\url{docs/api.md} & Référence complète de l'API Python \\
\url{docs/latex.md} & Détails du port LaTeX et de l'intégration \texttt{fmtcount} \\
\url{docs/linguistic-model.md} & Règles de composition des cardinaux, sources \\
\url{docs/formal-grammar.md} & Grammaire formelle, historique des révisions \\
\url{docs/ordinal-model.md}, \url{decimal-model.md}, \url{currency-model.md}, \url{date-model.md} & Règles par module \\
\url{docs/article.pdf} & Article de synthèse (contexte, méthodologie, comparaison) \\
\url{CONTRIBUTING.md} & Comment proposer une source ou une correction \\
\bottomrule
\end{tabular}
\end{center}

\end{document}