Re: Add docs stub for recovery.conf

Greetings,

* Craig Ringer (craig(dot)ringer(at)enterprisedb(dot)com) wrote:
> On Sat, Nov 14, 2020 at 1:42 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > Clearly we have need for documenting these renamings somewhere. We were
> > going to go with a simple URL redirect and a "tip" for
> > default/pre-installed roles, but I like the idea of doing something more
> > wholistic that covers all of our recent renaming cases. Let's get
> > buy-in from that, and then someone can work on a patch.
>
> Is there anything further I can do to address this specific documentation
> issue?
>
> Can I get you to consider the user experience arising from the current docs
> - try using the docs to find out how to set up a standby?

For my 2c, at least, I'm in favor of making some kind of change here to
make things better for users. I tried to figure out a way using the
features we have easily available in pgweb, but I tend to agree with
Craig that those just aren't enough for the more recent set of changes
that we've made.

> I'm not prepared to expand the scope of this to do a major review of all
> past renamings and changes without a very clear agreement about how that
> should be implemented in the docs and how that will address all the
> relevant UX issues - vanishing terms from indexes and docs without
> x-refs/see-alsos, vanishing URLs endpoints for public links, vanishing
> next-version links in www docs.

The past renamings haven't really been as much of an issue since the
redirects and such, imv anyway, have been sufficient to deal with them.

> Can we please just address this docs issue? If you don't like my solution
> can you please supply a patch that you feel addresses the problem? Or
> clearly state that you don't think there is a problem, and do so in a way
> that actually addresses the specific points I have raised about what's
> wrong with the status quo?

While I understand not wanting to go back through and check for all
renamings, it seems like we should probably at least list out the ones
we know about pretty easily, if we're going to create a new section
specifically for those cases..? Or do we think the current approach
works well enough for those other cases but just not for this one?

Think I listed this elsewhere but not seeing it on the thread so I'll
include it here anyway. These are the current doc aliases:

catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
pgxlogdump.html <-> pgwaldump.html
app-pgresetxlog.html <-> app-pgresetwal.html
legalnotice.html <-> LEGALNOTICE.html
app-pgreceivexlog.html <-> app-pgreceivewal.html

As relates to the specific patch, I don't think the comments line up
quite right (we can prevent a 404 from happening through other means,
but the point of the patch is really to give a deeper explanation of
what happened). Also- wrt pg_basebackup, isn't that expected to support
older versions, and so we should document the behavior against older
versions..?

Thanks,

Stephen