Add split documentation

docs/book/src/README.md

@@ -6,7 +6,7 @@
 
 Das Toolkit _pica-rs_ ermöglicht eine effiziente Verarbeitung von
 bibliografischen Metadaten, die in PICA+, dem internen Format des
-[_OCLC_]-Katalogsystems, kodiert sind. Mit Hilfe verschiedener
+[_OCLC_]-Katalogsystems, kodiert sind. Mithilfe verschiedener
 [_Kommandos_] können aus den Metadaten elementare statistische Größen
 ermittelt und aufbereitet werden. Zudem kann das Toolkit als
 Brückentechnologie fungieren, um Metadaten für populäre Frameworks wie

docs/book/src/SUMMARY.md

@@ -18,3 +18,4 @@
     - [hash](./referenz/kommandos/hash.md)
     - [invalid](./referenz/kommandos/invalid.md)
     - [print](./referenz/kommandos/print.md)
+    - [split](./referenz/kommandos/split.md)

docs/book/src/referenz/kommandos/cat.md

@@ -2,7 +2,7 @@
 
 ![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square)
 
-Das `cat` Kommando liest Datensätze direkt von der Standardeingabe
+Das `cat`-Kommando liest Datensätze direkt von der Standardeingabe
 (`stdin`) oder aus Dateien ein und fügt diese zusammen. Die Ausgabe
 kann entweder in eine Datei oder in die Standardausgabe (`stdout`)
 geschrieben werden.
@@ -40,7 +40,7 @@ $ pica cat ger.dat eng.dat -o ger_eng.dat
   Ausgabe an die Datei angehangen. Ist das Flag nicht gesetzt, wird eine
   bestehende Datei standardmäßig überschrieben.
 * `--tee <filename>` — abzweigen der Ausgabe in eine zusätzliche Datei.
