BUG #15224: Poor documentation

The following bug has been logged on the website:

Bug reference:      15224
Logged by:          Rob Ransbottom
Email address:      rirans@comcast.net
PostgreSQL version: 10.4
Operating system:   Linux
Description:

Hi,

Thanks again for the software.

This applies to 9s, 10s and 11.   Possibly back to 7.3 though the doc has
changed and I am presuming the behavior was the same.
 
In  "22.3. Template Databases" it says:

is not (yet) intended as a general-purpose “COPY DATABASE” facility. The
principal limitation is that no other sessions can be connected to the
source database while it is being copied. 

"Principal" should be "only";  if not please expand upon those limitations.


Likely, a general purpose copy-database command will not be called CREATE
DATABASE; so implying this may become the "COPY DATABASE" is strictly
implementation talk for devs.

Here is fodder.  A rewrite of the quoted paragraph.   I might be missing
some subtlety which makes the cluster-wide reference worthy. 

Copying any database by using it as a template is supported.  This is not a
general-purpose "COPY DATABASE" tool because CREATE DATABASE requires
exclusive access to the template for the duration of the copy.  CREATE
DATABASE will fail if another connection exists when it starts.  New
connections to the source database will fail during the copy.

Rob