Re: [HACKERS] Revised nonblocking patches + quasi docs

* admin <admin(at)wtbwts(dot)com> [000114 11:35] wrote:
> Alfred wrote:
> > * Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> [000109 08:18] wrote:
> > > Don Baccus <dhogaza(at)pacifier(dot)com> writes:
> > > > At 05:27 PM 1/8/00 -0500, Tom Lane wrote:
> > > >> I also object strongly to the lack of documentation.
> > >
> > > > ... I know there are some folks who aren't native-english speakers, so
> > > > perhaps you don't want to require that the implementor of such patches
> > > > provide the final documentation wording. But the information should
> > > > be there and spelled out in a form that can be very easily moved to
> > > > the docs.
> > >
> > > Oh, absolutely. Thomas, our master of the docs, has always had the
> > > policy of "give me some words, I'll take care of formatting and
> > > editing..."
> > >
> > > I was probably too harsh on Alfred last night, since in fact his code
> > > was fairly well commented, and some minimal doco could have been
> > > extracted from the routine headers. But on a change like this, I think
> > > some paragraphs of coherent high-level explanation are needed: what it
> > > does, when and why you'd use it. I didn't see that anywhere...
> >
> > I've actually been trying to work on the sgml and failing miserably,
> > I have no clue how this stuff works (sgml compilation) are you asking
> > for a couple of paragraphs that describe the proposed changes?
> >
> > If so I hope this suffices, if not some help on building the sgml
> > would be much appreciated:
> >
> > --------
> >
> The FreeBSD Documentation Project (FDP) has excellent references to get a
> general idea on building sgml docs. First, you can install the
> textproc/docproj port or, if you're not running freebsd, refer to the
> website to see which programs you need. Second, you can read the FDP
> Primer which details how everything comes together:
> http://www.freebsd.org/tutorials/docproj-primer/
>
> Furthermore, again if you happen to be running FreeBSD, you can grab the
> doc src using cvsup. The proper reference is also documented somewhere in
> the Primer or in the Synchronisation chapter in the Handbook.
>
> Keep at it, sgml and the docbook stylesheets are really worthwhile when
> you start getting the hang of it.
> Marc

'course I run freebsd. :) I even have the docproj port installed,
however it seems that there's some things missing here, (see the
end of this message).

I really have no problem with commenting my code nor do I have a
problem with producing documentation for these changes, however
I'm _extremely_ pressed for time with this project, haven't slept
in 2 days and I and don't have time to fight with building the sgml
files to check that my changes/additions are valid, I'd much rather
focus on working on the rest of libpq for blocking issues and getting
my app into test mode.

Perhaps someone can offer a step-by-step to building _postgresql's_
doc files, or maybe there's a machine out there where this will
build properly and someone can give me an account on it?

If so then I'll be glad to update the docs myself, otherwise I'd
also be happy to provide coupious amounts of plaintext docs and
comments in my code like I have been so far.

thanks,
-Alfred Perlstein - [bright(at)wintelcom(dot)net|alfred(at)freebsd(dot)org]

~/pgcvs/pgsql/doc/src % gmake
gmake all
gmake[1]: Entering directory `/home/bright/pgcvs/pgsql/doc/src'
gmake -C sgml clean
gmake[2]: Entering directory `/home/bright/pgcvs/pgsql/doc/src/sgml'
(rm -rf HTML.manifest *.html *.htm *.1 *.l man1 manl manpage*)
gmake[2]: Leaving directory `/home/bright/pgcvs/pgsql/doc/src/sgml'
gmake -C sgml admin.html
gmake[2]: Entering directory `/home/bright/pgcvs/pgsql/doc/src/sgml'
(rm -rf *.htm)
jade -D ref -D ../graphics -V %use-id-as-filename% -d /home/users/t/thomas/db118.d/docbook/html/docbook.dsl -t sgml admin.sgml

^^^^^^^^^^^^---- huh?
~/pgcvs/pgsql/doc % find . -name "*.dsl"
~/pgcvs/pgsql/doc %

continues...

