Skip to content

02 Verwendung

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

Verwendung

Alle Kommandos folgen dem gleichen Muster:

poetry run <kommando> [pfad] [--include GLOB] [--exclude GLOB]

Oder ueber das Makefile:

make <target> [MANUSCRIPT=pfad] [INCLUDE=pattern] [EXCLUDE=pattern]

Standard-Pfad ist immer manuscript/, Standard-Include ist **/*.md.

ms-check - Style-Validierung

Prueft Manuskript-Dateien gegen definierte Regeln. Zwei Modi:

Standardmodus (Core-Regeln)

make check

Prueft auf technische Probleme, die in jedem Text Fehler sind:

Regel Prueft auf
no-dashes En-Dashes und Em-Dashes (Unicode U+2013, U+2014)
no-invisible-chars Zero-Width-Spaces, BOM, Bidi-Controls
no-repeated-words Doppelte Woerter ("der der", "und und")
no-double-spaces Mehrfache Leerzeichen innerhalb einer Zeile
non-german-quotes Nicht-deutsche Anführungszeichen (gerade, englische)
broken-formatting Gebrochene Bold/Italic-Marker (Eclipse-Formatter)

Strict-Modus (Core + Prosa-Regeln)

make check-strict
# oder
poetry run ms-check manuscript/ --strict

Aktiviert zusaetzlich Regeln fuer Prosaqualitaet. Diese sind beratend, nicht jeder Treffer ist ein Fehler:

Regel Prueft auf
max-sentence-length Saetze mit mehr als 40 Woertern
filler-words-de Deutsche Fuellwoerter (eigentlich, irgendwie, quasi, halt, sozusagen, ...)
passive-voice-de Passivkonstruktionen inkl. inseparabler Praefixe (wird gelesen, wurde behoben, ist versandt worden)

Beispiele

# Ganzes Manuskript pruefen (Core)
make check

# Strenge Pruefung (Core + Prosa)
make check-strict

# Einzelne Datei
poetry run ms-check kapitel-03.md

# Bestimmtes Verzeichnis, Entwuerfe ausschliessen
make check MANUSCRIPT=buch/ EXCLUDE="entwuerfe/*"

# Streng + gefiltert
poetry run ms-check buch/ --strict --exclude 'entwuerfe/*'

Ausgabe

OK: manuscript/kapitel-01.md (3412 Woerter)
FAIL: manuscript/kapitel-02.md:17 [no-dashes] Gedankenstrich (en/em-dash) gefunden
FAIL: manuscript/kapitel-02.md:42 [no-repeated-words] Wiederholtes Wort: 'der'
FAIL: manuscript/kapitel-02.md:89 [filler-words-de] Fuellwort: 'eigentlich'
OK: manuscript/kapitel-03.md (2891 Woerter)
------------------------------------------------------------
Dateien: 3, Woerter: 9194
Status: FEHLER (1 Dateien, 3 Verstoss(e))

Exit-Code 1 bei Verstoessen, 0 wenn alles sauber ist.

ms-sanitize - Textbereinigung

Repariert und normalisiert den Text in Markdown-Dateien:

  • Mojibake-Reparatur (via ftfy)
  • Unicode-Normalisierung (NFKC)
  • Ersetzung von No-Break-Spaces, Soft Hyphens, Line Separators
  • Entfernung von Zero-Width-Zeichen, BOM, Bidi-Controls
  • Entfernung von Control Characters (ausser Tab und Newline)
  • Normalisierung von Zeilenenden auf \n
  • Sicherstellung eines abschliessenden Newline

Modi

# Vorschau: zeigt was geaendert wuerde, schreibt nichts
make sanitize-dry

# Mit Backup: erstellt .bak-Dateien vor dem Schreiben
make sanitize-backup

# In-Place: aendert Dateien direkt
make sanitize

Backup-Dateien aufraeumen

make clean-bak

ms-quotes - Deutsche Anführungszeichen

Konvertiert gerade ASCII-Quotes ("), englische typografische ("\u201c \u201d") und einfache (\u2018 \u2019) Anführungszeichen in deutsche Typografie:

  • Doppelt: \u201e \u201c (U+201E / U+201C)
  • Einfach: \u201a \u2018 (U+201A / U+2018)
# Vorschau
poetry run ms-quotes manuscript/ --dry-run

# Korrigieren (mit Backup)
poetry run ms-quotes manuscript/

# Ohne Backup
poetry run ms-quotes manuscript/ --no-backup

Geschützte Bereiche (YAML-Frontmatter, Code-Blöcke, Inline-Code, HTML-Attribute) werden nicht angefasst. Asymmetrische Anführungszeichen erzeugen eine Warnung statt einer Korrektur.

ms-check warnt über non-german-quotes, ms-quotes behebt das Problem.

ms-format - Gebrochene Formatierung

Erkennt und repariert Bold/Italic-Marker, die durch Code-Formatter (z.B. Eclipse) über Zeilengrenzen gebrochen wurden:

# Vorher (Eclipse hat umgebrochen)
Das ist ein **
wichtiger** Absatz.

# Nachher
Das ist ein **wichtiger** Absatz.
# Vorschau
poetry run ms-format manuscript/ --dry-run

# Korrigieren (mit Backup)
poetry run ms-format manuscript/

# Ohne Backup
poetry run ms-format manuscript/ --no-backup

Geschützte Bereiche (Frontmatter, Code-Blöcke) und Listen-Marker werden nicht angefasst.

ms-check warnt über broken-formatting, ms-format behebt das Problem.

ms-metrics - Textmetriken und Lesbarkeit

Zaehlt Woerter, Saetze und berechnet Lesbarkeitsmetriken pro Datei.

make metrics

Ausgabe

kapitel-01.md                     3,412 Woerter    187 Saetze  Flesch: 68.3 (Mittel)
kapitel-02.md                     2,891 Woerter    154 Saetze  Flesch: 72.1 (Leicht)
kapitel-03.md                     2,891 Woerter    148 Saetze  Flesch: 55.7 (Mittelschwer)
------------------------------------------------------------
Gesamt                            9,194 Woerter    489 Saetze     489 Zeilen

Lesbarkeitsanalyse (gesamt):
  Flesch-DE:                  64.2 (Mittel)
  Durchschn. Satzlaenge:      18.8 Woerter
  Durchschn. Silben/Wort:     1.72

Flesch-DE Skala

Der Flesch-Lesbarkeitsindex nach Amstad (1978), angepasst fuer deutsche Texte:

Score Bewertung Typische Verwendung
80-100 Sehr leicht Kinderbuch, einfache Sprache
70-80 Leicht Unterhaltungsliteratur
60-70 Mittel Belletristik, Sachbuch
50-60 Mittelschwer Qualitaetsjournalismus
30-50 Schwer Fachliteratur
0-30 Sehr schwer Akademisch, juristisch

Die Wortzaehlung nutzt Regex-Word-Boundaries statt str.split(). Markdown-Syntax wie #, **, > wird nicht mitgezaehlt. Die Silbenzaehlung erkennt deutsche Diphthonge (ei, au, eu, ie, ...).

ms-validate - Vollstaendige Validierungs-Pipeline

Fuehrt alle fünf Phasen in einem Lauf aus:

  1. Sanitize-Check (Dry-Run oder mit --fix)
  2. Anführungszeichen-Check (Dry-Run oder mit --fix)
  3. Formatierungs-Check (Dry-Run oder mit --fix)
  4. Style-Check (alle Regeln, also Core + Prosa)
  5. Lesbarkeitsreport
# Standard: Sanitize als Dry-Run, nur Bericht
make validate

# Mit automatischer Bereinigung (erstellt Backups)
make validate-fix

Ausgabe

============================================================
PHASE 1: Sanitize
============================================================
  MUSS BEREINIGT WERDEN: manuscript/kapitel-02.md
  1 Datei(en) benoetigen Bereinigung.
  Tipp: --fix zum automatischen Bereinigen verwenden.

============================================================
PHASE 2: Anführungszeichen
============================================================
  MUSS KORRIGIERT WERDEN: manuscript/kapitel-02.md (3 Ersetzung(en))
  1 Datei(en) mit nicht-deutschen Anführungszeichen.
  Tipp: --fix oder ms-quotes zum Korrigieren verwenden.

============================================================
PHASE 3: Formatierung (Bold/Italic)
============================================================
  Keine gebrochenen Formatierungen.

============================================================
PHASE 4: Style-Check (alle Regeln)
============================================================
  OK: manuscript/kapitel-01.md
  FAIL: manuscript/kapitel-02.md:17 [no-dashes] Gedankenstrich (en/em-dash) gefunden
  FAIL: manuscript/kapitel-02.md:89 [filler-words-de] Fuellwort: 'eigentlich'
  FAIL: manuscript/kapitel-02.md:112 [passive-voice-de] Passivkonstruktion: 'wird ... gelesen'
  3 Verstoss(e) gefunden.

============================================================
PHASE 5: Lesbarkeit
============================================================
  kapitel-01.md                 3,412 W   187 S  Flesch 68.3 (Mittel)
  kapitel-02.md                 2,891 W   154 S  Flesch 72.1 (Leicht)
    Laengster Satz: 47 Woerter (Zeile 203)

  Gesamt: 6,303 Woerter, Flesch-DE 69.8 (Mittel)

============================================================
ERGEBNIS: Probleme gefunden. Siehe Details oben.

ms-validate ist der empfohlene Einstiegspunkt fuer Pre-Push-Checks und CI-Pipelines.

Alle Kommandos respektieren die Projekt-Konfiguration aus [tool.manuscript-tools] in der pyproject.toml. Damit lassen sich Regeln, Schwellenwerte und Fuellwortlisten pro Projekt anpassen. Siehe Konfiguration.

Zurueck: Installation | Weiter: Eigene Regeln

Clone this wiki locally