docguide.sgml

关系型数据库 Postgresql 6.5.2

<!--
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.18 1999/07/06 17:19:41 thomas Exp $
Documentation Guide
Thomas Lockhart

Revision 1.15  1999/05/27 15:49:07  thomas
Markup fixes.
Update for v6.5 release.

Revision 1.12  1998/12/18 16:17:29  thomas
Include more details on editing with Emacs.
Remove mention of the old "migration" flat files.
Change URLs for resources to point to areas, not particular files.
 That way things stay correct even when version of tools change.
 Suggested by Vince Vielhaber.

Revision 1.11  1998/10/30 19:36:57  thomas
Minor editing and markup changes as a result of preparing the Postscript
 documentation for v6.4.
Bigger updates to the installation instructions (install and config).

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.

-->

<appendix label="DG2" id="docguide">
 <docinfo>
  <authorgroup>
   <author>
    <firstname>Thomas</firstname>
    <surname>Lockhart</surname>
   </author>
   <author>
    <firstname>Tom Ivar</firstname>
    <surname>Helbekkmo</surname>
   </author>
  </authorgroup>
  <date>1999-05-27</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>

 <sect1>
  <title>Documentation Roadmap</title>

  <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>

  <para>
   <table tocentry="1">
    <title><productname>Postgres</productname> Documentation Products</title>
    <tgroup cols="2">
     <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>
  </para>

  <para>
   There are man pages available, as well as a large number
   of plain-text README-type files throughout the <productname>Postgres</productname>
   source tree.
  </para>
 </sect1>

 <sect1>
  <title>The Documentation Project</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.
  </para>

  <para>
   The documentation sources are written using <acronym>SGML</acronym>
   markup of plain text files.
   The purpose of <productname>DocBook</productname> <acronym>SGML</acronym>
   is to allow an author to
   specify the structure and content of a technical document (using the
   <productname>DocBook</productname> <acronym>DTD</acronym>),  and to
   have a document style define how that content is rendered into a
   final form (e.g. using Norm Walsh's 
   <productname>Modular Style Sheets</productname>).</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.nwalsh.com/docbook/dsssl/">
    Modular DocBook Stylesheets</ulink>.
  </para>

  <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 is 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>Documentation Sources</title>

<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>

<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>
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>

<para>
Here is the documentation plan for v6.5:

<itemizedlist>
<listitem>
<para>
Start compiling index information for the User's and Administrator's Guides.
</para>
</listitem>

<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.
</para>
</listitem>

<listitem>
<para>
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.
</para>
</listitem>

<listitem>
<para>
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
</para>
</listitem>

<listitem>
<para>
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.
</para>
</listitem>

</itemizedlist>
</para>

<sect2>
<title>Document Structure</title>