french-typo 1.3.0

= French Typo
Dhrions
Version 1.0.0, 27/07/2026
:sectnums:
:toc:
:toclevels: 3
:toc-title: Sommaire
:description: Moteur de correction typographique française (core Python, CLI, intégrations)
:keywords: typographie française, espaces insécables, Python, CLI, Anki, AsciiDoc
:icons: font

ifdef::env-github[]
image:https://img.shields.io/badge/version-1.0.0-blue[]
image:https://img.shields.io/badge/license-MIT-green[]
image:https://img.shields.io/badge/python-3.8%2B-blue[]
endif::[]

== ⚡ TL;DR

* 📝 Corrige la typographie française usuelle (espaces insécables, unités, ordinaux) d'un texte, d'un fichier AsciiDoc ou d'une note Anki
* 🎯 Quand : en bibliothèque Python dans un autre outil, en CLI sur des fichiers `.adoc`, ou comme add-on Anki
* 🚀 `french-typo mon_fichier.adoc` — corrige un fichier AsciiDoc en place

== 📖 Introduction

**French Typo** est un moteur de correction typographique française écrit en Python.

Il applique automatiquement les règles typographiques françaises usuelles (conformes au
link:https://les-unpertinents.fr/Manuscrits/Lexique%20des%20r%C3%A8gles%20typographiques%20en%20usage%20%C3%A0%20l%27Imprimerie%20nationale2.pdf[lexique de l’Imprimerie nationale]) :

* 📏 espaces insécables avant les ponctuations doubles (`: ; ? ! % €`),
* 🔠 normalisation des unités (`KM` → `km`, `KG` → `kg`, etc.),
* 🔢 formatage des ordinaux (`1er` → `1<sup>er</sup>`, `n°4` → `n<sup>o</sup>4`),
* ✂️ suppression des espaces multiples,
* 🔤 gestion des guillemets français (« »).

Le projet est structuré autour :
* 🧩 d’un **core Python pur**, réutilisable partout ;
* 💻 d’une **CLI** pour le traitement de fichiers ;
* 🔌 d’**adaptateurs** pour des environnements spécifiques (Anki, AsciiDoc).

---

== ✨ Fonctionnalités

* ✅ Moteur typographique indépendant (sans dépendance UI)
* ✅ API Python simple et stable
* ✅ Interface en ligne de commande
* ✅ Support d’AsciiDoc
* ✅ Intégration Anki (HTML + cloze)
* ✅ Tests unitaires couvrant le core

---

== 🚀 Installation

=== Installation via pip (recommandée)

[source,bash]
----
pip install french-typo
----

---

== 💻 Utilisation

=== Utilisation en tant que bibliothèque Python

[source,python]
----
from french_typo import format_text

text = "Voir n°4 : 10 KM et article 5."
result = format_text(text, add_nbsp_enabled=True)

print(result)
# Voir n<sup>o</sup>&nbsp;4&nbsp;: 10&nbsp;km et article&nbsp;5.
----

`add_nbsp_enabled` insère les espaces insécables (`&nbsp;`) ; désactivé par défaut.

---

=== Utilisation via la CLI

French Typo fournit une commande `french-typo` pour corriger des fichiers AsciiDoc.

[source,bash]
----
french-typo mon_fichier.adoc
----

Ou récursivement sur un dossier :

[source,bash]
----
french-typo docs/
----

Par défaut, seules les règles typographiques hors espaces insécables sont appliquées
(unités, ordinaux, espaces superflues…). Pour ajouter les espaces insécables :

[source,bash]
----
french-typo --nbsp mon_fichier.adoc
----

Les fichiers sont modifiés *in place*.

---

== 🔗 Intégrations

=== Anki

Le moteur expose un adaptateur Anki (`french_typo.adapters.anki`) qui applique la typographie au
HTML des champs de notes :

* 🔤 gestion des cloze (`{{c1::...}}`) et du HTML ;
* 📝 espaces insécables adaptés au rendu Anki.

L’add-on Anki qui consomme cet adaptateur vit dans un dépôt séparé :
link:https://github.com/dhrions/anki-french-typo[anki-french-typo].

---

=== AsciiDoc

L’adaptateur AsciiDoc permet de corriger automatiquement :

* 📄 les paragraphes standards ;
* 🚫 en ignorant les blocs littéraux (`----`) ;
* 🚫 en ignorant les commentaires (`//`) ;
* 🔤 en ignorant les marqueurs structurels (titres `= …`, attributs `:clé: valeur`,
  chemins relatifs `./…`) et les URL, jamais touchés par les règles typographiques ;
* 🈳 en écrivant le vrai caractère insécable Unicode (`U+00A0`), pas l’entité HTML
  `&nbsp;` — celle-ci reste réservée à l’adaptateur Anki, pensé pour du HTML. Un fichier
  déjà formaté par une version antérieure de l’outil (avec l’entité) est relu et
  reconnu correctement.

---

== 🏗️ Architecture du projet

[source]
----
french-typo/
├── french_typo/
│   ├── core/              # Moteur typographique pur
│   ├── adapters/          # Intégrations (Anki, AsciiDoc)
│   └── cli.py             # Interface CLI
└── tests/                 # Tests unitaires
----

Le dépôt ne contient que le moteur et sa CLI. Les intégrations applicatives (comme l’add-on
link:https://github.com/dhrions/anki-french-typo[anki-french-typo]) vivent dans leurs propres
dépôts et consomment `french-typo` depuis PyPI.

---

== 🛠️ Développement

=== Installation pour le développement

[source,bash]
----
git clone https://github.com/dhrions/french-typo.git
cd french-typo
python -m venv env
source env/bin/activate
pip install -e ".[dev]"
----

=== Exécuter les tests

[source,bash]
----
pytest
----

---

== 💭 Philosophie du projet

* 🧱 séparation stricte entre **moteur** et **interfaces** ;
* 🎯 API simple, explicite, testée ;
* 🪶 aucune dépendance lourde dans le core ;
* 🔮 extensible vers d’autres formats (Markdown, LaTeX, etc.).

---

== 🗺️ Feuille de route

Les jalons du projet sont décrits dans link:ROADMAP.md[ROADMAP.md] ; le backlog technique
détaillé vit dans link:TODO.md[TODO.md].

---

== 📜 Licence

Ce projet est distribué sous licence MIT.
Voir le fichier link:LICENSE[LICENSE].