Some cleanups in CREATE/ALTER/DROP USER ref pages.

36addaff · Peter Eisentraut · af1b72d8 · 36addaff · 36addaff · 36addaff
Commit 36addaff authored Feb 27, 2002 by Peter Eisentraut
3 changed files
--- a/doc/src/sgml/ref/alter_user.sgml
+++ b/doc/src/sgml/ref/alter_user.sgml
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.18 2001/12/08 03:24:33 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.19 2002/02/27 21:14:53 petere Exp $
 PostgreSQL documentation
 -->
 <refentry id="SQL-ALTERUSER">
 <refmeta>
-  <refentrytitle id="sql-alteruser-title">
+  <refentrytitle id="sql-alteruser-title">ALTER USER</refentrytitle>
-   ALTER USER
-  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
-  <refname>
+  <refname>ALTER USER</refname>
-   ALTER USER
+  <refpurpose>change a database user account</refpurpose>
-  </refname>
-  <refpurpose>
-   change a database user account
-  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
-  <refsynopsisdivinfo>
+<synopsis>
-   <date>2001-07-10</date>
-  </refsynopsisdivinfo>
-  <synopsis>
 ALTER USER <replaceable class="PARAMETER">username</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
 where <replaceable class="PARAMETER">option</replaceable> can be:
@@ -31,15 +24,26 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
    | CREATEDB | NOCREATEDB
    | CREATEUSER | NOCREATEUSER 
    | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
-  </synopsis>
+</synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+  <title>Description</title>
+  <para>
+   <command>ALTER USER</command> is used to change the attributes of a
+   <productname>PostgreSQL</productname> user account.  Attributes not
+   mentioned in the command retain their previous settings.
+  </para>
+  <para>
+   Only a database superuser can change privileges and password
+   expiration with this command. Ordinary users can only change their
+   own password.
+  </para>
-  <refsect2 id="R2-SQL-ALTERUSER-1">
+  <refsect2>
-   <refsect2info>
+   <title>Parameters</title>
-    <date>1998-09-08</date>
-   </refsect2info>
-   <title>
-    Inputs
-   </title>
   <para>
    <variablelist>
@@ -47,7 +51,7 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
      <term><replaceable class="PARAMETER">username</replaceable></term>
      <listitem>
       <para>
-	The name of the user whose details are to be altered.
+	The name of the user whose attributes are to be altered.
       </para>
      </listitem>
     </varlistentry>
@@ -62,12 +66,12 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
     </varlistentry>
     <varlistentry>
-      <term>ENCRYPTED</term>
+      <term><literal>ENCRYPTED</literal></term>
-      <term>UNENCRYPTED</term>
+      <term><literal>UNENCRYPTED</literal></term>
      <listitem>
       <para>
