diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 3e571f33ad8aaaac8e81df71ec143e42168c8b54..a5da8c4eaf0e54a65dcedc9a60227cbf352a3537 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,4 +1,4 @@ - + @@ -16,15 +16,560 @@ Documentation -Postgres documentation is written using the +The purpose of documentation is to make Postgres +easier to learn, use, and develop. +The documentation set should describe the Postgres +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. + + +Postgres has four primary documentation +formats: + + + +Plain text for pre-installation information. + + +HTML, for on-line browsing and reference. + + +Hardcopy, for in-depth reading and reference. + + +man pages, for quick reference. + + + + +Documentation sources include plain text files, man pages, and html. However, +most new Postgres documentation will be written using the Standard Generalized Markup Language -(SGML) -DocBook Document Type -Definition (DTD). +(SGML) + DocBook + Document Type Definition (DTD). +Much of the existing documentation has been or will be converted to SGML. + + + +Documentation Roadmap + + +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. + + +Here is the documentation plan for v6.4: + + + + +Convert Jose Soares Da Silva's + text-based reference pages to SGML +reference sections for the User's Guide. +Oliver Elphick is working on this +and it is roughly half-way completed. + + + +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. + + + +Merge information in the existing man pages into the reference pages and User's Guide. + + + +Convert the new sgml reference pages to new man pages, replacing the existing man pages. +Brandon Ibach is working on the conversion filter. + + + +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 SGML). + + + + + + + + + +<ProductName>Postgres</ProductName> Documentation Products + + + + +File + + +Description + + + + + + ./COPYRIGHT Copyright notice + ./register.txt Registration message during make + ./doc/postgres.tar.gz Integrated docs (HTML) + ./doc/programmer.ps.gz Programmer's Guide (Postscript) + ./doc/programmer.tar.gz Programmer's Guide (HTML) + ./doc/reference.ps.gz Reference Manual (Postscript) + ./doc/reference.tar.gz Reference Manual (HTML) + ./doc/tutorial.ps.gz Introduction (Postscript) + ./doc/tutorial.tar.gz Introduction (HTML) + ./doc/user.ps.gz User's Guide (Postscript) + ./doc/user.tar.gz User's Guide (HTML) + + +
+ + +Documentation Sources + + + +<ProductName>Postgres</ProductName> Documentation Sources + + + + +File + + +Status + + + + + + ./doc/src/graphics/catalogs.gif Output file + ./doc/src/graphics/clientserver.ag Source file. Convert to CGM + ./doc/src/graphics/clientserver.gif Output file + ./doc/src/graphics/connections.ag Source file. Convert to CGM + ./doc/src/graphics/connections.gif Output file + ./doc/src/graphics/layout.ag Source file. Convert to CGM + ./doc/src/graphics/layout.gif Output file + ./doc/src/sgml/spi.sgml Converted. Original removed. + ./doc/src/sgml/admin.sgml Converted + ./doc/src/sgml/advanced.sgml Converted + ./doc/src/sgml/arch-dev.sgml Converted + ./doc/src/sgml/arch-pg.sgml Converted + ./doc/src/sgml/arch.sgml Converted + ./doc/src/sgml/array.sgml Converted + ./doc/src/sgml/biblio.sgml Converted + ./doc/src/sgml/compiler.sgml Converted + ./doc/src/sgml/contacts.sgml Sample. Either complete or discard + ./doc/src/sgml/datatype.sgml New document. Replaces man/pgbuiltin.3 + ./doc/src/sgml/dfunc.sgml Converted + ./doc/src/sgml/docguide.sgml New document. + ./doc/src/sgml/ecpg.sgml Converted + ./doc/src/sgml/environ.sgml Converted + ./doc/src/sgml/extend.sgml Converted + ./doc/src/sgml/func-ref.sgml Converted + ./doc/src/sgml/func.sgml Converted + ./doc/src/sgml/geqo.sgml Converted. Original removed. + ./doc/src/sgml/gist.sgml New from mailing list + ./doc/src/sgml/inherit.sgml Converted + ./doc/src/sgml/install.sgml Converted + ./doc/src/sgml/intro-pg.sgml Converted + ./doc/src/sgml/intro.sgml Converted + ./doc/src/sgml/jdbc.sgml Converted + ./doc/src/sgml/libpgtcl.sgml Converted + ./doc/src/sgml/libpq.sgml Converted + ./doc/src/sgml/lobj.sgml Converted + ./doc/src/sgml/manage.sgml Converted + ./doc/src/sgml/odbc.sgml Converted + ./doc/src/sgml/oper.sgml Converted + ./doc/src/sgml/pgaccess.sgml Converted + ./doc/src/sgml/ports.sgml Converted + ./doc/src/sgml/postgres.sgml Converted + ./doc/src/sgml/programmer.sgml Converted + ./doc/src/sgml/protocol.sgml Converted + ./doc/src/sgml/psql.sgml Converted + ./doc/src/sgml/query-ug.sgml Converted + ./doc/src/sgml/query.sgml Converted + ./doc/src/sgml/recovery.sgml Converted + ./doc/src/sgml/reference.sgml Converted + ./doc/src/sgml/regress.sgml Converted + ./doc/src/sgml/release.sgml Converted + ./doc/src/sgml/rules.sgml Converted + ./doc/src/sgml/start-ag.sgml Converted + ./doc/src/sgml/start.sgml Converted + ./doc/src/sgml/storage.sgml Converted + ./doc/src/sgml/trigger.sgml Converted + ./doc/src/sgml/tutorial.sgml Converted + ./doc/src/sgml/typeconv.sgml New document + ./doc/src/sgml/user.sgml Converted + ./doc/src/sgml/xaggr.sgml Converted + ./doc/src/sgml/xfunc.sgml Converted + ./doc/src/sgml/xindex.sgml Converted + ./doc/src/sgml/xoper.sgml Converted + ./doc/src/sgml/xtypes.sgml Converted + ./doc/src/sgml/ref/allfiles.sgml List of files in ref/ (internal) + ./doc/src/sgml/ref/alter_table.sgml New + ./doc/src/sgml/ref/alter_user.sgml New + ./doc/src/sgml/ref/begin.sgml New + ./doc/src/sgml/ref/close.sgml New + ./doc/src/sgml/ref/cluster.sgml New + ./doc/src/sgml/ref/commands.sgml List of commands (internal) + ./doc/src/sgml/ref/commit.sgml New + ./doc/src/sgml/ref/copy.sgml New + ./doc/src/sgml/ref/create_aggregate.sgml New + ./doc/src/sgml/ref/create_database.sgml New + ./doc/src/sgml/ref/create_function.sgml New + ./doc/src/sgml/ref/create_index.sgml New + ./doc/src/sgml/ref/create_language.sgml New + ./doc/src/sgml/ref/drop_function.sgml New + ./doc/src/sgml/ref/select.sgml New + ./doc/src/sgml/ref/create_operator.sgml New + ./doc/src/sgml/ref/create_rule.sgml New + ./doc/src/sgml/ref/create_sequence.sgml New + ./doc/src/sgml/ref/create_table.sgml New + + +
+ + +Document Conversion Status + + + +<ProductName>Postgres</ProductName> Documentation Sources + + + + +File + + +Status + + + + + + ./HISTORY Not converted + ./README Not converted + ./INSTALL Not converted + ./contrib/README Not converted + ./contrib/apache_logging/README Not converted + ./contrib/array/array_iterator.doc Not converted + ./contrib/datetime/datetime_functions.doc Not converted + ./contrib/earthdistance/README Not converted + ./contrib/int8/README Not converted + ./contrib/ip_and_mac/README Not converted + ./contrib/lo/README Not converted + ./contrib/mSQL-interface/README Not converted + ./contrib/noupdate/noup.example Not converted + ./contrib/pginterface/README Not converted + ./contrib/sequence/set_sequence.sql.in Not converted + ./contrib/soundex/soundex.sql.in Not converted + ./contrib/spi/README Not converted + ./contrib/spi/autoinc.example Not converted + ./contrib/spi/insert_username.example Not converted + ./contrib/spi/refint.example Not converted + ./contrib/spi/timetravel.example Not converted + ./contrib/string/string_io.sql.in Not converted + ./contrib/unixdate/unixdate.sql Not converted + ./contrib/userlock/user_locks.doc Not converted + ./doc/FAQ Not converted + ./doc/FAQ_DEV Not converted + ./doc/FAQ_FreeBSD Not converted + ./doc/FAQ_Irix Not converted + ./doc/FAQ_Linux Not converted + ./doc/TODO Not converted + ./doc/README.GEQO Removed. Superceded by geqo.sgml + ./doc/README.fsync Not converted + ./doc/README.locale Not converted + ./doc/README.mb Not converted + ./doc/README.mb.jp Not converted + ./doc/README.support Not converted + ./doc/TODO.GEQO Removed. Superceded by geqo.sgml + ./doc/bug.template Not converted + ./doc/userguide.ps Obsolete. Remove from distribution + ./migration/1.02_to_1.02.1 Removed (converted to SGML) + ./migration/1.09_to_6.0 Removed (converted to SGML) + ./migration/1.0_to_1.01 Removed (converted to SGML) + ./migration/6.0_to_6.1 Removed (converted to SGML) + ./migration/6.1_to_6.1.1 Removed (converted to SGML) + ./migration/6.1_to_6.2 Removed (converted to SGML) + ./migration/6.2.1_to_6.3 Removed (converted to SGML) + ./migration/6.2_to_6.2.1 Removed (converted to SGML) + ./migration/6.3.1_to_6.3.2 Removed (converted to SGML) + ./src/DEVELOPERS Not converted + ./src/backend/access/nbtree/README Not converted + ./src/backend/catalog/README Not converted + ./src/backend/libpq/pg_hba.conf.sample Not converted + ./src/backend/libpq/pg_ident.conf.sample Not converted + ./src/backend/nodes/README Not converted + ./src/backend/optimizer/README Not converted + ./src/backend/optimizer/geqo/pg_geqo.sample Not converted + ./src/backend/optimizer/plan/README Not converted + ./src/backend/parser/README Not converted + ./src/backend/port/dynloader/README.dlfcn.aix Not converted + ./src/backend/regex/COPYRIGHT Not converted + ./src/backend/regex/WHATSNEW Not converted + ./src/backend/regex/re_format.7 Not converted + ./src/backend/regex/regex.3 Not converted + ./src/backend/storage/ipc/README Not converted + ./src/backend/storage/lmgr/README Not converted + ./src/backend/storage/smgr/README Not converted + ./src/bin/pg_dump/README Not converted + ./src/bin/pgaccess/README.pga Not converted + ./src/bin/pgaccess/formdemo.sql Not converted + ./src/bin/pgtclsh/README Not converted + ./src/data/charset.conf Not converted + ./src/data/koi-alt.tab Not converted + ./src/data/koi-iso.tab Not converted + ./src/data/koi-koi.tab Not converted + ./src/data/koi-mac.tab Not converted + ./src/data/koi-win.tab Not converted + ./src/interfaces/ecpg/ChangeLog Not converted + ./src/interfaces/ecpg/TODO Not converted + ./src/interfaces/jdbc/README Not converted + ./src/interfaces/jdbc/README_6.3 Not converted + ./src/interfaces/jdbc/example/ImageViewer.java Not converted + ./src/interfaces/jdbc/example/basic.java Not converted + ./src/interfaces/jdbc/example/blobtest.java Not converted + ./src/interfaces/jdbc/example/datestyle.java Not converted + ./src/interfaces/jdbc/example/psql.java Not converted + ./src/interfaces/libpgtcl/README Not converted + ./src/interfaces/libpq/README Not converted + ./src/interfaces/libpq++/README Not converted + ./src/interfaces/libpq++/examples/testlibpq0.cc Not converted + ./src/interfaces/libpq++/examples/testlibpq1.cc Not converted + ./src/interfaces/libpq++/examples/testlibpq2.cc Not converted + ./src/interfaces/libpq++/examples/testlibpq2.sql Not converted + ./src/interfaces/libpq++/examples/testlibpq3.cc Not converted + ./src/interfaces/libpq++/examples/testlibpq3.sql Not converted + ./src/interfaces/libpq++/examples/testlibpq4.cc Not converted + ./src/interfaces/libpq++/examples/testlibpq4.sql Not converted + ./src/interfaces/libpq++/examples/testlibpq5.cc Not converted + ./src/interfaces/libpq++/examples/testlibpq5.sql Not converted + ./src/interfaces/libpq++/examples/testlibpq6.cc Not converted + ./src/interfaces/libpq++/examples/testlo.cc Not converted + ./src/interfaces/libpq++/man/libpq++.3 Not converted + ./src/interfaces/odbc/license.txt Not converted + ./src/interfaces/odbc/notice.txt Not converted + ./src/interfaces/odbc/readme.txt Not converted + ./src/interfaces/perl5/MANIFEST Not converted + ./src/interfaces/perl5/Changes Not converted + ./src/interfaces/perl5/eg/example.newstyle Not converted + ./src/interfaces/perl5/README Not converted + ./src/interfaces/python/Announce Not converted + ./src/interfaces/python/ChangeLog Not converted + ./src/interfaces/python/README Not converted + ./src/interfaces/python/tutorial/advanced.py Not converted + ./src/interfaces/python/tutorial/advanced.pyc Not converted + ./src/interfaces/python/tutorial/basics.py Not converted + ./src/interfaces/python/tutorial/func.py Not converted + ./src/interfaces/python/tutorial/func.pyc Not converted + ./src/interfaces/python/tutorial/pgtools.py Not converted + ./src/interfaces/python/tutorial/pgtools.pyc Not converted + ./src/interfaces/python/tutorial/syscat.py Not converted + ./src/interfaces/python/tutorial/syscat.pyc Not converted + ./src/man/README Not converted + ./src/man/ecpg.1 Not converted + ./src/man/abort.l Not converted + ./src/man/alter_table.l Not converted + ./src/man/alter_user.l Not converted + ./src/man/begin.l Not converted + ./src/man/bki.5 Not converted + ./src/man/catalogs.3 Not converted + ./src/man/cleardbdir.1 Not converted + ./src/man/close.l Not converted + ./src/man/cluster.l Not converted + ./src/man/commit.l Not converted + ./src/man/copy.l Not converted + ./src/man/create_aggregate.l Not converted + ./src/man/create_database.l Not converted + ./src/man/create_function.l Not converted + ./src/man/create_index.l Not converted + ./src/man/create_language.l Not converted + ./src/man/create_operator.l Not converted + ./src/man/create_rule.l Not converted + ./src/man/create_sequence.l Not converted + ./src/man/create_table.l Not converted + ./src/man/create_trigger.l Not converted + ./src/man/create_type.l Not converted + ./src/man/create_user.l Not converted + ./src/man/create_version.l Not converted + ./src/man/create_view.l Not converted + ./src/man/createdb.1 Not converted + ./src/man/createuser.1 Not converted + ./src/man/declare.l Not converted + ./src/man/delete.l Not converted + ./src/man/destroydb.1 Not converted + ./src/man/destroyuser.1 Not converted + ./src/man/drop.l Not converted + ./src/man/drop_aggregate.l Not converted + ./src/man/drop_database.l Not converted + ./src/man/drop_function.l Not converted + ./src/man/drop_index.l Not converted + ./src/man/drop_language.l Not converted + ./src/man/drop_operator.l Not converted + ./src/man/drop_rule.l Not converted + ./src/man/drop_sequence.l Not converted + ./src/man/drop_table.l Not converted + ./src/man/drop_trigger.l Not converted + ./src/man/drop_type.l Not converted + ./src/man/drop_user.l Not converted + ./src/man/drop_view.l Not converted + ./src/man/end.l Not converted + ./src/man/explain.l Not converted + ./src/man/fetch.l Not converted + ./src/man/grant.l Not converted + ./src/man/initdb.1 Not converted + ./src/man/initlocation.1 Not converted + ./src/man/insert.l Not converted + ./src/man/ipcclean.1 Not converted + ./src/man/large_objects.3 Not converted + ./src/man/libpq.3 Not converted + ./src/man/listen.l Not converted + ./src/man/load.l Not converted + ./src/man/lock.l Not converted + ./src/man/move.l Not converted + ./src/man/notify.l Not converted + ./src/man/oracle_compat.3 Obsolete. Superceded by func.sgml + ./src/man/page.5 Not converted + ./src/man/pg_dump.1 Not converted + ./src/man/pg_dumpall.1 Not converted + ./src/man/pg_hba.conf.5 Not converted + ./src/man/pg_passwd.1 Not converted + ./src/man/pgbuiltin.3 Obsolete. Superceded by datatype.sgml + ./src/man/pgintro.1 Not converted + ./src/man/postgres.1 Not converted + ./src/man/postmaster.1 Not converted + ./src/man/psql.1 Not converted + ./src/man/reset.l Not converted + ./src/man/revoke.l Not converted + ./src/man/rollback.l Not converted + ./src/man/select.l Not converted + ./src/man/set.l Not converted + ./src/man/show.l Not converted + ./src/man/sql.l Not converted + ./src/man/update.l Not converted + ./src/man/vacuum.l Not converted + ./src/pl/tcl/INSTALL Not converted + ./src/pl/tcl/modules/README Not converted + ./src/pl/tcl/license.terms Not converted + ./src/pl/tcl/test/README Not converted + ./src/pl/tcl/test/runtest Not converted + ./src/pl/tcl/test/test.expected Not converted + ./src/pl/tcl/test/test_mklang.sql Not converted + ./src/pl/tcl/test/test_queries.sql Not converted + ./src/pl/tcl/test/test_setup.sql Not converted + ./src/test/bench/WISC-README Not converted + ./src/test/locale/README Not converted + ./src/test/performance/results/PgSQL.970926 Not converted + ./src/test/regress/README Not converted + ./src/test/suite/README Not converted + ./src/tools/RELEASE_CHANGES Not converted + ./src/tools/SQL_keywords Not converted + ./src/tools/backend/README Not converted + ./src/tools/backend/flow.fig Not converted + ./src/tools/backend/flow.jpg Not converted + ./src/tools/make_keywords.README Not converted + ./src/tools/entab/entab.man Not converted + ./src/tools/make_diff/README Not converted + ./src/tools/mkldexport/README Not converted + ./src/tools/pgindent/README Not converted + ./src/tutorial/README Not converted + ./src/utils/README Not converted + ./lib/pg_hba.conf.sample Not converted + ./lib/pg_geqo.sample Not converted + + +
+ + +Document Structure + + +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 +doc/src/sgml/, along with many of the other source files +used for the documentation. The primary source files are: + + + +postgres.sgml + + +This is the integrated document, including all other documents as parts. + + + + + +tutorial.sgml + + +The introductory tutorial, with examples. Does not include programming topics, +and is intended to help a reader unfamiliar with SQL. +This is the "getting started" document. + + + + + +user.sgml + + +The User's Guide. Includes information on data types and user-level interfaces. +This is the place to put information on "why". + + + + + +reference.sgml + + +The Reference Manual. Includes Postgres SQL syntax. +This is the place to put information on "how". + + + + + +programming.sgml + + +The Programmer's Guide. Includes information on Postgres +extensibility and on the programming interfaces. + + + + + +admin.sgml + + +The Administrator's Guide. Include installation and release notes. + + + + + + +Introduction Packaged documentation is available in both -HTML and Postscript +HTML and Postscript formats. These are available as part of the standard Postgres installation. We discuss here working with the documentation sources and generating documentation @@ -38,9 +583,6 @@ and still evolving. - -Introduction - The purpose of SGML is to allow an author to specify the structure and content of a document (e.g. using the @@ -49,20 +591,19 @@ have the document style define how that content is rendered into a final form (e.g. using Norm Walsh's stylesheets). -See +See Introduction to DocBook for a nice "quickstart" summary of -DocBook features. DocBook +DocBook features. + DocBook Elements provides a powerful cross-reference for features of DocBook. This documentation set is constructed using several tools, including -James Clark's -jade and Norm Walsh's Modular DocBook -Stylesheets. +James Clark's + jade + and Norm Walsh's +Modular DocBook Stylesheets. Currently, hardcopy is produced by importing Rich Text @@ -109,16 +650,16 @@ be included below. - Book + Book Delimits a Book element - Chapter + Chapter Delimits a Chapter element - Appendix - Delimits a Appendix element + Appendix + Delimits a Appendix element @@ -853,3 +1394,4 @@ Run texhash to update the tex database. +