Skip to content

docs: fix rendering and support indexes - #561

Merged
codeforester merged 3 commits into
mainfrom
documentation/556-20261007-doc-rendering
Oct 7, 2026
Merged

codeforester merged 3 commits into
mainfrom
documentation/556-20261007-doc-rendering

Conversation

@codeforester

Copy link
Copy Markdown
Collaborator

Summary

  • repair escaped Markdown code spans and TSV escape examples
  • make module and documentation indexes complete
  • align the documented Bash floor with the supported 4.2.53 minimum
  • add contract assertions for the repaired documentation

Validation

  • git diff --check
  • tests/docs-contract.sh
  • tests/integration-release-contract.sh
  • tests/reference-release-contract.sh
  • scripts/first-party-cutover check
  • bats tests/first-party-cutover.bats tests/integrations.bats

Fixes #556

@codeforester
codeforester force-pushed the documentation/555-20261007-changelog-fixes branch from 4d58883 to 0af91c4 Compare October 7, 2026 02:39
@codeforester
codeforester force-pushed the documentation/556-20261007-doc-rendering branch from 82774d0 to 4bc469f Compare October 7, 2026 02:39
Base automatically changed from documentation/555-20261007-changelog-fixes to documentation/554-20261007-refresh-cutover-ledgers October 7, 2026 10:05
@codeforester

Copy link
Copy Markdown
Collaborator Author

Review at the current head: the rendering fixes (escaped backticks, \\t), the STANDARDS/docs index additions, and the new contract checks are good, and CI is green. One change is needed.

Needs changes

  1. Behaviour statements now claim a Bash floor the code does not enforce. The PR rewrites statements such as "base_std_check_bash_version returns zero for Bash 4.2.53 or newer" (lib/bash/std/README.md), "The launcher itself requires Bash 4.2.53 or newer" and "The runtime stays Bash 4.2.53-compatible" (docs/v2-api-contract.md), and the lib/bash README sentence. The code checks only major.minor: lib/bash/std/lib_std.sh:94 rejects below 4.2, and bin/base-bash reports "requires Bash 4.2 or newer". A 4.2.0 interpreter passes those checks. Please keep "4.2" where the text describes what the code enforces, and use "tested minimum 4.2.53" (as the support matrix does) where the text describes the supported floor. The README badge/text, support matrix, STANDARDS, and docs index changes can stay as they are.

If 4.2.53 should become the enforced floor instead, that is a behaviour change for a separate issue with code and tests.

@codeforester
codeforester force-pushed the documentation/554-20261007-refresh-cutover-ledgers branch from ad4ec4d to 1cf5571 Compare October 7, 2026 10:11
@codeforester
codeforester force-pushed the documentation/556-20261007-doc-rendering branch from 4bc469f to f60acfa Compare October 7, 2026 10:13
@codeforester
codeforester force-pushed the documentation/554-20261007-refresh-cutover-ledgers branch from 3489b7f to 0b9b808 Compare October 7, 2026 10:18
@codeforester
codeforester force-pushed the documentation/556-20261007-doc-rendering branch from f60acfa to 37c4a78 Compare October 7, 2026 10:18
@codeforester

Copy link
Copy Markdown
Collaborator Author

Addressed the follow-up review by distinguishing the enforced runtime boundary from the tested minimum:\n\n- Code/API documentation now says the launcher and version helper enforce Bash 4.2 or newer.\n- It identifies Bash 4.2.53 as the tested minimum.\n- The support badge, support matrix, STANDARDS, and docs-index changes remain unchanged.\n\nFocused documentation, API-manifest, BATS, and diff checks pass.

@codeforester

Copy link
Copy Markdown
Collaborator Author

Follow-up review: the Bash-floor fix is in. The code and API docs now say the launcher and base_std_check_bash_version enforce Bash 4.2 or newer, with 4.2.53 as the tested minimum. No blockers; CI was still running when I checked. Two optional nits:

  • One remaining inconsistency. lib/bash/README.md ("All public modules support Bash 4.2.53 or newer with every combination of caller-...") reads as a support statement while the neighbouring docs say 4.2 is enforced and 4.2.53 is the tested minimum. Using the same "4.2 or newer; tested minimum 4.2.53" phrasing there would make the page consistent with the rest.
  • Very long lines. A few reflowed passages in lib/bash/std/README.md (for example the "Callers should run on Bash 4.2 or newer; the tested minimum is Bash 4.2.53. The library has passive Bash version helpers, but sourcing it does not prompt, install packages, or ..." paragraph and the strict-option paragraph near it) are now single very long lines. Re-wrapping them to the surrounding width keeps the diff and future edits readable.

This PR is stacked on #559 and should merge after it.

Base automatically changed from documentation/554-20261007-refresh-cutover-ledgers to main October 7, 2026 10:44
@codeforester

Copy link
Copy Markdown
Collaborator Author

Addressed the additional review nits:\n\n- Updated lib/bash/README.md to say Bash 4.2 or newer is supported, with Bash 4.2.53 as the tested minimum.\n- Rewrapped the two long paragraphs in lib/bash/std/README.md.\n\nDocumentation, API-manifest, BATS, and diff checks pass.

@codeforester
codeforester force-pushed the documentation/556-20261007-doc-rendering branch from ba3fe59 to 1440042 Compare October 7, 2026 10:45
@codeforester
codeforester merged commit 71a32e0 into main Oct 7, 2026
11 checks passed
@codeforester
codeforester deleted the documentation/556-20261007-doc-rendering branch October 7, 2026 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: fix rendering and index inconsistencies (escaped backticks, backslash escapes, module lists, Bash floor)

1 participant