\documentclass[a4paper,12pt]{article}

% ── Encoding and language ──────────────────────────────────────────
\usepackage{fontspec}
\usepackage[turkish]{babel}

% ── Package under documentation ────────────────────────────────────
% To compile in-tree (without installing): run lualatex from the project root,
% e.g.:  lualatex --output-directory=doc doc/dokumanlar.tex
\usepackage{turkce-sayi}

% ── Typesetting utilities ──────────────────────────────────────────
\usepackage{booktabs}
\usepackage{amssymb}
\usepackage{microtype}
\usepackage{xcolor}
\usepackage{listings}
\lstset{
  basicstyle=\ttfamily\small,
  columns=flexible,
  keepspaces=true,
}
\usepackage{hyperref}

% ── Convenience macros for this document ──────────────────────────
\newcommand{\cmd}[1]{\texttt{\textbackslash #1}}
\newcommand{\meta}[1]{\textlangle\textit{#1}\textrangle}
\newcommand{\pkg}[1]{\textsf{#1}}

\title{\pkg{turkce-sayi} — Türkçe Sayı Eklerinin Otomatik Uyumu}
\author{}
\date{2026-06-11 \quad v1.0}

\begin{document}
\maketitle
\tableofcontents
\bigskip

%────────────────────────────────────────────────────────────────────
\section{Introduction}
%────────────────────────────────────────────────────────────────────

When a Turkish suffix is appended to a number produced by a LaTeX
cross-reference (\cmd{pageref}, \cmd{ref}), the correct form of the suffix
cannot be known at editing time because it depends on how that number is
\emph{pronounced} in Turkish.
Writing a fixed suffix works for some numbers but silently produces wrong
output for others:

\begin{center}
\begin{tabular}{lll}
\toprule
\textbf{Source} & \textbf{Wrong output} & \textbf{Correct output} \\
\midrule
\verb|sayfa 2'te|        & sayfa 2'te        & sayfa 2'de \\
\verb|sayfa 3'de|        & sayfa 3'de        & sayfa 3'te \\
\verb|sayfa 6'de|        & sayfa 6'de        & sayfa 6'da \\
\verb|2'inci madde|      & 2'inci madde      & 2'nci madde \\
\bottomrule
\end{tabular}
\end{center}

The \pkg{turkce-sayi} package resolves the suffix automatically at compile
time via LuaTeX, taking the Turkish pronunciation of the number into account.
It requires LuaLaTeX; loading it with pdfLaTeX or XeLaTeX raises a
compilation error.

The rest of this document is written in Turkish and assumes the reader has
a working knowledge of the language.

%────────────────────────────────────────────────────────────────────
\section{Giriş}
%────────────────────────────────────────────────────────────────────

LaTeX'te çapraz gönderme (\cmd{pageref}, \cmd{ref}) ile üretilen sayılara
Türkçe ek eklendiğinde ek biçimi derleme zamanında bilinemez; ek sabit
yazılırsa birçok sayı için yanlış sonuç üretilir:

\begin{center}
\begin{tabular}{lll}
\toprule
\textbf{Kaynak} & \textbf{Yanlış çıktı} & \textbf{Doğru çıktı} \\
\midrule
\verb|sayfa 2'te|   & sayfa 2'te   & sayfa 2'de \\
\verb|sayfa 3'de|   & sayfa 3'de   & sayfa 3'te \\
\verb|sayfa 6'de|   & sayfa 6'de   & sayfa 6'da \\
\verb|2'inci madde| & 2'inci madde & 2'nci madde \\
\bottomrule
\end{tabular}
\end{center}

\pkg{turkce-sayi} paketi, sayının Türkçe söylenişini dikkate alarak
eki LuaTeX aracılığıyla otomatik dönüştürür.
Paket yalnızca LuaLaTeX ile çalışır; pdfLaTeX veya XeLaTeX ile
yüklenirse derleme hatası verilir.

%────────────────────────────────────────────────────────────────────
\section{Dört Kural}
%────────────────────────────────────────────────────────────────────

Sayılar her zaman rakam olarak yazılır; dönüşüm yalnızca eke uygulanır.
Dört ses kuralı sırasıyla ve genel olarak uygulanır — desteklenen ek
listesi yoktur; kural tabanlı olduğu için \emph{anlamlı olmayan ekler
de dahil} herhangi bir ek dizisinde çalışır.

\subsection{Sertleşme (Ünsüz Benzeşmesi — d/t, c/ç)}

Sayının son sesi süreksiz ve tonsuz ise (ç, k, p, t, ş, s, f, h),
ekin baş ünsüzü \emph{d\,→\,t} ve \emph{c\,→\,ç} dönüşümüne uğrar.

\begin{center}
\begin{tabular}{lll}
\toprule
\textbf{Sayı (Türkçe)} & \textbf{Ek} & \textbf{Sonuç} \\
\midrule
3 (üç, tonsuz ç) & -de & \trkappend{3}{'de} \\
4 (dört, tonsuz t) & -de & \trkappend{4}{'de} \\
40 (kırk, tonsuz k) & -de & \trkappend{40}{'de} \\
\bottomrule
\end{tabular}
\end{center}

\subsection{Yumuşama (d/t, c/ç)}

Sayının son sesi ünlü ya da tonlu ünsüz ise,
ekin baş ünsüzü \emph{t\,→\,d} ve \emph{ç\,→\,c} dönüşümüne uğrar.

\begin{center}
\begin{tabular}{lll}
\toprule
\textbf{Sayı (Türkçe)} & \textbf{Ek} & \textbf{Sonuç} \\
\midrule
2 (iki, ünlü i) & -te & \trkappend{2}{'te} \\
1 (bir, tonlu r) & -te & \trkappend{1}{'te} \\
\bottomrule
\end{tabular}
\end{center}

\subsection{Ünlü Uyumu}

İki tip ünlü uyumu uygulanır:

\begin{description}
\item[2'li uyum (e/a):] Ekin \emph{e} veya \emph{a} ünlüsü, sayının
  son ünlüsüne göre değişir: ön ünlü (e, i, ö, ü) → \emph{e};
  arka ünlü (a, ı, o, u) → \emph{a}.
\item[4'lü uyum (i/ı/ü/u):] Ekin \emph{i}, \emph{ı}, \emph{ü} veya
  \emph{u} ünlüsü dört yönlü değişir:
  ön+yuvarlak → ü, ön+düz → i, arka+yuvarlak → u, arka+düz → ı.
\end{description}

\begin{center}
\begin{tabular}{llll}
\toprule
\textbf{Sayı} & \textbf{Son ünlü} & \textbf{Ek} & \textbf{Sonuç} \\
\midrule
6  (altı, arka+düz ı)    & arka+düz    & -de   & \trkappend{6}{'de} \\
3  (üç, ön+yuvarlak ü)   & ön+yuvarlak & -de   & \trkappend{3}{'de} \\
9  (dokuz, arka+yuvarlak u) & arka+yuvarlak & -de & \trkappend{9}{'de} \\
3  & ön+yuvarlak & -iniz & \trkappend{3}{'iniz} \\
9  & arka+yuvarlak & -iniz & \trkappend{9}{'iniz} \\
\bottomrule
\end{tabular}
\end{center}

\subsection{Kaynaştırma Harfi ve Ünlü Düşmesi}

Sayının Türkçe söylenişi ünlüyle bitiyorsa ve ek de ünlüyle başlıyorsa
üç alt durum geçerlidir:

\begin{description}
\item[A — Tek ünlülü ek:] y kaynaştırma harfi eklenir
  (belirtme hali varsayımı; bkz. \S\,\ref{sec:kaynas}).
\item[B — ünlü\,+\,n biçimli ek:] n kaynaştırma harfi eklenir
  (ilgi hali: \emph{-in}).
\item[C — Diğer ünlü başlangıçlı ekler:] baş ünlü düşer
  (sıra sayıları, iyelik ekleri, vb.).
\end{description}

\begin{center}
\begin{tabular}{lll}
\toprule
\textbf{Örnek} & \textbf{Durum} & \textbf{Sonuç} \\
\midrule
6 + \textquotesingle e    & A (y) & \trkappend{6}{'e} \\
6 + \textquotesingle in   & B (n) & \trkappend{6}{'in} \\
2 + \textquotesingle inci & C (düşme) & \trkappend{2}{'inci} \\
2 + \textquotesingle im   & C (düşme) & \trkappend{2}{'im} \\
\bottomrule
\end{tabular}
\end{center}

\subsection{Büyük Ünlü Uyumuna Uymayan Ekler}

\emph{-ki}, \emph{-yor}, \emph{-ken}, \emph{-gil}, \emph{-leyin} ve
\emph{-mtırak} ekleri ünlü uyumuna uymaz; bu eklerin bulunduğu konumda
uyum durumu söz konusu ekin son ünlüsüne sıfırlanır, böylece bu ekten
sonra gelen ekler de doğru uyumu alır.

\begin{center}
\begin{tabular}{ll}
\toprule
\textbf{Kaynak} & \textbf{Sonuç} \\
\midrule
\verb|\trkappend{6}{'deki}|         & \trkappend{6}{'deki} \\
\verb|\trkappend{6}{'dekilerden}|   & \trkappend{6}{'dekilerden} \\
\verb|\trkappend{9}{'durken}|       & \trkappend{9}{'durken} \\
\bottomrule
\end{tabular}
\end{center}

%────────────────────────────────────────────────────────────────────
\section{Komutlar}
%────────────────────────────────────────────────────────────────────

Tüm komutlarda ek argümanı son kullanıcı tarafından belirlenir.
Argümanın başındaki harf olmayan karakterler (kesme işareti, tire,
boşluk vb.) değiştirilmeden aktarılır; dönüşüm yalnızca harf kısmına
uygulanır.

\subsection{\cmd{trksuffix}\{\meta{sayı}\}\{\meta{ek}\}}

Dönüştürülmüş eki çıktılar; rakamı yazmaz.
Kesme işareti ek argümanına dahil edilmelidir.

\begin{lstlisting}
\trksuffix{3}{'de}   % 'te
\end{lstlisting}

\subsection{\cmd{trkappend}\{\meta{sayı}\}\{\meta{ek}\}}

Rakamı, ardından dönüştürülmüş eki çıktılar.
Kesme işareti ek argümanına dahil edilmelidir.
Argümanın saf tamsayı ifadesi olması gerekir (\cmd{the}\cmd{value}\{\ldots\} gibi).

\begin{lstlisting}
\trkappend{6}{'de}              % 6'da
\trkappend{\the\value{chapter}}{'de}  % X'da (bölüm numarasına göre)
\end{lstlisting}

\subsection{\cmd{trkpageref}\{\meta{etiket}\}\{\meta{ek}\}}

\cmd{pageref} ile eşdeğerdir; ek otomatik dönüştürülür.

\begin{lstlisting}
\trkpageref{bolum:giris}{'de}   % ör. 3'te
\end{lstlisting}

\subsection{\cmd{trkref}\{\meta{etiket}\}\{\meta{ek}\}}

\cmd{ref} ile eşdeğerdir; ek otomatik dönüştürülür.

\begin{lstlisting}
\trkref{bolum:giris}{'inci}     % ör. 3'üncü
\end{lstlisting}

\subsection{\cmd{trkbibappend}\{\meta{sayı}\}\{\meta{ek}\}}

Sayıyı köşeli parantez içinde çıktılar, ardından dönüştürülmüş eki ekler.
Kaynakça numarası doğrudan bilindiğinde kullanılır.

\begin{lstlisting}
\trkbibappend{3}{'de}    % [3]'te
\trkbibappend{6}{'de}    % [6]'da
\trkbibappend{40}{'de}   % [40]'ta
\end{lstlisting}

\subsection{\cmd{trkbibref}\{\meta{anahtarlar}\}\{\meta{ek}\}}

\cmd{cite} ile eşdeğerdir; ek, virgülle ayrılmış anahtar listesinin
\emph{son} anahtarının numarasına göre otomatik dönüştürülür.
Standart sayısal kaynakça (\cmd{bibitem}) gerektirir ve en az iki
derleme gerektirir.

\begin{lstlisting}
\trkbibref{smith2021}{'de}        % [3]'te  (smith2021 = kaynak 3)
\trkbibref{jones,smith2021}{'de}  % [1, 3]'te  (son anahtar = 3)
\end{lstlisting}

\subsection{\cmd{trkmanual}\{\meta{gösterim}\}\{\meta{sabit-ek}\}}

Kaçış kapısı: herhangi bir dönüşüm uygulamaz; ek argümanı olduğu gibi
çıktılanır. Kesme işareti yine ek argümanına dahil edilmelidir.

\begin{lstlisting}
\trkmanual{6}{'daş}   % 6'daş  (dönüşüm yapılmaz)
\end{lstlisting}

\subsection{\cmd{trksetoverride}\{\meta{sayı}\}\{\meta{algoritma-çıktısı}\}\{\meta{yerine-geçen}\} /
            \cmd{trkremoveoverride}\{\meta{sayı}\}\{\meta{algoritma-çıktısı}\}}

Algoritmanın belirli bir sayı için ürettiği belirli bir eki geçersiz kılar.
İkinci argüman algoritmanın ürettiği ek (kesme işareti olmadan),
üçüncü argüman ise onun yerine kullanılacak ektir.
Aynı sayıya ait diğer ekler etkilenmez.

\begin{lstlisting}
% 100 (yüz) + 'inci → algoritma 'üncü üretir.
% Bunu 'uncu ile değiştir; 'de gibi diğer ekler etkilenmez.
\trksetoverride{100}{üncü}{uncu}
\trkappend{100}{'inci}   % 100'uncu  (override ateşlendi)
\trkappend{100}{'de}     % 100'de    (override yok, algoritma çalıştı)
\trkremoveoverride{100}{üncü}
\trkappend{100}{'inci}   % 100'üncü  (otomatik kurallara döndü)
\end{lstlisting}

\subsection{debug seçeneği}

Paket \texttt{debug} seçeneği ile yüklenirse her dönüşüm TeX günlüğüne
yazılır:

\begin{lstlisting}
\usepackage[debug]{turkce-sayi}
\end{lstlisting}

%────────────────────────────────────────────────────────────────────
\section{Kaynaştırma Harfi Seçimi}
\label{sec:kaynas}
%────────────────────────────────────────────────────────────────────

Ünlüyle biten bir sayı (ör. 6 — \emph{altı}) ile tek bir ünlü ek
(belirtme hali \emph{-i/ı/ü/u} ya da yönelme hali \emph{-e/a})
bir araya geldiğinde hangi kaynaştırma harfinin kullanılacağı
yalnızca dilsel bağlamdan çıkarsanabilir:

\begin{center}
\begin{tabular}{lll}
\toprule
\textbf{İşlev} & \textbf{Kullanım} & \textbf{Çıktı} \\
\midrule
Belirtme hali (nesne) & \verb|\trkappend{6}{'i}|  & \trkappend{6}{'i} \\
İyelik/tanımlık       & \verb|\trkappend{6}{'si}| & \trkappend{6}{'si} \\
\bottomrule
\end{tabular}
\end{center}

Paket tek ünlülü ek için \emph{y} kaynaştırmasını \textbf{varsayılan}
olarak kabul eder (belirtme hali).
İyelik ya da tanımlık yapı istendiğinde kullanıcı ilgili kaynaştırma
harfini eke dahil ederek yazar (\verb|'si|, \verb|'sı|, \verb|'sü|,
\verb|'su|); bu durumda ek ünsüzle başladığı için kaynaştırma kuralı
devreye girmez ve yalnızca ünlü uyumu uygulanır.

%────────────────────────────────────────────────────────────────────
\section{Sayı Tablosu}
%────────────────────────────────────────────────────────────────────

Aşağıdaki tablo paketin her sayı bileşeni için kullandığı
ses özelliklerini gösterir.
\emph{f}: ön ünlü; \emph{r}: yuvarlak ünlü;
\emph{v}: ünlüyle biter; \emph{d}: son ses tonlu.

\begin{center}
\begin{tabular}{rlcccc}
\toprule
\textbf{Sayı} & \textbf{Türkçe} & \textbf{f} & \textbf{r} & \textbf{v} & \textbf{d} \\
\midrule
0    & sıfır   & --  & --  & --  & $\checkmark$ \\
1    & bir     & $\checkmark$   & --  & --  & $\checkmark$ \\
2    & iki     & $\checkmark$   & --  & $\checkmark$   & $\checkmark$ \\
3    & üç      & $\checkmark$   & $\checkmark$   & --  & -- \\
4    & dört    & $\checkmark$   & $\checkmark$   & --  & -- \\
5    & beş     & $\checkmark$   & --  & --  & -- \\
6    & altı    & --  & --  & $\checkmark$   & $\checkmark$ \\
7    & yedi    & $\checkmark$   & --  & $\checkmark$   & $\checkmark$ \\
8    & sekiz   & $\checkmark$   & --  & --  & $\checkmark$ \\
9    & dokuz   & --  & $\checkmark$   & --  & $\checkmark$ \\
10   & on      & --  & $\checkmark$   & --  & $\checkmark$ \\
20   & yirmi   & $\checkmark$   & --  & $\checkmark$   & $\checkmark$ \\
30   & otuz    & --  & $\checkmark$   & --  & $\checkmark$ \\
40   & kırk    & --  & --  & --  & -- \\
50   & elli    & $\checkmark$   & --  & $\checkmark$   & $\checkmark$ \\
60   & altmış  & --  & --  & --  & -- \\
70   & yetmiş  & $\checkmark$   & --  & --  & -- \\
80   & seksen  & $\checkmark$   & --  & --  & $\checkmark$ \\
90   & doksan  & --  & --  & --  & $\checkmark$ \\
100  & yüz     & $\checkmark$   & $\checkmark$   & --  & $\checkmark$ \\
1000 & bin     & $\checkmark$   & --  & --  & $\checkmark$ \\
$10^6$  & milyon  & --  & $\checkmark$   & --  & $\checkmark$ \\
$10^9$  & milyar  & --  & --  & --  & $\checkmark$ \\
$10^{12}$ & trilyon & --  & $\checkmark$   & --  & $\checkmark$ \\
\bottomrule
\end{tabular}
\end{center}

%────────────────────────────────────────────────────────────────────
\section{Uygulama Notları}
%────────────────────────────────────────────────────────────────────

\paragraph{Algoritma özeti.}
\cmd{trkpageref} ve \cmd{trkref} sırasıyla \pkg{refcount} paketinin
\cmd{getpagerefnumber} ve \cmd{getrefnumber} komutlarını kullanarak
referans değerini saf bir tamsayı dizesine dönüştürür; bu dize
\texttt{\textbackslash directlua} içinde Lua'ya geçirilir.
Lua modülü \texttt{last\_word(n)} ile sayının belirleyici bileşenini
bulur, ardından \texttt{harmonize()} ile dört kuralı karakter karakter
uygular.

\paragraph{Büyük/küçük harf.}
Algoritma büyük/küçük harfi korur: ek argümanındaki her karakter
dönüşüm sonrasında özgün harf büyüklüğünü korur.
Örneğin \verb|\trkappend{3}{'De}| çıktısı \trkappend{3}{'De} biçimindedir
(D büyük, e küçük; sertleşme kuralıyla D→T korunur).

\paragraph{Büyük sayılar.}
IEEE\,754 çift duyarlıklı kayan nokta $2^{53} \approx 9 \times 10^{15}$
üzerindeki tam sayıları tam olarak temsil edemez.
Pratikte sayfa ve bölüm numaraları bu sınırı aşmaz.

\paragraph{UTF-8.}
Modül standart Lua\,5.3 \texttt{utf8} kütüphanesini kullanır;
LuaTeX\,1.10+ (TeX\,Live\,2019+) gereklidir.

%────────────────────────────────────────────────────────────────────
\section{Sınırlılıklar}
%────────────────────────────────────────────────────────────────────

\begin{itemize}
\item \textbf{Sayı olmayan referanslar:} Harfli bölüm numaraları
  (\emph{A}, \emph{B}, \ldots) \cmd{trkref} ile kullanılamaz;
  \cmd{trkmanual} tercih edilmelidir.
\item \textbf{İlk derleme:} LaTeX çapraz gönderme sistemi gereği ilk
  derlemede referans değerleri henüz bilinmez; en az iki kez derleyin.
\end{itemize}

\end{document}