docs(readme): restructure CLI section; voice polish#3
Merged
Conversation
The CLI section listed flags inline in a comment block. Promote it to the same `<details><summary><code>signature</code></summary>` pattern used by `clean(input, options?)` in the API section, with explicit Arguments / Options / Exit codes / Examples tables. Every flag now has its own row with type, default, and a one-line description. The previous `Common forms` examples are preserved. Two voice fixes in the `Why this exists` paragraph: - "but they upload your file" → "then upload the bytes" — drops second-person addressing in favor of third-person institutional voice. - "runs the same strips locally on a single dependency (...), opens no network connections, and writes no telemetry" → "runs the same strips in-process on a single dependency (...). No network calls, no telemetry." — collapses the three-item conjunction.
Per review: the CLI deserves its own top-level section instead of sitting nested under `## Usage` alongside the library example. Move the `<details><summary><code>pdf-cleaner <input> [options]</code></summary>` block plus the npx + global-install snippets out to a fresh `## CLI` section that follows `## Why this exists`. `## Usage` now holds only the library import + try/catch example, parallel to other Coroboros packages that ship a library and no CLI. Switch the global-install snippet from `npm install -g` to `pnpm add -g` to match the package manager used throughout the rest of the README. Add `CLI` to the Contents TOC.
`## Usage` now sits as a quick-start: one minimal programmatic example and one minimal CLI invocation, labeled with bold rather than H3 subheaders. The H3s avoided an anchor collision with the full `## CLI` section below (both would have rendered to `#cli`, sending the Contents TOC to the wrong place). Full library reference stays in `## API` (Types, Cleaning, Errors). Full CLI reference stays in `## CLI` (the `<details>` block with args, options, exit codes, and examples). Drop the redundant ESM and CommonJS one-liners that lived in the old Usage block — the `import` line in the quick-start example already shows the ESM form, and Install lists the package manager commands.
…e reference Install now splits **As a library** (four package-manager add commands) from **As a CLI** (the npx run-without-install and the `pnpm add -g` global install). All ways to get the package end up in one place. `## CLI` becomes a pure reference section: only the `<details><summary><code>pdf-cleaner <input> [options]</code></summary>` block with arguments, options, exit codes, and examples. No more install snippets repeating what Install already covers. Section roles are now cleanly separated: Install = how to get it, Usage = quick start with one example of each form, CLI = full command-line reference, API = full library reference.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
<details><summary><code>signature</code></summary>pattern used byclean(input, options?)in## API. Every flag now has its own row with type, default, and a one-line description. Arguments, Options, Exit codes, and Examples are split into four explicit tables.## Installabsorbs the CLI install methods (npx,pnpm add -g) alongside the four package-manageraddcommands. Single place for "how to get it".## Usageshrinks to a quick start: one minimal programmatic example, one minimalnpxinvocation.## Why this existsstays.## CLI(afterWhy this exists) is now pure reference — just the<details>block.## APIunchanged.Why this existsparagraph:but they upload your file→then upload the bytes.runs the same strips locally on a single dependency (...), opens no network connections, and writes no telemetry→runs the same strips in-process on a single dependency (...). No network calls, no telemetry.Test plan
<details>expands, the four tables in## CLIrender, the Contents anchors all resolve.