Increasing number of unnecessary blank lines in the documentation

From: Noboru Saito <noborusai(at)gmail(dot)com>
To: pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Increasing number of unnecessary blank lines in the documentation
Date: 2026-10-31 21:20:18
Message-ID: CAAM3qnJD-HAkzwQrFKTHidW4ZUtwfkjHNz9s4cmjwWRKDr_q5A@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi all,

I am a member of the Japanese translation team for the PostgreSQL
documentation. When reviewing translations, we check for blank lines that
may indicate a translation mistake. In practice, however, many of the blank
lines we find are already present in the English source.

I am referring here to blank lines within text flow, rather than blank lines
that separate block elements. For example:

<para>
First sentence.

Second sentence.
</para>

Assuming that an automatic formatter for the PostgreSQL documentation is not
currently practical, I wrote a script, check-blank-lines.py, to find these
blank lines. The script is not limited to <para> elements; it reports blank
lines that appear to be unnecessary.

On the current master branch, it reports 35 candidate blank lines in 436
files. That is about 0.1% of the 35,625 blank lines in those files. In my
view, the reported cases are unusual and worth reviewing. The count has also
increased over recent releases:

version Candidate blank lines
15.0 24
16.0 28
17.0 29
18.0 31
master 35

In the rendered HTML, these blank lines appear as whitespace, so removing
them would not change the rendered output. In many cases, though, splitting
the content into separate <para> elements would better express its
structure.

I would like to propose reviewing and correcting the cases reported by the
script, and adding an equivalent check to the documentation build tools.
The check need not use this script as-is; it could provide the same
functionality as part of the existing tooling.

Would this be a useful check to add?

I have attached check-blank-lines.py and its output, blank.log, for
reference.

Regards,
Noboru Saito

Attachment Content-Type Size
check-blank-lines.py text/x-python 4.8 KB
blank.log text/x-log 5.4 KB

Browse pgsql-hackers by date

  From Date Subject
Next Message Daniel Gustafsson 2026-10-31 21:25:25 Re: [PATCH] doc: Clarify pg_checksums --filenode mode restriction
Previous Message Alexander Lakhin 2026-10-31 21:00:00 Re: ALTER COLLATION misses errcode