From 6c8b143a6d86676da189d798a4ac6af6b993e7bc Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Tue, 4 Aug 2026 14:48:14 +0100 Subject: [PATCH] docs: the PowerShell commands run as written MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both pages gave Windows readers a command that fails. PowerShell splits a -D flag whose property name contains a dot: it hands the native command -Dexec and .mainClass=... as two arguments, and Maven rejects the second with "Unknown lifecycle phase". Quoting the flag fixes it. examples/README.md also claimed the bash form works unchanged on PowerShell. It cannot: the trailing backslash is a continuation PowerShell does not have, so the command runs as two, and the advice about backslash paths was beside the point — forward slashes work fine in -f. benchmarks.md already quoted the flags on its java lines and missed the one on its mvnw line, so the page half-knew. --- CHANGELOG.md | 9 +++++++++ docs/operations/benchmarks.md | 7 ++++++- examples/README.md | 15 +++++++++++++-- 3 files changed, 28 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 94d779e3..a49a9fb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -211,6 +211,15 @@ follow semantic versioning; release dates are ISO 8601. ### Documentation +- **The PowerShell commands run as written.** Two pages handed Windows readers a + command that fails. PowerShell splits a `-D` flag whose property name contains a dot, + passing the native command `-Dexec` and `.mainClass=…` as separate arguments, and + Maven then rejects the fragment with `Unknown lifecycle phase ".mainClass=…"`; a flag + with no dot before the `=` survives, which is what makes it easy to miss. The + examples README compounded it by claiming the bash form works unchanged on + PowerShell — the block above it ends a line with `\`, a continuation PowerShell does + not have — while pointing at backslash paths, which were never the problem. Both + pages now carry the command that was run on PowerShell to check it. - **The authoring cheatsheet stops describing `lineSpacing` as a multiple.** Its address-block recipe passed `1.3` and explained it as overriding a default of `1.0` — the reading a CSS `line-height` invites, and the one the number itself suggests. diff --git a/docs/operations/benchmarks.md b/docs/operations/benchmarks.md index b6f18c64..73169ecb 100644 --- a/docs/operations/benchmarks.md +++ b/docs/operations/benchmarks.md @@ -293,8 +293,13 @@ reference, with the IDE closed: **Windows (PowerShell):** +A `-D` flag whose property name contains a dot has to be quoted here — unquoted, +PowerShell hands the native command `-Dmdep` and `.outputFile=…` as two arguments and +Maven rejects the second as a lifecycle phase. That is why the `java` lines below quote +theirs too. + ```powershell -.\mvnw.cmd -B -ntp -f benchmarks\pom.xml test-compile dependency:build-classpath -DincludeScope=test -Dmdep.outputFile=target/benchmark.classpath +.\mvnw.cmd -B -ntp -f benchmarks\pom.xml test-compile dependency:build-classpath -DincludeScope=test "-Dmdep.outputFile=target/benchmark.classpath" $cp = 'benchmarks\target\test-classes;benchmarks\target\classes;' + (Get-Content benchmarks\target\benchmark.classpath -Raw).Trim() 1..5 | ForEach-Object { & java "-Dgraphcompose.benchmark.profile=full" -cp "$cp" com.demcha.compose.CurrentSpeedBenchmark } $runs = Get-ChildItem target\benchmarks\current-speed\run-*.json | Sort-Object Name | Select-Object -Last 5 | ForEach-Object { $_.FullName } diff --git a/examples/README.md b/examples/README.md index 4b26768c..76c8fc66 100644 --- a/examples/README.md +++ b/examples/README.md @@ -27,8 +27,19 @@ Source path into a class name: drop `src/main/java/` and `.java`, then swap `/` So `src/main/java/com/demcha/examples/flagships/ModuleFirstFileExample.java` becomes `com.demcha.examples.flagships.ModuleFirstFileExample`. -Generated PDFs land in `examples/target/generated-pdfs/`. The same `mvnw.cmd` form -works on Windows PowerShell with backslash paths. +Generated PDFs land in `examples/target/generated-pdfs/`. + +On Windows PowerShell the wrapper is `.\mvnw.cmd` and the command needs two changes, +neither of them cosmetic. The trailing `\` above is a shell continuation PowerShell does +not have, so the command must be one line. And `-Dexec.mainClass=…` has to be quoted: +unquoted, PowerShell splits it and Maven receives `.mainClass=…` as a separate argument, +failing with `Unknown lifecycle phase ".mainClass=…"`. + +```powershell +.\mvnw.cmd -f examples/pom.xml exec:java "-Dexec.mainClass=com.demcha.examples.flagships.ModuleFirstFileExample" +``` + +Forward slashes are fine in the `-f` path; nothing needs converting to backslashes. To regenerate the **whole catalogue** — roughly a hundred documents, and the output directory is emptied first — run the batch entry point. You do not need it to read one