Re: Usage instructions for pg_hba.conf file

On Tue, Aug  2, 2022 at 08:08:07PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html
> Description:
> 
> On the pg_hba.conf page,
> https://www.postgresql.org/docs/current/auth-pg-hba-conf.html, the bulk of
> the page involves the format of the file and what the fields mean. There are
> a couple of sentences of usage information (how to reload the file after
> changes) in the middle of the reference info. It's possible to overlook the
> how-to info on the long page if you don't need the details about the file
> contents, just that one tip about reloading.
> 
> > The pg_hba.conf file is read on start-up and when the main server process
> receives a SIGHUP signal. If you edit the file on an active system, you will
> need to signal the postmaster (using pg_ctl reload, calling the SQL function
> pg_reload_conf(), or using kill -HUP) to make it re-read the file.
> 
> I suggest moving the usage info to one end of the page or the other, and
> adding a subheading to clarify that the page covers more than the syntax of
> the file contents.  Possibilities:
> 
> 21.1. The pg_hba.conf File
>   Client authentication is controlled... (same first paragraph as before)
> 
> 21.1.1 Loading or Reloading the Configuration
>   The pg_hba.conf file is read on start-up...
>   Note: The preceding statement...
>   The system view pg_hba_file_rules can be helpful...
> 
> 21.1.2 Contents of pg_hba.conf
>   The general format of the pg_hba.conf file is a set of records...
>   <all the other info about the format and contents of the file>
> 
> Example 21.1. Example pg_hba.conf Entries
> 
> or
> 
> 21.1. The pg_hba.conf File
>   Client authentication is controlled...
>   The general format of the pg_hba.conf file is a set of records...
>   <all the other info about the format and contents of the file>
> 
> Example 21.1. Example pg_hba.conf Entries
> 
> 21.1.1 Loading or Reloading the Configuration
>   The pg_hba.conf file is read on start-up...
>   Note: The preceding statement...
>   The system view pg_hba_file_rules can be helpful...

This is a good point.  I moved the reload sections for pg_hba.conf and
pg_ident.conf up near the top of their sections in the attached patch.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.