Re: Add docs stub for recovery.conf

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...