Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1iktEU-0000zh-EO
	for pgsql-docs@arkaria.postgresql.org; Fri, 27 Dec 2019 17:17:02 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.89)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1iktET-0004cF-78
	for pgsql-docs@arkaria.postgresql.org; Fri, 27 Dec 2019 17:17:01 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <bruce@momjian.us>)
	id 1iktES-0004c4-SS
	for pgsql-docs@lists.postgresql.org; Fri, 27 Dec 2019 17:17:01 +0000
Received: from momjian.us ([72.94.173.45])
	by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1iktEO-0004K0-16
	for pgsql-docs@lists.postgresql.org; Fri, 27 Dec 2019 17:16:59 +0000
Received: from bruce by momjian.us with local (Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1iktEM-0006Z0-Tu; Fri, 27 Dec 2019 12:16:54 -0500
Date: Fri, 27 Dec 2019 12:16:54 -0500
From: Bruce Momjian <bruce@momjian.us>
To: rirans@comcast.net, pgsql-docs@lists.postgresql.org
Subject: Re: Documentation:  21.5. Default Roles
Message-ID: <20191227171654.GA2992@momjian.us>
References: <157742545062.1149.11052653770497832538@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="wac7ysb48OaltWcw"
Content-Disposition: inline
In-Reply-To: <157742545062.1149.11052653770497832538@wrigleys.postgresql.org>
User-Agent: Mutt/1.10.1 (2018-07-13)
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk


--wac7ysb48OaltWcw
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/default-roles.html
> Description:
> 
> The title is wrong.   The roles are not defaults; they are predefined and
> privileged.  The title suggests that a user should expect  to be assigned
> these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
> clarity over all  and removing any need to explain why postgres is not in
> this list of roles.
> 

Good points.  I have developed the attached documentation patch which
includes your ideas.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

--wac7ysb48OaltWcw
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="roles.diff"

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index dcb58115af..136778cb8a 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -277,7 +277,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
    existence of a session and its general properties such as its sessions user
    and database are visible to all users.  Superusers and members of the
    built-in role <literal>pg_read_all_stats</literal> (see also <xref
-   linkend="default-roles"/>) can see all the information about all sessions.
+   linkend="predefined-roles"/>) can see all the information about all sessions.
   </para>
 
   <table id="monitoring-stats-dynamic-views-table">
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 66f162703d..4432ee266b 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -483,30 +483,30 @@ DROP ROLE doomed_role;
   </para>
  </sect1>
 
- <sect1 id="default-roles">
-  <title>Default Roles</title>
+ <sect1 id="predefined-roles">
+  <title>Predefined Roles</title>
 
-  <indexterm zone="default-roles">
+  <indexterm zone="predefined-roles">
    <primary>role</primary>
   </indexterm>
 
   <para>
-   <productname>PostgreSQL</productname> provides a set of default roles
-   which provide access to certain, commonly needed, privileged capabilities
-   and information.  Administrators can GRANT these roles to users and/or
-   other roles in their environment, providing those users with access to
-   the specified capabilities and information.
+   <productname>PostgreSQL</productname> provides a set of predefined
+   roles which allow access to privileged capabilities and information.
+   Administrators can GRANT these roles to login and non-login roles,
+   providing those roles with access to the specified capabilities and
+   information.
   </para>
 
   <para>
-   The default roles are described in <xref linkend="default-roles-table"/>.
-   Note that the specific permissions for each of the default roles may
+   The predefined roles are described in <xref linkend="predefined-roles-table"/>.
+   Note that the specific permissions for each of the predefined roles may
    change in the future as additional capabilities are added.  Administrators
    should monitor the release notes for changes.
   </para>
 
-   <table tocentry="1" id="default-roles-table">
-    <title>Default Roles</title>
+   <table tocentry="1" id="predefined-roles-table">
+    <title>Predefined Roles</title>
     <tgroup cols="2">
      <thead>
       <row>
@@ -565,8 +565,8 @@ DROP ROLE doomed_role;
   <literal>pg_read_all_stats</literal> and <literal>pg_stat_scan_tables</literal>
   roles are intended to allow administrators to easily configure a role for the
   purpose of monitoring the database server. They grant a set of common privileges
-  allowing the role to read various useful configuration settings, statistics and
-  other system information normally restricted to superusers.
+  allowing the role to read configuration settings, statistics, and other
+  system information normally restricted to superusers.
   </para>
 
   <para>

--wac7ysb48OaltWcw--