Thread: assorted documentation errors

assorted documentation errors

From
Rich Morin
Date:
Your name               : Rich Morin
Your email address      : rdm@cfcl.com


System Configuration
---------------------
   Architecture (example: Intel Pentium)         : Intel Pentium II

   Operating System (example: Linux 2.0.26 ELF)  : FreeBSD 4.2

   PostgreSQL version (example: PostgreSQL-7.1.1): PostgreSQL-7.1.2

   Compiler used (example:  gcc 2.95.2)          : gcc 2.95.2


Please enter a FULL description of your problem:
------------------------------------------------

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.

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"?

pg_restore.1

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

alter_group.l

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

fetch.l

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


Please describe a way to repeat the problem.   Please try to provide a
concise reproducible example, if at all possible:
----------------------------------------------------------------------

Print the referenced manual pages, using "groff -man"

If you know how this problem might be fixed, list the solution below:
---------------------------------------------------------------------

Edit the original files and/or fix the conversion script.

--
email: rdm@cfcl.com; phone: +1 650-873-7841
http://www.cfcl.com/rdm - home page, resume, etc.
http://www.cfcl.com/Meta/md_fb.html - The FreeBSD Browser
http://www.ptf.com/tdc - Prime Time Freeware's Darwin Collection

Re: assorted documentation errors

From
Bruce Momjian
Date:
> 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>

Re: assorted documentation errors

From
Bruce Momjian
Date:
FYI, this section of the patch was not applied.  It is part of other
work I am doing.


> 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.

--
  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

Re: assorted documentation errors

From
Bruce Momjian
Date:
See later message.  These were not applied.  This is other work I am doing.

> Bruce Momjian writes:
>
> > 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> [, ...]
>
>
> --
> Peter Eisentraut   peter_e@gmx.net   http://funkturm.homeip.net/~peter
>
>

--
  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

Re: assorted documentation errors

From
Peter Eisentraut
Date:
Rich Morin writes:

> 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:

You seem to be using the wrong distribution then.

> 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.

Unfortunately, I'm kind of at a loss of how to do this sort of thing on
troff.  I'm glad I got reasonably looking man (terminal) output; print
output is not really planned.  (You can use the provided Postscript
version of the Reference Manual for that.)

You can follow the link at
http://www.ca.postgresql.org/~petere/docbook2man.html and see if you can
fix the code yourself.  Look in docbook2man-spec.pl at function
verbatim_start.

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

Probably need to hack the spec file even more.  There's already a lot of
that just to get the synopsis lines look okay.

> If you know how this problem might be fixed, list the solution below:
> ---------------------------------------------------------------------
>
> Edit the original files and/or fix the conversion script.

Generations of programmers have tried that and failed. :-(

--
Peter Eisentraut   peter_e@gmx.net   http://funkturm.homeip.net/~peter

Re: assorted documentation errors

From
Peter Eisentraut
Date:
Bruce Momjian writes:

> 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> [, ...]


--
Peter Eisentraut   peter_e@gmx.net   http://funkturm.homeip.net/~peter