DOCS - System Applications 'datadir' parameter
Hi.
In most places, each of the Server Application documentation pages [1]https://www.postgresql.org/docs/devel/reference-server.html
refers to the directory where the database cluster lives as 'datadir'.
However, a few places called it 'directory' instead.
This patch changes the outliers also to 'datadir', making everything
more consistent.
e.g.
initdb: change in Synopsis and Options
pg_checksums: change in Options
pg_controldata: OK
pg_createsubscriber: change in Options
pg_ctl: OK
pg_resetwal: OK
pg_rewind: change in Synopsis and Options
pg_upgrade: Leave as-is (e.g. configdir may not be the same as datadir)
postgres: OK
PSA patch for details.
======
[1]: https://www.postgresql.org/docs/devel/reference-server.html
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v1-0001-DOCS-use-datadir-parameter-consistently.patchapplication/octet-stream; name=v1-0001-DOCS-use-datadir-parameter-consistently.patchDownload+12-13
On 2/18/26 8:27 AM, Peter Smith wrote:
In most places, each of the Server Application documentation pages [1]
refers to the directory where the database cluster lives as 'datadir'.
However, a few places called it 'directory' instead.This patch changes the outliers also to 'datadir', making everything
more consistent.
The change looks good!
But I wonder if there isn't an issue with our XML. If you look at
initdb.sgml you will se that there is a space before datadir, but if you
look at e.g. pg_checksums you will then notice a lack of space, both in
the source and the generated HTML, so the space in initdb.sgml was
clearly added for a reason. Do you understand our documentation pipeline
good enough to know why that space seems to be necessary?
https://www.postgresql.org/docs/current/app-pgchecksums.html
Andreas
On Thu, Feb 19, 2026 at 8:29 AM Andreas Karlsson <andreas@proxel.se> wrote:
On 2/18/26 8:27 AM, Peter Smith wrote:
In most places, each of the Server Application documentation pages [1]
refers to the directory where the database cluster lives as 'datadir'.
However, a few places called it 'directory' instead.This patch changes the outliers also to 'datadir', making everything
more consistent.The change looks good!
Thanks.
But I wonder if there isn't an issue with our XML. If you look at
initdb.sgml you will se that there is a space before datadir, but if you
look at e.g. pg_checksums you will then notice a lack of space, both in
the source and the generated HTML, so the space in initdb.sgml was
clearly added for a reason. Do you understand our documentation pipeline
good enough to know why that space seems to be necessary?
Yeah, I've also noticed this before. I have always assumed whoever
authored those pages did not like the rendering of the <replaceable>
jammed against the previous synopsis group.
FYI - I have posted a separate thread to get to the bottom of the
mystery, and to ask what, if anything, to do about it.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Ping. This thread has been idle for 1 month.
Is there anything else I can do to move it forwards?
======
Kind Regards,
Peter Smith.
Fujitsu Australia.
On Wed, Feb 18, 2026 at 06:27:50PM +1100, Peter Smith wrote:
Hi.
In most places, each of the Server Application documentation pages [1]
refers to the directory where the database cluster lives as 'datadir'.
However, a few places called it 'directory' instead.This patch changes the outliers also to 'datadir', making everything
more consistent.
Good catch. These clearly need to be datadirs and not just any
directory. Patch applied to master, thanks.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
On Tue, Mar 24, 2026 at 3:14 AM Bruce Momjian <bruce@momjian.us> wrote:
...
Good catch. These clearly need to be datadirs and not just any
directory. Patch applied to master, thanks.
Thanks for pushing!
======
Kind Regards,
Peter Smith.
Fujitsu Australia