diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 472dc5f12..be20d1ea9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -326,23 +326,19 @@ jobs: needs: test steps: - uses: actions/checkout@v4 + with: + submodules: true + fetch-depth: 0 - uses: abbbi/github-actions-tune@v1 - - uses: actions/cache@v4 + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 with: - key: ${{ env.CACHE_KEY }}-${{ hashFiles('**/Cargo.toml') }} - path: | - ~/.cargo/bin/ - ~/.cargo/git/db/ - ~/.cargo/registry/cache/ - ~/.cargo/registry/index/ - target/ - - uses: dtolnay/rust-toolchain@nightly - - name: "Install `mdbook`" + hugo-version: 'latest' + extended: true + - name: Build run: | - cargo install -f mdbook - - run: | - mdbook build docs/book - mdbook test docs/book + cd docs + hugo --minify gh-pages: if: ${{ github.ref == 'refs/heads/main' }} @@ -374,15 +370,13 @@ jobs: ~/.cargo/registry/index/ target/ - uses: dtolnay/rust-toolchain@nightly - - name: "Install `mdbook`" - run: | - cargo install -f mdbook + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: 'latest' + extended: true - run: | - mkdir -p target/docs - cargo doc --all --no-deps --workspace --target-dir target/docs/api - mdbook build docs/book --dest-dir ../../target/docs/book - echo 'Redirect' >> target/docs/api/index.html - echo 'Redirect' >> target/docs/index.html + make docs - uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/Makefile b/Makefile index 038258da1..0bc20632e 100644 --- a/Makefile +++ b/Makefile @@ -5,6 +5,7 @@ MAKEFLAGS += -rR DESTDIR= CARGO ?= cargo +HUGO ?= hugo PREFIX=/usr/local BINDIR=$(PREFIX)/bin @@ -29,6 +30,15 @@ fmt: doc: $(CARGO) doc --no-deps +docs: + mkdir -p target/docs + $(CARGO) doc --all --no-deps --workspace --target-dir target/docs/api + $(HUGO) --minify --gc --source docs --destination ../target/docs/book + echo 'Redirect' \ + > target/docs/api/index.html + echo 'Redirect' \ + > target/docs/index.html + release: $(CARGO) build --workspace --all-features --release $(CARGO) test --workspace --all-features --release @@ -39,4 +49,4 @@ install: release clean: $(CARGO) clean -.PHONY: build clean check clippy test fmt doc release install +.PHONY: build clean check clippy test fmt doc docs release install diff --git a/ci/prepare-tests.sh b/ci/prepare-tests.sh index 871a9934a..e0a69093c 100755 --- a/ci/prepare-tests.sh +++ b/ci/prepare-tests.sh @@ -3,7 +3,7 @@ set -euo pipefail # set -x -DIRS=$(find docs/book/src/referenz/kommandos -type f -iname "*.md" -print) +DIRS=$(find docs/content/docs/kommandos -type f -iname "*.md" -print) DUMP="tests/data/DUMP.dat.gz" for i in $DIRS; do diff --git a/crates/pica-toolkit/tests/snapshot.rs b/crates/pica-toolkit/tests/snapshot.rs index b44c05cb3..b6cc420e5 100644 --- a/crates/pica-toolkit/tests/snapshot.rs +++ b/crates/pica-toolkit/tests/snapshot.rs @@ -34,14 +34,14 @@ fn cli_tests() { #[test] fn doc_tests() { trycmd::TestCases::new() - .case("../../docs/book/src/referenz/kommandos/count.md") - .case("../../docs/book/src/referenz/kommandos/filter.md") - .case("../../docs/book/src/referenz/kommandos/frequency.md") - .case("../../docs/book/src/referenz/kommandos/explode.md") - .case("../../docs/book/src/referenz/kommandos/hash.md") - .case("../../docs/book/src/referenz/kommandos/invalid.md") - .case("../../docs/book/src/referenz/kommandos/partition.md") - .case("../../docs/book/src/referenz/kommandos/print.md") - .case("../../docs/book/src/referenz/kommandos/slice.md") - .case("../../docs/book/src/referenz/kommandos/split.md"); + .case("../../docs/content/docs/kommandos/count.md") + .case("../../docs/content/docs/kommandos/filter.md") + .case("../../docs/content/docs/kommandos/frequency.md") + .case("../../docs/content/docs/kommandos/explode.md") + .case("../../docs/content/docs/kommandos/hash.md") + .case("../../docs/content/docs/kommandos/invalid.md") + .case("../../docs/content/docs/kommandos/partition.md") + .case("../../docs/content/docs/kommandos/print.md") + .case("../../docs/content/docs/kommandos/slice.md") + .case("../../docs/content/docs/kommandos/split.md"); } diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..138df1fa5 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,4 @@ +content/docs/kommandos/*.in/ +/public +/resources/_gen/ +/.hugo_build.lock diff --git a/docs/book/.gitignore b/docs/book/.gitignore deleted file mode 100644 index 1a12d9f0b..000000000 --- a/docs/book/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -book -**/*.in/ diff --git a/docs/book/book.toml b/docs/book/book.toml deleted file mode 100644 index 0e81a9939..000000000 --- a/docs/book/book.toml +++ /dev/null @@ -1,18 +0,0 @@ -[book] -authors = ["Nico Wagner"] -language = "de" -multilingual = false -title = "pica-rs" -src = "src" - -[build] -create-missing = false - -[rust] -edition = "2021" - -[output.html] -additional-css = ["custom.css"] - -[output.html.search] -limit-results = 15 diff --git a/docs/book/custom.css b/docs/book/custom.css deleted file mode 100644 index f51f8e9f8..000000000 --- a/docs/book/custom.css +++ /dev/null @@ -1,25 +0,0 @@ -:root { - --content-max-width: 90%; - --sidebar-width: 230px; -} - - -body { - font-family: arial, sans-serif; -} - -main h1, h2 { - border-bottom: 1px solid #d8dee4; -} - -main h1 { - text-transform: uppercase; -} - -main h2, h3 { - margin-top: 1em; -} - -.content ul li { - /* padding: 5px 0px; */ -} diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md deleted file mode 100644 index 5426d526f..000000000 --- a/docs/book/src/SUMMARY.md +++ /dev/null @@ -1,25 +0,0 @@ -# Summary - -[Einführung](./README.md) - - - -# Anleitungen - -- [Installation](./anleitungen/installation.md) - -# Referenz -- [Kommandos](./referenz/kommandos/index.md) - - [cat](./referenz/kommandos/cat.md) - - [completions](./referenz/kommandos/completions.md) - - [convert](./referenz/kommandos/convert.md) - - [count](./referenz/kommandos/count.md) - - [explode](./referenz/kommandos/explode.md) - - [filter](./referenz/kommandos/filter.md) - - [frequency](./referenz/kommandos/frequency.md) - - [hash](./referenz/kommandos/hash.md) - - [invalid](./referenz/kommandos/invalid.md) - - [partition](./referenz/kommandos/partition.md) - - [print](./referenz/kommandos/print.md) - - [slice](./referenz/kommandos/slice.md) - - [split](./referenz/kommandos/split.md) diff --git a/docs/book/src/anleitungen/index.md b/docs/book/src/anleitungen/index.md deleted file mode 100644 index 8c56bd21b..000000000 --- a/docs/book/src/anleitungen/index.md +++ /dev/null @@ -1 +0,0 @@ -# Anleitungen diff --git a/docs/book/src/referenz/index.md b/docs/book/src/referenz/index.md deleted file mode 100644 index d8c80e1bb..000000000 --- a/docs/book/src/referenz/index.md +++ /dev/null @@ -1,2 +0,0 @@ -# Referenz - diff --git a/docs/book/src/referenz/kommandos/index.md b/docs/book/src/referenz/kommandos/index.md deleted file mode 100644 index 6826cf3ed..000000000 --- a/docs/book/src/referenz/kommandos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Kommandos - -## Übersicht - -* [cat](./cat.md) — Zusammenfügen (Konkatenieren) von Datensätzen -* [convert](./convert.md) — Konvertierung zwischen verschiedenen - PICA-Formaten -* [completions](./completions.md) — Erzeugung von Shell-Skripten zur - Autovervollständigung -* [count](./count.md) — Zählen von Datensätzen, Feldern und Unterfeldern -* [explode](./explode.md) — Teilt Datensätze in Lokal- oder - Exemplardatensätze auf -* [filter](./filter.md) — Filtert Datensätze anhand eines Kriteriums -* [frequency](./frequency.md) — Ermitteln einer Häufigkeitsverteilung - über ein oder mehrere Unterfelder -* [hash](./hash.md) — Erzeugt SHA-256-Hashwerte von Datensätzen -* [invalid](./invalid.md) — Findet ungültige Zeilen in der Eingabe -* [partition](./partition.md) — Partitioniert Datensätze anhand eines - Unterfelds -* [print](./print.md) — Gibt Datensätze in einer menschenlesbaren Form - aus -* [slice](./slice.md) — Ausschneiden eines zusammenhängenden - Teilbereichs aus der Eingabe -* [split](./split.md) — Teilt eine Menge an Datensätzen in Dateien fester - Größe diff --git a/docs/book/src/tutorials/index.md b/docs/book/src/tutorials/index.md deleted file mode 100644 index 81c8590f8..000000000 --- a/docs/book/src/tutorials/index.md +++ /dev/null @@ -1 +0,0 @@ -# Tutorials diff --git a/docs/config.toml b/docs/config.toml new file mode 100644 index 000000000..258ebedf5 --- /dev/null +++ b/docs/config.toml @@ -0,0 +1,17 @@ +baseURL = "https://deutsche-nationalbibliothek.github.io/pica-rs/book/" +languageCode = "de-DE" +title = "pica-rs" + +enableGitInfo = true + +[markup.goldmark.renderer] +unsafe = true + +[module] +[[module.imports]] +path = "github.com/alex-shpak/hugo-book" + +[params] +BookComments = false +BookSearch = false +BookToc = false diff --git a/docs/book/src/README.md b/docs/content/_index.md similarity index 68% rename from docs/book/src/README.md rename to docs/content/_index.md index 3d9c0a628..3cb162d25 100644 --- a/docs/book/src/README.md +++ b/docs/content/_index.md @@ -1,11 +1,12 @@ -