-* `-g`, `--gzip` — komprimieren der Ausgabe im
+* `-g`, `--gzip` — Komprimieren der Ausgabe im
   [gzip](https://de.wikipedia.org/wiki/Gzip)-Format.
 * `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben
   werden soll. Standardmäßig wird die Ausgabe in die Standardausgabe
@@ -153,7 +153,7 @@ $ pica cat partitions/Tp*.dat --tee gnd_person.dat | \
 Das vorhergehende Beispiel zeigt auch, dass das `cat`-Kommando sowohl
 unkomprimierte als auch komprimierte Dateien verarbeiten kann. Endet
 eine Datei mit dem Suffix `.gz`, wird die Datei automatisch
-dekompromiert (als Eingabedatei) bzw. komprimiert (als Ausgabedatei).
+dekomprimiert (als Eingabedatei) bzw. komprimiert (als Ausgabedatei).
 
 Mittels der Option `-g`/`--gzip` erfolgt eine Komprimierung der Ausgabe
 unabhängig von der Dateiendung:

docs/book/src/referenz/kommandos/index.md

@@ -13,4 +13,5 @@
 * [hash](./hash.md) — Erzeugt SHA-256 Hashwerte von Datensätzen
 * [invalid](./invalid.md) — Findet ungültige Zeilen in der Eingabe
 * [print](./print.md) — Gibt Datensätze in einer menschenlesbaren Form
-  aus
+* [split](./split.md) — Teilt eine Menge an Datensätzen in Dateien fester
+  Größe

docs/book/src/referenz/kommandos/split.md

@@ -0,0 +1,113 @@
+# split
+
+![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square)
+
+Das `split`-Kommando teilt eine Menge an Datensätzen in mehrere Dateien
+mit einer maximalen Anzahl pro Datei auf.
+
+## Beschreibung
+
+Mithilfe des `split`-Kommandos können alle Datensätze aus der Eingabe in
+mehrere Dateien aufgeteilt werden, wobei jede Datei eine maximale Anzahl
+an Datensätzen nicht überschreitet. Ein Anwendungsfall für das Splitting
+könnte eine automatisierte [Stapelverarbeitung] oder die parallele
+Verarbeitung der entstandenen Dateien sein.
+
+Der folgende Aufruf des `split`-Kommandos teilt die zwölf Datensätze der
+Eingabe (`DUMP.dat.gz`) in drei Dateien mit maximal fünf Datensätzen pro
+Datei. Die ersten beiden Dateien (`0.dat` und `1.dat`) enthalten die
+maximale Anzahl an Datensätzen, die letzte Datei (`2.dat`) die
+restlichen zwei Datensätze.
+
+```console
+$ pica split -s 5 DUMP.dat.gz
+$ tree
+.
+├── 0.dat
+├── 1.dat
+├── 2.dat
+└── DUMP.dat.gz
+```
+
+
+## Optionen
+
+* `-s`, `--skip-invalid` — überspringt jene Zeilen aus der Eingabe, die
+  nicht dekodiert werden konnten.
+* `-g`, `--gzip` — Komprimieren der Ausgabe im [Gzip]-Format.
+* `--template` — Template für die Dateinamen. Der Platzhalter `{}` wird
+  durch eine fortlaufende Nummer ersetzt.
+* `-o`, `--outdir` — Angabe, in welches Verzeichnis die Ausgabe
+  geschrieben werden soll. Standardmäßig wird das aktuelle Verzeichnis
+  verwendet.
+
+
+## Konfiguration
+
+<!-- TODO: Link zum allgemeinen Kapitel über die Konfigurationsdatei -->
+
+Einige Kommandozeilen-Optionen lassen sich per Konfigurationsdatei
+(`Pica.toml`) einstellen:
+
+```toml
+[split]
+template = "CHUNK_{}.dat"
+skip-invalid = true
+gzip = true
+```
+
+Die Werte der Kommandozeilen-Optionen haben Vorrang vor den Werten aus
+der Konfiguration.
+
+
+## Beispiele
+
+### Benutzerdefinierte Dateinamen
+
+Standardmäßig werden die erstellten Dateien beginnend bei `0`
+durchnummeriert. Der Dateiname kann individuell mit der
+`--template`-Option angepasst werden. Jedes Vorkommen der Zeichenfolge
+`{}` im Template wird durch die aktuelle Nummer ersetzt. Endet die Datei
+auf der Dateiendung `.gz`, wird die Ausgabe automatisch im [Gzip]-Format
+komprimiert.
+
+```console
+$ pica split -s --template "CHUNK_{}.dat.gz" 10 DUMP.dat.gz
+$ tree
+.
+├── CHUNK_0.dat.gz
+├── CHUNK_1.dat.gz
+└── DUMP.dat.gz
+
+$ pica count --records CHUNK_0.dat.gz
+10
+
+$ pica count --records CHUNK_1.dat.gz
+2
+
+```
+
+
+### Komprimierte Ausgabe
+
+Mittels der Option `-g`/`--gzip` erfolgt eine Komprimierung der Ausgabe:
+
+```console
+$ pica split -s --gzip 10 DUMP.dat.gz
+$ tree
+.
+├── 0.dat.gz
+├── 1.dat.gz
+└── DUMP.dat.gz
+
+$ pica count --records 0.dat.gz
+10
+
+$ pica count --records 1.dat.gz
+2
+
+```
+
+
+[Stapelverarbeitung]: https://de.wikipedia.org/wiki/Stapelverarbeitung
+[Gzip]: https://de.wikipedia.org/wiki/Gzip

pica-toolkit/tests/snapshot.rs

@@ -36,5 +36,6 @@ fn doc_tests() {
         .case("../docs/book/src/referenz/kommandos/frequency.md")
         .case("../docs/book/src/referenz/kommandos/hash.md")
         .case("../docs/book/src/referenz/kommandos/invalid.md")
-        .case("../docs/book/src/referenz/kommandos/print.md");
+        .case("../docs/book/src/referenz/kommandos/print.md")
+        .case("../docs/book/src/referenz/kommandos/split.md");
 }