# turkce-sayi

A LuaLaTeX package that automatically applies Turkish suffix harmony to
numbers produced by LaTeX (page references, section numbers, counters).

## The Problem

Turkish suffixes must agree phonologically with the word they attach to.
When a number is written as a digit, the suffix depends on how that number
is *pronounced* in Turkish — which LaTeX cannot know at editing time.

Writing a fixed suffix works for some numbers but silently breaks for others:

| Intended | Wrong output | Reason |
|----------|-------------|--------|
| 3'**te** | 3'**de** | *üç* ends in voiceless *ç* → suffix must harden *d→t* |
| 6'**da** | 6'**de** | *altı* has back vowel *ı* → suffix vowel must shift *e→a* |
| 2'**nci** | 2'**inci** | *iki* ends in vowel → initial vowel of suffix must drop |

## The Solution

`turkce-sayi` looks up the phonological properties of the number's Turkish
name and rewrites the suffix string at compile time using four rules:

1. **Consonant hardening** — *d→t*, *c→ç* when the number ends in a
   voiceless consonant (e.g. *üç*, *dört*, *kırk*).
2. **Consonant softening** — *t→d*, *ç→c* when it ends in a voiced
   consonant or vowel.
3. **Vowel harmony** — *e/a* shifts 2-way (front/back); *i/ı/ü/u* shifts
   4-way based on the number's final vowel.
4. **Buffer letter / vowel drop** — when both the number and the suffix
   start with a vowel, three sub-cases apply:
   - single-vowel suffix (dative/accusative): insert *y* — `6'ya`, `6'yı`
   - *V+n* suffix (genitive): insert *n* — `6'nın`
   - all other vowel-initial suffixes: drop the first vowel — `2'nci`, `2'm`

Rules are applied character-by-character to the full suffix string with no
predefined suffix list, so compound suffixes such as *dekilerden* work
automatically. Invariant morphemes (*-ki*, *-yor*, *-ken*, *-gil*,
*-leyin*, *-mtırak*) are detected and harmony is reset to their vowel so
that subsequent morphemes harmonize correctly.

## Usage

```latex
\usepackage{turkce-sayi}   % requires lualatex

\trkappend{6}{'de}          % 6'da
\trkappend{3}{'inci}        % 3'üncü
\trkpageref{sec:intro}{'de} % e.g. 5'te  (uses \pageref internally)
\trkref{sec:results}{'de}   % e.g. 2'de  (uses \ref internally)
```

The apostrophe (or any leading punctuation) is part of the suffix argument —
the package transforms only the letter portion and leaves the punctuation
untouched.

For the possessive/definite suffix, supply the buffer consonant yourself
since a bare vowel is ambiguous:

```latex
\trkappend{6}{'i}    % 6'yı  — accusative (y-buffer is the default)
\trkappend{6}{'si}   % 6'sı  — possessive/definite (user writes "si")
```

For bibliography (numeric) citations, use the bracket-aware variants:

```latex
\trkbibappend{3}{'te}              % [3]'te  — number known directly
\trkbibref{smith2021}{'de}         % [3]'te  — resolved from cite key
\trkbibref{jones,smith2021}{'de}   % [1, 3]'te  — list: suffix from last key
```

An escape hatch is available for cases the rules cannot handle:

```latex
\trkmanual{6}{'daş}                   % 6'daş — no transformation applied

% Override: when the algorithm produces 'üncü for 100, use 'uncu instead.
% Other suffixes for 100 (e.g. 'de) are unaffected.
\trksetoverride{100}{üncü}{uncu}
\trkappend{100}{'inci}                % 100'uncu  (override fired)
\trkappend{100}{'de}                  % 100'de    (no override for 'de)
\trkremoveoverride{100}{üncü}         % restore automatic behaviour
```

## Files

| File | Purpose |
|------|---------|
| `turkce-sayi.sty` | LaTeX package |
| `turkce-sayi.lua` | Lua module with all phonological logic |
| `doc/dokumanlar.tex` | Full documentation (Turkish, with an English introduction) |
| `doc/ornek.tex` | Sample document and test table |

## Requirements

- LuaLaTeX (LuaTeX 1.10 / TeX Live 2019 or later)
- Standard packages: `iftex`, `luatexbase`, `refcount`

## Compiling the sample documents

```sh
l3build doc
```

Or directly from the project root:

```sh
lualatex --output-directory=build/doc doc/ornek.tex
lualatex --output-directory=build/doc doc/ornek.tex      # second pass for refs
lualatex --output-directory=build/doc doc/dokumanlar.tex
lualatex --output-directory=build/doc doc/dokumanlar.tex
```

## License

LPPL 1.3c — https://www.latex-project.org/lppl.txt