Ga naar inhoud

Overzicht

vsa is de commandoregel-tool van de vsa-toolset. Ermee controleer je geldige VSA-notatie, bekijk je de interne parser-structuur, en genereer je SVG, Hugo-Markdown en MusicXML uit vsa-bestanden en Markdown.

Deze pagina geeft het overzicht. Elk subcommando heeft een eigen man-pagina met de volledige argumentenlijst, voorbeelden en foutgevallen.

Werkmap-conventie

Alle voorbeelden in deze referentie gaan uit van Windows cmd.exe en de repository-root als werkmap:

cd /d C:\Git\orthodox-ronl\VSA-tooling

Paden in commando's zijn relatief aan die map, tenzij je een absoluut pad opgeeft.

Algemene syntax

vsa [--config CONFIG] [--version] <subcommando> …

vsa zonder subcommando en zonder --version toont een foutmelding (Geen commando opgegeven.) en stopt met exitcode 1.

Globale opties

Optie Verplicht Betekenis
--config CONFIG Nee Pad naar een alternatief vsa.toml. Zonder deze optie zoekt elk commando zelf naar vsa.toml (zie config.md).
--version Nee Toon de geïnstalleerde versie en stop direct (subcommando wordt genegeerd).
-h, --help Nee Toon hulp. Werkt zowel op vsa --help als op vsa <subcommando> --help.

Sommige subcommando's (svg, process, build-markdown, musicxml, pdf) accepteren --config ook als subcommando-optie. Die overschrijft dan de globale --config.

Exitcodes

Exitcode Betekenis
0 Commando succesvol
1 Fout gevonden of commando mislukt

Controleer in cmd.exe de laatste exitcode direct na een commando:

echo %ERRORLEVEL%

Subcommando's

Subcommando Doel
validate Controleer op geldige VSA-notatie (.vsa, .md, of een map).
parse Toon parseroutput of de interne ast van één vsa-bestand.
blocks Vind en inspecteer VSA-blokken in een Markdownbestand.
svg Render één vsa-bestand naar één SVG-bestand.
process Genereer SVG-bestanden uit VSA-blokken in Markdown (zonder Markdown te herschrijven).
build-markdown Genereer Hugo-geschikte Markdown én SVG-assets uit content-source.
pdf Render één Markdownbestand (VSA, includes, pagebreaks) naar A4-PDF.
resolve-catalogus Los :::include … zoek="…" op naar catalogus-paden (bron:… / lokaal:…).
syllabify Lettergreepstreepjes in VSA-tekst, ook op scope-grenzen (bestand/map; Pyphen nl_NL).
text Platte gezongen tekst uit .vsa / .mvsa / MusicXML / .mscz (zoekindex).
zoektekst Vul/controleer YAML-zoektekst in canonieke .vsa / .mvsa (editorzoeken).
musicxml Exporteer VSA naar MusicXML (.mxl of .musicxml).
audio Exporteer naar audio (.mp3) voor preview-luisteren (via MuseScore).
mvsa Draft: bron .mvsa — validate/normalize/mxl/mscz/pdf/mp3/import (mvsa ≡ vsa mvsa).
mxl Bron .mxl/.musicxml: import → mvsa; mscz via MuseScore.
mscz Bron .mscz: import → mvsa; mxl via MuseScore; text (lyrics).

Elke pagina hierboven beschrijft de volledige syntax, alle argumenten en opties (inclusief defaults), voorbeeldoutput, en typische foutgevallen. Deze overzichtspagina herhaalt die details niet.

Scripts

De onderstaande scripts gebruik je rond vsa zelf (installatie, testen, docs). Zie scripts/README.md voor het volledige overzicht.

Script Doel
test Installeert de lokale omgeving (.venv, vsa, pytest).
scripts\test.cmd Draait de pytest-suite.
scripts\ci.cmd Draait de volledige lokale CI (pytest + consumer-minimal).
serve Serveert deze MkDocs-documentatie lokaal.

Diagnosevolgorde

Bij problemen: eerst vsa validate, daarna scripts\test.cmd, eventueel vsa blocks … --json. Volledige uitleg: specification/cli.md.

Verwante documentatie