DOCS QUESTION - space added within synopsis replaceable tag.

From: Peter Smith <smithpb2250(at)gmail(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: DOCS QUESTION - space added within synopsis replaceable tag.
Date: 2026-02-18 23:33:58
Message-ID: CAHut+Pu8JahGm76CMdpzH350pHJedA4R2b8JmOim3+m3yxft3Q@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi,

Looking at the Server Applications page synopses:

AFAICT whenever there is a preceeding <group> in the SGML, then the
next <replaceable> part renders jammed against that group.

It seems like historically some people did not like that result, so
have added a space in the <replaceable> to make the rendered synopsis
look (they judged) a bit more readable.

But this "fix" is quite ad-hoc: Only a couple of pages do it, other
pages do not.

e.g
initdb - space added in <replaceable> datadir</replaceable>
pg_rewind - space in <replaceable> datadir</replaceable>

versus

pg_checksums - no space before datadir
pg_controldata - no space before datadir
pg_createsubscriber - no space before any of dbname,datadir,connstr
pg_resetwal - no space before datadir

~~~

The only examples I can find that do this are in initdb.sgml and pg_rewind.sgml.

What do others think about it, and what is the next step?

0. Do nothing. It's harmless. Leave as-is.
1. Remove the space hacks, and just let the SGML rendering do whatever it wants.
2. Add more space hacks to other places so they render the same.

TBH, I prefer option 0.

Thanks.

======
[1] initdb - https://www.postgresql.org/docs/devel/app-initdb.html
[2] pg_checksums - https://www.postgresql.org/docs/devel/app-pgchecksums.html

Kind Regards.
Peter Smith.
Fujitsu Australia.

Browse pgsql-hackers by date

  From Date Subject
Next Message Andreas Karlsson 2026-02-18 23:34:58 Re: Headerscheck support for meson
Previous Message Jacob Champion 2026-02-18 23:27:14 Re: libpq: Bump protocol version to version 3.2 at least until the first/second beta