Doc: clarify introduction to database roles.

Word-smith section 22.1 ("Database Roles") a little bit in hopes
of removing confusion about how the bootstrap superuser's name
is chosen.

While here, I couldn't help noticing that the claim that the bootstrap
superuser is the only initially-existing role has been a lie since
we started to invent predefined roles.  We don't want too much detail
in this very introductory text, but it seems worth changing it to say
that it's the only initially-existing login-capable role.

Per documentation comment from Maja Zaloznik.

Discussion: https://postgr.es/m/167931662853.3349090.18217722739345182859@wrigleys.postgresql.org

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 93978e550e932408b66e18d412455bf6316627c7..d99dcb2017ffbff144cca0afbe1e6b0d4af6e38f 100644 (file)
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -88,9 +88,13 @@ dropuser <replaceable>name</replaceable>
 
   <para>
    To determine the set of existing roles, examine the <structname>pg_roles</structname>
-   system catalog, for example
+   system catalog, for example:
 <synopsis>
 SELECT rolname FROM pg_roles;
+</synopsis>
+   or to see just those capable of logging in:
+<synopsis>
+SELECT rolname FROM pg_roles WHERE rolcanlogin;
 </synopsis>
    The <xref linkend="app-psql"/> program's <literal>\du</literal> meta-command
    is also useful for listing the existing roles.
@@ -98,11 +102,12 @@ SELECT rolname FROM pg_roles;
 
   <para>
    In order to bootstrap the database system, a freshly initialized
-   system always contains one predefined role. This role is always
-   a <quote>superuser</quote>, and by default (unless altered when running
-   <command>initdb</command>) it will have the same name as the
-   operating system user that initialized the database
-   cluster. Customarily, this role will be named
+   system always contains one predefined login-capable role. This role
+   is always a <quote>superuser</quote>, and by default it will have
+   the same name as the operating system user that initialized the
+   database cluster, unless another name is specified while
+   running <command>initdb</command>.
+   It is common, but not required, to arrange for this role to be named
    <literal>postgres</literal>. In order to create more roles you
    first have to connect as this initial role.
   </para>