docguide.sgml

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

      </substeps>
    </step>

    <step performance="required">
     <para>
      Save the document as native <productname>Applixware
      Words</productname> format to allow easier last minute editing
      later.
     </para>
    </step>

    <step performance="required">
     <para>
      <quote>Print</quote> the document
      to a file in Postscript format.
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2>
   <title>Plain Text Files</title>

   <para>
    Several files are distributed as plain text, for reading during
    the installation process. The <filename>INSTALL</filename> file
    corresponds to <xref linkend="installation">, with some minor
    changes to account for the different context.  To recreate the
    file, change to the directory <filename>doc/src/sgml</filename>
    and enter <userinput>gmake INSTALL</userinput>.  This will create
    a file <filename>INSTALL.html</filename> that can be saved as text
    with <productname>Netscape Navigator</productname> and put into
    the place of the existing file.
    <productname>Netscape</productname> seems to offer the best
    quality for <acronym>HTML</acronym> to text conversions (over
    <application>lynx</application> and
    <application>w3m</application>).
   </para>

   <para>
    The file <filename>HISTORY</filename> can be created similarly,
    using the command <userinput>gmake HISTORY</userinput>.  For the
    file <filename>src/test/regress/README</filename> the command is
    <userinput>gmake regress_README</userinput>.
   </para>
  </sect2>

  <sect2>
   <title>Syntax Check</title>

   <para>
    Building the documentation can take very long.  But there is a
    method to just check the correct syntax of the documentation
    files, which only takes a few seconds:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake check</userinput>
</screen>
   </para>
  </sect2>
 </sect1>


 <sect1 id="docguide-authoring">
  <title>Documentation Authoring</title>

   <para>
    <acronym>SGML</acronym> and <productname>DocBook</productname> do
    not suffer from an oversupply of open-source authoring tools. The
    most common tool set is the
    <productname>Emacs</productname>/<productname>XEmacs</productname>
    editor with appropriate editing mode.  On some systems
    these tools are provided in a typical full installation.
   </para>

   <sect2>
    <title>Emacs/PSGML</title>

    <para>
     <productname>PSGML</productname> is the most common and most
     powerful mode for editing <acronym>SGML</acronym> documents.
     When properly configured, it will allow you to use
     <application>Emacs</application> to insert tags and check markup
     consistency.  You could use it for <acronym>HTML</acronym> as
     well.  Check the <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
     PSGML web site</ulink> for downloads, installation instructions, and
     detailed documentation.
    </para>

    <para>
     There is one important thing to note with
     <productname>PSGML</productname>: its author assumed that your
     main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
     would be <filename>/usr/local/lib/sgml</filename>.  If, as in the
     examples in this chapter, you use
     <filename>/usr/local/share/sgml</filename>, you have to
     compensate for this, either by setting
     <envar>SGML_CATALOG_FILES</envar> environment variable, or you
     can customize your <productname>PSGML</productname> installation
     (its manual tells you how).
    </para>

    <para>
     Put the following in your <filename>~/.emacs</filename>
     environment file (adjusting the path names to be appropriate for
     your system):

<programlisting>
; ********** for SGML mode (psgml)

(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
</programlisting>

     and in the same file add an entry for <acronym>SGML</acronym>
     into the (existing) definition for
     <varname>auto-mode-alist</varname>:
<programlisting>
(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))
</programlisting>
    </para>

    <para>
     Currently, each <acronym>SGML</acronym> source file has the
     following block at the end of the file:

<programlisting>
&lt;!-- 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:
--&gt;
</programlisting>
     This will set up a number of editing mode parameters even if you
     do not set up your <filename>~/.emacs</filename> file, but it is
     a bit unfortunate, since if you followed the installation
     instructions above, then the catalog path will not match your
     location.  Hence you might need to turn off local variables:
<programlisting>
(setq inhibit-local-variables t)
</programlisting>
    </para>

    <para>
     The <productname>PostgreSQL</productname> distribution includes a
     parsed DTD definitions file <filename>reference.ced</filename>.
     You may find that when using <productname>PSGML</productname>, a
     comfortable way of working with these separate files of book
     parts is to insert a proper <literal>DOCTYPE</literal>
     declaration while you're editing them.  If you are working on
     this source, for instance, it is an appendix chapter, so you
     would specify the document as an <quote>appendix</quote> instance
     of a DocBook document by making the first line look like this:

<programlisting>
&lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"&gt;
</programlisting>

     This means that anything and everything that reads
     <acronym>SGML</acronym> will get it right, and I can verify the
     document with <command>nsgmls -s docguide.sgml</command>.  (But
     you need to take out that line before building the entire
     documentation set.)
    </para>
   </sect2>

   <sect2>
    <title>Other Emacs modes</title>

    <para>
     <productname>GNU Emacs</productname> ships with a different
     <acronym>SGML</acronym> mode, which is not quite as powerful as
     <productname>PSGML</productname>, but it's less confusing and
     lighter weight.  Also, it offers syntax highlighting (font lock),
     which can be very helpful.
    </para>

    <para>
     Norm Walsh offers a
     <ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
     specifically for DocBook which also has font-lock and a number of features to 
     reduce typing.
    </para>
   </sect2>

 </sect1>


 <sect1 id="docguide-style">
  <title>Style Guide</title>

  <sect2>
   <title>Reference Pages</title>

   <para>
    Reference pages should follow a standard layout.  This allows
    users to find the desired information more quickly, and it also
    encourages writers to document all relevant aspects of a command.
    Consistency is not only desired among
    <productname>PostgreSQL</productname> reference pages, but also
    with reference pages provided by the operating system and other
    packages.  Hence the following guidelines have been developed.
    They are for the most part consistent with similar guidelines
    established by various operating systems.
   </para>

   <para>
    Reference pages that describe executable commands should contain
    the following sections, in this order.  Sections that do not apply
    may be omitted.  Additional top-level sections should only be used
    in special circumstances; often that information belongs in the
    <quote>Usage</quote> section.

    <variablelist>
     <varlistentry>
      <term>Name</term>
      <listitem>
       <para>
        This section is generated automatically.  It contains the
        command name and a half-sentence summary of its functionality.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Synopsis</term>
      <listitem>
       <para>
        This section contains the syntax diagram of the command.  The
        synopsis should normally not list each command-line option;
        that is done below.  Instead, list the major components of the
        command line, such as where input and output files go.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Description</term>
      <listitem>
       <para>
        Several paragraphs explaining what the command does.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Options</term>
      <listitem>
       <para>
        A list describing each command-line option.  If there are a
        lot of options, subsections may be used.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Exit Status</term>
      <listitem>
       <para>
        If the program uses 0 for success and non-zero for failure,
        then you do not need to document it.  If there is a meaning
        behind the different non-zero exit codes, list them here.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Usage</term>
      <listitem>
       <para>
        Describe any sublanguage or run-time interface of the program.
        If the program is not interactive, this section can usually be
        omitted.  Otherwise, this section is a catch-all for
        describing run-time features.  Use subsections if appropriate.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Environment</term>
      <listitem>
       <para>
        List all environment variables that the program might use.
        Try to be complete; even seemingly trivial variables like
        <envar>SHELL</envar> might be of interest to the user.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Files</term>
      <listitem>
       <para>
        List any files that the program might access implicitly.  That
        is, do not list input and output files that were specified on
        the command line, but list configuration files, etc.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Diagnostics</term>
      <listitem>
       <para>
        Explain any unusual output that the program might create.
        Refrain from listing every possible error message.  This is a
        lot of work and has little use in practice.  But if, say, the
        error messages have a standard format that the user can parse,
        this would be the place to explain it.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Notes</term>
      <listitem>
       <para>
        Anything that doesn't fit elsewhere, but in particular bugs,
        implementation flaws, security considerations, compatibility
        issues.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>Examples</term>
      <listitem>
       <para>
        Examples
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>History</term>
      <listitem>
       <para>
        If there were some major milestones in the history of the
        program, they might be listed here.  Usually, this section can
        be omitted.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term>See Also</term>
      <listitem>
       <para>
        Cross-references, listed in the following order: other
        <productname>PostgreSQL</productname> command reference pages,
        <productname>PostgreSQL</productname> SQL command reference
        pages, citation of <productname>PostgreSQL</productname>
        manuals, other reference pages (e.g., operating system, other
        packages), other documentation.  Items in the same group are
        listed alphabetically.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <para>
    Reference pages describing SQL commands should contain the
    following sections: Name, Synopsis, Description, Parameters,
    Outputs, Notes, Examples, Compatibility, History, See
    Also.  The Parameters section is like the Options section, but
    there is more freedom about which clauses of the command can be
    listed.  The Outputs section is only needed if the command returns
    something other than a default command-completion tag.  The Compatibility
    section should explain to what extent
    this command conforms to the SQL standard(s), or to which other
    database system it is compatible.  The See Also section of SQL
    commands should list SQL commands before cross-references to
    programs.
   </para>
  </sect2>

 </sect1>
</appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
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:
-->