The work the other paper tools planned for paperspec (paperdesk PLAN M5.4, paperform PLAN 4.2): - paperspec correct and paperspec.revision apply proposed corrections to a package, folder or zip, and write it only once it validates. - doc.math.form is checked: label and style commands always, the form's own spelling when papermath is installed or forms= is passed. - paperspec.datasets and seven doc.dataset.* rules check a package's datasets. - fixtures/invalid gains suspect-witness and math-form-label (33 in all). - Canonical JSON reads numbers as doubles, so 1e20 round-trips. - The registries and the JSON-LD context ship in the wheel. - Public names for what paperdesk and paperform imported as private ones, with the old names kept as aliases. - The text and lossy-projection functions are about three times faster through the gate, tested equal to the old code on every code point. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013XwDhn4LkrKQfw4ArDEr2E
104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# Command line
|
|
|
|
One command, `paperspec`, with seven subcommands.
|
|
`python -m paperspec` runs the same program.
|
|
`paperspec --version` prints the package version and the Unicode version it pins, and `paperspec COMMAND --help` prints a command's options, advice and examples.
|
|
|
|
| Command | Works | Does |
|
|
| --- | --- | --- |
|
|
| [`validate`](#validate) | anywhere the package is installed with its `tools` extra | Validate packages, or run proposed corrections through the gate. |
|
|
| [`correct`](#correct) | anywhere the package is installed with its `tools` extra | Apply proposed corrections to a package and write the corrected package. |
|
|
| [`load`](#load) | anywhere the package is installed with its `tools` extra | Validate packages and load them into a SQLite database. |
|
|
| [`check`](#check) | in a checkout | Check the whole repository. |
|
|
| [`build`](#build) | in a checkout | Rebuild `fixtures/` and `vectors/` from their sources. |
|
|
| [`stress`](#stress) | in a checkout | Stress the oracle with random inputs. |
|
|
| [`site`](#site) | in a checkout | Build the website into `_site/`. |
|
|
|
|
A misspelled command gets a suggestion, and an option a command does not know is refused.
|
|
"In a checkout" means the repository an editable install points at, or else the one around the current folder.
|
|
|
|
## validate
|
|
|
|
```text
|
|
paperspec validate [-h] [--correction PROPOSALS] [--max-size BYTES] PACKAGE [PACKAGE ...]
|
|
```
|
|
|
|
| Option | Meaning |
|
|
| --- | --- |
|
|
| `PACKAGE` | A package folder or a zipped package (`.sct.zip`), unpacked under the specification's path rules first. |
|
|
| `--correction PROPOSALS` | A JSON file holding one proposed correction, or a JSON Lines file of several, run through the gate against the one package given. Each record that would be appended to `corrections.jsonl` is printed, until one is refused. Nothing is written. |
|
|
| `--max-size BYTES` | Refuse a zipped package that expands past this many bytes (default 1073741824). |
|
|
|
|
Each failure is printed to standard error as `package: where: rule: message`.
|
|
Exit status: 0 when everything is valid, 1 when something is refused, 2 for a usage error.
|
|
|
|
## correct
|
|
|
|
```text
|
|
paperspec correct [-h] --correction PROPOSALS [--out PATH] [--answered SUSPECT] [--asset FILE] [--max-size BYTES] PACKAGE
|
|
```
|
|
|
|
| Option | Meaning |
|
|
| --- | --- |
|
|
| `PACKAGE` | A package folder or a zipped package. It is validated first. |
|
|
| `--correction PROPOSALS` | A JSON file holding one proposed correction, or a JSON Lines file of several, applied in order. Nothing is written unless every one passes the gate. |
|
|
| `--out PATH` | Write the corrected package here, a folder, or a zip for a zipped package, which must not exist. By default `PACKAGE` is replaced. |
|
|
| `--answered SUSPECT` | The ID of a suspect the corrections answer, which leaves `suspects.jsonl`. Repeat for several. |
|
|
| `--asset FILE` | A file to add under `assets/` as `<sha256>.<extension>`, such as a crop a correction's evidence names. Repeat for several. |
|
|
| `--max-size BYTES` | As for `validate`. |
|
|
|
|
The corrected package is validated before it replaces anything.
|
|
Each record appended to `corrections.jsonl` is printed, one per line; standard error names the derived lines and datasets left out because they read corrected text, and ends with the document's new revision and package hash.
|
|
A refusal is printed as `validate` prints it, and nothing is written.
|
|
Exit status: 0 when the corrections were applied, 1 when the package or a proposal is refused, 2 for a usage error.
|
|
|
|
## load
|
|
|
|
```text
|
|
paperspec load [-h] --sqlite DATABASE [--bundle] [--built-from REV] [--store STORE] [--max-size BYTES] PACKAGE [PACKAGE ...]
|
|
```
|
|
|
|
| Option | Meaning |
|
|
| --- | --- |
|
|
| `PACKAGE` | A package folder or a zipped package. Every package is validated first, and nothing is loaded if any fails. |
|
|
| `--sqlite DATABASE` | The database file, created with the tables of `sql/` if it does not exist. Files with no table of their own are copied into `DATABASE.assets/`. |
|
|
| `--bundle` | Build a new `scienting-bundle/1` file with the full-text search index. Needs `--built-from`. |
|
|
| `--built-from REV` | With `--bundle`: the store revision the packages come from. |
|
|
| `--store STORE` | With `--bundle`: the store's name (default: the packages' common store). |
|
|
| `--max-size BYTES` | As for `validate`. |
|
|
|
|
## check
|
|
|
|
```text
|
|
paperspec check [-h] [--quick]
|
|
```
|
|
|
|
`--quick` skips the byte-for-byte rebuild.
|
|
Exit status: 0 when every check passed, 1 otherwise.
|
|
|
|
## build
|
|
|
|
```text
|
|
paperspec build [-h] [--out DIR]
|
|
```
|
|
|
|
Without `--out` it rewrites `fixtures/` and `vectors/` in the checkout; with it, it builds into `DIR` instead.
|
|
|
|
## stress
|
|
|
|
```text
|
|
paperspec stress [-h] [--seed SEED] [--rounds ROUNDS]
|
|
```
|
|
|
|
`--seed` sets the random seed (default 20261014) and `--rounds` the cases per property (default 200).
|
|
Exit status: 0 when every property held, 1 otherwise.
|
|
|
|
## site
|
|
|
|
```text
|
|
paperspec site [-h] [--out DIR] [--base-url URL]
|
|
```
|
|
|
|
`--out` sets the output folder, which must not be the repository or contain it (default `_site/` in the checkout).
|
|
`--base-url` sets the site's address for canonical links (default `https://paperspec.scient.ing`).
|