docguide.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.56 2005/05/13 16:48:14 tgl Exp $ -->

<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
   may be optional, as noted.

   <variablelist>
    <varlistentry>
     <term><ulink url="http://www.oasis-open.org/docbook/sgml/">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.  Note
       that there is also an <acronym>XML</acronym> version of DocBook
       &mdash; do not use that.
      </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://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://docbook.sourceforge.net/projects/dsssl/index.html">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://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
     <listitem>
      <para>
       This optional package is used to create man pages.  It has a
       number of prerequisite packages of its own.  Check the web
       site.
      </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 may 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><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>

   <para>
    Most vendors provide a complete RPM set for DocBook processing in
    their distribution.  Look for an <quote>SGML</quote> option while
    installing, or the following packages:
    <filename>sgml-common</filename>, <filename>docbook</filename>,
    <filename>stylesheets</filename>, <filename>openjade</filename>
    (or <filename>jade</filename>).  Possibly
    <filename>sgml-tools</filename> will be needed as well.  If your
    distributor does not provide these then you should be able to make
    use of the packages from some other, reasonably compatible vendor.
   </para>
  </sect2>

  <sect2>
   <title>FreeBSD Installation</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/sp</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/openjade</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/iso8879</filename></para>
     </listitem>
     <listitem>
      <para><filename>textproc/dsssl-docbook-modular</filename></para>
     </listitem>
    </itemizedlist>
    Apparently, there is no port for the DocBook V4.2 SGML DTD
    available right now.  You will need to install it manually.
   </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>
    It's possible that the ports do not update the main catalog file
    in <filename>/usr/local/share/sgml/catalog</filename>.  Be sure to
    have the following line in there:
<programlisting>
CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"
</programlisting>
    If you do not want to edit the file you can also set the
    environment variable <envar>SGML_CATALOG_FILES</envar> to a
    colon-separated list of catalog files (such as the one above).
   </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>
apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets
</programlisting>
   </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>
      </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>
CATALOG "dsssl/catalog"
</programlisting>
        (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>
CATALOG "docbook-4.2/docbook.cat"
</programlisting>
      </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>
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
</programlisting>
       (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>
CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog"
</programlisting>
     Because stylesheets change rather often, and it's sometimes
     beneficial to try out alternative versions,