Обсуждение: assorted documentation errors
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
> 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>
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
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
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
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