D0001 prose-run-words¶
Rule: Prose between two visual breaks stays short.
| Code | D0001 (stable, never reused) |
| Id | prose-run-words |
| Category | reading |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a long stretch of prose with no heading, figure, table or code block is skimmed, not read |
| small-workspace | warn |
a long stretch of prose with no heading, figure, table or code block is skimmed, not read |
| medium | warn |
a long stretch of prose with no heading, figure, table or code block is skimmed, not read |
| big | warn |
a long stretch of prose with no heading, figure, table or code block is skimmed, not read |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
max-words |
integer | 250 |
words of prose a reader meets between two headings, figures, tables or code blocks |
pages |
one of "all", "guide", "reference" | "all" |
the kinds of page judged |
Why¶
A reader takes in a page in stretches. A heading, a figure, a table or a code block gives the eye a place to rest and to find its way back. A long run of prose with none of them is a wall: the reader skims it, and the point in the middle of it is lost.
A run is the prose between two visual breaks: headings, code blocks, tables, figures, admonitions, content tabs, and HTML figures, videos, tables and <details> blocks. Paragraphs and list items both count as prose. The budget is in words, so it means the same on any page.
How to fix¶
Find where the topic turns and put a heading there. Turn parallel facts into a list, a comparison into a table, and a process into numbered steps. A figure that shows what the text describes is a break too.
A reference page whose long prose is right as it is can be left out with pages = "guide"; see Docs as the reader meets them.
Configure¶
[lints.prose-run-words]
level = "deny"
max-words = 250
pages = "all"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(prose-run-words) <reason> (waivers); the code works there too, as in [lints.D0001].