[BUG] Manual build succeeds with final-pass typesetting warnings #3

New issue

Open

opened 2026-09-12 08:05:32 +02:00 by erikinkinen · 0 comments

erikinkinen commented

2026-09-12 08:05:32 +02:00

Owner

Summary

The technical-manual build succeeds and publishes its PDF while the final TeX pass still emits underfull box diagnostics. This means a green manual job does not establish the required warning-free documentation result.

Reproduction

The observation is from one completed clean-checkout CI run at the exact revision below; this report did not rerun the compiler locally.

Check out 3beaff9142b46e5fdb1a4245aa629a90f0735b69 in docs.
Use the manual job's documented TeX dependencies and execute ./scripts/build-manual.sh with fresh output directories.
Inspect the final pdflatex pass and its main.log, then inspect the script's exit status.

For isolated reproduction, set BUILD_DIR and OUT_DIR to separate private directories before invoking the maintained script. Intermediate cross-reference warnings must be distinguished from diagnostics that survive the final pass.

Expected and actual behavior

Expected: the final manual build has no warnings or layout diagnostics, and the validation gate rejects a final log that still contains them before copying/publishing the accepted PDF.

Actual: manual CI run 789, job manual (job ID 19127, attempt 1), succeeded. Its third and final pdflatex pass emitted 869 underfull horizontal-box and 14 underfull vertical-box diagnostics. The final pass had no overfull boxes and no remaining LaTeX unresolved-reference warnings. The resulting manual contains 1,825 pages.

The maintained build script checks final-log overfull horizontal/vertical boxes but has no corresponding check for underfull diagnostics. Fix the source/layout causes and add final-log regression coverage; do not hide the diagnostics globally.

Environment and identity

Component repository/revision: erix/docs at 3beaff9142b46e5fdb1a4245aa629a90f0735b69; exact main merge revision selected by run 789.
Image profile, digest and build/runtime configuration: host documentation build; no guest image or runtime graph executes in this job.
Hardware or VM, architecture, firmware and toolchain versions: Forgejo Docker job using the repository workflow; latexmk 4.86; pdfTeX 3.141592653-2.6-1.40.26, TeX Live 2025/dev/Debian, as recorded in the job log. Runner hardware details were not collected.
Input/session route and granted authority: maintained manual sources and explicit build/output directories; no new runtime capability grant.
Last known working revision: not established; this is a confirmed baseline defect, not a proven newly introduced regression.

Evidence and prior checks

The run 789 log records the third pass beginning at 05:34:17 UTC, final PDF generation at 05:35:28 UTC, and successful job completion. The first final-pass underfull diagnostic appears at 05:34:18 UTC. Read-only inspection retained the complete job log and separated final-pass counts from first/second-pass reference warnings.

Inspect scripts/build-manual.sh at the affected revision for the current overfull-only gate. No local compiler/VM was executed and no CI run was restarted or cancelled during this observation.

The fix is published for review at signed commit
22d524bf234d5b205d543102d9e2d7dece2fe21d in erix/docs#4. It corrects displayed
API headings and prose/page/table layout and rejects nonempty final logs with
surviving diagnostics, missing logs, compiler failures and scanner failures.
No warning-threshold suppression is used. All 26 documentation tests pass.
The complete local maintained build exits 0 with 1,991 pages, zero final warnings,
all 5,715 API labels retained and zero out-of-page text among 379,275 checked word
boxes. Representative contents, prose, table and API pages were visually inspected.
PDF SHA-256: 70c3074aba101ad0c7ff79247152c7e57a6a06bf53c350ad3c60f812e9028d51.
Earlier failed layout attempts remain separate evidence. Exact new-head CI is
still pending, so this issue remains open.

Tracking

Closure needs source/layout corrections, a final-log gate regression that rejects underfull diagnostics, warning-free complete manual generation at the changed revision, and inspection of affected rendered pages. Keep early-pass reference resolution and final-pass acceptance separate.

Related documentation work: inline documentation and warning-free builds and documentation repository audit.

