test/docs_style.sh enforces seven rules over every user-facing page: sentence length, the
idiom list, em and en dashes, prose double-hyphens, conflict markers, the roadmap nav entry, and
every VERSION citation. All seven are about prose. None is about structure.
So a markdown table that stops being a table is invisible to the gate whose whole purpose is
keeping these pages readable.
Measured, on an open PR
#1022 splices a note and a second table into the middle of the set_options argument table in
docs/configuration.md:
158 | `stripe_row_limit` | integer | ... | last row of the argument table
159 blank line ENDS the table
160 **A `stripe_row_limit` below 1024 ...** the note
165 | `stripe_row_limit` | FSST tables | ...| a second table, with its own header
171 At 1000 the column costs more ... prose
175 | `compression` | name | ... | a table ROW with no header above it
180 | `ttl_interval` | interval | ... |
Six of the nine set_options arguments render as a headerless table. docs_style.sh passes,
14 checks. Found by @linuxhikerpm in review; I had reviewed the same PR twice and checked
sentence length, a guard's scoping claim and a three-row mutation table without once asking
whether the markdown still renders.
It is the second occurrence today. The first was the configuration.md GUC table having no
blank lines, which made an awk RS='' guard read stripe_row_limit's row and
chunk_group_row_limit's row as one record and pass on main. Both are the same underlying
fact: a markdown table is a contiguous block of | lines and a blank line is structural, which
is easy to forget while editing prose.
The check
About fifteen lines, and it found the live case on the first run:
in_tbl = has_sep = False
for i, line in enumerate(lines, 1):
row = line.lstrip().startswith("|")
if row and not in_tbl:
in_tbl, has_sep, start = True, False, i
elif not row and in_tbl:
if not has_sep:
bad.append(start) # a table block with no separator row
in_tbl = False
if in_tbl and re.match(r'^\s*\|[\s:|-]+\|\s*$', line):
has_sep = True
Belongs in plain_language_check.py, which already walks every page and already reports per-file
counts that docs_style.sh asserts, so it costs one counter rather than a new traversal.
What it must meet first
A static guard in this tree needs its false-positive budget measured over the whole tree before
it lands -- run it over docs/, README.md and anything else in scope and show the count is 0
on main, or name each exception. A guard that arrives red on existing content is a guard
somebody disables.
Two shapes to check against before claiming 0: a single-row table used as a callout (legitimately
has a separator), and an indented | inside a fenced code block, which is not a table at all and
would need the fence tracked.
test/docs_style.shenforces seven rules over every user-facing page: sentence length, theidiom list, em and en dashes, prose double-hyphens, conflict markers, the roadmap nav entry, and
every
VERSIONcitation. All seven are about prose. None is about structure.So a markdown table that stops being a table is invisible to the gate whose whole purpose is
keeping these pages readable.
Measured, on an open PR
#1022 splices a note and a second table into the middle of the
set_optionsargument table indocs/configuration.md:Six of the nine
set_optionsarguments render as a headerless table.docs_style.shpasses,14 checks. Found by @linuxhikerpm in review; I had reviewed the same PR twice and checked
sentence length, a guard's scoping claim and a three-row mutation table without once asking
whether the markdown still renders.
It is the second occurrence today. The first was the
configuration.mdGUC table having noblank lines, which made an
awk RS=''guard readstripe_row_limit's row andchunk_group_row_limit's row as one record and pass onmain. Both are the same underlyingfact: a markdown table is a contiguous block of
|lines and a blank line is structural, whichis easy to forget while editing prose.
The check
About fifteen lines, and it found the live case on the first run:
Belongs in
plain_language_check.py, which already walks every page and already reports per-filecounts that
docs_style.shasserts, so it costs one counter rather than a new traversal.What it must meet first
A static guard in this tree needs its false-positive budget measured over the whole tree before
it lands -- run it over
docs/,README.mdand anything else in scope and show the count is 0on
main, or name each exception. A guard that arrives red on existing content is a guardsomebody disables.
Two shapes to check against before claiming 0: a single-row table used as a callout (legitimately
has a separator), and an indented
|inside a fenced code block, which is not a table at all andwould need the fence tracked.