Skip to content

07 FAQ

Jump to bottom
Asterios Raptis edited this page Mar 11, 2026 · 5 revisions

FAQ

Allgemein

Warum eine eigene Library statt drei Skripte?

Wiederverwendbarkeit. Die Logik (Wortzaehlung, Textbereinigung, Regelvalidierung) ist in jedem Buchprojekt gleich. Mit einer Library importierst du sie direkt, statt Code zu kopieren. Ausserdem sind pure Functions testbar, lose Skripte nicht.

Warum Poetry statt pip/setuptools?

Poetry verwaltet Dependencies, Virtual Environments, Build und Publish in einem Tool. Die pyproject.toml ist der einzige Konfigurationsort. Kein setup.py, kein setup.cfg, kein requirements.txt, kein MANIFEST.in.

Warum ftfy als einzige externe Dependency?

Mojibake-Reparatur korrekt zu implementieren ist aufwaendig und fehleranfaellig. ftfy loest dieses Problem seit Jahren zuverlaessig. Alles andere (Regex, Unicode-Normalisierung, File-I/O) kommt aus der Standardlibrary.

Verwendung

Kann ich die Tools auf Nicht-Markdown-Dateien anwenden?

Ja. Aendere den --include Parameter:

poetry run ms-check manuscript/ --include '**/*.txt'
make check INCLUDE="**/*.rst"

Die Bereinigung und Wortzaehlung funktionieren auf jedem Plaintext-Format. Die Markdown-Syntax-Filterung in count_words greift nur bei Markdown-typischen Zeichen.

Wie fuege ich eine neue Regel dauerhaft hinzu?

Zwei Wege:

  1. Als Entwickler (im Library-Code): Regel in checker.py implementieren, zur Gruppe und zum RULE_REGISTRY hinzufuegen.

  2. Als Nutzer (ohne Code-Aenderung): Existierende Prosa-Regeln per pyproject.toml aktivieren:

[tool.manuscript-tools]
rules = ["max-sentence-length", "filler-words-de"]

Das fuegt die genannten Regeln zu den Core-Defaults hinzu. Siehe Konfiguration fuer alle Optionen.

Kann ich einzelne Regeln abschalten?

Ja, ueber disable in der pyproject.toml:

[tool.manuscript-tools]
disable = ["passive-voice-de", "no-double-spaces"]

Die Regeln werden aus dem aktiven Set entfernt, auch wenn sie ueber rules aktiviert wurden. In dem Fall erscheint eine Warnung.

Die Wortzaehlung weicht von meinem Texteditor ab. Warum?

manuscript-tools nutzt Regex-Word-Boundaries (\b\w+\b). Das zaehlt praeziser als Whitespace-Splitting, weil Markdown-Syntax (#, **, >) ignoriert wird. Editoren zaehlen oft anders (manche zaehlen Bindestriche als Worttrennungen, andere nicht). Fuer konsistente Ergebnisse innerhalb deines Workflows ist die interne Methode entscheidend, nicht die absolute Uebereinstimmung mit einem bestimmten Editor.

Sanitizer

Welche Zeichen werden ersetzt, welche entfernt?

Ersetzt (durch regulaere Aequivalente):

Zeichen Unicode Ersetzt durch
No-Break Space U+00A0 normales Leerzeichen
Narrow No-Break Space U+202F normales Leerzeichen
Soft Hyphen U+00AD (entfernt)
Line Separator U+2028 \n
Paragraph Separator U+2029 \n

Entfernt (ohne Ersatz):

Zeichen Unicode
Zero-Width Space U+200B
Zero-Width Non-Joiner U+200C
Zero-Width Joiner U+200D
Left-to-Right Mark U+200E
Right-to-Left Mark U+200F
Bidi Overrides U+202A bis U+202E
BOM U+FEFF
Control Characters U+0000 bis U+001F (ausser Tab, LF, CR)

Ist der Sanitizer destruktiv?

Potenziell ja. Deshalb gibt es --dry-run und --backup. Empfohlener Workflow: Immer zuerst make sanitize-dry, dann make sanitize-backup beim ersten Durchlauf. Wenn du sicher bist, dass die Bereinigung korrekt arbeitet, reicht make sanitize.

Probleme

make check findet keine Dateien

Pruefen ob der Pfad existiert und Markdown-Dateien enthaelt:

ls manuscript/**/*.md

Falls die Dateien in einem anderen Verzeichnis liegen:

make check MANUSCRIPT=mein/pfad/

poetry install schlaegt fehl mit Python-Version

Das Projekt erfordert Python 3.11+. Version pruefen:

python3 --version

Falls aelter, mit pyenv oder Conda aktualisieren.

ms-check meldet Gedankenstriche, die ich im Editor nicht sehe

En-Dashes (U+2013) und Em-Dashes (U+2014) sehen in vielen Editoren fast identisch aus wie Bindestriche. Nutze ms-sanitize nicht dafuer, denn der Sanitizer ersetzt keine Dashes. Die muessen manuell korrigiert werden, weil die Ersetzung kontextabhaengig ist (manchmal Bindestrich, manchmal Komma, manchmal Umformulierung).

--strict meldet zu viele Fuellwoerter. Was tun?

Die Prosa-Regeln sind beratend. Nicht jedes "eigentlich" oder "halt" ist falsch, besonders in Dialogen oder informellen Texten. Drei Optionen:

  1. Ignorieren: Die Meldungen als Hinweis lesen, nicht als Fehler.
  2. Dialogdateien ausschliessen: make check-strict EXCLUDE="dialoge/*"
  3. Eigene Regelliste ohne Fuellwoerter: check_file(path, rules=[...]) ohne rule_filler_words_de.

Was bedeutet der Flesch-DE-Wert fuer mein Buch?

Richtwerte nach Genre:

  • Kinderbuch: 80+ anstreben
  • Unterhaltungsroman: 65-80
  • Sachbuch: 50-65
  • Fachbuch: 30-50

Ein niedriger Wert ist nicht per se schlecht. Juristische oder wissenschaftliche Texte liegen naturbedingt unter 30. Entscheidend ist, ob der Wert zum Zielpublikum passt.

Wie genau ist die Silbenzaehlung?

Die Silbenzaehlung basiert auf Vokalgruppen-Erkennung mit deutscher Diphthong-Behandlung (ei, au, eu, ie, ...). Das ist eine Heuristik, keine linguistische Analyse. Genauigkeit liegt bei ca. 85-90% fuer deutschen Text. Fuer den Flesch-Index reicht das, weil Fehler sich ueber grosse Textmengen herausmitteln.

Versionierung

Muss ich die Version manuell in zwei Dateien aendern?

Nein. Das Bump-Skript synchronisiert pyproject.toml und __init__.py automatisch:

make bump-patch   # 0.2.0 -> 0.2.1
make bump-minor   # 0.2.0 -> 0.3.0
make bump-major   # 0.2.0 -> 1.0.0

Was ist der Unterschied zwischen ms-check, ms-check --strict und ms-validate?

  • ms-check: Nur Core-Regeln (Dashes, unsichtbare Zeichen, doppelte Woerter, doppelte Leerzeichen). Schnell, wenig Rauschen.
  • ms-check --strict: Core + Prosa-Regeln (Satzlaenge, Fuellwoerter, Passiv). Mehr Treffer, beratend.
  • ms-validate: Fünf-Phasen-Pipeline (Sanitize + Quotes + Format + Check + Lesbarkeit). Fuer den vollen Pre-Push-Check.

Zurueck: Entwicklung und CI | Weiter: Quick Start

Clone this wiki locally