Horton

Thread

Commits

  1. doc: make "datadir" argument specification more specific

  1. DOCS - System Applications 'datadir' parameter

    Peter Smith <smithpb2250@gmail.com> — 2026-02-18T07:27:50Z

    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.

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

  2. Re: DOCS - System Applications 'datadir' parameter

    Andreas Karlsson <andreas@proxel.se> — 2026-02-18T21:29:14Z

    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

  3. Re: DOCS - System Applications 'datadir' parameter

    Peter Smith <smithpb2250@gmail.com> — 2026-02-18T23:39:42Z

    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

  4. Re: DOCS - System Applications 'datadir' parameter

    Peter Smith <smithpb2250@gmail.com> — 2026-03-20T03:43:56Z

    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.

  5. Re: DOCS - System Applications 'datadir' parameter

    Bruce Momjian <bruce@momjian.us> — 2026-03-23T16:14:19Z

    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.

  6. Re: DOCS - System Applications 'datadir' parameter

    Peter Smith <smithpb2250@gmail.com> — 2026-03-23T22:38:28Z

    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