Re: assorted documentation errors - Mailing list pgsql-bugs

> I have been looking over the PostgreSQL manual pages and have noted a
> number of formatting problems.  Unfortunately, as the DocBook source
> code does not seem to be in the distribution, I have no way of knowing
> where these problems originated.  In any case, here is a summary:
>
> createdb.1, createlang.1, createuser.1, dropdb.1, droplang.1, etc.
>
>    In many places where code and output examples are being given, the
>    font used is proportional.  If a monospace font were used, the code
>    would stand out better and the output would line up correctly.

Looks fine at:

    http://www.ca.postgresql.org/devel-corner/docs/postgres/app-createdb.html

Do you see the problem there?

> droplang.1, dropuser.1, etc.
>
>    There is insufficient consistentcy to the NAME entries.  For instance:
>
>      droplang - Remove a programming language from a Postgres database
>      dropuser - Drops (removes) a Postgres user
>
>    Why not settle on either "Removes/Drops" or "Remove/Drop"?


Agreed.

> pg_restore.1
>
>    In the NAME entry, there is a missing space in "created bypg_dump".

I don't see that problem here.

> alter_group.l
>
>    In the NAME entry, the comma should be a semi-colon: "group; remove".

Agreed.

> fetch.l
>
>    In the NAME entry, there should be a comma: "rows, using".

I don't agree on the use of the comma here.

Patch attached and applied.


--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026
Index: alter_group.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v
retrieving revision 1.3
diff -c -r1.3 alter_group.sgml
*** alter_group.sgml    2000/07/24 13:17:44    1.3
--- alter_group.sgml    2001/08/13 15:21:13
***************
*** 15,21 ****
     ALTER GROUP
    </refname>
    <refpurpose>
!    Add users to a group, remove users from a group
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
--- 15,21 ----
     ALTER GROUP
    </refname>
    <refpurpose>
!    Add users to a group;  remove users from a group
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
Index: alter_user.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v
retrieving revision 1.14
diff -c -r1.14 alter_user.sgml
*** alter_user.sgml    2001/07/10 22:09:27    1.14
--- alter_user.sgml    2001/08/13 15:21:13
***************
*** 27,33 ****

  where <replaceable class="PARAMETER">option</replaceable> can be:

!       PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
          | CREATEDB | NOCREATEDB
          | CREATEUSER | NOCREATEUSER
          | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
--- 27,33 ----

  where <replaceable class="PARAMETER">option</replaceable> can be:

!       [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
          | CREATEDB | NOCREATEDB
          | CREATEUSER | NOCREATEUSER
          | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
***************
*** 53,62 ****
       </varlistentry>

       <varlistentry>
!       <term><replaceable class="PARAMETER">password</replaceable></term>
        <listitem>
         <para>
      The new password to be used for this account.
         </para>
        </listitem>
       </varlistentry>
--- 53,65 ----
       </varlistentry>

       <varlistentry>
!       <term><replaceable class="PARAMETER">[ encrypted | unencrypted ] password</replaceable></term>
        <listitem>
         <para>
      The new password to be used for this account.
+     <literal>Encrypted</literal>/ <literal>unencrypted</literal>
+     controls whether the password is stored encrypted in the
+     database.
         </para>
        </listitem>
       </varlistentry>
Index: create_user.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v
retrieving revision 1.17
diff -c -r1.17 create_user.sgml
*** create_user.sgml    2001/07/10 22:09:27    1.17
--- create_user.sgml    2001/08/13 15:21:14
***************
*** 28,34 ****
  where <replaceable class="PARAMETER">option</replaceable> can be:

        SYSID <replaceable class="PARAMETER">uid</replaceable>
!         | PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
          | CREATEDB | NOCREATEDB
          | CREATEUSER | NOCREATEUSER
          | IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
--- 28,34 ----
  where <replaceable class="PARAMETER">option</replaceable> can be:

        SYSID <replaceable class="PARAMETER">uid</replaceable>
!         | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
          | CREATEDB | NOCREATEDB
          | CREATEUSER | NOCREATEUSER
          | IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
***************
*** 72,83 ****
       </varlistentry>

       <varlistentry>
!       <term><replaceable class="parameter">password</replaceable></term>
        <listitem>
         <para>
          Sets the user's password. If you do not plan to use password
          authentication you can omit this option, otherwise the user
          won't be able to connect to a password-authenticated server.
          See the chapter on client authentication in the
      <citetitle>Administrator's Guide</citetitle> for details on
          how to set up authentication mechanisms.
--- 72,90 ----
       </varlistentry>

       <varlistentry>
!       <term><replaceable class="parameter">[ encrypted | unencrypted ] password</replaceable></term>
        <listitem>
         <para>
          Sets the user's password. If you do not plan to use password
          authentication you can omit this option, otherwise the user
          won't be able to connect to a password-authenticated server.
+     </para>
+     <para>
+     <literal>ENCRYPTED/UNENCRYPTED</literal> controls whether the
+     password is stored encrypted in the database. Older clients may
+     have trouble communicating using encrypted password storage.
+     </para>
+     <para>
          See the chapter on client authentication in the
      <citetitle>Administrator's Guide</citetitle> for details on
          how to set up authentication mechanisms.
Index: drop_rule.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/drop_rule.sgml,v
retrieving revision 1.8
diff -c -r1.8 drop_rule.sgml
*** drop_rule.sgml    2000/10/22 23:32:38    1.8
--- drop_rule.sgml    2001/08/13 15:21:14
***************
*** 15,21 ****
     DROP RULE
    </refname>
    <refpurpose>
!    Removes existing rules from the database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
--- 15,21 ----
     DROP RULE
    </refname>
    <refpurpose>
!    Removes rules from the database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
Index: drop_sequence.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/drop_sequence.sgml,v
retrieving revision 1.8
diff -c -r1.8 drop_sequence.sgml
*** drop_sequence.sgml    2000/10/22 23:32:38    1.8
--- drop_sequence.sgml    2001/08/13 15:21:14
***************
*** 15,21 ****
     DROP SEQUENCE
    </refname>
    <refpurpose>
!    Removes existing sequences from a database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
--- 15,21 ----
     DROP SEQUENCE
    </refname>
    <refpurpose>
!    Removes sequences from a database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
Index: drop_table.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/drop_table.sgml,v
retrieving revision 1.9
diff -c -r1.9 drop_table.sgml
*** drop_table.sgml    2000/10/22 23:32:38    1.9
--- drop_table.sgml    2001/08/13 15:21:14
***************
*** 15,21 ****
     DROP TABLE
    </refname>
    <refpurpose>
!    Removes existing tables from a database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
--- 15,21 ----
     DROP TABLE
    </refname>
    <refpurpose>
!    Removes tables from a database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
Index: drop_view.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/drop_view.sgml,v
retrieving revision 1.8
diff -c -r1.8 drop_view.sgml
*** drop_view.sgml    2000/10/22 23:32:38    1.8
--- drop_view.sgml    2001/08/13 15:21:14
***************
*** 15,21 ****
     DROP VIEW
    </refname>
    <refpurpose>
!    Removes existing views from a database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
--- 15,21 ----
     DROP VIEW
    </refname>
    <refpurpose>
!    Removes views from the database
    </refpurpose>
   </refnamediv>
   <refsynopsisdiv>
Index: dropdb.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v
retrieving revision 1.9
diff -c -r1.9 dropdb.sgml
*** dropdb.sgml    2000/12/25 23:15:26    1.9
--- dropdb.sgml    2001/08/13 15:21:14
***************
*** 16,22 ****

   <refnamediv>
    <refname>dropdb</refname>
!   <refpurpose>Remove an existing <productname>Postgres</productname> database</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
--- 16,22 ----

   <refnamediv>
    <refname>dropdb</refname>
!   <refpurpose>Removes a <productname>Postgres</productname> database</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
Index: droplang.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v
retrieving revision 1.10
diff -c -r1.10 droplang.sgml
*** droplang.sgml    2001/05/09 22:08:18    1.10
--- droplang.sgml    2001/08/13 15:21:14
***************
*** 16,22 ****

   <refnamediv>
    <refname id="droplang">droplang</refname>
!   <refpurpose>Remove a programming language from a <productname>Postgres</productname> database</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
--- 16,22 ----

   <refnamediv>
    <refname id="droplang">droplang</refname>
!   <refpurpose>Removes a programming language from a <productname>Postgres</productname> database</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
Index: dropuser.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v
retrieving revision 1.11
diff -c -r1.11 dropuser.sgml
*** dropuser.sgml    2001/01/13 23:58:55    1.11
--- dropuser.sgml    2001/08/13 15:21:14
***************
*** 16,22 ****

   <refnamediv>
    <refname>dropuser</refname>
!   <refpurpose>Drops (removes) a <productname>Postgres</productname> user</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
--- 16,22 ----

   <refnamediv>
    <refname>dropuser</refname>
!   <refpurpose>Removes a <productname>Postgres</productname> user</refpurpose>
   </refnamediv>

   <refsynopsisdiv>