Point out that --adduser actually makes the new user a superuser. This

was mentioned on the man page for the underlying CREATE USER command,
but it should be explained here too.

diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index 40d8a7afe661275ce62f04c2235a136456db3015..b54e4f8476ae085e99b2775b1d8ab91981051b3c 100644 (file)
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -1,5 +1,5 @@
 
 
@@ -79,7 +79,7 @@ PostgreSQL documentation
       -d, --createdb
       
        
-   Allows the new user to create databases.
+   The new user is allowed to create databases.
        
       
      
@@ -88,7 +88,7 @@ PostgreSQL documentation
       -D, --no-createdb
       
        
-   Forbids the new user to create databases.
+   The new user is not allowed to create databases.
        
       
      
@@ -97,7 +97,9 @@ PostgreSQL documentation
       -a, --adduser
       
        
-   Allows the new user to create other users.
+   The new user is allowed to create other users.
+   (Note: actually, this makes the new user a superuser.
+   The option is poorly named.)
        
       
      
@@ -106,7 +108,8 @@ PostgreSQL documentation
       -A, --no-adduser
       
        
-   Forbids the new user to create other users.
+   The new user is not allowed to create other users (i.e.,
+   the new user is a regular user not a superuser).
        
       
      
@@ -215,9 +218,17 @@ PostgreSQL documentation
   
    createuser creates a 
    new PostgreSQL user.  
-   Only users with usesuper set in
-   the pg_shadow table can create 
-   new PostgreSQL users.
+   Only superusers (users with usesuper set in
+   the pg_shadow table) can create 
+   new PostgreSQL users,
+   so createuser must be
+   invoked by someone who is a PostgreSQL
+   superuser.
+  
+
+  
+   Being a superuser also implies the ability to bypass access permission
+   checks within the database, so superuser-dom should not be granted lightly.
   
 
   
@@ -227,10 +238,11 @@ PostgreSQL documentation
    the PostgreSQL interactive terminal
    . Thus, there is nothing
    special about creating users via this or other methods. This means
-   that the psql must be found by the script and that
-   a database server is running at the targeted host. Also, any default
-   settings and environment variables available to psql
-   and the libpq front-end library do apply.
+   that the psql application must be found by the
+   script and that 
+   a database server must be running at the targeted host. Also, any default
+   settings and environment variables used by psql
+   and the libpq front-end library will apply.