+--- +title: Einführung +type: docs +---
- -[![CI](https://github.com/deutsche-nationalbibliothek/pica-rs/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/deutsche-nationalbibliothek/pica-rs/actions/workflows/ci.yml) -[![Documentation](https://img.shields.io/badge/Documentation-main-orange.svg)](https://deutsche-nationalbibliothek.github.io/pica-rs/) -[![dependency status](https://deps.rs/repo/github/deutsche-nationalbibliothek/pica-rs/status.svg)](https://deps.rs/repo/github/deutsche-nationalbibliothek/pica-rs) - + + +
Das Toolkit _pica-rs_ ermöglicht eine effiziente Verarbeitung von @@ -31,11 +32,7 @@ mögliche Fehler, Fragen und neue Ideen als [GitHub-Issues][Issues] anzulegen. Diese werden wir dann intern beraten und möglichst zeitnah ein Feedback geben. -## Verwandte Projekte - -- [Catmandu::Pica](https://metacpan.org/pod/Catmandu::PICA) — Catmandu modules for working with PICA+ data -- [Metafacture](https://github.com/metafacture) — Tool suite for metadata processing - +[Kommandos]: {{< relref "docs/kommandos/" >}} [AE]: https://blog.dnb.de/erschliessungsmaschine-gestartet/ [DNB]: https://www.dnb.de/ @@ -43,7 +40,6 @@ ein Feedback geben. [Installation]: https://deutsche-nationalbibliothek.github.io/pica-rs/book/anleitungen/installation.html [Issues]: https://github.com/deutsche-nationalbibliothek/pica-rs/issues [KI]: https://www.dnb.de/DE/Professionell/ProjekteKooperationen/Projekte/KI/ki_node.html -[Kommandos]: referenz/kommandos/index.md [OCLC]: https://www.oclc.org/ [Pandas]: https://pandas.pydata.org/ [Polars]: https://www.pola.rs/ diff --git a/docs/content/docs/anleitungen/_index.md b/docs/content/docs/anleitungen/_index.md new file mode 100644 index 000000000..dc90796dc --- /dev/null +++ b/docs/content/docs/anleitungen/_index.md @@ -0,0 +1,35 @@ +--- +bookFlatSection: true +--- + +# Kommandos + +## Übersicht + +* **[cat]** --- Zusammenfügen (Konkatenieren) von Datensätzen +* **[convert]** --- Konvertierung zwischen verschiedenen PICA-Formaten +* **[completions]** --- Erzeugung von Shell-Skripten zur Autovervollständigung +* **[count]** --- Zählen von Datensätzen, Feldern und Unterfeldern +* **[explode]** --- Teilt Datensätze in Lokal- oder Exemplardatensätze auf +* **[filter]** --- Filtert Datensätze anhand eines Kriteriums +* **[frequency]** --- Ermitteln einer Häufigkeitsverteilung über ein oder mehrere Unterfelder +* **[hash]** --- Erzeugt SHA-256-Hashwerte von Datensätzen +* **[invalid]** --- Findet ungültige Zeilen in der Eingabe +* **[partition]** --- Partitioniert Datensätze anhand eines Unterfelds +* **[print]** --- Gibt Datensätze in einer menschenlesbaren Form aus +* **[slice]** --- Ausschneiden eines zusammenhängenden Teilbereichs aus der Eingabe +* **[split]** --- Teilt eine Menge an Datensätzen in Dateien fester Größe + +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} diff --git a/docs/book/src/anleitungen/installation.md b/docs/content/docs/installation.md similarity index 99% rename from docs/book/src/anleitungen/installation.md rename to docs/content/docs/installation.md index 2ae2b48e1..07fb72576 100644 --- a/docs/book/src/anleitungen/installation.md +++ b/docs/content/docs/installation.md @@ -1,4 +1,5 @@ # Installation + Das Toolkit _pica-rs_ kann unter Linux, macOS und Windows verwendet werden. Für diese Betriebssysteme stehen unterschiedliche Pakete zum [Download auf GitHub](https://github.com/deutsche-nationalbibliothek/pica-rs/releases) diff --git a/docs/content/docs/kommandos/_index.md b/docs/content/docs/kommandos/_index.md new file mode 100644 index 000000000..dc90796dc --- /dev/null +++ b/docs/content/docs/kommandos/_index.md @@ -0,0 +1,35 @@ +--- +bookFlatSection: true +--- + +# Kommandos + +## Übersicht + +* **[cat]** --- Zusammenfügen (Konkatenieren) von Datensätzen +* **[convert]** --- Konvertierung zwischen verschiedenen PICA-Formaten +* **[completions]** --- Erzeugung von Shell-Skripten zur Autovervollständigung +* **[count]** --- Zählen von Datensätzen, Feldern und Unterfeldern +* **[explode]** --- Teilt Datensätze in Lokal- oder Exemplardatensätze auf +* **[filter]** --- Filtert Datensätze anhand eines Kriteriums +* **[frequency]** --- Ermitteln einer Häufigkeitsverteilung über ein oder mehrere Unterfelder +* **[hash]** --- Erzeugt SHA-256-Hashwerte von Datensätzen +* **[invalid]** --- Findet ungültige Zeilen in der Eingabe +* **[partition]** --- Partitioniert Datensätze anhand eines Unterfelds +* **[print]** --- Gibt Datensätze in einer menschenlesbaren Form aus +* **[slice]** --- Ausschneiden eines zusammenhängenden Teilbereichs aus der Eingabe +* **[split]** --- Teilt eine Menge an Datensätzen in Dateien fester Größe + +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} diff --git a/docs/book/src/referenz/kommandos/cat.md b/docs/content/docs/kommandos/cat.md similarity index 88% rename from docs/book/src/referenz/kommandos/cat.md rename to docs/content/docs/kommandos/cat.md index b86fd3410..7db9829ec 100644 --- a/docs/book/src/referenz/kommandos/cat.md +++ b/docs/content/docs/kommandos/cat.md @@ -1,6 +1,4 @@ -# `cat` - -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) +# cat Das `cat`-Kommando liest Datensätze direkt von der Standardeingabe (`stdin`) oder aus Dateien ein und fügt diese zusammen. Die Ausgabe @@ -10,8 +8,8 @@ geschrieben werden. ## Beschreibung Der wichtigste Anwendungsfall des Kommandos besteht in Kombination mit -den Kommandos [_partition_] oder [_split_], da mittels `cat` das -Ergebnis von [_partition_] oder [_split_] (teil-)rückgängig gemacht +den Kommandos _[partition]_ oder _[split]_, da mittels `cat` das +Ergebnis von _[partition]_ oder _[split]_ (teil-)rückgängig gemacht werden kann. Häufig macht es Sinn, eine große Datei in viele kleinere Dateien anhand eines Kriteriums zu teilen und anschließend eine Teilmenge wieder zusammenzufügen. @@ -40,8 +38,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 ` — Abzweigen der Ausgabe in eine zusätzliche Datei. -* `-g`, `--gzip` — Komprimieren der Ausgabe im - [gzip](https://de.wikipedia.org/wiki/Gzip)-Format. +* `-g`, `--gzip` — Komprimieren der Ausgabe im [Gzip]-Format. * `-p`, `--progress` — Anzeige des Fortschritts, der die Anzahl der eingelesenen gültigen sowie invaliden Datensätze anzeigt. Das Aktivieren der Option erfordert das Schreiben der Datensätze in eine @@ -49,7 +46,7 @@ $ pica cat ger.dat eng.dat -o ger_eng.dat * `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben werden soll. Standardmäßig wird die Ausgabe in die Standardausgabe `stdout` geschrieben. Endet der Dateiname mit dem Suffix `.gz`, wird - die Ausgabe automatisch im gzip-Format komprimiert. + die Ausgabe automatisch im [Gzip]-Format komprimiert. ## Konfiguration @@ -87,7 +84,6 @@ $ pica cat --skip-invalid DUMP.dat.gz -o dump_valid.dat $ pica cat -s DUMP.dat.gz --output dump_valid.dat.gz ``` - ### Lesen von der Standardeingabe Das Kommando kann auch direkt von der Standardeingabe (`stdin`) lesen. @@ -132,7 +128,6 @@ $ pica cat --append Tu*.dat -o gnd.dat ... ``` - ### Abzweigen der Ausgabe Gelegenlich kann es nützlich sein, die Ausgabe des `cat`-Kommandos in @@ -167,7 +162,18 @@ $ pica cat --gzip ger.dat eng.dat -o eng_ger_compressed.dat $ pica cat ger.dat eng.dat -o eng_ger.dat.gz ``` - -[_filter_]: filter.md -[_partition_]: partition.md -[_split_]: split.md +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} + +[Gzip]: https://de.wikipedia.org/wiki/Gzip diff --git a/docs/book/src/referenz/kommandos/completions.md b/docs/content/docs/kommandos/completions.md similarity index 64% rename from docs/book/src/referenz/kommandos/completions.md rename to docs/content/docs/kommandos/completions.md index ea945e5b7..9d5a192e1 100644 --- a/docs/book/src/referenz/kommandos/completions.md +++ b/docs/content/docs/kommandos/completions.md @@ -1,17 +1,18 @@ # completions -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Das `completions`-Kommando erzeugt Dateien, die Anweisungen enthalten, -welche Argumente und Optionen des Toolkits für eine -[Shell](https://de.wikipedia.org/wiki/Shell_(Betriebssystem)) zur +welche Argumente und Optionen des Toolkits für eine [Shell] zur Befehlszeilenergänzung verfügbar sind. ## Beschreibung -> **Hinweis:** Mit jeder neuen `pica`-Version können sich die Argumente -> und Optionen des _command-line interface_ (CLI) ändern. Daher ist ein -> regelmäßiges Updaten der Skripte zu empfehlen. +{{< hint info >}} +**Hinweis** + +Mit jeder neuen `pica`-Version können sich die Argumente und Optionen +des _command-line interface_ (CLI) ändern. Daher ist ein regelmäßiges +Updaten der Skripte zu empfehlen. +{{< /hint >}} Nachfolgend werden exemplarisch die Befehle gezeigt, die für die Einbindung in die jeweilige Shell nötig sind. Die Schritte sind vom @@ -72,3 +73,20 @@ die Funktion `compinit` aufgerufen wird. ```bash $ pica completions zsh -o ~/.zfunc/_pica ``` + +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} + +[Gzip]: https://de.wikipedia.org/wiki/Gzip +[Shell]: https://de.wikipedia.org/wiki/Shell_(Betriebssystem) diff --git a/docs/book/src/referenz/kommandos/convert.md b/docs/content/docs/kommandos/convert.md similarity index 62% rename from docs/book/src/referenz/kommandos/convert.md rename to docs/content/docs/kommandos/convert.md index 9fa8ebabb..8b7a693e1 100644 --- a/docs/book/src/referenz/kommandos/convert.md +++ b/docs/content/docs/kommandos/convert.md @@ -1,14 +1,14 @@ -# `convert` - -![stability-badge](https://img.shields.io/badge/stability-unstable-red?style=flat-square) +# convert Das `convert`-Kommando wird für die Konvertierung von und in andere Datenformate verwendet. -> **Hinweis:** Das `convert`-Kommando befindet sich in der aktiven -> Entwicklung. Funktionalitäten können unvollständig oder fehlerhaft -> sein. Änderungen am _command-line interface_ (CLI) sind nicht -> ausgeschlossen. +{{< hint danger >}} +**Hinweis:** +Das `convert`-Kommando befindet sich in der aktiven Entwicklung. +Funktionalitäten können unvollständig oder fehlerhaft sein. Änderungen +am _command-line interface_ (CLI) sind nicht ausgeschlossen. +{{< /hint >}} ## Beschreibung @@ -16,7 +16,7 @@ Das PICA-Format kann in verschiedene Datenformate serialisiert werden. Das `convert`-Kommando ermöglicht es, Datensätze von einem Format in ein anderes Format zu konvertieren. Es bietet insbesondere die Möglichkeit, Datensätze, die nicht in normalisiertem PICA+ vorliegen, nach PICA+ zu -konvertieren, um sie durch andere [_Kommandos_] verarbeiten zu können. +konvertieren, um sie durch andere Kommandos verarbeiten zu können. Folgende Formate werden unterstützt: @@ -27,8 +27,8 @@ Folgende Formate werden unterstützt: * PICA-JSON (`json`), * und PICA-XML (`xml`). -Die Angabe der Datenformate erfolgt über die Optionen `--from` und -`--to`: +Die Angabe der Datenformate erfolgt über die Optionen `--from`/`-f` und +`--to`/`-t`: ```bash $ pica convert --from plus --to binary DUMP.dat.gz -o dump.bin @@ -53,5 +53,18 @@ $ pica convert --from plus --to xml DUMP.dat.gz -o dump.xml `stdout` geschrieben. -[_Kommandos_]: ./index.md +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} +[Gzip]: https://de.wikipedia.org/wiki/Gzip diff --git a/docs/book/src/referenz/kommandos/count.md b/docs/content/docs/kommandos/count.md similarity index 89% rename from docs/book/src/referenz/kommandos/count.md rename to docs/content/docs/kommandos/count.md index 16c8ddce4..259c9b48f 100644 --- a/docs/book/src/referenz/kommandos/count.md +++ b/docs/content/docs/kommandos/count.md @@ -1,7 +1,5 @@ # count -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Mithilfe des `count`-Kommandos lässt sich die Anzahl an Datensätzen (_records_), Feldern (_fields_) sowie Unterfeldern (_subfields_) ermitteln. @@ -49,6 +47,7 @@ subfields: 3973 werden soll. Standardmäßig wird die Ausgabe in die Standardausgabe `stdout` geschrieben. + ## Konfiguration @@ -133,7 +132,7 @@ Soll die Veränderung (Anzahl Datensätze, Felder, Unterfelder) eines PICA-Abzugs über die Zeit verfolgt werden, könnte dies wie folgt erreicht werden: -```console,ignore +```sh $ echo "date,records,fields,subfields" > count.csv # Kopfzeile $ pica count -s dump_20220222.dat.gz --append -o count.csv # Initialer Aufruf $ pica count -s dump_20220223.dat.gz --append -o count.csv # Aufruf nach x Tagen @@ -147,7 +146,7 @@ $ records,fields,subfields Soll auch das aktuelle Datum vor die Zeile geschrieben werden, könnten bspw. folgende Unix-Kommandos genutzt werden: -```console,ignore +```sh # Schreiben der Kopfzeile $ echo "date,records,fields,subfields" > count.csv @@ -164,3 +163,20 @@ $ date,records,fields,subfields 2022-02-22,7,247,549 2022-02-23,9,347,1022 ``` + +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} + +[Gzip]: https://de.wikipedia.org/wiki/Gzip + diff --git a/docs/book/src/referenz/kommandos/explode.in/COPY.dat.gz b/docs/content/docs/kommandos/explode.in/COPY.dat.gz similarity index 100% rename from docs/book/src/referenz/kommandos/explode.in/COPY.dat.gz rename to docs/content/docs/kommandos/explode.in/COPY.dat.gz diff --git a/docs/book/src/referenz/kommandos/explode.md b/docs/content/docs/kommandos/explode.md similarity index 86% rename from docs/book/src/referenz/kommandos/explode.md rename to docs/content/docs/kommandos/explode.md index 91a5d4ca4..c0aec4586 100644 --- a/docs/book/src/referenz/kommandos/explode.md +++ b/docs/content/docs/kommandos/explode.md @@ -1,14 +1,14 @@ # `explode` -![stability-badge](https://img.shields.io/badge/stability-unstable-red?style=flat-square) - Mithilfe des `explode`-Kommandos lassen sich Datensätze in Lokal- bzw. Exemplardatensätze aufteilen. -> **Hinweis:** Das `explode`-Kommando befindet sich in der aktiven -> Entwicklung. Funktionalitäten können unvollständig oder fehlerhaft -> sein. Änderungen am _command-line interface_ (CLI) sind nicht -> ausgeschlossen. +{{< hint danger >}} +**Hinweis:** +Das `explode`-Kommando befindet sich in der aktiven Entwicklung. +Funktionalitäten können unvollständig oder fehlerhaft sein. Änderungen +am _command-line interface_ (CLI) sind nicht ausgeschlossen. +{{< /hint >}} ## Beschreibung @@ -132,7 +132,7 @@ $ pica print copy.dat * `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben werden soll. Standardmäßig wird die Ausgabe in die Standardausgabe `stdout` geschrieben. Endet der Dateiname mit dem Suffix `.gz`, wird - die Ausgabe automatisch im gzip-Format komprimiert. + die Ausgabe automatisch im [Gzip]-Format komprimiert. ## Konfiguration @@ -176,5 +176,18 @@ $ pica print copy.dat ``` +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} [Gzip]: https://de.wikipedia.org/wiki/Gzip diff --git a/docs/book/src/referenz/kommandos/filter.md b/docs/content/docs/kommandos/filter.md similarity index 91% rename from docs/book/src/referenz/kommandos/filter.md rename to docs/content/docs/kommandos/filter.md index 7d4d2acd3..75a8c88ec 100644 --- a/docs/book/src/referenz/kommandos/filter.md +++ b/docs/content/docs/kommandos/filter.md @@ -1,7 +1,5 @@ # filter -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Mithilfe des `filter`-Kommandos können Datensätze anhand eines Kriterums aus der Eingabe gefiltert werden. @@ -188,11 +186,25 @@ $ pica print out2.dat [^1]: Eine Positiv- oder Negativliste muss entweder als [CSV]-Datei - vorliegen, die in der **ersten Spalte** die IDN/PPN des Datensatzes - enthält, oder als eine [Arrow]-Datei, die eine `idn`-Spalte enthält. + vorliegen oder als eine [Arrow]-Datei, die eine `idn`-Spalte enthält. Alle Dateien werden automatisch als [CSV]-Datei interpretiert, es sei denn, die Datei endet mit `.ipc`, `.arrow` oder `.feather`, dann - erfolgt die Interpretation im [Arrow]-Format. + erfolgt die Interpretation im [Arrow]-Format. CSV- bzw. TSV-Dateien + mit der Ending `.csv.gz` bzw. `.tsv.gz` werden automatisch entpackt. + +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} [Arrow]: https://arrow.apache.org/ [CSV]: https://de.wikipedia.org/wiki/CSV_(Dateiformat) diff --git a/docs/book/src/referenz/kommandos/frequency.md b/docs/content/docs/kommandos/frequency.md similarity index 91% rename from docs/book/src/referenz/kommandos/frequency.md rename to docs/content/docs/kommandos/frequency.md index 3bdb5b577..702a57b50 100644 --- a/docs/book/src/referenz/kommandos/frequency.md +++ b/docs/content/docs/kommandos/frequency.md @@ -1,7 +1,5 @@ # frequency -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Mithilfe des Kommandos `frequency` lässt sich die Häufigkeitsverteilung aller Werte eines oder mehrerer Unterfelder bestimmen. @@ -191,7 +189,7 @@ vbal,4 ### Änderung der Sortierreihenfolge (Limit) Standardmäßig wird die Häufigkeitsverteilung absteigend ausgegeben, -d.h., der häufigste Wert steht in der Ausgabe oben[^fn1]. Soll das +d.h., der häufigste Wert steht in der Ausgabe oben[^1]. Soll das Verhalten so geändert werden, dass die Ausgabe aufsteigend sortiert wird, kann dies mit der Option `--reverse` bzw. `-r` erfolgen. Das folgende Kommando sucht nach den vier Satzarten, die am wenigsten vorkommen: @@ -217,6 +215,20 @@ Tsz 2 ... ``` -[^fn1]: Alle Werte mit gleicher Häufigkeit werden immer in lexikographisch +[^1]: Alle Werte mit gleicher Häufigkeit werden immer in lexikographisch aufsteigender Reihenfolge sortiert. Dies erfolgt unabhängig vom Parameter `--reverse`. + +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} diff --git a/docs/book/src/referenz/kommandos/hash.md b/docs/content/docs/kommandos/hash.md similarity index 88% rename from docs/book/src/referenz/kommandos/hash.md rename to docs/content/docs/kommandos/hash.md index 4d082f2c3..2a4f05697 100644 --- a/docs/book/src/referenz/kommandos/hash.md +++ b/docs/content/docs/kommandos/hash.md @@ -1,12 +1,9 @@ # hash -![stability-badge](https://img.shields.io/badge/stability-unstable-red?style=flat-square) - Mithilfe des Kommandos `hash` lässt sich eine Tabelle erzeugen, die in der ersten Spalte die IDN (Feld `003@.0`) eines Datensatzes und in der zweiten Spalte den [_SHA-256_] Hashwert enthält. - ## Beschreibung Mitunter kommt es vor, dass eine regelmäßige und aufwändige Berechnung @@ -110,5 +107,19 @@ $ sha256sum 1.dat 762cf3a1b18a0cad2d0401cd2b573a89ff9c81b43c4ddab76e136d7a10a851f3 ``` +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} + [_SHA-256_]: https://de.wikipedia.org/wiki/SHA-2 [_sha256sum_]: https://manpages.ubuntu.com/manpages/trusty/de/man1/sha256sum.1.html diff --git a/docs/book/src/referenz/kommandos/invalid.md b/docs/content/docs/kommandos/invalid.md similarity index 56% rename from docs/book/src/referenz/kommandos/invalid.md rename to docs/content/docs/kommandos/invalid.md index 12cf8f58a..1bd1f70ac 100644 --- a/docs/book/src/referenz/kommandos/invalid.md +++ b/docs/content/docs/kommandos/invalid.md @@ -1,7 +1,5 @@ # invalid -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Das `invalid`-Kommando findet Zeilen in der Eingabe, die nicht als normalisiertes PICA+ dekodiert werden konnten und somit ungültig sind. @@ -31,3 +29,31 @@ $ pica invalid DUMP.dat.gz -o invalid.dat * `-o`, `--output` — Angabe, in welche Datei die Ausgabe geschrieben werden soll. Standardmäßig wird die Ausgabe in die Standardausgabe `stdout` geschrieben. + + +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} diff --git a/docs/book/src/referenz/kommandos/partition.md b/docs/content/docs/kommandos/partition.md similarity index 86% rename from docs/book/src/referenz/kommandos/partition.md rename to docs/content/docs/kommandos/partition.md index 976120540..dbd268948 100644 --- a/docs/book/src/referenz/kommandos/partition.md +++ b/docs/content/docs/kommandos/partition.md @@ -1,7 +1,5 @@ # partition -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Mittels des `partition`-Kommandos lassen sich Datensätze anhand eines Unterfelds in Partitionen einteilen. @@ -113,5 +111,18 @@ out ``` +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} [Gzip]: https://de.wikipedia.org/wiki/Gzip diff --git a/docs/book/src/referenz/kommandos/print.md b/docs/content/docs/kommandos/print.md similarity index 88% rename from docs/book/src/referenz/kommandos/print.md rename to docs/content/docs/kommandos/print.md index a72cfa80b..9eac54aa3 100644 --- a/docs/book/src/referenz/kommandos/print.md +++ b/docs/content/docs/kommandos/print.md @@ -1,7 +1,5 @@ # print -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Das `print`-Kommando gibt Datensätze in einer menschenlesbaren Form aus. @@ -141,7 +139,20 @@ $ pica print -s -l1 --translit nfc DUMP.dat.gz ... ``` - -[_Ansi256-Farbcode_]: https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797#256-colors -[_Escaping_]: https://de.wikipedia.org/wiki/Escape-Sequenz -[_Unicode-Normalform_]: https://de.wikipedia.org/wiki/Normalisierung_(Unicode) +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} + +[Ansi256-Farbcode]: https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797#256-colors +[Escaping]: https://de.wikipedia.org/wiki/Escape-Sequenz +[Unicode-Normalform]: https://de.wikipedia.org/wiki/Normalisierung_(Unicode) diff --git a/docs/book/src/referenz/kommandos/slice.md b/docs/content/docs/kommandos/slice.md similarity index 85% rename from docs/book/src/referenz/kommandos/slice.md rename to docs/content/docs/kommandos/slice.md index 829adbf0f..611e968f4 100644 --- a/docs/book/src/referenz/kommandos/slice.md +++ b/docs/content/docs/kommandos/slice.md @@ -1,7 +1,5 @@ # slice -![stability-badge](https://img.shields.io/badge/stability-stable-green?style=flat-square) - Das `slice`-Kommando schneidet einen zusammenhängenden Teilbereich aus der Eingabe aus. @@ -19,7 +17,6 @@ bis 999 durchnummeriert. Das folgende Beispiel extrahiert alle (gültigen) Datensätze aus den Positionen 2 bis 4: - ```console $ pica slice -s --start 2 --end 5 DUMP.dat.gz -o slice.dat $ pica count --records slice.dat @@ -89,5 +86,18 @@ $ pica count --records slice.dat ``` +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} [Gzip]: https://de.wikipedia.org/wiki/Gzip diff --git a/docs/book/src/referenz/kommandos/split.md b/docs/content/docs/kommandos/split.md similarity index 85% rename from docs/book/src/referenz/kommandos/split.md rename to docs/content/docs/kommandos/split.md index c36b6d080..c6c904899 100644 --- a/docs/book/src/referenz/kommandos/split.md +++ b/docs/content/docs/kommandos/split.md @@ -1,7 +1,5 @@ # 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. @@ -89,7 +87,6 @@ $ pica count --records CHUNK_1.dat.gz ``` - ### Komprimierte Ausgabe Mittels der Option `-g`/`--gzip` erfolgt eine Komprimierung der Ausgabe: @@ -110,6 +107,19 @@ $ pica count --records 1.dat.gz ``` +[cat]: {{< relref "cat.md" >}} +[completions]: {{< relref "completions.md" >}} +[convert]: {{< relref "convert.md" >}} +[count]: {{< relref "count.md" >}} +[explode]: {{< relref "explode.md" >}} +[filter]: {{< relref "filter.md" >}} +[frequency]: {{< relref "frequency.md" >}} +[hash]: {{< relref "hash.md" >}} +[invalid]: {{< relref "invalid.md" >}} +[partition]: {{< relref "partition.md" >}} +[print]: {{< relref "print.md" >}} +[slice]: {{< relref "slice.md" >}} +[split]: {{< relref "split.md" >}} [Stapelverarbeitung]: https://de.wikipedia.org/wiki/Stapelverarbeitung [Gzip]: https://de.wikipedia.org/wiki/Gzip diff --git a/docs/go.mod b/docs/go.mod new file mode 100644 index 000000000..fa3480c2d --- /dev/null +++ b/docs/go.mod @@ -0,0 +1,5 @@ +module github.com/deutsche-nationalbibliothek/pica-rs + +go 1.19 + +require github.com/alex-shpak/hugo-book v0.0.0-20240217175702-a111041867b1 // indirect diff --git a/docs/go.sum b/docs/go.sum new file mode 100644 index 000000000..c1a8fc548 --- /dev/null +++ b/docs/go.sum @@ -0,0 +1,2 @@ +github.com/alex-shpak/hugo-book v0.0.0-20240217175702-a111041867b1 h1:iNmSezHKNFBfUAqdhkYXPd7ozT9WaaME9iv7WNFJjXc= +github.com/alex-shpak/hugo-book v0.0.0-20240217175702-a111041867b1/go.mod h1:L4NMyzbn15fpLIpmmtDg9ZFFyTZzw87/lk7M2bMQ7ds= diff --git a/docs/book/src/images/pica-rs_logo.png b/docs/static/images/logo.png similarity index 100% rename from docs/book/src/images/pica-rs_logo.png rename to docs/static/images/logo.png