Re: Add docs stub for recovery.conf
| От | Craig Ringer |
|---|---|
| Тема | Re: Add docs stub for recovery.conf |
| Дата | |
| Msg-id | CAGRY4nzaNNGKujgAYPb7K=M+SxJA39EbarcnBPO0NWyZa2BETw@mail.gmail.com обсуждение исходный текст |
| Ответ на | Re: Add docs stub for recovery.conf (Stephen Frost <sfrost@snowman.net>) |
| Ответы |
Re: Add docs stub for recovery.conf
Re: Add docs stub for recovery.conf Re: Add docs stub for recovery.conf |
| Список | pgsql-hackers |
On Thu, Nov 12, 2020 at 11:25 PM Stephen Frost <sfrost@snowman.net> wrote:
> Now, the pgweb feature that Jonathan wrote recently might actually be
> exactly what we need to fix that, and to address the issue with
> recovery config documentation that Craig raises.
After chatting with Jonathan about this for a bit and testing it out in
our test environment, I've gone ahead and added an entry for
pgxlogdump.html to redirect to pgwaldump.html, and that seems to be
working well.
Thanks.
With that then- Craig, can you look at how the pgxlogdump -> pgwaldump
pages work and see if using that would address the concerns you've
raised here..?
Though we need to decide which page 'recovery-config' should go to in
newer versions.
Since we basically vanished all evidence of the old configuration, I don't think there is a suitable place.
I maintain that simply vanishing terms from the docs without any sort of explanation is a user-hostile action that we should fix and stop doing If we had something in the docs and we remove it, it's not unduly burdensome to have some index entries that point to the replacement/renamed terms, and a short appendix entry explaining what happened.
If that is for some reason unacceptable (and I don't see anyone giving any actual reason why) the closest I can come up with is probably redirecting to https://www.postgresql.org/docs/current/warm-standby.html#STANDBY-SERVER-OPERATION . But that needs to be fixed to actually explicitly state what makes a standby server into a standby server (per my patch), since right now it just kind of assumes you know about standby.signal .
But... fiddling with the website addresses none of my other concerns. In particular, it doesn't help a user understand that "standby_mode" is gone and to look for "standby.signal" instead. It doesn't provide any "see also" pointers for old terms to point to new terms in the index. Website redirects won't help users with local copies of the docs or manpages who are wondering what the heck happened to recovery.conf and standby_mode either.
So I still think this needs a docs patch. Redirects on the website are not sufficient. If you don't like how I spelled it, consider calling it "important incompatible changes" or something.
The release notes are IMO not sufficient for this because (a) they don't appear in the index; (b) you have to know something has been removed/changed before you know to look in the relnotes for it; (c) you have to find the relnotes for the correct release to find the info you want. An appendix covering important renamings, removals and other incompatible changes would address all those points *and* fix the web links, man page names, etc.
Can anyone tell me why the solution I proposed is not acceptable, and why we have to invent a different one instead? The website redirect is good and all, but doesn't really solve the problem, and I still don't know what's wrong with just fixing the docs...
В списке pgsql-hackers по дате отправления:
Следующее
От: "lchch1990@sina.cn"Дата:
Сообщение: Re: Add statistics to pg_stat_wal view for wal related parameter tuning