-	These keywords control whether the
+	These key words control whether the password is stored
-	password is stored encrypted in <literal>pg_shadow</>.  (See
+	encrypted in <literal>pg_shadow</>.  (See
 	<xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
 	for more information about this choice.)
       </para>
@@ -75,21 +79,22 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
     </varlistentry>
     <varlistentry>
-      <term>CREATEDB</term>
+      <term><literal>CREATEDB</literal></term>
-      <term>NOCREATEDB</term>
+      <term><literal>NOCREATEDB</literal></term>
      <listitem>
       <para>
-	These clauses define a user's ability to create databases.
+	These clauses define a user's ability to create databases.  If
-	If CREATEDB is specified, the user being defined will
+	<literal>CREATEDB</literal> is specified, the user being
-	be allowed to create his own databases. Using NOCREATEDB
+	defined will be allowed to create his own databases. Using
-	will deny a user the ability to create databases.
+	<literal>NOCREATEDB</literal> will deny a user the ability to
+	create databases.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-      <term>CREATEUSER</term>
+      <term><literal>CREATEUSER</literal></term>
-      <term>NOCREATEUSER</term>
+      <term><literal>NOCREATEUSER</literal></term>
      <listitem>
       <para>
 	These clauses determine whether a user will be permitted to
@@ -111,14 +116,11 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
    </variablelist>
   </para>
  </refsect2>
+ </refsect1>
+ <refsect1>
+  <title>Diagnostics</title>
-  <refsect2 id="R2-SQL-ALTERUSER-2">
-   <refsect2info>
-    <date>1998-09-08</date>
-   </refsect2info>
-   <title>
-    Outputs
-   </title>
  <para>
   <variablelist>
    <varlistentry>
@@ -131,9 +133,7 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
    </varlistentry>
    <varlistentry>
-      <term><computeroutput>
+     <term><computeroutput>ERROR:  ALTER USER: user "username" does not exist</computeroutput></term>
-ERROR:  ALTER USER: user "username" does not exist
-       </computeroutput></term>
     <listitem>
      <para>
       Error message returned if the specified user is not known to
@@ -143,90 +143,78 @@ ERROR:  ALTER USER: user "username" does not exist
    </varlistentry>
   </variablelist>
  </para>
-  </refsect2>
+ </refsect1>
- </refsynopsisdiv>
+ <refsect1>
+  <title>Notes</title>
- <refsect1 id="R1-SQL-ALTERUSER-1">
-  <refsect1info>
-   <date>1998-09-08</date>
-  </refsect1info>
-  <title>
-   Description
-  </title>
-  <para>
-   <command>ALTER USER</command> is used to change the attributes of a user's
-   <productname>PostgreSQL</productname> account.  Attributes not mentioned
-   in the command retain their previous settings.
-  </para>
  <para>
-   Only a database superuser
+   Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
-   can change privileges and password expiration with this command. Ordinary
+   to add new users, and <xref linkend="SQL-DROPUSER"
-   users can only change their own password.
+   endterm="SQL-DROPUSER-title"> to remoe a user.
  </para>
  <para>
   <command>ALTER USER</command> cannot change a user's group memberships.
   Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
   to do that.
  </para>
-  <para>
-   Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
-   to create a new user and <xref linkend="SQL-DROPUSER"
-   endterm="SQL-DROPUSER-title"> to remove a user.
-  </para>
 </refsect1>
- <refsect1 id="R1-SQL-ALTERUSER-2">
+ <refsect1>
-  <title>
+  <title>Examples</title>
-   Usage
-  </title>
  <para>
   Change a user password:
 <programlisting>
 ALTER USER davide WITH PASSWORD 'hu8jmn3';
 </programlisting>
+  </para>
+  <para>
   Change a user's valid until date:
 <programlisting>
 ALTER USER manuel VALID UNTIL 'Jan 31 2030';
 </programlisting>
+  </para>
+  <para>
   Change a user's valid until date, specifying that his
   authorization should expire at midday on 4th May 1998 using
   the time zone which is one hour ahead of UTC:
 <programlisting>
 ALTER USER chris VALID UNTIL 'May 4 12:00:00 1998 +1';
 </programlisting>
+  </para>
+  <para>
   Give a user the ability to create other users and new databases:
 <programlisting>
 ALTER USER miriam CREATEUSER CREATEDB;
 </programlisting>
  </para>
 </refsect1>
- <refsect1 id="R1-SQL-ALTERUSER-3">
+ <refsect1>
-  <title>
+  <title>Compatibility</title>
-   Compatibility
-  </title>
-  <refsect2 id="R2-SQL-ALTERUSER-4">
-   <refsect2info>
-    <date>1998-09-08</date>
-   </refsect2info>
-   <title>
-    SQL92
-   </title>
  <para>
-    There is no <command>ALTER USER</command> statement in
+   The <command>ALTER USER</command> statement is a
-    <acronym>SQL92</acronym>.
+   <productname>PostgreSQL</productname> extension.  The SQL standard
-    The standard leaves
+   leaves the definition of users to the implementation.
-    the definition of users to the implementation.
  </para>
-  </refsect2>
+ </refsect1>
+ <refsect1>
+  <title>See Also</title>
+  <simplelist type="inline">
+   <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
+   <member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member>
+  </simplelist>
 </refsect1>
 </refentry>

--- a/doc/src/sgml/ref/create_user.sgml
+++ b/doc/src/sgml/ref/create_user.sgml
--- a/doc/src/sgml/ref/drop_user.sgml
+++ b/doc/src/sgml/ref/drop_user.sgml
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.14 2002/01/20 22:19:56 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.15 2002/02/27 21:14:54 petere Exp $
 PostgreSQL documentation
 -->
 <refentry id="SQL-DROPUSER">
 <refmeta>
-  <refentrytitle id="SQL-DROPUSER-TITLE">
+  <refentrytitle id="SQL-DROPUSER-TITLE">DROP USER</refentrytitle>
-   DROP USER
-  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
-  <refname>
+  <refname>DROP USER</refname>
-   DROP USER
+  <refpurpose>remove a database user account</refpurpose>
-  </refname>
-  <refpurpose>
-   remove a database user account
-  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
-  <refsynopsisdivinfo>
+<synopsis>
-   <date>1999-07-20</date>
-  </refsynopsisdivinfo>
-  <synopsis>
 DROP USER <replaceable class="PARAMETER">name</replaceable>
-  </synopsis>
+</synopsis>
+ </refsynopsisdiv>
-  <refsect2 id="R2-SQL-DROPUSER-1">
-   <refsect2info>
+ <refsect1>
-    <date>1998-09-22</date>
+  <title>Description</title>
-   </refsect2info>
-   <title>
-    Inputs
-   </title>
  <para>
+   <command>DROP USER</command> removes the specified user from the database.
+   It does not remove tables, views, or other objects owned by the user. If the
+   user owns any database, an error is raised.
+  </para>
+  <refsect2>
+   <title>Parameters</title>
+   <para>
    <variablelist>
     <varlistentry>
      <term><replaceable class="PARAMETER">name</replaceable></term>
@@ -48,13 +45,11 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
   </para>
  </refsect2>
-  <refsect2 id="R2-SQL-DROPUSER-2">
+ </refsect1>
-   <refsect2info>
-    <date>1998-09-22</date>
+ <refsect1>
-   </refsect2info>
+  <title>Diagnostics</title>
-   <title>
-    Outputs
-   </title>
  <para>
   <variablelist>
    <varlistentry>
@@ -67,9 +62,7 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
    </varlistentry>
    <varlistentry>
-      <term><computeroutput>
+     <term><computeroutput>ERROR:  DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
-ERROR:  DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist
-       </computeroutput></term>
     <listitem>
      <para>
       This message occurs if the user name is not found.
@@ -78,9 +71,7 @@ ERROR:  DROP USER: user "<replaceable class="parameter">name</replaceable>" does
    </varlistentry>
    <varlistentry>
-      <term><computeroutput>
+     <term><computeroutput>DROP USER: user "<replaceable class="parameter">name</replaceable>" owns database "<replaceable class="parameter">name</replaceable>", cannot be removed</computeroutput></term>
-DROP USER: user "<replaceable class="parameter">name</replaceable>" owns database "<replaceable class="parameter">name</replaceable>", cannot be removed
-       </computeroutput></term>
     <listitem>
      <para>
       You must drop the database first or change its ownership.
@@ -90,37 +81,25 @@ DROP USER: user "<replaceable class="parameter">name</replaceable>" owns databas
   </variablelist>
  </para>
-  </refsect2>
+ </refsect1>
- </refsynopsisdiv>
+ <refsect1>
+  <title>Notes</title>
- <refsect1 id="R1-SQL-DROPUSER-1">
-  <refsect1info>
-   <date>1998-09-22</date>
-  </refsect1info>
-  <title>
-   Description
-  </title>
-  <para>
-   <command>DROP USER</command> removes the specified user from the database.
-   It does not remove tables, views, or other objects owned by the user. If the
-   user owns any database you get an error.
-  </para>
  <para>
   Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
   to add new users, and <xref linkend="SQL-ALTERUSER"
-   endterm="SQL-ALTERUSER-title"> to change a user's properties.
+   endterm="SQL-ALTERUSER-title"> to change a user's attributes.
-   <productname>PostgreSQL</productname>
+   <productname>PostgreSQL</productname> includes a program <xref
-   comes with a script <xref linkend="APP-DROPUSER"
+   linkend="APP-DROPUSER" endterm="APP-DROPUSER-title"> that has the
-   endterm="APP-DROPUSER-title">
+   same functionality as this command (in fact, it calls this command)
-   which has the same functionality as this command (in fact, it calls this command)
   but can be run from the command shell.
  </para>
 </refsect1>
- <refsect1 id="R1-SQL-DROPUSER-2">
+ <refsect1>
-  <title>
+  <title>Examples</title>
-   Usage
-  </title>
  <para>
   To drop a user account:
 <programlisting>
@@ -129,23 +108,26 @@ DROP USER jonathan;
  </para>
 </refsect1>
- <refsect1 id="R1-SQL-DROPUSER-3">
+ <refsect1>
-  <title>
+  <title>Compatibility</title>
-   Compatibility
-  </title>
-  <refsect2 id="R2-SQL-DROPUSER-4">
-   <refsect2info>
-    <date>1998-09-22</date>
-   </refsect2info>
-   <title>
-    SQL92
-   </title>
  <para>
-    There is no <command>DROP USER</command> in <acronym>SQL92</acronym>.
+   The <command>DROP USER</command> statement is a
+   <productname>PostgreSQL</productname> extension.  The SQL standard
+   leaves the definition of users to the implementation.
  </para>
-  </refsect2>
 </refsect1>
+ <refsect1>
+  <title>See Also</title>
+  <simplelist type="inline">
+   <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
+   <member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
+   <member><xref linkend="app-dropuser"></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file