jade:admin.sgml:26:59:W: cannot generate system identifier for public text "-//Davenport//DTD DocBook V3.0//EN"
jade:admin.sgml:51:0:E: reference to entity "BOOK" for which no system identifier could be generated
jade:admin.sgml:26:0: entity was defined here
jade:admin.sgml:51:0:E: DTD did not contain element declaration for document type name
jade:admin.sgml:53:9:E: there is no attribute "ID"
jade:admin.sgml:53:16:E: element "BOOK" undefined
jade:admin.sgml:57:7:E: element "TITLE" undefined
jade:admin.sgml:58:10:E: element "BOOKINFO" undefined
jade:admin.sgml:59:14:E: element "RELEASEINFO" undefined
jade:admin.sgml:60:13:E: element "BOOKBIBLIO" undefined
jade:admin.sgml:61:15:E: element "AUTHORGROUP" undefined
jade:admin.sgml:62:15:E: element "CORPAUTHOR" undefined
jade:admin.sgml:67:10:E: element "EDITOR" undefined
jade:admin.sgml:68:14:E: element "FIRSTNAME" undefined
jade:admin.sgml:69:12:E: element "SURNAME" undefined
jade:admin.sgml:70:16:E: element "AFFILIATION" undefined
jade:admin.sgml:71:13:E: element "ORGNAME" undefined
jade:admin.sgml:82:8:E: element "DATE" undefined
jade:admin.sgml:85:14:E: element "LEGALNOTICE" undefined
jade:admin.sgml:86:8:E: element "PARA" undefined
jade:admin.sgml:87:16:E: element "PRODUCTNAME" undefined
jade:admin.sgml:87:56:E: general entity "copy" not defined and no default entity
jade:admin.sgml:107:13:E: there is no attribute "ID"
jade:admin.sgml:107:22:E: element "PREFACE" undefined
jade:admin.sgml:108:8:E: element "TITLE" undefined
jade:admin.sgml:110:7:E: element "PARA" undefined
jade:admin.sgml:111:15:E: element "PRODUCTNAME" undefined
jade:admin.sgml:117:15:E: element "PRODUCTNAME" undefined
jade:intro-ag.sgml:1:13:E: there is no attribute "ID"
jade:intro-ag.sgml:1:23:E: element "CHAPTER" undefined
jade:intro-ag.sgml:2:8:E: element "TITLE" undefined
jade:intro-ag.sgml:4:7:E: element "PARA" undefined
jade:intro-ag.sgml:6:14:E: there is no attribute "URL"
jade:intro-ag.sgml:6:38:E: element "ULINK" undefined
jade:intro-ag.sgml:6:51:E: element "PRODUCTNAME" undefined
jade:intro-ag.sgml:10:15:E: element "PRODUCTNAME" undefined
jade:intro-ag.sgml:11:74:E: element "ULINK" undefined
jade:intro-ag.sgml:12:16:E: element "PRODUCTNAME" undefined
jade:intro-ag.sgml:13:19:E: element "PRODUCTNAME" undefined
jade:intro-ag.sgml:15:55:E: element "ACRONYM" undefined
jade:intro-ag.sgml:16:33:E: element "ACRONYM" undefined
jade:intro-ag.sgml:17:23:E: element "ACRONYM" undefined
jade:info.sgml:1:6:E: element "SECT1" undefined
jade:info.sgml:2:7:E: element "TITLE" undefined
jade:info.sgml:4:6:E: element "PARA" undefined
jade:info.sgml:8:14:E: element "VARIABLELIST" undefined
jade:info.sgml:9:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:10:8:E: element "TERM" undefined
jade:info.sgml:11:12:E: element "LISTITEM" undefined
jade:info.sgml:12:9:E: element "PARA" undefined
jade:info.sgml:18:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:19:8:E: element "TERM" undefined
jade:info.sgml:20:12:E: element "LISTITEM" undefined
jade:info.sgml:21:9:E: element "PARA" undefined
jade:info.sgml:27:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:28:8:E: element "TERM" undefined
jade:info.sgml:29:12:E: element "LISTITEM" undefined
jade:info.sgml:30:9:E: element "PARA" undefined
jade:info.sgml:38:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:39:8:E: element "TERM" undefined
jade:info.sgml:40:12:E: element "LISTITEM" undefined
jade:info.sgml:41:9:E: element "PARA" undefined
jade:info.sgml:47:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:48:8:E: element "TERM" undefined
jade:info.sgml:49:12:E: element "LISTITEM" undefined
jade:info.sgml:50:9:E: element "PARA" undefined
jade:info.sgml:51:33:E: element "PRODUCTNAME" undefined
jade:info.sgml:53:17:E: element "PRODUCTNAME" undefined
jade:info.sgml:55:15:E: element "CITETITLE" undefined
jade:info.sgml:56:41:E: element "CITETITLE" undefined
jade:info.sgml:61:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:62:8:E: element "TERM" undefined
jade:info.sgml:63:12:E: element "LISTITEM" undefined
jade:info.sgml:64:9:E: element "PARA" undefined
jade:info.sgml:66:41:E: element "CITETITLE" undefined
jade:info.sgml:72:6:E: element "PARA" undefined
jade:info.sgml:74:14:E: element "PRODUCTNAME" undefined
jade:info.sgml:77:14:E: element "VARIABLELIST" undefined
jade:info.sgml:78:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:79:8:E: element "TERM" undefined
jade:info.sgml:80:12:E: element "LISTITEM" undefined
jade:info.sgml:81:9:E: element "PARA" undefined
jade:info.sgml:87:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:88:8:E: element "TERM" undefined
jade:info.sgml:89:12:E: element "LISTITEM" undefined
jade:info.sgml:90:9:E: element "PARA" undefined
jade:info.sgml:97:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:98:8:E: element "TERM" undefined
jade:info.sgml:99:12:E: element "LISTITEM" undefined
jade:info.sgml:100:9:E: element "PARA" undefined
jade:info.sgml:106:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:107:8:E: element "TERM" undefined
jade:info.sgml:108:12:E: element "LISTITEM" undefined
jade:info.sgml:109:9:E: element "PARA" undefined
jade:info.sgml:111:32:E: element "ULINK" undefined
jade:info.sgml:111:45:E: element "PRODUCTNAME" undefined
jade:info.sgml:113:28:E: element "PRODUCTNAME" undefined
jade:info.sgml:119:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:120:8:E: element "TERM" undefined
jade:info.sgml:121:12:E: element "LISTITEM" undefined
jade:info.sgml:122:9:E: element "PARA" undefined
jade:info.sgml:124:53:E: element "ULINK" undefined
jade:info.sgml:125:67:E: element "ULINK" undefined
jade:info.sgml:133:15:E: element "VARLISTENTRY" undefined
jade:info.sgml:134:8:E: element "TERM" undefined
jade:info.sgml:135:12:E: element "LISTITEM" undefined
jade:info.sgml:136:9:E: element "PARA" undefined
jade:info.sgml:137:17:E: element "PRODUCTNAME" undefined
jade:info.sgml:139:37:E: element "PRODUCTNAME" undefined
jade:info.sgml:147:9:E: element "PARA" undefined
jade:info.sgml:151:50:E: element "ULINK" undefined
jade:info.sgml:152:64:E: element "ULINK" undefined
jade:notation.sgml:1:10:E: there is no attribute "ID"
jade:notation.sgml:1:23:E: element "SECT1" undefined
jade:notation.sgml:2:7:E: element "TITLE" undefined
jade:notation.sgml:4:6:E: element "PARA" undefined
jade:notation.sgml:6:12:E: element "FIRSTTERM" undefined
jade:notation.sgml:8:14:E: element "PRODUCTNAME" undefined
jade:notation.sgml:10:14:E: element "PRODUCTNAME" undefined
jade:notation.sgml:13:14:E: element "PRODUCTNAME" undefined
jade:notation.sgml:16:6:E: element "PARA" undefined
jade:notation.sgml:18:14:E: element "PRODUCTNAME" undefined
jade:notation.sgml:18:48:E: element "FIRSTTERM" undefined
jade:notation.sgml:19:32:E: element "REPLACEABLE" undefined
jade:notation.sgml:20:27:E: element "PRODUCTNAME" undefined
jade:notation.sgml:24:31:E: element "PRODUCTNAME" undefined
jade:notation.sgml:26:28:E: element "PRODUCTNAME" undefined
jade:notation.sgml:27:11:E: element "EMPHASIS" undefined
jade:notation.sgml:28:73:E: element "FIRSTTERM" undefined
jade:notation.sgml:29:66:E: element "FIRSTTERM" undefined
jade:notation.sgml:33:6:E: element "PARA" undefined
jade:notation.sgml:35:12:E: element "FIRSTTERM" undefined
jade:notation.sgml:36:13:E: element "ACRONYM" undefined
jade:notation.sgml:37:14:E: element "PRODUCTNAME" undefined
jade:notation.sgml:41:14:E: element "APPLICATION" undefined
jade:notation.sgml:44:6:E: element "PARA" undefined
jade:notation.sgml:45:18:E: element "APPLICATION" undefined
jade:notation.sgml:47:21:E: element "PRODUCTNAME" undefined
jade:notation.sgml:48:51:E: element "APPLICATION" undefined
jade:notation.sgml:50:38:E: element "APPLICATION" undefined
jade:notation.sgml:56:6:E: element "PARA" undefined
jade:notation.sgml:57:18:E: element "PRODUCTNAME" undefined
jade:notation.sgml:58:45:E: element "APPLICATION" undefined
jade:notation.sgml:60:14:E: element "PRODUCTNAME" undefined
jade:notation.sgml:68:20:E: element "SECT1" undefined
jade:notation.sgml:69:7:E: element "TITLE" undefined
jade:notation.sgml:71:6:E: element "PARA" undefined
jade:notation.sgml:72:8:E: element "QUOTE" undefined
jade:notation.sgml:72:33:E: element "FILENAME" undefined
jade:notation.sgml:74:26:E: element "PRODUCTNAME" undefined
jade:notation.sgml:77:6:E: element "PARA" undefined
jade:notation.sgml:79:9:E: element "QUOTE" undefined
jade:notation.sgml:79:30:E: element "QUOTE" undefined
jade:notation.sgml:81:9:E: element "QUOTE" undefined
jade:notation.sgml:81:30:E: element "QUOTE" undefined
jade:notation.sgml:81:78:E: element "QUOTE" undefined
jade:notation.sgml:85:6:E: element "PARA" undefined
jade:notation.sgml:86:34:E: element "QUOTE" undefined
jade:notation.sgml:86:55:E: element "QUOTE" undefined
jade:notation.sgml:87:22:E: element "QUOTE" undefined
jade:notation.sgml:90:6:E: element "PARA" undefined
jade:notation.sgml:92:71:E: element "QUOTE" undefined
jade:notation.sgml:92:73:E: general entity "gt" not defined and no default entity
jade:notation.sgml:93:41:E: element "PRODUCTNAME" undefined
jade:notation.sgml:94:49:E: element "QUOTE" undefined
jade:notation.sgml:96:8:E: element "QUOTE" undefined
jade:notation.sgml:97:10:E: element "ACRONYM" undefined
jade:notation.sgml:97:63:E: element "QUOTE" undefined
jade:notation.sgml:101:6:E: element "NOTE" undefined
jade:notation.sgml:102:7:E: element "PARA" undefined
jade:notation.sgml:103:39:E: element "PRODUCTNAME" undefined
jade:notation.sgml:106:42:E: element "ULINK" undefined
jade:y2k.sgml:1:15:E: element "SECT1" undefined
jade:y2k.sgml:2:7:E: element "TITLE" undefined
jade:y2k.sgml:4:6:E: element "NOTE" undefined
jade:y2k.sgml:5:8:E: element "TITLE" undefined
jade:y2k.sgml:7:7:E: element "PARA" undefined
jade:y2k.sgml:9:50:E: element "ULINK" undefined
jade:y2k.sgml:14:6:E: element "PARA" undefined
jade:y2k.sgml:15:18:E: element "PRODUCTNAME" undefined
jade:y2k.sgml:16:18:E: element "PRODUCTNAME" undefined
jade:y2k.sgml:21:14:E: element "ITEMIZEDLIST" undefined
jade:y2k.sgml:22:11:E: element "LISTITEM" undefined
jade:y2k.sgml:23:8:E: element "PARA" undefined
jade:y2k.sgml:24:65:E: element "PRODUCTNAME" undefined
jade:y2k.sgml:26:36:E: element "PRODUCTNAME" undefined
jade:y2k.sgml:31:11:E: element "LISTITEM" undefined
jade:y2k.sgml:32:8:E: element "PARA" undefined
jade:y2k.sgml:36:19:E: element "PRODUCTNAME" undefined
jade:y2k.sgml:42:11:E: element "LISTITEM" undefined
jade:y2k.sgml:43:8:E: element "PARA" undefined
jade:y2k.sgml:47:65:E: element "ULINK" undefined
jade:y2k.sgml:50:15:E: element "QUOTE" undefined
jade:y2k.sgml:50:57:E: element "QUOTE" undefined
jade:y2k.sgml:51:18:E: element "QUOTE" undefined
jade:y2k.sgml:51:60:E: element "QUOTE" undefined
jade:y2k.sgml:55:11:E: element "LISTITEM" undefined
jade:y2k.sgml:56:8:E: element "PARA" undefined
jade:y2k.sgml:59:16:E: element "PRODUCTNAME" undefined
jade:y2k.sgml:64:6:E: element "PARA" undefined
jade:y2k.sgml:66:56:E: element "ULINK" undefined
jade:y2k.sgml:68:53:E: element "ULINK" undefined
jade:I: maximum number of errors (200) reached; change with -E option
jade:E: cannot open "/home/users/t/thomas/db118.d/docbook/html/docbook.dsl" (No such file or directory)
jade:E: specification document does not have the DSSSL architecture as a base architecture

