Skip to content

docs_style checks prose but not structure: a markdown table that stops being a table passes the gate #1026

Description

@OffgridwithJD

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions