-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.10 1998/10/25 00:25:30 thomas Exp $
-Documentation Guide
-Thomas Lockhart
-
-$Log: docguide.sgml,v $
-Revision 1.10 1998/10/25 00:25:30 thomas
-Update info on source files for v6.4.
-Should add/change ToDo list some more before release...
-
-Revision 1.9 1998/10/15 05:46:54 momjian
-SGML updates from post 6.3.2 manual changes. Added pg_upgrade man page.
-
-Revision 1.8 1998/08/17 16:17:07 thomas
-Bring document list closer to up to day.
-Add a note on sgml-tools that they are now working with jade and so
- may become the toolset of choice in the future.
-
-Revision 1.7 1998/08/15 06:53:52 thomas
-Include working list of all documentation sources, with current status
- and plans for some of them.
-
--->
-
-<appendix label="A" Id="docguide">
-<docinfo>
-<authorgroup>
-<author>
-<firstname>Thomas</firstname>
-<surname>Lockhart</surname>
-</author>
-<author>
-<firstname>Tom Ivar</firstname>
-<surname>Helbekkmo</surname>
-</author>
-</authorgroup>
-<date>1998-04-28</date>
-</docinfo>
-
-<title>Documentation</title>
-
-<para>
-The purpose of documentation is to make <productname>Postgres</productname>
-easier to learn, use, and develop.
-The documentation set should describe the <productname>Postgres</productname>
-system, language, and interfaces.
-It should be able to answer
-common questions and to allow a user to find those answers on his own
-without resorting to mailing list support.
-
-<para>
-<productname>Postgres</productname> has four primary documentation
-formats:
-
-<itemizedlist>
-<listitem><para>
-Plain text for pre-installation information.
-</para></listitem>
-<listitem><para>
-<acronym>HTML</acronym>, for on-line browsing and reference.
-</para></listitem>
-<listitem><para>
-Hardcopy, for in-depth reading and reference.
-</para></listitem>
-<listitem><para>
-<acronym>man pages</acronym>, for quick reference.
-</para></listitem>
-</itemizedlist>
-
-<para>
-Documentation sources include plain text files, man pages, and html. However,
-most new <productname>Postgres</productname> documentation will be written using the
-<firstterm>Standard Generalized Markup Language</firstterm>
-(<acronym>SGML</acronym>)
-<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
- <firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
-Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
-</para>
-
-<sect1>
-<title>Documentation Roadmap</title>
-
-<para>
-Documentation has accumulated from several sources. As we integrate
-and assimilate existing documentation into a coherent documentation set,
-the older versions will become obsolete and will be removed from the
-distribution. However, this will not happen immediately, and will not
-happen to all documents at the same time. To ease the transition, and
-to help guide developers and writers, we have defined a transition roadmap.
-
-<para>
-Here is the documentation plan for v6.4:
-
-<itemizedlist>
-<listitem>
-<para>
-Convert <ulink url="sferac@bo.nettuno.it">Jose Soares Da Silva</ulink>'s
- text-based reference pages to <acronym>SGML</acronym>
-reference sections for the User's Guide.
-<ulink url="olly@lfix.co.uk">Oliver Elphick</ulink> is working on this
-and it is roughly half-way completed.
-
-<listitem>
-<para>
-Write more sections for the User's Guide covering areas outside the reference pages.
-This would include introductory information and suggestions for approaches to typical
- design problems.
-
-<listitem>
-<para>
-Merge information in the existing man pages into the reference pages and User's Guide.
-
-<listitem>
-<para>
-Convert the new sgml reference pages to new man pages, replacing the existing man pages.
-Brandon Ibach is working on the conversion filter.
-
-<listitem>
-<para>
-Rebuild the User's Guide, Reference Guide, and Administrator's Guide
-(the admin guide only if we get release notes and installation
-information updated in <acronym>SGML</acronym>).
-</itemizedlist>
-
-<itemizedlist>
-<listitem><para>
-</para></listitem>
-</itemizedlist>
-
-<para>
-<table tocentry="1">
-<title><ProductName>Postgres</ProductName> Documentation Products</title>
-<tgroup cols="3">
-<thead>
-<row>
-<entry>
-File
-</entry>
-<entry>
-Description
-</entry>
-</row>
-</thead>
-
-<tbody>
-<row><entry> ./COPYRIGHT </entry><entry> Copyright notice </entry></row>
-<row><entry> ./INSTALL </entry><entry> Installation instructions (text from sgml->rtf->text) </entry></row>
-<row><entry> ./README </entry><entry> Introductory info </entry></row>
-<row><entry> ./register.txt </entry><entry> Registration message during make </entry></row>
-<row><entry> ./doc/bug.template </entry><entry> Bug report template </entry></row>
-<row><entry> ./doc/postgres.tar.gz </entry><entry> Integrated docs (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/programmer.ps.gz </entry><entry> Programmer's Guide (Postscript) </entry></row>
-<row><entry> ./doc/programmer.tar.gz </entry><entry> Programmer's Guide (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/reference.ps.gz </entry><entry> Reference Manual (Postscript) </entry></row>
-<row><entry> ./doc/reference.tar.gz </entry><entry> Reference Manual (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/tutorial.ps.gz </entry><entry> Introduction (Postscript) </entry></row>
-<row><entry> ./doc/tutorial.tar.gz </entry><entry> Introduction (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/user.ps.gz </entry><entry> User's Guide (Postscript) </entry></row>
-<row><entry> ./doc/user.tar.gz </entry><entry> User's Guide (<acronym>HTML</acronym>) </entry></row>
-</tbody>
-</tgroup>
-</table>
-
-<sect1>
-<title>Documentation Sources</title>
-
-<para>
-<table tocentry="1">
-<title><ProductName>Postgres</ProductName> Documentation Sources</title>
-<tgroup cols="3">
-<thead>
-<row>
-<entry>
-File
-</entry>
-<entry>
-Status
-</entry>
-</row>
-</thead>
-
-<tbody>
-<row><entry> ./doc/src/graphics/catalogs.gif </entry><entry> Output file </entry></row>
-<row><entry> ./doc/src/graphics/clientserver.ag </entry><entry> Source file. Convert to CGM </entry></row>
-<row><entry> ./doc/src/graphics/clientserver.gif </entry><entry> Output file </entry></row>
-<row><entry> ./doc/src/graphics/connections.ag </entry><entry> Source file. Convert to CGM </entry></row>
-<row><entry> ./doc/src/graphics/connections.gif </entry><entry> Output file </entry></row>
-<row><entry> ./doc/src/graphics/layout.ag </entry><entry> Source file. Convert to CGM </entry></row>
-<row><entry> ./doc/src/graphics/layout.gif </entry><entry> Output file </entry></row>
-<row><entry> ./doc/src/sgml/about.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/admin.sgml </entry><entry> Administrator's Guide container </entry></row>
-<row><entry> ./doc/src/sgml/advanced.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/arch-dev.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/arch-pg.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/arch.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/array.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/biblio.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/bki.sgml </entry><entry> Converted from bki.5 </entry></row>
-<row><entry> ./doc/src/sgml/compiler.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/config.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/contacts.sgml </entry><entry> Docs contributors? Not used. Either complete or discard </entry></row>
-<row><entry> ./doc/src/sgml/datatype.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/dfunc.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/docguide.sgml </entry><entry> Documentation info. New document </entry></row>
-<row><entry> ./doc/src/sgml/ecpg.sgml </entry><entry> ecpg eSQL pre-compiler docs </entry></row>
-<row><entry> ./doc/src/sgml/environ.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/extend.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/func-ref.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/func.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/geqo.sgml </entry><entry> GEQO genetic optimizer docs </entry></row>
-<row><entry> ./doc/src/sgml/gist.sgml </entry><entry> New from mailing list </entry></row>
-<row><entry> ./doc/src/sgml/history.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/indices.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/info.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/inherit.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/install.sgml </entry><entry> Installation instructions </entry></row>
-<row><entry> ./doc/src/sgml/intro-ag.sgml </entry><entry> Admin Guide intro. Converted </entry></row>
-<row><entry> ./doc/src/sgml/intro-pg.sgml </entry><entry> Programmers Guide intro. Converted </entry></row>
-<row><entry> ./doc/src/sgml/intro.sgml </entry><entry> Users Guide intro </entry></row>
-<row><entry> ./doc/src/sgml/jdbc.sgml </entry><entry> New document from Peter Mount </entry></row>
-<row><entry> ./doc/src/sgml/keys.sgml </entry><entry> New document </entry></row>
-<row><entry> ./doc/src/sgml/legal.sgml </entry><entry> Copyright etc. for intros </entry></row>
-<row><entry> ./doc/src/sgml/libpgtcl.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/libpq++.sgml </entry><entry> C++ library. Converted </entry></row>
-<row><entry> ./doc/src/sgml/libpq.sgml </entry><entry> C library </entry></row>
-<row><entry> ./doc/src/sgml/lobj.sgml </entry><entry> Large objects </entry></row>
-<row><entry> ./doc/src/sgml/manage.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/notation.sgml </entry><entry> Docs notation for intros </entry></row>
-<row><entry> ./doc/src/sgml/odbc.sgml </entry><entry> ODBC driver </entry></row>
-<row><entry> ./doc/src/sgml/oper.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/page.sgml </entry><entry> On-disk storage scheme </entry></row>
-<row><entry> ./doc/src/sgml/pg_options.sgml </entry><entry> Backend configuration </entry></row>
-<row><entry> ./doc/src/sgml/pgaccess.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/ports.sgml </entry><entry> Supported/unsupported platforms </entry></row>
-<row><entry> ./doc/src/sgml/postgres.sgml </entry><entry> Container for all docs. Best for html output </entry></row>
-<row><entry> ./doc/src/sgml/programmer.sgml </entry><entry> Programmer's Guide </entry></row>
-<row><entry> ./doc/src/sgml/protocol.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/psql.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/query-ug.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/query.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/recovery.sgml </entry><entry> Database recovery </entry></row>
-<row><entry> ./doc/src/sgml/reference.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/regress.sgml </entry><entry> Regression testing </entry></row>
-<row><entry> ./doc/src/sgml/release.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/rules.sgml </entry><entry> Rule system </entry></row>
-<row><entry> ./doc/src/sgml/runtime.sgml </entry><entry> Runtime environment. New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/security.sgml </entry><entry> Server security </entry></row>
-<row><entry> ./doc/src/sgml/signals.sgml </entry><entry> System signals for backend. </entry></row>
-<row><entry> ./doc/src/sgml/spi.sgml </entry><entry> Converted. Original removed </entry></row>
-<row><entry> ./doc/src/sgml/start-ag.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/start.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/storage.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/syntax.sgml </entry><entry> SQL syntax. In UG </entry></row>
-<row><entry> ./doc/src/sgml/trigger.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/tutorial.sgml </entry><entry> Container for tutorial </entry></row>
-<row><entry> ./doc/src/sgml/typeconv.sgml </entry><entry> Datatype conversion. New for v6.4. In UG </entry></row>
-<row><entry> ./doc/src/sgml/user.sgml </entry><entry> User's Guide </entry></row>
-<row><entry> ./doc/src/sgml/xaggr.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/xfunc.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/xindex.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/xoper.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/xplang.sgml </entry><entry> Programming Language. New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/xtypes.sgml </entry><entry> Converted </entry></row>
-<row><entry> ./doc/src/sgml/y2k.sgml </entry><entry> Y2K statement. New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/abort.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/allfiles.sgml </entry><entry> List of files in ref/ (internal) </entry></row>
-<row><entry> ./doc/src/sgml/ref/alter_table.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/alter_user.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/begin.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/close.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/cluster.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/commands.sgml </entry><entry> List of commands (internal) </entry></row>
-<row><entry> ./doc/src/sgml/ref/commit.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/copy.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_aggregate.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_database.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_function.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_index.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_language.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_operator.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_rule.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_sequence.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_table.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_trigger.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_type.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_user.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/create_view.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/createdb.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/createuser.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/declare.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/delete.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/destroydb.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/destroyuser.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_aggregate.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_database.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_function.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_index.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_language.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_operator.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_rule.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_sequence.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_table.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_trigger.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_type.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_user.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/drop_view.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/explain.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/fetch.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/grant.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/initdb.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/initlocation.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/insert.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/listen.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/load.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/lock.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/move.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/notify.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/pg_dump.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/pg_dumpall.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/psql-ref.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/reset.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/revoke.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/rollback.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/select.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/set.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/show.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/update.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/vacuum.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/unlisten.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/vacuumdb.sgml </entry><entry> New for v6.4 </entry></row>
-<row><entry> ./doc/src/sgml/ref/pg_upgrade.sgml </entry><entry> New for v6.4 </entry></row>
-</tbody>
-</tgroup>
-</table>
-
-<sect1>
-<title>Document Conversion Status</title>
-
-<para>
-<table tocentry="1">
-<title><ProductName>Postgres</ProductName> Documentation Sources</title>
-<tgroup cols="3">
-<thead>
-<row>
-<entry>
-File
-</entry>
-<entry>
-Status
-</entry>
-</row>
-</thead>
-
-<tbody>
-<row><entry> ./HISTORY </entry><entry> Obsolete. Converted to release.sgml </entry></row>
-<row><entry> ./README </entry><entry> Not converted </entry></row>
-<row><entry> ./INSTALL </entry><entry> Obsolete. Converted to install.sgml </entry></row>
-<row><entry> ./contrib/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/apache_logging/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/array/array_iterator.doc </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/datetime/datetime_functions.doc </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/earthdistance/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/int8/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/ip_and_mac/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/lo/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/mSQL-interface/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/noupdate/noup.example </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/pginterface/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/sequence/set_sequence.sql.in </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/soundex/soundex.sql.in </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/spi/README </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/spi/autoinc.example </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/spi/insert_username.example </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/spi/refint.example </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/spi/timetravel.example </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/string/string_io.sql.in </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/unixdate/unixdate.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./contrib/userlock/user_locks.doc </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/FAQ </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/FAQ_DEV </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/FAQ_FreeBSD </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/FAQ_Irix </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/FAQ_Linux </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/TODO </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/README.GEQO </entry><entry> Removed. Superceded by geqo.sgml </entry></row>
-<row><entry> ./doc/README.fsync </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./doc/README.locale </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./doc/README.mb </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./doc/README.mb.jp </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/README.support </entry><entry> Not converted </entry></row>
-<row><entry> ./doc/TODO.GEQO </entry><entry> Removed. Superceded by geqo.sgml </entry></row>
-<row><entry> ./doc/userguide.ps </entry><entry> Removed (converted to SGML) </entry></row>
-<row><entry> ./migration/1.02_to_1.02.1 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/1.09_to_6.0 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/1.0_to_1.01 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/6.0_to_6.1 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/6.1_to_6.1.1 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/6.1_to_6.2 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/6.2.1_to_6.3 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/6.2_to_6.2.1 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./migration/6.3.1_to_6.3.2 </entry><entry> Removed. Superceded by release.sgml </entry></row>
-<row><entry> ./src/DEVELOPERS </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/access/nbtree/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/catalog/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/libpq/pg_hba.conf.sample </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/libpq/pg_ident.conf.sample </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/nodes/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/optimizer/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/optimizer/geqo/pg_geqo.sample </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/optimizer/plan/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/parser/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/port/dynloader/README.dlfcn.aix </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/regex/COPYRIGHT </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/regex/WHATSNEW </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/regex/re_format.7 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/regex/regex.3 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/storage/ipc/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/storage/lmgr/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/backend/storage/smgr/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/bin/pg_dump/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/bin/pgaccess/README.pga </entry><entry> Not converted </entry></row>
-<row><entry> ./src/bin/pgaccess/formdemo.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/bin/pgtclsh/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/data/charset.conf </entry><entry> Not converted </entry></row>
-<row><entry> ./src/data/koi-alt.tab </entry><entry> Not converted </entry></row>
-<row><entry> ./src/data/koi-iso.tab </entry><entry> Not converted </entry></row>
-<row><entry> ./src/data/koi-koi.tab </entry><entry> Not converted </entry></row>
-<row><entry> ./src/data/koi-mac.tab </entry><entry> Not converted </entry></row>
-<row><entry> ./src/data/koi-win.tab </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/ecpg/ChangeLog </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/ecpg/TODO </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/jdbc/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/jdbc/README_6.3 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/jdbc/example/ImageViewer.java </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/jdbc/example/basic.java </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/jdbc/example/blobtest.java </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/jdbc/example/datestyle.java </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/jdbc/example/psql.java </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpgtcl/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq0.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq1.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq2.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq2.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq3.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq3.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq4.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq4.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq5.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq5.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlibpq6.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/libpq++/examples/testlo.cc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/odbc/license.txt </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/odbc/notice.txt </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/odbc/readme.txt </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/perl5/MANIFEST </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/perl5/Changes </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/perl5/eg/example.newstyle </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/perl5/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/Announce </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/ChangeLog </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/advanced.py </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/advanced.pyc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/basics.py </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/func.py </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/func.pyc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/pgtools.py </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/pgtools.pyc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/syscat.py </entry><entry> Not converted </entry></row>
-<row><entry> ./src/interfaces/python/tutorial/syscat.pyc </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/abort.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/alter_table.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/alter_user.l </entry><entry> Split into Reference and Admin Guide </entry></row>
-<row><entry> ./src/man/begin.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/catalogs.3 </entry><entry> Catalog synopsis. Move to Programmer's Guide? </entry></row>
-<row><entry> ./src/man/cleardbdir.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/close.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/cluster.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/commit.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/copy.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_aggregate.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_database.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_function.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_index.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_language.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_operator.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_rule.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_sequence.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_table.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_trigger.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_type.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_user.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_version.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/create_view.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/createdb.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/createuser.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/declare.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/delete.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/destroydb.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/destroyuser.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_aggregate.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_database.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_function.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_index.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_language.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_operator.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_rule.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_sequence.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_table.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_trigger.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_type.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_user.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/drop_view.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/end.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/ecpg.1 </entry><entry> Short man page. Retain </entry></row>
-<row><entry> ./src/man/explain.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/fetch.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/grant.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/initdb.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/initlocation.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/insert.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/ipcclean.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/listen.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/load.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/lock.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/move.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/notify.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/pg_dump.1 </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./src/man/pg_dumpall.1 </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./src/man/pg_upgrade.1 </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./src/man/pg_hba.conf.5 </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./src/man/pg_passwd.1 </entry><entry> Assimilate into Admin Guide </entry></row>
-<row><entry> ./src/man/pgintro.1 </entry><entry> Assimilate into User's Guide? </entry></row>
-<row><entry> ./src/man/postgres.1 </entry><entry> Assimilate into User's, Admin Guides </entry></row>
-<row><entry> ./src/man/postmaster.1 </entry><entry> Assimilate into User's, Admin Guides </entry></row>
-<row><entry> ./src/man/psql.1 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/reset.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/revoke.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/rollback.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/select.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/set.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/show.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/sql.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/update.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/man/vacuum.l </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/INSTALL </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/modules/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/license.terms </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/test/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/test/runtest </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/test/test.expected </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/test/test_mklang.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/test/test_queries.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/pl/tcl/test/test_setup.sql </entry><entry> Not converted </entry></row>
-<row><entry> ./src/test/bench/WISC-README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/test/locale/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/test/performance/results/PgSQL.970926 </entry><entry> Not converted </entry></row>
-<row><entry> ./src/test/regress/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/test/suite/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/RELEASE_CHANGES </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/SQL_keywords </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/backend/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/backend/flow.fig </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/backend/flow.jpg </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/make_keywords.README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/entab/entab.man </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/make_diff/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/mkldexport/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tools/pgindent/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/tutorial/README </entry><entry> Not converted </entry></row>
-<row><entry> ./src/utils/README </entry><entry> Not converted </entry></row>
-<row><entry> ./lib/pg_hba.conf.sample </entry><entry> Not converted </entry></row>
-<row><entry> ./lib/pg_geqo.sample </entry><entry> Not converted </entry></row>
-</tbody>
-</tgroup>
-</table>
-
-<sect2>
-<title>Document Structure</title>
-
-<para>
-There are currently five separate documents written in DocBook. Each document
-has a container source document which defines the DocBook environment and other
-document source files. These primary source files are located in
-<filename>doc/src/sgml/</filename>, along with many of the other source files
-used for the documentation. The primary source files are:
-
-<variablelist>
-<varlistentry>
-<term>postgres.sgml</term>
-<listitem>
-<para>
-This is the integrated document, including all other documents as parts.
-Output is generated in <acronym>HTML</acronym> since the browser interface
-makes it easy to move around all of the documentation by just clicking.
-The other documents are available in both <acronym>HTML</acronym> and hardcopy.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>tutorial.sgml</term>
-<listitem>
-<para>
-The introductory tutorial, with examples. Does not include programming topics,
-and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
-This is the "getting started" document.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>user.sgml</term>
-<listitem>
-<para>
-The User's Guide. Includes information on data types and user-level interfaces.
-This is the place to put information on "why".
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>reference.sgml</term>
-<listitem>
-<para>
-The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
-This is the place to put information on "how".
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>programming.sgml</term>
-<listitem>
-<para>
-The Programmer's Guide. Includes information on <productname>Postgres</productname>
-extensibility and on the programming interfaces.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>admin.sgml</term>
-<listitem>
-<para>
-The Administrator's Guide. Include installation and release notes.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-<sect1>
-<title>Introduction</title>
-
-<para>
-Packaged documentation is available in both
-<acronym>HTML</acronym> and <firstterm>Postscript</firstterm>
-formats. These are available as part of the standard
-<productname>Postgres</productname> installation. We discuss here
-working with the documentation sources and generating documentation
-packages.
-
-<note>
-<para>
-This is the first release of new <productname>Postgres</productname>
-documentation in three years. The content and environment are in flux
-and still evolving.
-</para>
-</note></para>
-
-<para>
-The purpose of <acronym>SGML</acronym> is to allow an author to
-specify the structure and content of a document (e.g. using the
-<productname>DocBook</productname> <acronym>DTD</acronym>), and to
-have the document style define how that content is rendered into a
-final form (e.g. using Norm Walsh's stylesheets).</para>
-
-<para>
-See <ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">
-Introduction to DocBook</ulink> for a nice "quickstart" summary of
-DocBook features.
-<ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/"> DocBook
-Elements</ulink> provides a powerful cross-reference for features of
-<productname>DocBook</productname>.</para>
-
-<para>
-This documentation set is constructed using several tools, including
-James Clark's
-<ulink url="http://www.jclark.com/jade/"> <productname>jade</productname></ulink>
- and Norm Walsh's
-<ulink url="http://www.berkshire.net/~norm/docbook/dsssl">Modular DocBook Stylesheets</ulink>.
-
-<para>
-Currently, hardcopy is produced by importing <firstterm>Rich Text
-Format</firstterm> (<acronym>RTF</acronym>) output from
-<application>jade</application> into
-<productname>ApplixWare</productname> for minor formatting fixups then
-exporting as a Postscript file.</para>
-
-<para>
-<ulink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/">
-<productname>TeX</productname></ulink> is a supported format for
-<application>jade</application> output, but was not used at this time
-for several reasons, including the inability to make minor format
-fixes before committing to hardcopy and generally inadequate table
-support in the <productname>TeX</productname>
-stylesheets.</para></sect1>
-
-<sect1>
-<title>Styles and Conventions</title>
-
-<para>
-<productname>DocBook</productname> has a rich set of tags and
-constructs, and a suprisingly large percentage are directly and
-obviously useful for well-formed documentation. The
-<productname>Postgres</productname> documentation set has only
-recently been adapted to <acronym>SGML</acronym>, and in the near
-future several sections of the set will be selected and maintained as
-prototypical examples of <productname>DocBook</productname> usage.
-Also, a short summary of <productname>DocBook</productname> tags will
-be included below.
-</para>
-
-<!--
-<para>
-<table tocentry="1">
-<title>SGML Constructs</title>
-<titleabbrev>SGML Constructs</titleabbrev>
-<tgroup cols="2">
-<thead>
- <row>
- <entry>SGML Tag</entry>
- <entry>Usage</entry>
- </row>
-</thead>
-<tbody>
- <row>
- <entry><sgmltag>Book</sgmltag></entry>
- <entry>Delimits a Book element</entry>
- </row>
- <row>
- <entry><sgmltag>Chapter</sgmltag></entry>
- <entry>Delimits a Chapter element</entry>
- </row>
- <row>
- <entry><sgmltag>Appendix</sgmltag></entry>
- <entry><sgmltag>Delimits a Appendix element</sgmltag></entry>
- </row>
-</tbody>
-</tgroup>
-</table>
-</para>
--->
-
-</sect1>
-
-<sect1>
-<title>Document Writing</title>
-
-<sect2>
-<title>Document Structure</title>
-
-<para>
-There are currently five separate documents written in DocBook. Each document
-has a container source document which defines the DocBook environment and other
-document source files. These primary source files are located in
-<filename>doc/src/sgml/</filename>, along with many of the other source files
-used for the documentation. The primary source files are:
-
-<variablelist>
-<varlistentry>
-<term>postgres.sgml</term>
-<listitem>
-<para>
-This is the integrated document, including all other documents.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>tutorial.sgml</term>
-<listitem>
-<para>
-The introductory tutorial, with examples. Does not include programming topics,
-and is intended to help get someone unfamiliar with <acronym>SQL</acronym> started.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>user.sgml</term>
-<listitem>
-<para>
-The User's Guide. Includes information on data types and user-level interfaces.
-This is the place to put information on "why".
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>reference.sgml</term>
-<listitem>
-<para>
-The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>programming.sgml</term>
-<listitem>
-<para>
-The Programmer's Guide. Includes information on <productname>Postgres</productname>
-extensibility and on the programming interfaces.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>admin.sgml</term>
-<listitem>
-<para>
-The Administrator's Guide. Include installation and release notes.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-<sect2>
-<title>Authoring Tools</title>
-
-<para>
-The current <acronym>Postgres</acronym> documentation set is written using
-a plain text editor (or emacs/psgml; see below) with the content marked up using
-<acronym>SGML</acronym>.
-
-<para>
-<acronym>SGML</acronym> and <productname>DocBook</productname> do not suffer
-from an oversupply of open-source authoring tools. The most common toolset is
-the emacs/xemacs editing package with the psgml feature extension.
-On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation.
-
-<sect3>
-<title>emacs/psgml</title>
-
-<para>
-When using emacs/psgml, a comfortable way of working with
-these separate files of book parts is to insert a proper DOCTYPE
-declaration while you're editing them. If you are working on this source, for instance,
-it's an appendix chapter, so you would specify the document as an "appendix" instance of
-a DocBook document by making the first line look like this:
-
-<programlisting>
-<sgmltag>!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"</sgmltag>
-</programlisting>
-
-This means that anything and everything that reads <acronym>SGML</acronym> will get it
-right, and I can verify the document with "nsgmls -s docguide.sgml".
-
-</sect3>
-</sect2>
-</sect1>
-
-<sect1>
-<title>Building Documentation</title>
-
-<para>
-GNU <application>make</application> is used to build documentation from the DocBook sources.
-There are a few environment definitions which may need to be set or modified for your installation.
-The <filename>Makefile</filename> looks for
-<filename>doc/../src/Makefile</filename>
-and (implicitly) for
-<filename>doc/../src/Makefile.custom</filename>
-to obtain environment information. On my system, the <filename>src/Makefile.custom</filename> looks like
-
-<programlisting>
-# Makefile.custom
-# Thomas Lockhart 1998-03-01
-
-POSTGRESDIR= /opt/postgres/current
-CFLAGS+= -m486
-YFLAGS+= -v
-
-# documentation
-
-HSTYLE= /home/tgl/SGML/db107.d/docbook/html
-PSTYLE= /home/tgl/SGML/db107.d/docbook/print
-</programlisting>
-
-where HSTYLE and PSTYLE determine the path to <filename>docbook.dsl</filename> for <acronym>HTML</acronym>
-and hardcopy (print) stylesheets, respectively. These stylesheet file names are for Norm Walsh's
-Modular Style Sheets; if other stylesheets are used then one can define HDSL and PDSL as the full path
-and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
-On many systems, these stylesheets will be found in packages installed in
-<filename>/usr/lib/sgml/</filename>,
-<filename>/usr/share/lib/sgml/</filename>,
-or
-<filename>/usr/local/lib/sgml/</filename>.
-
-<para>
-<acronym>HTML</acronym> documentation packages can be generated from the <acronym>SGML</acronym> source by
-typing
+<!-- doc/src/sgml/docguide.sgml -->
+
+<appendix id="docguide">
+ <title>Documentation</title>
+
+ <para>
+ <productname>PostgreSQL</productname> has four primary documentation
+ formats:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Plain text, for pre-installation information
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <acronym>HTML</acronym>, for on-line browsing and reference
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ PDF or PostScript, for printing
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ man pages, for quick reference.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Additionally, a number of plain-text <filename>README</filename> files can
+ be found throughout the <productname>PostgreSQL</productname> source tree,
+ documenting various implementation issues.
+ </para>
+
+ <para>
+ <acronym>HTML</acronym> documentation and man pages are part of a
+ standard distribution and are installed by default. PDF and
+ PostScript format documentation is available separately for
+ download.
+ </para>
+
+ <sect1 id="docguide-docbook">
+ <title>DocBook</title>
+ <para>
+ The documentation sources are written in
+ <firstterm>DocBook</firstterm>, which is a markup language
+ superficially similar to <acronym>HTML</acronym>. Both of these
+ languages are applications of the <firstterm>Standard Generalized
+ Markup Language</firstterm>, <acronym>SGML</acronym>, which is
+ essentially a language for describing other languages. In what
+ follows, the terms DocBook and <acronym>SGML</acronym> are both
+ used, but technically they are not interchangeable.
+ </para>
+
+ <para>
+ <productname>DocBook</productname> allows an author to specify the
+ structure and content of a technical document without worrying
+ about presentation details. A document style defines how that
+ content is rendered into one of several final forms. DocBook is
+ maintained by the <ulink url="http://www.oasis-open.org">
+ OASIS group</ulink>. The <ulink url="http://www.oasis-open.org/docbook/">
+ official DocBook site</ulink> has good introductory and reference documentation and
+ a complete O'Reilly book for your online reading pleasure. The
+ <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
+ NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
+ The <ulink url="http://www.freebsd.org/docproj/docproj.html">
+ FreeBSD Documentation Project</ulink> also uses DocBook and has some good
+ information, including a number of style guidelines that might be
+ worth considering.
+ </para>
+ </sect1>
+
+
+ <sect1 id="docguide-toolsets">
+ <title>Tool Sets</title>
+
+ <para>
+ The following tools are used to process the documentation. Some
+ might be optional, as noted.
+
+ <variablelist>
+ <varlistentry>
+ <term><ulink url="http://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
+ <listitem>
+ <para>
+ This is the definition of DocBook itself. We currently use
+ version 4.2; you cannot use later or earlier versions. You
+ need the <acronym>SGML</acronym> variant of the DocBook DTD,
+ but to build man pages you also need the <acronym>XML</acronym>
+ variant of the same version.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
+ <listitem>
+ <para>
+ These are required by DocBook but are distributed separately
+ because they are maintained by ISO.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://wiki.docbook.org/DocBookDssslStylesheetDocs">DocBook DSSSL Stylesheets</ulink></term>
+ <listitem>
+ <para>
+ These contain the processing instructions for converting the
+ DocBook sources to other formats, such as
+ <acronym>HTML</acronym>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://wiki.docbook.org/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
+ <listitem>
+ <para>
+ This is another stylesheet for converting DocBook to other
+ formats. We currently use this to produce man pages and
+ optionally HTMLHelp. You can also use this toolchain to
+ produce HTML or PDF output, but official PostgreSQL releases
+ use the DSSSL stylesheets for that.
+ </para>
+
+ <para>
+ The minimum required version is currently 1.74.0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
+ <listitem>
+ <para>
+ This is the base package of <acronym>SGML</acronym> processing.
+ It contains an <acronym>SGML</acronym> parser, a
+ <acronym>DSSSL</acronym> processor (that is, a program to
+ convert <acronym>SGML</acronym> to other formats using
+ <acronym>DSSSL</acronym> stylesheets), as well as a number of
+ related tools. <productname>Jade</productname> is now being
+ maintained by the OpenJade group, no longer by James Clark.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
+ <listitem>
+ <para>
+ This library and the <command>xmllint</command> tool it contains are
+ used for processing XML. Many developers will already
+ have <application>Libxml2</application> installed, because it is also
+ used when building the PostgreSQL code. Note, however,
+ that <command>xmllint</command> might need to be installed from a
+ separate subpackage.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
+ <listitem>
+ <para>
+ This is the processing tool to use with the XSLT stylesheets
+ (like <command>jade</command> is the processing tool for DSSSL
+ stylesheets).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
+ <listitem>
+ <para>
+ If you want to, you can also install
+ <productname>JadeTeX</productname> to use
+ <productname>TeX</productname> as a formatting backend for
+ <productname>Jade</productname>.
+ <application>JadeTeX</application> can create PostScript or
+ <acronym>PDF</acronym> files (the latter with bookmarks).
+ </para>
+
+ <para>
+ However, the output from <application>JadeTeX</application> is
+ inferior to what you get from the <acronym>RTF</acronym>
+ backend. Particular problem areas are tables and various
+ artifacts of vertical and horizontal spacing. Also, there is
+ no opportunity to manually polish the results.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ We have documented experience with several installation methods for
+ the various tools that are needed to process the documentation.
+ These will be described below. There might be some other packaged
+ distributions for these tools. Please report package status to the
+ documentation mailing list, and we will include that information
+ here.
+ </para>
+
+ <sect2>
+ <title>Installation on Fedora, RHEL, and Derivatives</title>
+
+ <para>
+ To install the required packages, use:
<programlisting>
-% cd doc/src
-% make tutorial.tar.gz
-% make user.tar.gz
-% make admin.tar.gz
-% make programmer.tar.gz
-% make postgres.tar.gz
-% make install
+yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade
</programlisting>
-</para>
-
-<para>
-These packages can be installed from the main documentation directory
-by typing
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Installation on FreeBSD</title>
+
+ <para>
+ The FreeBSD Documentation Project is itself a heavy user of
+ DocBook, so it comes as no surprise that there is a full set of
+ <quote>ports</quote> of the documentation tools available on
+ FreeBSD. The following ports need to be installed to build the
+ documentation on FreeBSD.
+ <itemizedlist>
+ <listitem>
+ <para><filename>textproc/docbook-sgml</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename>textproc/docbook-xml</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename>textproc/docbook-xsl</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename>textproc/dsssl-docbook-modular</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename>textproc/libxslt</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename>textproc/openjade</filename></para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ A number of things from <filename>/usr/ports/print</filename>
+ (<filename>tex</filename>, <filename>jadetex</filename>) might
+ also be of interest.
+ </para>
+
+ <para>
+ More information about the FreeBSD documentation tools can be
+ found in the <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">
+ FreeBSD Documentation Project's instructions</ulink>.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Debian Packages</title>
+
+ <para>
+ There is a full set of packages of the documentation tools
+ available for <productname>Debian GNU/Linux</productname>.
+ To install, simply use:
<programlisting>
-% cd doc
-% make install
+apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc
</programlisting>
-</para></sect1>
-
-<sect1>
-<title>Hardcopy Generation for v6.3</title>
+ </para>
+ </sect2>
-<para>
-The hardcopy Postscript documentation is generated by converting the
-<acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
-importing into Applixware. After a little cleanup (see the following
-section) the output is "printed" to a postscript file.</para>
+ <sect2>
+ <title>OS X</title>
-<para>
-Some figures were redrawn to avoid having bitmap
-<acronym>GIF</acronym> files in the hardcopy documentation. One
-figure, of the system catalogs, was sufficiently complex that there
-was not time to redraw it. It was converted to fit using the
-following commands:
-
-<programlisting>
-% convert -v -geometry 400x400'>' figure03.gif con.gif
-% convert -v -crop 400x380 con.gif connections.gif
-</programlisting></para>
-
-<sect2>
-<title><acronym>RTF</acronym> Cleanup Procedure</title>
-
-<para>
-Several items must be addressed in generating Postscript
-hardcopy:</para>
-
-<procedure>
-<title>Applixware <acronym>RTF</acronym> Cleanup</title>
-
-<para>
-Applixware does not seem to do a complete job of importing <acronym>RTF</acronym>
-generated by jade/MSS. In particular, all text is given the
-<quote>Header1</quote> style attribute label, although the text
-formatting itself is acceptable. Also, the Table of Contents page
-numbers do not refer to the section listed in the table, but rather
-refer to the page of the ToC itself.</para>
-
-<step performance="required">
-<para>
-Generate the <acronym>RTF</acronym> input by typing
+ <para>
+ If you use MacPorts, the following will get you set up:
<programlisting>
-% cd doc/src/sgml
-% make tutorial.rtf
+sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp
</programlisting>
-</para>
-</step>
-
-<step performance="required">
-<para>
-Open a new document in <productname>Applix Words</productname> and
-then import the <acronym>RTF</acronym> file.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Print out the existing Table of Contents, to mark up in the following
-few steps.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Insert figures into the document. Center each figure on the page using
-the centering margins button.</para>
-
-<para>
-Not all documents have figures. You can grep the <acronym>SGML</acronym> source files for
-the string <quote>Graphic</quote> to identify those parts of the
-documentation which may have figures. A few figures are replicated in
-various parts of the documentation.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Work through the document, adjusting page breaks and table column
-widths.
-</para>
-</step>
-
-<step performance="required">
-<para>
-If a bibliography is present, Applix Words seems to mark all remaining
-text after the first title as having an underlined attribute. Select
-all remaining text, turn off underlining using the underlining button,
-then explicitly underline each document and book title.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Work through the document, marking up the ToC hardcopy with the actual
-page number of each ToC entry.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Replace the right-justified incorrect page numbers in the ToC with
-correct values. This only takes a few minutes per document.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Save the document as native Applix Words format to allow easier last
-minute editing later.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Export the document to a file in Postscript format.
-</para>
-</step>
-
-<step performance="required">
-<para>
-Compress the Postscript file using <application>gzip</application>.
-Place the compressed file into the <filename>doc</filename> directory.
-</para>
-</step>
-</procedure>
-
-</sect2>
-</sect1>
-
-<sect1>
-<title>Toolsets</title>
-
-<para>
-We have documented experience with two installation methods for the
-various tools that are needed to process the documentation. One is
-installation from <acronym>RPM</acronym>s on
-<productname>Linux</productname>, the other is a general installation
-from original distributions of the individual tools. Both will be
-described below.</para>
-
-<para>
-We understand that there are some other packaged distributions for
-these tools. <productname>FreeBSD</productname> seems to have them
-available. Please report package status to the docs mailing list and
-we will include that information here.</para>
-
-<sect2>
-<title><acronym>RPM</acronym> installation on
-<productname>Linux</productname></title>
-
-<para>
-Install <ulink url="ftp://ftp.cygnus.com/pub/home/rosalia/">
-<acronym>RPM</acronym>s</ulink> for <productname>Jade</productname>
-and related packages.
-</para>
-</sect2>
-
-<sect2>
-<title>Manual installation of tools</title>
-
-<para>This is a brief run-through of the process of obtaining and
-installing the software you'll need to edit DocBook source with Emacs
-and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym>
-and <acronym>RTF</acronym>.</para>
-
-<sect3><title>Prerequisites</title>
-
-<para>What you need:
-
-<itemizedlist>
-<listitem><para>A working installation of GCC 2.7.2</para></listitem>
-<listitem><para>A working installation of Emacs 19.19 or later</para></listitem>
-<listitem><para>An unzip program for UNIX to unpack things</para></listitem>
-</itemizedlist>
-
-</para>
-
-<para>What you must fetch:
-
-<itemizedlist>
-<listitem>
-<para><ulink url="ftp://ftp.jclark.com/pub/jade/jade1_1.zip">
-James Clark's <productname>Jade</productname> version 1.1</ulink>
-</para></listitem>
-<listitem>
-<para><ulink url="http://www.ora.com/davenport/docbook/current/docbk30.zip">
-<productname>DocBook</productname> version 3.0</ulink>
-</para></listitem>
-<listitem>
-<para><ulink url="http://nwalsh.com/docbook/dsssl/db107.zip">
-Norman Walsh's <productname>Modular Stylesheets</productname>
-version 1.07</ulink>
-</para></listitem>
-<listitem>
-<para><ulink url="ftp://ftp.lysator.liu.se/pub/sgml/psgml-1.0.1.tar.gz">
-Lennart Staflin's <productname>PSGML</productname> version 1.0.1</ulink>
-</para></listitem>
-</itemizedlist>
-
-</para>
-
-<para>Important URLs:
-
-<itemizedlist>
-<listitem><para><ulink url="http://www.jclark.com/jade/">
-The <productname>Jade</productname> web page</ulink></para></listitem>
-<listitem><para><ulink url="http://www.ora.com/davenport/">
-The <productname>DocBook</productname> web page</ulink></para></listitem>
-<listitem><para><ulink url="http://nwalsh.com/docbook/dsssl/">
-The <productname>Modular Stylesheets</productname> web page</ulink>
-</para></listitem>
-<listitem><para>
-<ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
-The <productname>PSGML</productname> web page</ulink></para></listitem>
-<listitem><para><ulink url="http://www.infotek.no/sgmltool/guide.htm">
-Steve Pepper's Whirlwind Guide</ulink></para></listitem>
-<listitem><para><ulink url="http://www.sil.org/sgml/publicSW.html">
-Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem>
-</itemizedlist>
-
-</para>
-
-</sect3>
-
-<sect3><title>Installing Jade</title>
-
-<para>First, read the installation instructions at the above listed
-URL.</para>
-
-<para>Unzip the distribution kit in a suitable place. The command to do
-this will be something like
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Manual Installation from Source</title>
+
+ <para>
+ The manual installation process of the DocBook tools is somewhat
+ complex, so if you have pre-built packages available, use them.
+ We describe here only a standard setup, with reasonably standard
+ installation paths, and no <quote>fancy</quote> features. For
+ details, you should study the documentation of the respective
+ package, and read <acronym>SGML</acronym> introductory material.
+ </para>
+
+ <sect3>
+ <title>Installing OpenJade</title>
+
+ <procedure>
+ <step>
+ <para>
+ The installation of OpenJade offers a GNU-style
+ <literal>./configure; make; make install</literal> build
+ process. Details can be found in the OpenJade source
+ distribution. In a nutshell:
+<synopsis>
+./configure --enable-default-catalog=/usr/local/share/sgml/catalog
+make
+make install
+</synopsis>
+ Be sure to remember where you put the <quote>default
+ catalog</quote>; you will need it below. You can also leave
+ it off, but then you will have to set the environment variable
+ <envar>SGML_CATALOG_FILES</envar> to point to the file
+ whenever you use <application>jade</application> later on.
+ (This method is also an option if OpenJade is already
+ installed and you want to install the rest of the toolchain
+ locally.)
+ </para>
+
+ <note>
+ <para>
+ Some users have reported encountering a segmentation fault using
+ OpenJade 1.4devel to build the PDFs, with a message like:
+<screen>
+openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted
+make: *** [postgres-A4.tex-pdf] Segmentation fault
+</screen>
+ Downgrading to OpenJade 1.3 should get rid of this error.
+ </para>
+ </note>
+
+ </step>
+
+ <step id="doc-openjade-install">
+ <para>
+ Additionally, you should install the files
+ <filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
+ <filename>style-sheet.dtd</filename>, and
+ <filename>catalog</filename> from the
+ <filename>dsssl</filename> directory somewhere, perhaps into
+ <filename>/usr/local/share/sgml/dsssl</filename>. It's
+ probably easiest to copy the entire directory:
+<synopsis>
+cp -R dsssl /usr/local/share/sgml
+</synopsis>
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Finally, create the file
+ <filename>/usr/local/share/sgml/catalog</filename> and add
+ this line to it:
<programlisting>
-unzip -aU jade1_1.zip
+CATALOG "dsssl/catalog"
</programlisting>
-</para>
-
-<para><productname>Jade</productname> is not built using
-<productname>GNU Autoconf</productname>, so you'll need to edit a
-<filename>Makefile</filename> yourself. Since James Clark has been
-good enough to prepare his kit for it, it is a good idea to make a
-build directory (named for your machine architecture, perhaps) under
-the main directory of the <productname>Jade</productname>
-distribution, copy the file <filename>Makefile</filename> from the
-main directory into it, edit it there, and then run
-<command>make</command> there.</para>
-
-<para>However, the <filename>Makefile</filename> does need to be
-edited. There is a file called <filename>Makefile.jade</filename> in
-the main directory, which is intended to be used with <command>make -f
-Makefile.jade</command> when building <productname>Jade</productname>
-(as opposed to just <productname>SP</productname>, the <acronym>SGML</acronym> parser kit
-that <productname>Jade</productname> is built upon). We suggest that
-you don't do that, though, since there is more that you need to change
-than what is in <filename>Makefile.jade</filename>, so you'd have to
-edit one of them anyway.</para>
-
-<para>Go through the <filename>Makefile</filename>, reading James'
-instructions and editing as needed. There are various variables that
-need to be set. Here is a collected summary of the most important
-ones, with typical values:
+ (This is a relative path reference to the file installed in
+ <xref linkend="doc-openjade-install">. Be sure to adjust it
+ if you chose your installation layout differently.)
+ </para>
+ </step>
+ </procedure>
+ </sect3>
+
+ <sect3>
+ <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
+
+ <procedure>
+ <step>
+ <para>
+ Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">
+ DocBook V4.2 distribution</ulink>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Create the directory
+ <filename>/usr/local/share/sgml/docbook-4.2</filename> and change
+ to it. (The exact location is irrelevant, but this one is
+ reasonable within the layout we are following here.)
+<screen>
+<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
+<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
+</screen>
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Unpack the archive:
+<screen>
+<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
+</screen>
+ (The archive will unpack its files into the current directory.)
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Edit the file
+ <filename>/usr/local/share/sgml/catalog</filename> (or whatever
+ you told jade during installation) and put a line like this
+ into it:
<programlisting>
-prefix = /usr/local
-XDEFINES = -DSGML_CATALOG_FILES_DEFAULT=\"/usr/local/share/sgml/catalog\"
-XLIBS = -lm
-RANLIB = ranlib
-srcdir = ..
-XLIBDIRS = grove spgrove style
-XPROGDIRS = jade
+CATALOG "docbook-4.2/docbook.cat"
</programlisting>
-Note the specification of where to find the default catalog of
-<acronym>SGML</acronym> support files -- you may want to change that
-to something more suitable for your own installation. If your system
-doesn't need the above settings for the math library and the
-<command>ranlib</command> command, leave them as they are in the
-<filename>Makefile</filename>.
-</para>
-
-<para>Now type <command>make</command> to build Jade and the various
-<productname>SP</productname> tools.</para>
-
-<para>Once the software is built, <command>make install</command> will
-do the obvious.</para>
-
-</sect3>
-
-<sect3><title>Installing the <productname>DocBook</productname>
-<acronym>DTD</acronym> kit</title>
-
-<para>You'll want to place the files that make up the
-<productname>DocBook</productname> <acronym>DTD</acronym> kit in the
-directory you built <productname>Jade</productname> to expect them in,
-which, if you followed our suggestion above, is
-<filename>/usr/local/share/sgml/</filename>. In addition to the
-actual <productname>DocBook</productname> files, you'll need to have a
-<filename>catalog</filename> file in place, for the mapping of
-document type specifications and external entity references to actual
-files in that directory. You'll also want the <acronym>ISO</acronym>
-character set mappings, and probably one or more versions of
-<acronym>HTML</acronym>.</para>
-
-<para>One way to install the various <acronym>DTD</acronym> and
-support files and set up the <filename>catalog</filename> file, is to
-collect them all into the above mentioned directory, use a single file
-named <filename>CATALOG</filename> to describe them all, and then
-create the file <filename>catalog</filename> as a catalog pointer to
-the former, by giving it the single line of content:
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
+ ISO 8879 character entities archive</ulink>, unpack it, and put the
+ files in the same directory you put the DocBook files in:
+<screen>
+<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
+<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
+</screen>
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Run the following command in the directory with the DocBook and ISO files:
<programlisting>
-CATALOG /usr/local/share/sgml/CATALOG
+perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
</programlisting>
-The <filename>CATALOG</filename> file should then contain three types
-of lines. The first is the (optional) <acronym>SGML</acronym>
-declaration, thus:
+ (This fixes a mixup between the names used in the DocBook
+ catalog file and the actual names of the ISO character entity
+ files.)
+ </para>
+ </step>
+ </procedure>
+ </sect3>
+
+ <sect3>
+ <title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>
+
+ <para>
+ To install the style sheets, unzip and untar the distribution and
+ move it to a suitable place, for example
+ <filename>/usr/local/share/sgml</filename>. (The archive will
+ automatically create a subdirectory.)
+<screen>
+<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
+<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
+</screen>
+ </para>
+
+ <para>
+ The usual catalog entry in
+ <filename>/usr/local/share/sgml/catalog</filename> can also be
+ made:
<programlisting>
-SGMLDECL docbook.dcl
+CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog"
</programlisting>
-Next, the various references to <acronym>DTD</acronym> and entity
-files must be resolved. For the <productname>DocBook</productname>
-files, these lines look like this:
+ Because stylesheets change rather often, and it's sometimes
+ beneficial to try out alternative versions,
+ <productname>PostgreSQL</productname> doesn't use this catalog
+ entry. See <xref linkend="docguide-toolsets-configure"> for
+ information about how to select the stylesheets instead.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Installing <productname>JadeTeX</productname></title>
+
+ <para>
+ To install and use <productname>JadeTeX</productname>, you will
+ need a working installation of <productname>TeX</productname> and
+ <productname>LaTeX2e</productname>, including the supported
+ <productname>tools</productname> and
+ <productname>graphics</productname> packages,
+ <productname>Babel</productname>,
+ <productname><acronym>AMS</acronym> fonts</productname> and
+ <productname>AMS-LaTeX</productname>, the
+ <productname><acronym>PSNFSS</acronym></productname> extension
+ and companion kit of <quote>the 35 fonts</quote>, the
+ <productname>dvips</productname> program for generating
+ <productname>PostScript</productname>, the macro packages
+ <productname>fancyhdr</productname>,
+ <productname>hyperref</productname>,
+ <productname>minitoc</productname>,
+ <productname>url</productname> and
+ <productname>ot2enc</productname>. All of these can be found on
+ your friendly neighborhood <ulink url="http://www.ctan.org">
+ <acronym>CTAN</acronym> site</ulink>.
+ The installation of the <application>TeX</application> base
+ system is far beyond the scope of this introduction. Binary
+ packages should be available for any system that can run
+ <application>TeX</application>.
+ </para>
+
+ <para>
+ Before you can use <application>JadeTeX</application> with the
+ <productname>PostgreSQL</productname> documentation sources, you
+ will need to increase the size of
+ <application>TeX</application>'s internal data structures.
+ Details on this can be found in the <application>JadeTeX</application>
+ installation instructions.
+ </para>
+
+ <para>
+ Once that is finished you can install <application>JadeTeX</application>:
+<screen>
+<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
+<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
+<prompt>$</prompt> <userinput>cd jadetex</userinput>
+<prompt>$</prompt> <userinput>make install</userinput>
+<prompt>$</prompt> <userinput>mktexlsr</userinput>
+</screen>
+ The last two need to be done as <systemitem>root</systemitem>.
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="docguide-toolsets-configure">
+ <title>Detection by <command>configure</command></title>
+
+ <para>
+ Before you can build the documentation you need to run the
+ <filename>configure</filename> script as you would when building
+ the <productname>PostgreSQL</productname> programs themselves.
+ Check the output near the end of the run, it should look something
+ like this:
+<screen>
+<computeroutput>
+checking for onsgmls... onsgmls
+checking for openjade... openjade
+checking for DocBook V4.2... yes
+checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular
+checking for collateindex.pl... /usr/bin/collateindex.pl
+checking for xsltproc... xsltproc
+checking for osx... osx
+</computeroutput>
+</screen>
+ If neither <filename>onsgmls</filename> nor
+ <filename>nsgmls</filename> were found then some of the following tests
+ will be skipped. <filename>nsgmls</filename> is part of the Jade
+ package. You can pass the environment variables
+ <envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point
+ to the programs if they are not found automatically. If
+ <quote>DocBook V4.2</quote> was not found then you did not install
+ the DocBook DTD kit in a place where Jade can find it, or you have
+ not set up the catalog files correctly. See the installation hints
+ above. The DocBook stylesheets are looked for in a number of
+ relatively standard places, but if you have them some other place
+ then you should set the environment variable
+ <envar>DOCBOOKSTYLE</envar> to the location and rerun
+ <filename>configure</filename> afterwards.
+ </para>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="docguide-build">
+ <title>Building The Documentation</title>
+
+ <para>
+ Once you have everything set up, change to the directory
+ <filename>doc/src/sgml</filename> and run one of the commands
+ described in the following subsections to build the
+ documentation. (Remember to use GNU make.)
+ </para>
+
+ <sect2>
+ <title>HTML</title>
+
+ <para>
+ To build the <acronym>HTML</acronym> version of the documentation:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make html</userinput>
+</screen>
+ This is also the default target. The output appears in the
+ subdirectory <filename>html</filename>.
+ </para>
+
+ <para>
+ To create a proper index, the build might process several identical
+ stages. If you do not care about the index, and just want to
+ proof-read the output, use <literal>draft</>:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make draft</userinput>
+</screen>
+ </para>
+
+ <para>
+ To build the documentation as a single HTML page, use:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres.html</userinput>
+</screen>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Manpages</title>
+
+ <para>
+ We use the DocBook XSL stylesheets to
+ convert <productname>DocBook</productname>
+ <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
+ pages. The man pages are also distributed as a tar archive,
+ similar to the <acronym>HTML</acronym> version. To create the man
+ pages, use the commands:
<programlisting>
-PUBLIC "-//Davenport//DTD DocBook V3.0//EN" docbook.dtd
-PUBLIC "-//USA-DOD//DTD Table Model 951010//EN" cals-tbl.dtd
-PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
-PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
-PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
+cd doc/src/sgml
+make man
</programlisting>
-Of course, a file containing these comes with the
-<productname>DocBook</productname> kit. Note that the last item on
-each of these lines is a file name, given here without a path. You
-can put the files in subdirectories of your main
-<acronym>SGML</acronym> directory if you like, of course, and modify
-the reference in the <filename>CATALOG</filename> file.
-<productname>DocBook</productname> also references the
-<acronym>ISO</acronym> character set entities, so you need to fetch
-and install these (they are available from several sources, and are
-easily found by way of the URLs listed above), along with catalog
-entries for all of them, such as:
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Print Output via <application>JadeTeX</application></title>
+
+ <para>
+ If you want to use <application>JadeTex</application> to produce a
+ printable rendition of the documentation, you can use one of the
+ following commands:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ To generate PostScript via <acronym>DVI</acronym> in A4 format:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.ps</userinput>
+</screen>
+ In U.S. letter format:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.ps</userinput>
+</screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To make a <acronym>PDF</acronym>:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput>
+</screen>
+ or:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput>
+</screen>
+ (Of course you can also make a <acronym>PDF</acronym> version
+ from the PostScript, but if you generate <acronym>PDF</acronym>
+ directly, it will have hyperlinks and other enhanced features.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ When using JadeTeX to build the PostgreSQL documentation, you will
+ probably need to increase some of TeX's internal parameters. These
+ can be set in the file <filename>texmf.cnf</filename>. The following
+ settings worked at the time of this writing:
<programlisting>
-PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" ISO/ISOlat1
+hash_extra.jadetex = 200000
+hash_extra.pdfjadetex = 200000
+pool_size.jadetex = 2000000
+pool_size.pdfjadetex = 2000000
+string_vacancies.jadetex = 150000
+string_vacancies.pdfjadetex = 150000
+max_strings.jadetex = 300000
+max_strings.pdfjadetex = 300000
+save_size.jadetex = 15000
+save_size.pdfjadetex = 15000
</programlisting>
-Note how the file name here contains a directory name, showing that
-we've placed the <acronym>ISO</acronym> entity files in a subdirectory
-named <filename>ISO</filename>. Again, proper catalog entries should
-accompany the entity kit you fetch.
-</para>
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Overflow Text</title>
+
+ <para>
+ Occasionally text is too wide for the printed margins, and in
+ extreme cases, too wide for the printed page, e.g. non-wrapped
+ text, wide tables. Overly wide text generates <quote>Overfull
+ hbox</quote> messages in the TeX log output file, e.g.
+ <filename>postgres-US.log</> or <filename>postgres-A4.log</>.
+ There are 72 points in an inch so anything reported as over 72
+ points too wide will probably not fit on the printed page (assuming
+ one inch margins). To find the <acronym>SGML</acronym> text
+ causing the overflow, find the first page number mentioned above
+ the overflow message, e.g. <literal>[50 ###]</> (page 50), and
+ look at the page after that (e.g. page 51) in the <acronym>PDF</acronym>
+ file to see the overflow text and adjust the <acronym>SGML</acronym>
+ accordingly.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Print Output via <acronym>RTF</acronym></title>
+
+ <para>
+ You can also create a printable version of the <productname>PostgreSQL</productname>
+ documentation by converting it to <acronym>RTF</acronym> and
+ applying minor formatting corrections using an office suite.
+ Depending on the capabilities of the particular office suite, you
+ can then convert the documentation to PostScript of
+ <acronym>PDF</acronym>. The procedure below illustrates this
+ process using <productname>Applixware</productname>.
+ </para>
+
+ <note>
+ <para>
+ It appears that current versions of the <productname>PostgreSQL</productname> documentation
+ trigger some bug in or exceed the size limit of OpenJade. If the
+ build process of the <acronym>RTF</acronym> version hangs for a
+ long time and the output file still has size 0, then you might have
+ hit that problem. (But keep in mind that a normal build takes 5
+ to 10 minutes, so don't abort too soon.)
+ </para>
+ </note>
+
+ <procedure>
+ <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
+
+ <para>
+ <application>OpenJade</application> omits specifying a default
+ style for body text. In the past, this undiagnosed problem led to
+ a long process of table of contents generation. However, with
+ great help from the <productname>Applixware</productname> folks
+ the symptom was diagnosed and a workaround is available.
+ </para>
+
+ <step performance="required">
+ <para>
+ Generate the <acronym>RTF</acronym> version by typing:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make postgres.rtf</userinput>
+</screen>
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Repair the RTF file to correctly specify all styles, in
+ particular the default style. If the document contains
+ <sgmltag>refentry</sgmltag> sections, one must also replace
+ formatting hints which tie a preceding paragraph to the current
+ paragraph, and instead tie the current paragraph to the
+ following one. A utility, <command>fixrtf</command>, is
+ available in <filename>doc/src/sgml</filename> to accomplish
+ these repairs:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
+</screen>
+ </para>
+
+ <para>
+ The script adds <literal>{\s0 Normal;}</literal> as the zeroth
+ style in the document. According to
+ <productname>Applixware</productname>, the RTF standard would
+ prohibit adding an implicit zeroth style, though Microsoft Word
+ happens to handle this case. For repairing
+ <sgmltag>refentry</sgmltag> sections, the script replaces
+ <literal>\keepn</literal> tags with <literal>\keep</literal>.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Open a new document in <productname>Applixware Words</productname> and
+ then import the <acronym>RTF</acronym> file.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Generate a new table of contents (ToC) using
+ <productname>Applixware</productname>.
+ </para>
+
+ <substeps>
+ <step>
+ <para>
+ Select the existing ToC lines, from the beginning of the first
+ character on the first line to the last character of the last
+ line.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Build a new ToC using
+ <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
+ Building</guisubmenu><guimenuitem>Create Table of
+ Contents</guimenuitem></menuchoice>. Select the first three
+ levels of headers for inclusion in the ToC. This will replace
+ the existing lines imported in the RTF with a native
+ <productname>Applixware</productname> ToC.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Adjust the ToC formatting by using
+ <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
+ selecting each of the three ToC styles, and adjusting the
+ indents for <literal>First</literal> and
+ <literal>Left</literal>. Use the following values:
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Style</entry>
+ <entry>First Indent (inches)</entry>
+ <entry>Left Indent (inches)</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>TOC-Heading 1</literal></entry>
+ <entry><literal>0.4</literal></entry>
+ <entry><literal>0.4</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>TOC-Heading 2</literal></entry>
+ <entry><literal>0.8</literal></entry>
+ <entry><literal>0.8</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>TOC-Heading 3</literal></entry>
+ <entry><literal>1.2</literal></entry>
+ <entry><literal>1.2</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </step>
+ </substeps>
+ </step>
+
+ <step performance="required">
+ <para>
+ Work through the document to:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Adjust page breaks.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Adjust table column widths.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Replace the right-justified page numbers in the Examples and
+ Figures portions of the ToC with correct values. This only takes
+ a few minutes.
+ </para>
+ </step>
+
+ <step performance="optional">
+ <para>
+ Delete the index section from the document if it is empty.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Regenerate and adjust the table of contents.
+ </para>
+
+ <substeps>
+ <step>
+ <para>
+ Select the ToC field.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
+ Building</guisubmenu><guimenuitem>Create Table of
+ Contents</guimenuitem></menuchoice>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Unbind the ToC by selecting
+ <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
+ Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Delete the first line in the ToC, which is an entry for the
+ ToC itself.
+ </para>
+ </step>
+ </substeps>
+ </step>
+
+ <step performance="required">
+ <para>
+ Save the document as native <productname>Applixware
+ Words</productname> format to allow easier last minute editing
+ later.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ <quote>Print</quote> the document
+ to a file in PostScript format.
+ </para>
+ </step>
+ </procedure>
+ </sect2>
+
+ <sect2>
+ <title>Plain Text Files</title>
+
+ <para>
+ The installation instructions are also distributed as plain text,
+ in case they are needed in a situation where better reading tools
+ are not available. The <filename>INSTALL</filename> file
+ corresponds to <xref linkend="installation">, with some minor
+ changes to account for the different context. To recreate the
+ file, change to the directory <filename>doc/src/sgml</filename>
+ and enter <userinput>make INSTALL</userinput>.
+ </para>
+
+ <para>
+ In the past, the release notes and regression testing instructions
+ were also distributed as plain text, but this practice has been
+ discontinued.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Syntax Check</title>
+
+ <para>
+ Building the documentation can take very long. But there is a
+ method to just check the correct syntax of the documentation
+ files, which only takes a few seconds:
+<screen>
+<prompt>doc/src/sgml$ </prompt><userinput>make check</userinput>
+</screen>
+ </para>
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="docguide-authoring">
+ <title>Documentation Authoring</title>
+
+ <para>
+ <acronym>SGML</acronym> and <productname>DocBook</productname> do
+ not suffer from an oversupply of open-source authoring tools. The
+ most common tool set is the
+ <productname>Emacs</productname>/<productname>XEmacs</productname>
+ editor with appropriate editing mode. On some systems
+ these tools are provided in a typical full installation.
+ </para>
+
+ <sect2>
+ <title>Emacs/PSGML</title>
+
+ <para>
+ <productname>PSGML</productname> is the most common and most
+ powerful mode for editing <acronym>SGML</acronym> documents.
+ When properly configured, it will allow you to use
+ <application>Emacs</application> to insert tags and check markup
+ consistency. You could use it for <acronym>HTML</acronym> as
+ well. Check the <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
+ PSGML web site</ulink> for downloads, installation instructions, and
+ detailed documentation.
+ </para>
+
+ <para>
+ There is one important thing to note with
+ <productname>PSGML</productname>: its author assumed that your
+ main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
+ would be <filename>/usr/local/lib/sgml</filename>. If, as in the
+ examples in this chapter, you use
+ <filename>/usr/local/share/sgml</filename>, you have to
+ compensate for this, either by setting
+ <envar>SGML_CATALOG_FILES</envar> environment variable, or you
+ can customize your <productname>PSGML</productname> installation
+ (its manual tells you how).
+ </para>
+
+ <para>
+ Put the following in your <filename>~/.emacs</filename>
+ environment file (adjusting the path names to be appropriate for
+ your system):
-</sect3>
-
-<sect3><title>Installing Norman Walsh's <acronym>DSSSL</acronym>
-style sheets</title>
-
-<para>First, read the installation instructions at the above listed
-URL.</para>
-
-<para>To install Norman's style sheets, simply unzip the distribution
-kit in a suitable place. A good place to dot this would be
-<filename>/usr/local/share</filename>, which places the kit in a
-directory tree under <filename>/usr/local/share/docbook</filename>.
-The command will be something like
<programlisting>
-unzip -aU db107.zip
+; ********** for SGML mode (psgml)
+
+(setq sgml-omittag t)
+(setq sgml-shorttag t)
+(setq sgml-minimize-attributes nil)
+(setq sgml-always-quote-attributes t)
+(setq sgml-indent-step 1)
+(setq sgml-indent-data t)
+(setq sgml-parent-document nil)
+(setq sgml-exposed-tags nil)
+(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
+
+(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
</programlisting>
-</para>
-<para>One way to test the installation is to build the
-<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
-<productname>PostgreSQL</productname> manual. Go to the <acronym>SGML</acronym> source
-directory, <filename>doc/src/sgml</filename>, and say
-<programlisting>
-jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
-</programlisting>
-to build the <acronym>HTML</acronym> files ("book1.htm" is the top level node), and
+ and in the same file add an entry for <acronym>SGML</acronym>
+ into the (existing) definition for
+ <varname>auto-mode-alist</varname>:
<programlisting>
-jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
+(setq
+ auto-mode-alist
+ '(("\\.sgml$" . sgml-mode)
+ ))
</programlisting>
-to generate the <acronym>RTF</acronym> output, ready for importing
-into your favorite word processing system and printing.</para>
+ </para>
-</sect3>
-
-<sect3><title>Installing <productname>PSGML</productname></title>
-
-<para>First, read the installation instructions at the above listed
-URL.</para>
-
-<para>Unpack the distribution file, run configure, make and make
-install to put the byte-compiled files and info library in place.
-Then add the following lines to your
-<filename>/usr/local/share/emacs/site-lisp/site-start.el</filename>
-file to make <productname>Emacs</productname> properly load
-<productname>PSGML</productname> when needed:
-<programlisting>
-(setq load-path
- (cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
-(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
-</programlisting>
-If you want to use <productname>PSGML</productname> when editing
-<acronym>HTML</acronym> too, also add this:
-<programlisting>
-(setq auto-mode-alist
- (cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
-</programlisting>
-</para>
-
-<para>There is one important thing to note with
-<productname>PSGML</productname>: its author assumed that your main
-<acronym>SGML</acronym> <acronym>DTD</acronym> directory would be
-<filename>/usr/local/lib/sgml</filename>. If, as in the examples in
-this chapter, you use <filename>/usr/local/share/sgml</filename>, you
-have to compensate for this. You can set the
-<filename>SGML_CATALOG_FILES</filename> environment variable, you can
-customize your <productname>PSGML</productname> installation (its
-manual tells you how), or you can even edit the source file
-<filename>psgml.el</filename> before compiling and installing
-<productname>PSGML</productname>, changing the hard-coded paths to
-match your own default.</para>
-
-</sect3>
-
-<sect3><title>Optional: installing <productname>JadeTeX</productname></title>
-
-<para>If you want to, you can also install
-<productname>JadeTeX</productname> to use
-<productname>TeX</productname> as a formatting backend for
-<productname>Jade</productname>. Note that this is still quite
-unpolished software, and will generate printed output that is inferior
-to what you get from the <acronym>RTF</acronym> backend. Still, it
-works all right, especially for simpler documents that don't use
-tables, and as both <productname>JadeTeX</productname> and the style
-sheets are under continuous improvement, it will certainly get better
-over time.</para>
-
-<para>To install and use <productname>JadeTeX</productname>, you will
-need a working installation of <productname>TeX</productname> and
-<productname>LaTeX2e</productname>, including the supported
-<productname>tools</productname> and
-<productname>graphics</productname> packages,
-<productname>Babel</productname>, <productname><acronym>AMS</acronym>
-fonts</productname> and <productname>AMS-LaTeX</productname>, the
-<productname><acronym>PSNFSS</acronym></productname> extension and
-companion kit of "the 35 fonts", the <productname>dvips</productname>
-program for generating <productname>PostScript</productname>, the
-macro packages <productname>fancyhdr</productname>,
-<productname>hyperref</productname>,
-<productname>minitoc</productname>, <productname>url</productname> and
-<productname>ot2enc</productname>, and of course
-<productname>JadeTeX</productname> itself. All of these can be found
-on your friendly neighborhood <acronym>CTAN</acronym> site.</para>
-
-<para><productname>JadeTeX</productname> does not at the time of
-writing come with much of an installation guide, but there is a
-<filename>makefile</filename> which shows what is needed. It also
-includes a directory <filename>cooked</filename>, wherein you'll find
-some of the macro packages it needs, but not all, and not complete --
-at least last we looked.</para>
-
-<para>Before building the <filename>jadetex.fmt</filename> format
-file, you'll probably want to edit the
-<filename>jadetex.ltx</filename> file, to change the configuration of
-<productname>Babel</productname> to suit your locality. The line to
-change looks something like
-<programlisting>
-\RequirePackage[german,french,english]{babel}[1997/01/23]
-</programlisting>
-and you should obviously list only the languages you actually need,
-and have configured <productname>Babel</productname> for.</para>
-
-<para>With <productname>JadeTeX</productname> working, you should be
-able to generate and format <productname>TeX</productname> output for
-the <productname>PostgreSQL</productname> manuals by giving the
-commands (as above, in the <filename>doc/src/sgml</filename>
-directory)
-<programlisting>
-jade -t tex -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
-jadetex postgres.tex
-jadetex postgres.tex
-dvips postgres.dvi
-</programlisting>
-Of course, when you do this, <productname>TeX</productname> will stop
-during the second run, and tell you that its capacity has been
-exceeded. This is, as far as we can tell, because of the way
-<productname>JadeTeX</productname> generates cross referencing
-information. <productname>TeX</productname> can, of course, be
-compiled with larger data structure sizes. The details of this will
-vary according to your installation.
-</para>
-
-</sect3>
-
-</sect2>
-</sect1>
-
-<sect1>
-<title>Alternate Toolsets</title>
-
-<para>
-The current stable release of <productname>sgml-tools</productname> is
-version 1.0.4. The v1.0 release includes some restructuring of the
-directory tree to more easily support additional document styles,
-possibly including <productname>DocBook</productname>. The only
-version of <productname>sgml-tools</productname> evaluated for
-<productname>Postgres</productname> was v0.99.0.
-</para>
-
-<sect2>
-<title><productname>sgml-tools</productname></title>
-
-<para>
-Install
-<productname>sgml-tools-0.99.0</productname>
-</para>
-
-<sect2>
-<title><productname>sgml-tools</productname></title>
-
-<para>
-Apply <ulink
-url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml-tools-patches-0.99.0.tar.gz">
-<productname>sgml-tools-patches</productname> </ulink> to the linuxdoc
-styles. These patches fix small problems with table formatting and
-with figure file names on conversion to postscript or html.
-</para></sect2>
-
-<sect2>
-<title><productname>sgml2latex</productname></title>
-
-<para>
-The current stable release of <productname>sgml2latex</productname> is
-version 1.4. I have misplaced the original reference for this package,
-so will temporarily post it with this example.
-</para>
-
-<para>
-Install <ulink
-url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml2latex-format.1.4.tar.gz">
-<productname>sgml2latex</productname> </ulink>.
-</para></sect2>
-
-<sect2>
-<title><productname>latex</productname></title>
-
-<para>
-Get and install <productname>texmf</productname>,
-<productname>teTeX</productname>, or another package providing full
-tex/latex functionality.
-</para>
-
-<para>
-Add the
-<ulink
-url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/latex-styles-0.99.0.tar.gz">required styles</ulink>
-linuxdoc-sgml.sty, linuxdoc-sgml-a4.sty isolatin.sty, qwertz.sty, and
-null.sty to texmf/tex/latex/tools/ or the appropriate area.
+ <para>
+ You might find that when using <productname>PSGML</productname>, a
+ comfortable way of working with these separate files of book
+ parts is to insert a proper <literal>DOCTYPE</literal>
+ declaration while you're editing them. If you are working on
+ this source, for instance, it is an appendix chapter, so you
+ would specify the document as an <quote>appendix</quote> instance
+ of a DocBook document by making the first line look like this:
<programlisting>
-% cat latex-styles-0.99.0.tar.gz | (cd texmf/tex/latex/tools/; tar zxvf -)
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
</programlisting>
-Run <productname>texhash</productname> to update the tex database.
-</para></sect2></sect1>
-
+ This means that anything and everything that reads
+ <acronym>SGML</acronym> will get it right, and I can verify the
+ document with <command>nsgmls -s docguide.sgml</command>. (But
+ you need to take out that line before building the entire
+ documentation set.)
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Other Emacs Modes</title>
+
+ <para>
+ <productname>GNU Emacs</productname> ships with a different
+ <acronym>SGML</acronym> mode, which is not quite as powerful as
+ <productname>PSGML</productname>, but it's less confusing and
+ lighter weight. Also, it offers syntax highlighting (font lock),
+ which can be very helpful.
+ <filename>src/tools/editors/emacs.samples</filename> contains
+ sample settings for this mode.
+ </para>
+
+ <para>
+ Norm Walsh offers a
+ <ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
+ specifically for DocBook which also has font-lock and a number of features to
+ reduce typing.
+ </para>
+ </sect2>
+
+ </sect1>
+
+
+ <sect1 id="docguide-style">
+ <title>Style Guide</title>
+
+ <sect2>
+ <title>Reference Pages</title>
+
+ <para>
+ Reference pages should follow a standard layout. This allows
+ users to find the desired information more quickly, and it also
+ encourages writers to document all relevant aspects of a command.
+ Consistency is not only desired among
+ <productname>PostgreSQL</productname> reference pages, but also
+ with reference pages provided by the operating system and other
+ packages. Hence the following guidelines have been developed.
+ They are for the most part consistent with similar guidelines
+ established by various operating systems.
+ </para>
+
+ <para>
+ Reference pages that describe executable commands should contain
+ the following sections, in this order. Sections that do not apply
+ can be omitted. Additional top-level sections should only be used
+ in special circumstances; often that information belongs in the
+ <quote>Usage</quote> section.
+
+ <variablelist>
+ <varlistentry>
+ <term>Name</term>
+ <listitem>
+ <para>
+ This section is generated automatically. It contains the
+ command name and a half-sentence summary of its functionality.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Synopsis</term>
+ <listitem>
+ <para>
+ This section contains the syntax diagram of the command. The
+ synopsis should normally not list each command-line option;
+ that is done below. Instead, list the major components of the
+ command line, such as where input and output files go.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description</term>
+ <listitem>
+ <para>
+ Several paragraphs explaining what the command does.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Options</term>
+ <listitem>
+ <para>
+ A list describing each command-line option. If there are a
+ lot of options, subsections can be used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Exit Status</term>
+ <listitem>
+ <para>
+ If the program uses 0 for success and non-zero for failure,
+ then you do not need to document it. If there is a meaning
+ behind the different non-zero exit codes, list them here.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Usage</term>
+ <listitem>
+ <para>
+ Describe any sublanguage or run-time interface of the program.
+ If the program is not interactive, this section can usually be
+ omitted. Otherwise, this section is a catch-all for
+ describing run-time features. Use subsections if appropriate.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Environment</term>
+ <listitem>
+ <para>
+ List all environment variables that the program might use.
+ Try to be complete; even seemingly trivial variables like
+ <envar>SHELL</envar> might be of interest to the user.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Files</term>
+ <listitem>
+ <para>
+ List any files that the program might access implicitly. That
+ is, do not list input and output files that were specified on
+ the command line, but list configuration files, etc.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Diagnostics</term>
+ <listitem>
+ <para>
+ Explain any unusual output that the program might create.
+ Refrain from listing every possible error message. This is a
+ lot of work and has little use in practice. But if, say, the
+ error messages have a standard format that the user can parse,
+ this would be the place to explain it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes</term>
+ <listitem>
+ <para>
+ Anything that doesn't fit elsewhere, but in particular bugs,
+ implementation flaws, security considerations, compatibility
+ issues.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Examples</term>
+ <listitem>
+ <para>
+ Examples
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>History</term>
+ <listitem>
+ <para>
+ If there were some major milestones in the history of the
+ program, they might be listed here. Usually, this section can
+ be omitted.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Author</term>
+ <listitem>
+ <para>
+ Author (only used in the contrib section)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>See Also</term>
+ <listitem>
+ <para>
+ Cross-references, listed in the following order: other
+ <productname>PostgreSQL</productname> command reference pages,
+ <productname>PostgreSQL</productname> SQL command reference
+ pages, citation of <productname>PostgreSQL</productname>
+ manuals, other reference pages (e.g., operating system, other
+ packages), other documentation. Items in the same group are
+ listed alphabetically.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ <para>
+ Reference pages describing SQL commands should contain the
+ following sections: Name, Synopsis, Description, Parameters,
+ Outputs, Notes, Examples, Compatibility, History, See
+ Also. The Parameters section is like the Options section, but
+ there is more freedom about which clauses of the command can be
+ listed. The Outputs section is only needed if the command returns
+ something other than a default command-completion tag. The Compatibility
+ section should explain to what extent
+ this command conforms to the SQL standard(s), or to which other
+ database system it is compatible. The See Also section of SQL
+ commands should list SQL commands before cross-references to
+ programs.
+ </para>
+ </sect2>
+
+ </sect1>
</appendix>
-
projects / postgresql / blobdiff