PostgreSQL Administrator's Guide
Covering v6.5 for general release
The PostgreSQL Development Team

Thomas
Lockhart
Caltech/JPL

(last updated 1999-06-01)

PostgreSQL is Copyright 1996-9
by the Postgres Global Development Group.

Summary

Postgres,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
PostgreSQL is an open-source descendant
of this original Berkeley code.

Introduction

This document is the Administrator's Manual for the
PostgreSQL
database management system, originally developed at the University
of California at Berkeley.

PostgreSQL is based on
Postgres release 4.2.
The Postgres project,
led by Professor Michael Stonebraker, was sponsored by the
Defense Advanced Research Projects Agency (DARPA), the
Army Research Office (ARO), the National Science
Foundation (NSF), and ESL, Inc.

Resources

This manual set is organized into several parts:

Tutorial
An introduction for new users. Does not cover advanced features.

User's Guide
General information for users, including available commands and data types.

Programmer's Guide
Advanced information for application programmers. Topics include
type and function extensibility, library interfaces,
and application design issues.

Administrator's Guide
Installation and management information. List of supported machines.

Developer's Guide
Information for Postgres developers.
This is intended for those who are contributing to the
Postgres project;
application development information should appear in the
Programmer's Guide.
Currently included in the Programmer's Guide.

Reference Manual
Detailed reference information on command syntax.
Currently included in the User's Guide.

In addition to this manual set, there are other resources to help you with
Postgres installation and use:

man pages
The man pages have general information on command syntax.

FAQs
The Frequently Asked Questions (FAQ) documents address both general issues
and some platform-specific issues.

READMEs
README files are available for some contributed packages.

Web Site
The
Postgres
web site might have some information not appearing in the distribution.
There is a mhonarc catalog of mailing list traffic
which is a rich resource for many topics.

Mailing Lists
The
pgsql-general
(archive)
mailing list is a good place to have user questions answered.
Other mailing lists are available; consult the Info Central section of the
PostgreSQL web site for details.

Yourself!
Postgres is an open source product.
As such, it depends on the user community for ongoing support.
As you begin to use Postgres,
you will rely on others for help, either through the
documentation or through the mailing lists.
Consider contributing your knowledge back. If you learn something
which is not in the documentation, write it up and contribute it.
If you add features to the code, contribute it.

Even those without a lot of experience can provide corrections and
minor changes in the documentation, and that is a good way to start.
The
pgsql-docs
(archive)
mailing list is the place to get going.

Terminology

In the following documentation,
site
may be interpreted as the host machine on which
Postgres is installed.
Since it is possible to install more than one set of
Postgres
databases on a single host, this term more precisely denotes any
particular set of installed
Postgres binaries and databases.

The
Postgres superuser
is the user named postgres
who owns the Postgres
binaries and database files. As the database superuser, all
protection mechanisms may be bypassed and any data accessed
arbitrarily.
In addition, the Postgres superuser is allowed to execute
some support programs which are generally not available to all users.
Note that the Postgres superuser is
not
the same as the Unix superuser (which will be referred to as root).
The superuser should have a non-zero user identifier (UID)
for security reasons.

The
database administrator
or DBA, is the person who is responsible for installing
Postgres with mechanisms to
enforce a security policy for a site. The DBA can add new users by
the method described below
and maintain a set of template databases for use by
createdb.

The postmaster
is the process that acts as a clearing-house for requests
to the Postgres system.
Frontend applications connect to the postmaster,
which keeps tracks of any system errors and communication between the
backend processes. The postmaster
can take several command-line arguments to tune its behavior.
However, supplying arguments is necessary only if you intend to run multiple
sites or a non-default site.

The Postgres backend
(the actual executable program postgres) may be executed
directly from the user shell by the
Postgres super-user
(with the database name as an argument). However,
doing this bypasses the shared buffer pool and lock table associated
with a postmaster/site, therefore this is not recommended in a multiuser
site.

Notation

... or /usr/local/pgsql/
at the front of a file name is used to represent the
path to the Postgres superuser's home directory.

In a command synopsis, brackets
([ and ]) indicate an optional phrase or keyword.
Anything in braces
({ and }) and containing vertical bars (|)
indicates that you must choose one.

In examples, parentheses (( and )) are used to group boolean
expressions. | is the boolean operator OR.

Examples will show commands executed from various accounts and programs.
Commands executed from the root account will be preceeded with .
Commands executed from the Postgres
superuser account will be preceeded with %, while commands
executed from an unprivileged user's account will be preceeded with
$.
SQL commands will be preceeded with =
or will have no leading prompt, depending on the context.

At the time of writing (Postgres v6.5) the notation for
flagging commands is not universally consistant throughout the documentation set.
Please report problems to
the Documentation Mailing List.

Y2K Statement

Author

Written by
Thomas Lockhart
on 1998-10-22.

The PostgreSQL Global Development Team provides
the Postgres software code tree as a public service,
without warranty and without liability for it's behavior or performance.
However, at the time of writing:

The author of this statement, a volunteer on the Postgres
support team since November, 1996, is not aware of
any problems in the Postgres code base related
to time transitions around Jan 1, 2000 (Y2K).

The author of this statement is not aware of any reports of Y2K problems
uncovered in regression testing
or in other field use of recent or current versions
of Postgres. We might have expected
to hear about problems if they existed, given the installed base and
the active participation of users on the support mailing lists.

To the best of the author's knowledge, the
assumptions Postgres makes about dates specified with a two-digit year
are documented in the current
User's Guide
in the chapter on data types.
For two-digit years, the significant transition year is 1970, not 2000;
e.g. 70-01-01 is interpreted as 1970-01-01,
whereas 69-01-01 is interpreted as 2069-01-01.

Any Y2K problems in the underlying OS related to obtaining "the
current time" may propagate into apparent Y2K problems in
Postgres.

Refer to
The Gnu Project
and
gmake[2]: *** [admin.html] Error 1
gmake[2]: Leaving directory `/home/bright/pgcvs/pgsql/doc/src/sgml'
gmake[1]: *** [admin.tar] Error 2
gmake[1]: Leaving directory `/home/bright/pgcvs/pgsql/doc/src'
gmake: *** [install] Error 2

oy!