Re: [HACKERS] Revised nonblocking patches + quasi docs
От | Alfred Perlstein |
---|---|
Тема | Re: [HACKERS] Revised nonblocking patches + quasi docs |
Дата | |
Msg-id | 20000114120516.D824@fw.wintelcom.net обсуждение исходный текст |
Ответ на | Re: [HACKERS] Revised nonblocking patches + quasi docs (admin <admin@wtbwts.com>) |
Ответы |
Re: [HACKERS] Revised nonblocking patches + quasi docs
(The Hermit Hacker <scrappy@hub.org>)
|
Список | pgsql-hackers |
* admin <admin@wtbwts.com> [000114 11:35] wrote: > Alfred wrote: > > * Tom Lane <tgl@sss.pgh.pa.us> [000109 08:18] wrote: > > > Don Baccus <dhogaza@pacifier.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@wintelcom.net|alfred@freebsd.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-relationalconcepts 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 Berkeleycode. Introduction This document is the Administrator's Manual for the PostgreSQL database management system, originally developedat the University of California at Berkeley. PostgreSQL is based on Postgres release 4.2. The Postgres project, led by Professor Michael Stonebraker, wassponsored by the Defense Advanced Research Projects Agency (DARPA), the Army Research Office (ARO), the NationalScience 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 tothe Postgres project; application development information should appear in the Programmer's Guide. Currentlyincluded 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-specificissues. READMEs README files are available for some contributed packages. Web Site The Postgres web site might have some information not appearing in the distribution. Thereis 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 throughthe 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 thatis 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 ispossible to install more than one set of Postgres databases on a single host, this term more precisely denotes any particularset of installed Postgres binaries and databases. The Postgres superuser is the user named postgres who owns the Postgres binaries and database files. As the databasesuperuser, all protection mechanisms may be bypassed and any data accessed arbitrarily. In addition, the Postgressuperuser is allowed to execute some support programs which are generally not available to all users. Note that thePostgres superuser is not the same as the Unix superuser (which will be referred to as root). The superuser should havea 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 enforcea security policy for a site. The DBA can add new users by the method described below and maintain a set of templatedatabases for use by createdb. The postmaster is the process that acts as a clearing-house for requests to the Postgres system. Frontend applicationsconnect 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 necessaryonly 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 Postgressuper-user (with the database name as an argument). However, doing this bypasses the shared buffer pool and locktable 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 containingvertical 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 bepreceeded with . Commands executed from the Postgres superuser account will be preceeded with %, while commands executedfrom an unprivileged user's account will be preceeded with $. SQL commands will be preceeded with = or will haveno leading prompt, depending on the context. At the time of writing (Postgres v6.5) the notation for flagging commands is not universally consistant throughoutthe 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 andwithout 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 orin other field use of recent or current versions of Postgres. We might have expected to hear about problems if theyexisted, 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 significanttransition year is 1970, not 2000; e.g. 70-01-01 is interpreted as 1970-01-01, whereas 69-01-01 is interpretedas 2069-01-01. Any Y2K problems in the underlying OS related to obtaining "the current time" may propagate into apparent Y2K problemsin 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!
В списке pgsql-hackers по дате отправления:
Предыдущее
От: "Ansley, Michael"Дата:
Сообщение: RE: [HACKERS] [hackers]development suggestion needed
Следующее
От: The Hermit HackerДата:
Сообщение: Re: [HACKERS] Revised nonblocking patches + quasi docs