Re: Docs: inaccurate description about config settings

On Sep 1, 2020, at 8:20 PM, Ian Lawrence Barwick <barwick@gmail.com> wrote:

2020年9月1日(火) 19:37 Li Japin <japinli@hotmail.com>:

Hi, hackers

When I setup a stream replication I found that the documentation says that promote_trigger_file
parameter can only be set in the postgresql.conf file or on the server command line, however, it
can also be put into postgresql.auto.conf. If I use include to import a new config, it works too.

There are many parameters use this description:
$ grep 'This parameter can only be set in the' -rn doc/

(...)

I think this description is misleading. we should correct it, isn't it?

I must admit every time I see this wording, it strikes me as very specific
and potentially confusing given the alternative files the parameter could be
placed in.

I think it would be clearer for anyone not familiar with the configuration file
system to change occurrences of this wording to something like:

 This parameter can only be set in the <link
linkend="config-setting-configuration-file">configuration file</link>

which would link to:

 https://www.postgresql.org/docs/current/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE

which provides more information. Though on that page it seems like it would be
also sensible to bundle the section about include directives in the
configuration
file (19.1.5) together with the section about the configuration itself (19.1.2).