assorted documentation errors

Started by Rich Morinover 24 years ago6 messagesbugs

Jump to latest

Rich Morin

rdm@cfcl.com

over 24 years ago

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

Bruce Momjian

bruce@momjian.us

over 24 years ago

In reply to: Rich Morin (#1)

Re: assorted documentation errors

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

Bruce Momjian

bruce@momjian.us

over 24 years ago

In reply to: Bruce Momjian (#2)

Re: assorted documentation errors

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:

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

<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

Bruce Momjian

bruce@momjian.us

over 24 years ago

In reply to: Bruce Momjian (#3)

Re: assorted documentation errors

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

Import Notes

Reply to msg id not found: Pine.LNX.4.30.0108131838390.677-100000@peter.localdomain | Resolved by subject fallback

Peter Eisentraut

peter_e@gmx.net

over 24 years ago

In reply to: Bruce Momjian (#2)

Re: assorted documentation errors

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

Peter Eisentraut

peter_e@gmx.net

over 24 years ago

In reply to: Rich Morin (#1)

Re: assorted documentation errors

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

assorted documentation errors

Attachments: