Uh oh!
There was an error while loading. Please reload this page.
Clean up the documentation for the release - #589
Conversation
Audit of README.md, site.xml, and every page under src/site/markdown against the actual code, fixing what was wrong and cutting what was redundant or too deep for a Java or AWK developer reading the site. Documented behavior that does not exist: - The CLI reference documented `-r` (disable IllegalFormatException trapping). That option was removed with the AwkSink refactoring in v6.0.00 and is now rejected as unknown. Removed from the reference, and recorded in behavior-changes.md under v6.0.00, where the removal had never been noted. - `Awk.program(...)` does not exist: corrected the four references in java-variables.md and java-advanced.md to `script(...)`. - `setDefaultRS(String)` defaults to "\n", not to the platform line separator. Broken markup and links: - Two dead anchors in extensions.md (the site generates lowercase-dash anchors, not underscored ones). - A paragraph wedged between two bullets split the gawk builtins list in two, leaving bindtextdomain/dcgettext/dcngettext as an orphan list. - In java-output.md, the paragraph describing the default `getPrintStream()` sat three sections away from it, and the built-in sinks were listed as `AwkSink.from(...)` factories while later prose named classes the page never introduced. Duplication and dead weight: - One canonical statement, plus pointers, for the caveats that were repeated three or four times across pages: `--list-ext` only listing registered extensions, `-l` replacing the default extension set, and `getPrintStream()` versus subprocess stdout. - Dropped sections that restated their own page: "Choosing the Right Reuse Strategy", "Choosing the Right Output Strategy", java.md's duplicate "Next Steps", "How Extensions Are Enabled", "Tuple Serialization Compatibility", and the content-free bullets of "Sandbox Interaction". - Stopped calling the -K/-L artifact "tuples" in user-facing text: the CLI's own help calls it a program. "Tuple" now appears only where it names the internal representation (--dump-intermediate, -s). - Rewrote the index page's Key Capabilities in terms of what a reader gets, and trimmed the README's gawk feature list and its two stray paragraphs on @JawkAssocArray and Map/List variables. Standing semantics moved to the compatibility page: - The BEGINFILE/ENDFILE rules (next/nextfile restrictions, the getline file-boundary difference from gawk, --posix), out of the CLI quickstart, which keeps the description and the example. - The @include/@namespace/indirect-call semantics and the SYMTAB/FUNCTAB contract, out of extensions.md: they are interpreter behavior, not extension behavior. Also split the Integer arithmetic wall of text and dropped a release note that had leaked into it. Menu labels now match the page cross-references, and link texts across pages use the pages' real titles. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit:29413602f1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
- extensions.md claimed that none of the gawk interpreter features are
available in POSIX mode, which understates what --posix keeps: only
BEGINFILE and ENDFILE stop being keywords (AwkParser.isDisabledKeyword),
ERRNO and ARGIND become ordinary identifiers, SYMTAB and FUNCTAB are
left unpopulated, and every @ form is rejected — while `nextfile`
keeps working, as it does under `gawk --posix`. Verified with
`jawk --posix '{ print FILENAME":"$0; nextfile }' in1 in2`.
- The v6.0.00 note on the removed -r option said it is "rejected as an
unknown option", which only holds before the program text. Once -f or
-L has supplied the program, an unknown option ends option processing
and reaches the script through ARGV, so `jawk -f prog.awk -r` fails
with `FileNotFoundException: -r` instead of an option diagnostic.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>bertysentry
commented
Aug 19, 2026
@codex please review again |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit:f2baaf5a0e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Uh oh!
There was an error while loading. Please reload this page.
The trimmed sentence in install.md claimed the checksum is verified unconditionally, which overstates what src/site/resources/get does: a missing checksum asset (a release pinned with JAWK_VERSION that predates them) and a machine with neither sha256sum nor shasum both downgrade to a warning and install anyway. get.ps1 uses Get-FileHash, so only the missing-asset case applies on Windows. Stated both skip paths after the platform bullets, plus the fact that a present-but-mismatching checksum always aborts, instead of restoring the original mid-sentence aside that covered only the pinned-release case. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bertysentry
commented
Aug 19, 2026
@codex please review again |
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
The install page had grown installer internals that no reader needs: the exact jar and launcher directories, JAWK_DATA_DIR, the wording of the PATH warning, and a paragraph on when checksum verification is skipped. Compressed to what someone installing Jawk actually asks — what the installer does, where it puts things, no sudo, PATH, JAWK_INSTALL_DIR — with "verifies its published SHA-256 checksum when it can", which stays honest about the skip paths without spending a paragraph on them. The launcher's JRE discovery order moved to cli.md, next to the paragraph that introduces the jawk command, since that is where someone running the command looks; its JAWK_CLASSPATH mention was already covered by "Load Extensions" on that page and by extensions.md, so it is not repeated. Headings now say what each path is for: "Install the jawk CLI", "Add Jawk to Your Java Project", "Download Jawk Manually". No page links to the old anchors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bertysentry
commented
Aug 19, 2026
@codex please review again — the last review covered |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit:4ef1a3d4e1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Uh oh!
There was an error while loading. Please reload this page.
"then the usual platform locations" does not hold on Windows: the jawk.cmd shim generated by get.ps1 checks JAWK_JAVA_HOME, JAVA_HOME, and java.exe on the PATH, then errors out — only the POSIX launcher goes on to /usr/libexec/java_home, /usr/lib/jvm, and sdkman. Stated the three sources both launchers share, as a precedence order, rather than qualifying the fallback per platform: which variable wins is what a reader needs, and the launcher names Adoptium itself when it finds nothing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bertysentry
commented
Aug 19, 2026
@codex please review again |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit:ed1d395c85
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
- extensions.md described sandboxing as a run-time restriction, which contradicts cli-reference.md and the code: SandboxedAwkTuples throws AwkSandboxException from the tuple-emitting methods (system, printToPipe, useAsFileInput, ...), so the forbidden constructs are rejected while the program is compiled, and @include is rejected at parse time. - The Stdin extension summary grouped all three functions under consuming stdin "without blocking the whole run", but StdinGetline() blocks on getLineInput.take() until a line or EOF arrives. Described each function accurately and pointed at StdinHasInput() as the guard. - java.md claimed Jawk accepts "gawk syntax" categorically, while @load is deliberately reported as unsupported. Narrowed to the gawk extensions Jawk implements, with a link to the compatibility page. Also scoped install.md's JAWK_INSTALL_DIR sentence to the launcher directory, which is what that variable changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bertysentry
commented
Aug 19, 2026
@codex please review again |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit:1d942b27a1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Uh oh!
There was an error while loading. Please reload this page.
The guard I suggested one commit ago is itself the trap: stdInHasInput() returns 0 when the only queued item is the internal DONE marker, and isEof — which would make it return 1 — is set only by StdinGetline(), so a loop that reads only when the guard allows it never observes end of input. BlockObject.block() waits on the same predicate, so the blocking idiom deadlocks: the reader thread puts DONE, fires its last notify(), and exits. Verified both shapes against the standalone jar with `printf 'a\nb\n'`: the StdinBlock() loop hangs (timeout, exit 124) and the StdinHasInput() polling loop spins three million times without seeing EOF. Filed as #592 and warned about here; the note can go when that is fixed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bertysentry
commented
Aug 19, 2026
@codex please review again |
Codex Review: Didn't find any major issues. Breezy! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Uh oh!
There was an error while loading. Please reload this page.
What this is
A full audit of the documentation ahead of the release:
README.md,src/site/site.xml, and all 14 pages undersrc/site/markdown, checked against the code (Cli.java,Awk.java,AwkSettings, theAwkSinkimplementations, the extension annotations, and the installer scripts) and against the built site for links and anchors.Documentation only — no behavior change.
mvn sitebuilds clean, and every internal link and anchor in the generated site resolves.Documented behavior that does not exist
-rwas removed in v6.0.00 (with theAwkSinkrefactoring, commit 32ae5d8) but was still in the CLI reference as "disables Jawk's default trapping ofIllegalFormatException". It is rejected as an unknown option today. Removed from the reference, and recorded inbehavior-changes.mdunder v6.0.00 — the removal had never been noted there, so a user upgrading from 5.x had no way to learn about it.Awk.program(...)does not exist. Four references injava-variables.mdand the thread-safety rules ofjava-advanced.mdnow sayscript(...).setDefaultRS(String)defaults to"\n"(Awk.DEFAULT_RS), not to the platform line separator as the settings table claimed.Broken markup and links
extensions.md:index.html#Differences_with_Traditional_AWKandcli.html#BEGINFILE_and_ENDFILE_Rules. The site generates lowercase-dash anchors.<ul>s, leavingbindtextdomain/dcgettext/dcngettextrendered as an orphan one-item list.java-output.md, the paragraph describing the defaultgetPrintStream()sat under Special Filenames, three sections from the method it describes; and the built-in sinks were listed asAwkSink.from(...)factories while prose two sections later referred toOutputStreamAwkSink/AppendableAwkSink, names the page never introduced.Duplication and dead weight
--list-extlisting only what is registered,-lreplacing the default extension set, andgetPrintStream()versus subprocess stdout (three copies on one page).java.md's Next Steps (duplicate of its See Also), How Extensions Are Enabled plus anIMPORTANTbox repeating the paragraph above it, Tuple Serialization Compatibility (a third copy of the-K/-Lversion warning), and the content-free bullets of Sandbox Interaction.-K/-Lartifact "tuples" in user-facing text — the CLI's own help calls it a program. "Tuple" now appears only where it names the internal representation (--dump-intermediate,-s).AwkSink), and trimmed the README's gawk feature list plus its two stray paragraphs on@JawkAssocArrayandMap/Listvariables.Standing semantics moved to the compatibility page
Keeping quickstarts high-level and standing semantics in
compatibility.md.vm:BEGINFILE/ENDFILErules —next/nextfilerestrictions, thegetlinefile-boundary difference from gawk,--posix— left the CLI quickstart, which keeps the description and the worked example.@include/@namespace/indirect-call semantics and theSYMTAB/FUNCTABcontract leftextensions.md: they are interpreter behavior, not extension behavior. They are now thegawk source syntaxandSYMTAB and FUNCTABsubsections.-inf" release note that had leaked into it.Nothing was deleted outright in this section — all of it is still on the site, one link away.
For reviewers
behavior-changes.md.Two findings outside the scope of a docs change, for a maintainer decision:
--version/-Voption inCli.java, unlike every other awk.jawk --versionerrors out as an unknown option, or lands silently inARGVonce program text has been supplied.jawk -hprints its usage asjava -jar jawk-standalone.jar …(derived from the jar name), which reads oddly now that the docs lead with thejawklauncher.🤖 Generated with Claude Code