| 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 |
| 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 |