Реклама: |
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:
Start compiling index information for the User's and Administrator's Guides.
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. Condense the man pages down to reminder information, with references into the primary doc set.
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
Convert all source graphics to CGM format files for portability. Currently we mostly have Applix Graphics sources from which we can generate .gif output. One graphic is only available in .gif and .ps, and should be redrawn or removed.
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:
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.
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.
The User's Guide. Includes information on data types and user-level interfaces. This is the place to put information on "why".
The Reference Manual. Includes Postgres SQL syntax. This is the place to put information on "how".
The Programmer's Guide. Includes information on Postgres extensibility and on the programming interfaces.
The Administrator's Guide. Include installation and release notes.
Table DG2-2. Postgres 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/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 |
Table DG2-3. Postgres Documentation Sources
File | Status | |
---|---|---|
./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 |
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.
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 (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".