## Summary The technical-manual build succeeds and publishes its PDF while the final TeX pass still emits underfull box diagnostics. This means a green manual job does not establish the required warning-free documentation result. ## Reproduction The observation is from one completed clean-checkout CI run at the exact revision below; this report did not rerun the compiler locally. 1. Check out `3beaff9142b46e5fdb1a4245aa629a90f0735b69` in `docs`. 2. Use the manual job's documented TeX dependencies and execute `./scripts/build-manual.sh` with fresh output directories. 3. Inspect the final `pdflatex` pass and its `main.log`, then inspect the script's exit status. For isolated reproduction, set `BUILD_DIR` and `OUT_DIR` to separate private directories before invoking the maintained script. Intermediate cross-reference warnings must be distinguished from diagnostics that survive the final pass. ## Expected and actual behavior Expected: the final manual build has no warnings or layout diagnostics, and the validation gate rejects a final log that still contains them before copying/publishing the accepted PDF. Actual: [manual CI run 789](https://git.erikinkinen.fi/erix/docs/actions/runs/789), job `manual` (job ID 19127, attempt 1), succeeded. Its third and final `pdflatex` pass emitted **869 underfull horizontal-box and 14 underfull vertical-box diagnostics**. The final pass had no overfull boxes and no remaining LaTeX unresolved-reference warnings. The resulting manual contains 1,825 pages. The maintained build script checks final-log overfull horizontal/vertical boxes but has no corresponding check for underfull diagnostics. Fix the source/layout causes and add final-log regression coverage; do not hide the diagnostics globally. ## Environment and identity - Component repository/revision: `erix/docs` at `3beaff9142b46e5fdb1a4245aa629a90f0735b69`; exact main merge revision selected by run 789. - Image profile, digest and build/runtime configuration: host documentation build; no guest image or runtime graph executes in this job. - Hardware or VM, architecture, firmware and toolchain versions: Forgejo Docker job using the repository workflow; latexmk 4.86; pdfTeX 3.141592653-2.6-1.40.26, TeX Live 2025/dev/Debian, as recorded in the job log. Runner hardware details were not collected. - Input/session route and granted authority: maintained manual sources and explicit build/output directories; no new runtime capability grant. - Last known working revision: not established; this is a confirmed baseline defect, not a proven newly introduced regression. ## Evidence and prior checks The [run 789 log](https://git.erikinkinen.fi/erix/docs/actions/runs/789) records the third pass beginning at 05:34:17 UTC, final PDF generation at 05:35:28 UTC, and successful job completion. The first final-pass underfull diagnostic appears at 05:34:18 UTC. Read-only inspection retained the complete job log and separated final-pass counts from first/second-pass reference warnings. Inspect [`scripts/build-manual.sh` at the affected revision](https://git.erikinkinen.fi/erix/docs/src/commit/3beaff9142b46e5fdb1a4245aa629a90f0735b69/scripts/build-manual.sh) for the current overfull-only gate. No local compiler/VM was executed and no CI run was restarted or cancelled during this observation. The fix is published for review at signed commit `22d524bf234d5b205d543102d9e2d7dece2fe21d` in erix/docs#4. It corrects displayed API headings and prose/page/table layout and rejects nonempty final logs with surviving diagnostics, missing logs, compiler failures and scanner failures. No warning-threshold suppression is used. All 26 documentation tests pass. The complete local maintained build exits 0 with 1,991 pages, zero final warnings, all 5,715 API labels retained and zero out-of-page text among 379,275 checked word boxes. Representative contents, prose, table and API pages were visually inspected. PDF SHA-256: `70c3074aba101ad0c7ff79247152c7e57a6a06bf53c350ad3c60f812e9028d51`. Earlier failed layout attempts remain separate evidence. Exact new-head CI is still pending, so this issue remains open. ## Tracking Closure needs source/layout corrections, a final-log gate regression that rejects underfull diagnostics, warning-free complete manual generation at the changed revision, and inspection of affected rendered pages. Keep early-pass reference resolution and final-pass acceptance separate. Related documentation work: [inline documentation and warning-free builds](https://git.erikinkinen.fi/erix/docs/issues/1) and [documentation repository audit](https://git.erikinkinen.fi/erix/docs/issues/2).

erikinkinen added the

bug

phase-6

docs

labels

2026-09-12 08:05:32 +02:00

erikinkinen referenced this issue from a commit

2026-09-12 08:15:04 +02:00

docs: Record POSIX compatibility coordination

~~erikinkinen referenced this issue 2026-09-12 08:28:22 +02:00~~

WIP: Document native authority and verify workspace and command evidence #4

~~erikinkinen referenced this issue 2026-09-15 06:45:36 +02:00~~