Реклама:

info.krc.karelia.ru

win -:|:- koi -:|:- iso -:|:- dos -:|:- mac

Start -:|:- Проекты -:|:- О нас

Documentation Sources

Documentation sources include plain text files, man pages, an.shtml. However, most new Postgres documentation will be written using the Standard Generalized Markup Language (SGML) DocBook Document Type Definition (DTD). Much of the existing documentation has been or will be converted to SGML.

The purpose of SGML is to allow an author to specify the structure and content of a document (e.g. using the DocBook DTD), and to have the document style define how that content is rendered into a final form (e.g. using Norm Walsh's stylesheets).

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

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. Output is generated in HTML since the browser interface makes it easy to move around all of the documentation by just clicking. The other documents are available in both HTML and hardcopy.

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.

Documentation Files

Table DG2-2. Postgres Documentation Sources

FileStatus 
./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/about.sgml New document  
./doc/src/sgml/admin.sgml Administrator's Guide container  
./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 New document  
./doc/src/sgml/bki.sgml Converted from bki.5  
./doc/src/sgml/compiler.sgml New document  
./doc/src/sgml/config.sgml New document  
./doc/src/sgml/contacts.sgml Docs contributors? Not used. Either complete or discard  
./doc/src/sgml/datatype.sgml New document  
./doc/src/sgml/dfunc.sgml Converted  
./doc/src/sgml/docguide.sgml Documentation info. New document  
./doc/src/sgml/ecpg.sgml ecpg eSQL pre-compiler docs  
./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 GEQO genetic optimizer docs  
./doc/src/sgml/gist.sgml New from mailing list  
./doc/src/sgml/history.sgml New document  
./doc/src/sgml/indices.sgml New document  
./doc/src/sgml/info.sgml New document  
./doc/src/sgml/inherit.sgml Converted  
./doc/src/sgml/install.sgml Installation instructions  
./doc/src/sgml/intro-ag.sgml Admin Guide intro. Converted  
./doc/src/sgml/intro-pg.sgml Programmers Guide intro. Converted  
./doc/src/sgml/intro.sgml Users Guide intro  
./doc/src/sgml/jdbc.sgml New document from Peter Mount  
./doc/src/sgml/keys.sgml New document  
./doc/src/sgml/legal.sgml Copyright etc. for intros  
./doc/src/sgml/libpgtcl.sgml Converted  
./doc/src/sgml/libpq++.sgml C++ library. Converted  
./doc/src/sgml/libpq.sgml C library  
./doc/src/sgml/lobj.sgml Large objects  
./doc/src/sgml/manage.sgml Converted  
./doc/src/sgml/notation.sgml Docs notation for intros  
./doc/src/sgml/odbc.sgml ODBC driver  
./doc/src/sgml/oper.sgml Converted  
./doc/src/sgml/page.sgml On-disk storage scheme  
./doc/src/sgml/pg_options.sgml Backend configuration  
./doc/src/sgml/pgaccess.sgml Converted  
./doc/src/sgml/ports.sgml Supported/unsupported platforms  
./doc/src/sgml/postgres.sgml Container for all docs. Best fo.shtml output  
./doc/src/sgml/programmer.sgml Programmer's Guide  
./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 Database recovery  
./doc/src/sgml/reference.sgml Converted  
./doc/src/sgml/regress.sgml Regression testing  
./doc/src/sgml/release.sgml Converted  
./doc/src/sgml/rules.sgml Rule system  
./doc/src/sgml/runtime.sgml Runtime environment. New for v6.4  
./doc/src/sgml/security.sgml Server security  
./doc/src/sgml/signals.sgml System signals for backend.  
./doc/src/sgml/spi.sgml Converted. Original removed  
./doc/src/sgml/start-ag.sgml Converted  
./doc/src/sgml/start.sgml Converted  
./doc/src/sgml/storage.sgml Converted  
./doc/src/sgml/syntax.sgml SQL syntax. In UG  
./doc/src/sgml/trigger.sgml Converted  
./doc/src/sgml/tutorial.sgml Container for tutorial  
./doc/src/sgml/typeconv.sgml Datatype conversion. New for v6.4. In UG  
./doc/src/sgml/user.sgml User's Guide  
./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/xplang.sgml Programming Language. New for v6.4  
./doc/src/sgml/xtypes.sgml Converted  
./doc/src/sgml/y2k.sgml Y2K statement. New for v6.4  
./doc/src/sgml/ref/abort.sgml New for v6.4  
./doc/src/sgml/ref/allfiles.sgml List of files in ref/ (internal)  
./doc/src/sgml/ref/alter_table.sgml New for v6.4  
./doc/src/sgml/ref/alter_user.sgml New for v6.4  
./doc/src/sgml/ref/begin.sgml New for v6.4  
./doc/src/sgml/ref/close.sgml New for v6.4  
./doc/src/sgml/ref/cluster.sgml New for v6.4  
./doc/src/sgml/ref/commands.sgml List of commands (internal)  
./doc/src/sgml/ref/commit.sgml New for v6.4  
./doc/src/sgml/ref/copy.sgml New for v6.4  
./doc/src/sgml/ref/create_aggregate.sgml New for v6.4  
./doc/src/sgml/ref/create_database.sgml New for v6.4  
./doc/src/sgml/ref/create_function.sgml New for v6.4  
./doc/src/sgml/ref/create_index.sgml New for v6.4  
./doc/src/sgml/ref/create_language.sgml New for v6.4  
./doc/src/sgml/ref/create_operator.sgml New for v6.4  
./doc/src/sgml/ref/create_rule.sgml New for v6.4  
./doc/src/sgml/ref/create_sequence.sgml New for v6.4  
./doc/src/sgml/ref/create_table.sgml New for v6.4  
./doc/src/sgml/ref/create_trigger.sgml New for v6.4  
./doc/src/sgml/ref/create_type.sgml New for v6.4  
./doc/src/sgml/ref/create_user.sgml New for v6.4  
./doc/src/sgml/ref/create_view.sgml New for v6.4  
./doc/src/sgml/ref/createdb.sgml New for v6.4  
./doc/src/sgml/ref/createuser.sgml New for v6.4  
./doc/src/sgml/ref/declare.sgml New for v6.4  
./doc/src/sgml/ref/delete.sgml New for v6.4  
./doc/src/sgml/ref/destroydb.sgml New for v6.4  
./doc/src/sgml/ref/destroyuser.sgml New for v6.4  
./doc/src/sgml/ref/drop_aggregate.sgml New for v6.4  
./doc/src/sgml/ref/drop_database.sgml New for v6.4  
./doc/src/sgml/ref/drop_function.sgml New for v6.4  
./doc/src/sgml/ref/drop_index.sgml New for v6.4  
./doc/src/sgml/ref/drop_language.sgml New for v6.4  
./doc/src/sgml/ref/drop_operator.sgml New for v6.4  
./doc/src/sgml/ref/drop_rule.sgml New for v6.4  
./doc/src/sgml/ref/drop_sequence.sgml New for v6.4  
./doc/src/sgml/ref/drop_table.sgml New for v6.4  
./doc/src/sgml/ref/drop_trigger.sgml New for v6.4  
./doc/src/sgml/ref/drop_type.sgml New for v6.4  
./doc/src/sgml/ref/drop_user.sgml New for v6.4  
./doc/src/sgml/ref/drop_view.sgml New for v6.4  
./doc/src/sgml/ref/explain.sgml New for v6.4  
./doc/src/sgml/ref/fetch.sgml New for v6.4  
./doc/src/sgml/ref/grant.sgml New for v6.4  
./doc/src/sgml/ref/initdb.sgml New for v6.4  
./doc/src/sgml/ref/initlocation.sgml New for v6.4  
./doc/src/sgml/ref/insert.sgml New for v6.4  
./doc/src/sgml/ref/listen.sgml New for v6.4  
./doc/src/sgml/ref/load.sgml New for v6.4  
./doc/src/sgml/ref/lock.sgml New for v6.4  
./doc/src/sgml/ref/move.sgml New for v6.4  
./doc/src/sgml/ref/notify.sgml New for v6.4  
./doc/src/sgml/ref/pg_dump.sgml New for v6.4  
./doc/src/sgml/ref/pg_dumpall.sgml New for v6.4  
./doc/src/sgml/ref/psql-ref.sgml New for v6.4  
./doc/src/sgml/ref/reset.sgml New for v6.4  
./doc/src/sgml/ref/revoke.sgml New for v6.4  
./doc/src/sgml/ref/rollback.sgml New for v6.4  
./doc/src/sgml/ref/select.sgml New for v6.4  
./doc/src/sgml/ref/set.sgml New for v6.4  
./doc/src/sgml/ref/show.sgml New for v6.4  
./doc/src/sgml/ref/update.sgml New for v6.4  
./doc/src/sgml/ref/vacuum.sgml New for v6.4  
./doc/src/sgml/ref/unlisten.sgml New for v6.4  
./doc/src/sgml/ref/vacuumdb.sgml New for v6.4  
./doc/src/sgml/ref/pg_upgrade.sgml New for v6.4  

Document Conversion

Table DG2-3. Postgres Documentation Sources

FileStatus 
./HISTORY Obsolete. Converted to release.sgml  
./README Not converted  
./INSTALL Obsolete. Converted to install.sgml  
./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 Assimilate into Admin Guide  
./doc/README.locale Assimilate into Admin Guide  
./doc/README.mb Assimilate into Admin Guide  
./doc/README.mb.jp Not converted  
./doc/README.support Not converted  
./doc/TODO.GEQO Removed. Superceded by geqo.sgml  
./doc/userguide.ps 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/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/abort.l Not converted  
./src/man/alter_table.l Not converted  
./src/man/alter_user.l Split into Reference and Admin Guide  
./src/man/begin.l Not converted  
./src/man/catalogs.3 Catalog synopsis. Move to Programmer's Guide?  
./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/ecpg.1 Short man page. Retain  
./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/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/pg_dump.1 Assimilate into Admin Guide  
./src/man/pg_dumpall.1 Assimilate into Admin Guide  
./src/man/pg_upgrade.1 Assimilate into Admin Guide  
./src/man/pg_hba.conf.5 Assimilate into Admin Guide  
./src/man/pg_passwd.1 Assimilate into Admin Guide  
./src/man/pgintro.1 Assimilate into User's Guide?  
./src/man/postgres.1 Assimilate into User's, Admin Guides  
./src/man/postmaster.1 Assimilate into User's, Admin Guides  
./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  

Styles and Conventions

DocBook has a rich set of tags and constructs, and a suprisingly large percentage are directly and obviously useful for well-formed documentation. The Postgres documentation set has only recently been adapted to SGML, and in the near future several sections of the set will be selected and maintained as prototypical examples of DocBook usage. Also, a short summary of DocBook tags will be included below.

SGML Authoring Tools

The current Postgres documentation set was written using a plain text editor (or emacs/psgml; see below) with the content marked up using SGML DocBook tags.

SGML and DocBook 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.

emacs/psgml

emacs (and xemacs) have an SGML major mode. When properly configured, this will allow you to use emacs to insert tags and check markup consistancy.

Put the following in your ~/.emacs environment file:

; ********** for SGML mode (psgml)

(setq sgml-catalog-files "/usr/lib/sgml/CATALOG")
(setq sgml-local-catalogs "/usr/lib/sgml/CATALOG")

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
and add an entry in the same file for SGML into the (existing) definition for auto-mode-alist:
(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))
Each SGML source file has the following block at the end of the file:
!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
--

The Postgres distribution includes a parsed DTD definitions file reference.ced. You may find that

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:

!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"
This means that anything and everything that reads SGML will get it right, and I can verify the document with "nsgmls -s docguide.sgml".