Docs: make source file path references consistent
Hackorum builds and tests every patch posted to the lists, not only commitfest submissions. This is Hackorum's own CI rather than the PostgreSQL project's, and it is still under testing - please report anything that looks wrong.
You can run a PostgreSQL built from this patch straight from Docker, with no checkout and no build:
docker run --rm -p 5432:5432 ghcr.io/hackorum-dev/postgres-patch:t52962psql -h localhost -U postgresBuilt from patchset v1 (message #1), September 20, 2026 at 02:06 AM.
Every patchset is also pushed to a branch of our PostgreSQL fork, so you can check out the same tree CI built. Without a PostgreSQL checkout:
git clone --branch t52962_1 https://github.com/hackorum-dev/postgres.gitIn a checkout you already have, add the fork once:
git remote add hackorum https://github.com/hackorum-dev/postgres.gitthen, for this patchset and every later one:
git fetch hackorum t52962_1 && git checkout t52962_1Patchset v1 (message #1) is on t52962_1
Hi Hackers,
This patch is derived from [1]/messages/by-id/CAHGQGwEyYUzz0LjBV_fMcdwU3wgmu0NCoT+JJiozPa8DG6eeog@mail.gmail.com. While reviewing that thread, I noticed that
when the documentation refers to .h and .cfiles in the PostgreSQL source
tree, it uses a mix of full source-tree paths and short relative paths.
This inconsistency can be confusing for future documentation authors, who
may be unsure which form to use.
This patch aims to make the usage consistent. When the documentation
explicitly refers to a file’s location in the source tree (for example, “in
the file …”, "see the file ..."), it uses the full path. When the
documentation refers to a header in the context of inclusion, it uses the
short relative path, matching the form used in #include <header> directives.
[1]: /messages/by-id/CAHGQGwEyYUzz0LjBV_fMcdwU3wgmu0NCoT+JJiozPa8DG6eeog@mail.gmail.com
/messages/by-id/CAHGQGwEyYUzz0LjBV_fMcdwU3wgmu0NCoT+JJiozPa8DG6eeog@mail.gmail.com
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Dec 25, 2025, at 17:07, Chao Li <li.evan.chao@gmail.com> wrote:
Hi Hackers,
This patch is derived from [1]. While reviewing that thread, I noticed that when the documentation refers to .h and .cfiles in the PostgreSQL source tree, it uses a mix of full source-tree paths and short relative paths. This inconsistency can be confusing for future documentation authors, who may be unsure which form to use.
This patch aims to make the usage consistent. When the documentation explicitly refers to a file’s location in the source tree (for example, “in the file …”, "see the file ..."), it uses the full path. When the documentation refers to a header in the context of inclusion, it uses the short relative path, matching the form used in #include <header> directives.
[1] /messages/by-id/CAHGQGwEyYUzz0LjBV_fMcdwU3wgmu0NCoT+JJiozPa8DG6eeog@mail.gmail.com
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/<v1-0001-Docs-make-documentation-source-file-references-co.patch>
Added to CF for tracking: https://commitfest.postgresql.org/patch/6380/
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Chao Li <li.evan.chao@gmail.com> writes:
On Dec 25, 2025, at 17:07, Chao Li <li.evan.chao@gmail.com> wrote:
This patch is derived from [1]. While reviewing that thread, I noticed that when the documentation refers to .h and .cfiles in the PostgreSQL source tree, it uses a mix of full source-tree paths and short relative paths. This inconsistency can be confusing for future documentation authors, who may be unsure which form to use.
Added to CF for tracking: https://commitfest.postgresql.org/patch/6380/
Is this actually worth spending time on?
Sure, in an ideal world every last line of our source code and
documentation would be totally consistent and read like it had
flowed from a single pen. But the effort to get there seems
out of proportion to the value, and the effort to keep it there
over time would be even more so.
I'd be much happier to see us spending time on, say, improving
the many barely-intelligible comments in the code. That takes
serious thought and work though (ChatGPT is unlikely to help).
regards, tom lane
On Jan 8, 2026, at 14:44, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Chao Li <li.evan.chao@gmail.com> writes:
On Dec 25, 2025, at 17:07, Chao Li <li.evan.chao@gmail.com> wrote:
This patch is derived from [1]. While reviewing that thread, I noticed that when the documentation refers to .h and .cfiles in the PostgreSQL source tree, it uses a mix of full source-tree paths and short relative paths. This inconsistency can be confusing for future documentation authors, who may be unsure which form to use.
Added to CF for tracking: https://commitfest.postgresql.org/patch/6380/
Is this actually worth spending time on?
Sure, in an ideal world every last line of our source code and
documentation would be totally consistent and read like it had
flowed from a single pen. But the effort to get there seems
out of proportion to the value, and the effort to keep it there
over time would be even more so.
That’s a fair point. I agree it’s unrealistic to flow everything from a single pen. I noticed some inconsistencies in both the source tree and the documentation and was trying to make a small improvement. In my understanding, PG is built by many contributors around the world, with each person adding a small brick over time.
I'd be much happier to see us spending time on, say, improving
the many barely-intelligible comments in the code. That takes
serious thought and work though (ChatGPT is unlikely to help).
I will withdraw this patch and put my time elsewhere. Thanks for the perspective.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Hi,
On 2026-01-08 15:12:08 +0800, Chao Li wrote:
That’s a fair point. I agree it’s unrealistic to flow everything from a
single pen. I noticed some inconsistencies in both the source tree and the
documentation and was trying to make a small improvement. In my
understanding, PG is built by many contributors around the world, with each
person adding a small brick over time.
People have to read emails, read patches. That costs time & energy, spread
across a nontrivial number of people. That has to be balanced against the
plausible benefit of each patch.
Greetings,
Andres Freund