From: | Craig Ringer <craig(dot)ringer(at)enterprisedb(dot)com> |
---|---|
To: | Bruce Momjian <bruce(at)momjian(dot)us> |
Cc: | Daniel Gustafsson <daniel(at)yesql(dot)se>, pgsql-hackers <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Add docs stub for recovery.conf |
Date: | 2020-11-12 02:25:23 |
Message-ID: | CAGRY4nxV1YgFzo+CYvt7cN5QTQ4UJ+KxoZvxHXdOb3RpcJWcWQ@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
On Thu, Nov 12, 2020 at 4:01 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> On Wed, Nov 11, 2020 at 08:59:40PM +0100, Daniel Gustafsson wrote:
> > > On 11 Nov 2020, at 20:44, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > > On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
> >
> > >> I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!)
> the docs for
> > >> it were removed completely as well. That's largely sensible, but is
> confusing
> > >> when users have upgraded and are trying to find out what happened, or
> how to
> > >> configure equivalent functionality.
> > >
> > > I don't see the logic in carrying doc stuff that we don't have anymore.
> >
> > Well, we do have that already in <tip>'s sprinkled across the docs where
> it
> > makes sense to help transitioning users, like this one in func.sgml:
> >
> > "Prior to PostgreSQL 12, it was possible to skip arbitrary text in
> the
> > input string using non-letter or non-digit characters..."
> >
> > It doesn't seem like a terrible idea to do a similar one for
> recovery.conf.
>
> I am fine with a tip. The patch looked like it was creating a new
> chapter for it.
>
>
It is. Or rather, an appendix right at the end to hold info on things we
removed or renamed and where to find them now.
You can't AFAICS make docbook create a toplevel linkable file for a <tip> .
A <tip> won't un-break
https://www.postgresql.org/docs/current/recovery-config.html or make help
people who visit https://www.postgresql.org/docs/11/recovery-config.html
figure out what's going on if they're using pg12 and there's no link to
version 12 in the nav section. A <tip> won't add index entries for renamed
settings, so someone looking up "standby_mode" can find out that we've
switched to a file called "standby.signal" instead.
Pretend you're a user who has upgraded from pg 11. You're looking at the Pg
12 docs. How long does it take you to find out how to make a server into a
standby now? It took me longer than I would've expected...
From | Date | Subject | |
---|---|---|---|
Next Message | Fujii Masao | 2020-11-12 02:28:32 | Re: enable pg_stat_statements to track rows processed by REFRESH MATERIALIZED VIEW |
Previous Message | Craig Ringer | 2020-11-12 02:21:02 | Re: Add docs stub for recovery.conf |