[BUG] Inline manual options replace double hyphens with an en dash #8

New issue

Closed

opened 2026-09-15 22:15:32 +02:00 by erikinkinen · 0 comments

erikinkinen commented

2026-09-15 22:15:32 +02:00

Owner

Summary

Inline long options in the technical manual render their two ASCII hyphens as one Unicode en dash. Copying such an option from the PDF changes its bytes and no longer supplies the documented command-line flag. This affects existing Boot Tool and SHA2 Tool instructions; the new workspace-inspector option exposed the same rendering behavior during visual review.

Reproduction

Build the manual from Docs 31bd9524c31c9d8d6a8f00248f702e6b7d428106 with bash scripts/build-manual.sh. Inspect the inline options in the Boot Tool chapter, or extract the PDF text with pdftotext -bbox-layout. The source \texttt{--kernel} in manual/9-command-line-tools/25-boot-tool.tex renders as –kernel. The same occurs for --help, --version, --output and inline --zero in the SHA2 Tool chapter. These observations come from the retained complete original render, without changing its source or retrying a failed build.

Expected and actual behavior

Expected: inline command examples preserve two U+002D ASCII hyphens, including the standalone -- option delimiter.

Actual: the PDF displays/extracts U+2013 at the start of the observed long options. The manual build and its 45 tests pass, with no final TeX warning. Existing page-bounds and warning checks do not verify option punctuation. No command execution or guest failure is inferred from the PDF defect.

Environment and identity

Docs source: 31bd9524c31c9d8d6a8f00248f702e6b7d428106; complete 2,375-page native manual render.
Original PDF SHA-256: 3db7583585d3a95404dfb28b5a36a3145e1367cf333134a99f6f20895df56226.
Confirmed affected pages: 2254–2256 and 2261/2263. Eleven extracted long-option occurrences were checked explicitly.
Host PDF/TeX documentation build; no guest image, input route or runtime capability is involved.
Last known fully correct inline-option rendering is not established. Verbatim command blocks and ordinary prose punctuation need separate checks.

Evidence and prior checks

Retained source, PDF bytes and extracted Unicode code points establish the mismatch: --kernel becomes –kernel, and --zero becomes –zero. The source audit and 24 existing inline option/delimiter repairs are complete at the signed revision below; the new workspace option is also literal.

Acceptance requires preserving literal option bytes in inline text, checking standalone delimiters and flags embedded in longer commands, retaining normal prose punctuation, running documentation tests and a full warning-free render, and checking extracted text plus changed pages visually. Do not equate successful PDF generation with correct command examples.

Validated repair — 15 September 2026:

Signed Docs 5d77dc2b82bf5439e58234d901e30f4565aaa81a documents the independent pristine/packaged ELF workspace mapping domain, its native-loader assumption and the separate source borrowing, erasure and all-path frame obligations. It also fixes 24 existing inline long options and argument delimiters whose ASCII double hyphens previously became an en dash (issue #8). Numeric ranges, prose punctuation, verbatim command blocks and original signed API snapshots remain unchanged.

All 45 documentation tests, canonical and Markdown checks pass. The complete manual has 2,375 pages, 433,924 in-bounds word boxes and zero final warnings. Text extraction confirms literal option bytes, including embedded set -- and standalone delimiters; nine affected pages pass visual review. PDF SHA-256: fd33102422cc80697ead3f5c939b39d1e9c6bf69ce06475be4ce8767cafb2f23. The first render's punctuation failure remains recorded separately; the accepted PDF comes from the final corrected source. Docs CI 887/888 passes with all four complete classified logs (762,236 bytes). Both manual jobs pass 45 tests and converge with 35/1/0 reference warnings, leaving zero final warnings; both Markdown jobs pass. Rust and VM checks do not apply to these documentation-only edits.

The source repair, literal PDF bytes, visual checks and complete current-head CI satisfy this rendering defect's acceptance criteria. Closing this issue does not close any runtime, frame-proof or guest-build requirement.

Tracking

Documentation audit: #1. Current review: #4. The current workspace mapping implementation and complete frame proof keep their separate acceptance scopes.

## Summary Inline long options in the technical manual render their two ASCII hyphens as one Unicode en dash. Copying such an option from the PDF changes its bytes and no longer supplies the documented command-line flag. This affects existing Boot Tool and SHA2 Tool instructions; the new workspace-inspector option exposed the same rendering behavior during visual review. ## Reproduction Build the manual from Docs `31bd9524c31c9d8d6a8f00248f702e6b7d428106` with `bash scripts/build-manual.sh`. Inspect the inline options in the Boot Tool chapter, or extract the PDF text with `pdftotext -bbox-layout`. The source `\texttt{--kernel}` in `manual/9-command-line-tools/25-boot-tool.tex` renders as `–kernel`. The same occurs for `--help`, `--version`, `--output` and inline `--zero` in the SHA2 Tool chapter. These observations come from the retained complete original render, without changing its source or retrying a failed build. ## Expected and actual behavior Expected: inline command examples preserve two U+002D ASCII hyphens, including the standalone `--` option delimiter. Actual: the PDF displays/extracts U+2013 at the start of the observed long options. The manual build and its 45 tests pass, with no final TeX warning. Existing page-bounds and warning checks do not verify option punctuation. No command execution or guest failure is inferred from the PDF defect. ## Environment and identity - Docs source: `31bd9524c31c9d8d6a8f00248f702e6b7d428106`; complete 2,375-page native manual render. - Original PDF SHA-256: `3db7583585d3a95404dfb28b5a36a3145e1367cf333134a99f6f20895df56226`. - Confirmed affected pages: 2254–2256 and 2261/2263. Eleven extracted long-option occurrences were checked explicitly. - Host PDF/TeX documentation build; no guest image, input route or runtime capability is involved. - Last known fully correct inline-option rendering is not established. Verbatim command blocks and ordinary prose punctuation need separate checks. ## Evidence and prior checks Retained source, PDF bytes and extracted Unicode code points establish the mismatch: `--kernel` becomes `–kernel`, and `--zero` becomes `–zero`. The source audit and 24 existing inline option/delimiter repairs are complete at the signed revision below; the new workspace option is also literal. Acceptance requires preserving literal option bytes in inline text, checking standalone delimiters and flags embedded in longer commands, retaining normal prose punctuation, running documentation tests and a full warning-free render, and checking extracted text plus changed pages visually. Do not equate successful PDF generation with correct command examples. Validated repair — 15 September 2026: Signed Docs `5d77dc2b82bf5439e58234d901e30f4565aaa81a` documents the independent pristine/packaged ELF workspace mapping domain, its native-loader assumption and the separate source borrowing, erasure and all-path frame obligations. It also fixes 24 existing inline long options and argument delimiters whose ASCII double hyphens previously became an en dash (issue #8). Numeric ranges, prose punctuation, verbatim command blocks and original signed API snapshots remain unchanged. All 45 documentation tests, canonical and Markdown checks pass. The complete manual has 2,375 pages, 433,924 in-bounds word boxes and zero final warnings. Text extraction confirms literal option bytes, including embedded `set --` and standalone delimiters; nine affected pages pass visual review. PDF SHA-256: `fd33102422cc80697ead3f5c939b39d1e9c6bf69ce06475be4ce8767cafb2f23`. The first render's punctuation failure remains recorded separately; the accepted PDF comes from the final corrected source. Docs CI 887/888 passes with all four complete classified logs (762,236 bytes). Both manual jobs pass 45 tests and converge with 35/1/0 reference warnings, leaving zero final warnings; both Markdown jobs pass. Rust and VM checks do not apply to these documentation-only edits. The source repair, literal PDF bytes, visual checks and complete current-head CI satisfy this rendering defect's acceptance criteria. Closing this issue does not close any runtime, frame-proof or guest-build requirement. ## Tracking Documentation audit: https://git.erikinkinen.fi/erix/docs/issues/1. Current review: https://git.erikinkinen.fi/erix/docs/pulls/4. The current workspace mapping implementation and complete frame proof keep their separate acceptance scopes.

erikinkinen added the

docs

bug

phase-6

labels

2026-09-15 22:15:32 +02:00

~~erikinkinen referenced this issue from erix/exsh 2026-09-15 22:17:09 +02:00~~

WIP: Bind shell workspace and cleanup frame evidence #3

erikinkinen referenced this issue from erix/exsh

2026-09-15 22:17:10 +02:00

[FEATURE] Audit authority, code quality and documentation in exsh #2

erikinkinen referenced this issue from erix/integration