docguide.sgml

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

     <productname>PostgreSQL</productname> doesn't use this catalog
     entry.  See <xref linkend="docguide-toolsets-configure"> for
     information about how to select the stylesheets instead.
    </para>
   </sect3>

   <sect3>
    <title>Installing <productname>JadeTeX</productname></title>

    <para>
     To install and use <productname>JadeTeX</productname>, you will
     need a working installation of <productname>TeX</productname> and
     <productname>LaTeX2e</productname>, including the supported
     <productname>tools</productname> and
     <productname>graphics</productname> packages,
     <productname>Babel</productname>,
     <productname><acronym>AMS</acronym> fonts</productname> and
     <productname>AMS-LaTeX</productname>, the
     <productname><acronym>PSNFSS</acronym></productname> extension
     and companion kit of <quote>the 35 fonts</quote>, the
     <productname>dvips</productname> program for generating
     <productname>PostScript</productname>, the macro packages
     <productname>fancyhdr</productname>,
     <productname>hyperref</productname>,
     <productname>minitoc</productname>,
     <productname>url</productname> and
     <productname>ot2enc</productname>.  All of these can be found on
     your friendly neighborhood <ulink url="http://www.ctan.org">
     <acronym>CTAN site</acronym></ulink>.
     The installation of the <application>TeX</application> base
     system is far beyond the scope of this introduction.  Binary
     packages should be available for any system that can run
     <application>TeX</application>.
    </para>

    <para>
     Before you can use <application>JadeTeX</application> with the
     <productname>PostgreSQL</productname> documentation sources, you
     will need to increase the size of
     <application>TeX</application>'s internal data structures.
     Details on this can be found in the <application>JadeTeX</application>
     installation instructions.
    </para>

    <para>
     Once that is finished you can install <application>JadeTeX</application>:
<screen>
<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
<prompt>$</prompt> <userinput>cd jadetex</userinput>
<prompt>$</prompt> <userinput>make install</userinput>
<prompt>$</prompt> <userinput>mktexlsr</userinput>
</screen>
     The last two need to be done as <systemitem>root</systemitem>.
    </para>

   </sect3>

  </sect2>

  <sect2 id="docguide-toolsets-configure">
   <title>Detection by <command>configure</command></title>

  <para>
   Before you can build the documentation you need to run the
   <filename>configure</filename> script as you would when building
   the <productname>PostgreSQL</productname> programs themselves.
   Check the output near the end of the run, it should look something
   like this:
<screen>
<computeroutput>
checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V4.2... yes
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl
</computeroutput>
</screen>
   If neither <filename>onsgmls</filename> nor
   <filename>nsgmls</filename> were found then you will not see the
   remaining 4 lines.  <filename>nsgmls</filename> is part of the Jade
   package.  If <quote>DocBook V4.2</quote> was not found then you did
   not install the DocBook DTD kit in a place where jade can find it,
   or you have not set up the catalog files correctly.  See the
   installation hints above.  The DocBook stylesheets are looked for
   in a number of relatively standard places, but if you have them
   some other place then you should set the environment variable
   <envar>DOCBOOKSTYLE</envar> to the location and rerun
   <filename>configure</filename> afterwards.
  </para>

  </sect2>
 </sect1>

 <sect1 id="docguide-build">
  <title>Building The Documentation</title>

  <para>
   Once you have everything set up, change to the directory
   <filename>doc/src/sgml</filename> and run one of the commands
   described in the following subsections to build the
   documentation. (Remember to use GNU make.)
  </para>

  <sect2>
   <title>HTML</title>

   <para>
    To build the <acronym>HTML</acronym> version of the documentation:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
</screen>
    This is also the default target.
   </para>

   <para>
    When the HTML documentation is built, the process also generates
    the linking information for the index entries.  Thus, if you want
    your documentation to have a concept index at the end, you need to
    build the HTML documentation once, and then build the
    documentation again in whatever format you like.
   </para>

   <para>
    To allow for easier handling in the final distribution, the files
    comprising the HTML documentation are stored in a tar archive that
    is unpacked at installation time.  To create the
    <acronym>HTML</acronym> documentation package, use the commands
<programlisting>
cd doc/src
gmake postgres.tar.gz
</programlisting>
    In the distribution, these archives live in the
    <filename>doc</filename> directory and are installed by default
    with <command>gmake install</command>.
  </para>
 </sect2>

 <sect2>
  <title>Manpages</title>

  <para>
   We use the <application>docbook2man</application> utility to
   convert <productname>DocBook</productname>
   <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
   pages.  The man pages are also distributed as a tar archive,
   similar to the <acronym>HTML</acronym> version.  To create the man
   page package, use the commands
<programlisting>
cd doc/src
gmake man.tar.gz
</programlisting>
   which will result in a tar file being generated in the
   <filename>doc/src</filename> directory.
  </para>

  <para>
   To generate quality man pages, it might be necessary to use a
   hacked version of the conversion utility or do some manual
   postprocessing.  All man pages should be manually inspected before
   distribution.
  </para>
 </sect2>

  <sect2>
   <title>Print Output via <application>JadeTex</application></title>

   <para>
    If you want to use <application>JadeTex</application> to produce a
    printable rendition of the documentation, you can use one of the
    following commands:

    <itemizedlist>
     <listitem>
      <para>
       To make a <acronym>DVI</acronym> version:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.dvi</userinput>
</screen>
      </para>
     </listitem>

     <listitem>
      <para>
       To generate Postscript from the <acronym>DVI</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.ps</userinput>
</screen>
      </para>
     </listitem>
  
     <listitem>
      <para>
       To make a <acronym>PDF</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.pdf</userinput>
</screen>
       (Of course you can also make a <acronym>PDF</acronym> version
       from the Postscript, but if you generate <acronym>PDF</acronym>
       directly, it will have hyperlinks and other enhanced features.)
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect2>

  <sect2>
   <title>Print Output via <acronym>RTF</acronym></title>

   <para>
    You can also create a printable version of the <productname>PostgreSQL</productname>
    documentation by converting it to <acronym>RTF</acronym> and
    applying minor formatting corrections using an office suite.
    Depending on the capabilities of the particular office suite, you
    can then convert the documentation to Postscript of
    <acronym>PDF</acronym>.  The procedure below illustrates this
    process using <productname>Applixware</productname>.
   </para>

   <note>
    <para>
     It appears that current versions of the <productname>PostgreSQL</productname> documentation
     trigger some bug in or exceed the size limit of OpenJade.  If the
     build process of the <acronym>RTF</acronym> version hangs for a
     long time and the output file still has size 0, then you may have
     hit that problem.  (But keep in mind that a normal build takes 5
     to 10 minutes, so don't abort too soon.)
    </para>
   </note>

   <procedure>
    <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>

    <para>
     <application>OpenJade</application> omits specifying a default
     style for body text. In the past, this undiagnosed problem led to
     a long process of table of contents generation. However, with
     great help from the <productname>Applixware</productname> folks
     the symptom was diagnosed and a workaround is available.
    </para>

    <step performance="required">
     <para>
      Generate the <acronym>RTF</acronym> version by typing:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.rtf</userinput>
</screen>
     </para>
    </step>

    <step performance="required">
     <para>
      Repair the RTF file to correctly specify all styles, in
      particular the default style. If the document contains
      <sgmltag>refentry</sgmltag> sections, one must also replace
      formatting hints which tie a preceding paragraph to the current
      paragraph, and instead tie the current paragraph to the
      following one. A utility, <command>fixrtf</command>, is
      available in <filename>doc/src/sgml</filename> to accomplish
      these repairs:

<screen>
<prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
</screen>
     </para>

     <para>
      The script adds <literal>{\s0 Normal;}</literal> as the zeroth
      style in the document. According to
      <productname>Applixware</productname>, the RTF standard would
      prohibit adding an implicit zeroth style, though Microsoft Word
      happens to handle this case. For repairing
      <sgmltag>refentry</sgmltag> sections, the script replaces
      <literal>\keepn</literal> tags with <literal>\keep</literal>.
     </para>
    </step>

    <step performance="required">
     <para>
      Open a new document in <productname>Applixware Words</productname> and
      then import the <acronym>RTF</acronym> file.
     </para>
    </step>

    <step performance="required">
     <para>
      Generate a new table of contents (ToC) using
      <productname>Applixware</productname>.
     </para>

     <substeps>
      <step>
       <para>
        Select the existing ToC lines, from the beginning of the first
        character on the first line to the last character of the last
        line.
       </para>
      </step>

      <step>
       <para>
        Build a new ToC using
        <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
        Building</guisubmenu><guimenuitem>Create Table of
        Contents</guimenuitem></menuchoice>. Select the first three
        levels of headers for inclusion in the ToC. This will replace
        the existing lines imported in the RTF with a native
        <productname>Applixware</productname> ToC.
       </para>
      </step>

      <step>
       <para>
        Adjust the ToC formatting by using
        <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
        selecting each of the three ToC styles, and adjusting the
        indents for <literal>First</literal> and
        <literal>Left</literal>. Use the following values:

        <informaltable>
         <tgroup cols="3">
          <thead>
           <row>
            <entry>Style</entry>
            <entry>First Indent (inches)</entry>
            <entry>Left Indent (inches)</entry>
           </row>
          </thead>

          <tbody>
           <row>
            <entry><literal>TOC-Heading 1</literal></entry>
            <entry><literal>0.4</literal></entry>
            <entry><literal>0.4</literal></entry>
           </row>

           <row>
            <entry><literal>TOC-Heading 2</literal></entry>
            <entry><literal>0.8</literal></entry>
            <entry><literal>0.8</literal></entry>
           </row>

           <row>
            <entry><literal>TOC-Heading 3</literal></entry>
            <entry><literal>1.2</literal></entry>
            <entry><literal>1.2</literal></entry>
           </row>
          </tbody>
         </tgroup>
        </informaltable>
       </para>
      </step>
     </substeps>
    </step>

    <step performance="required">
     <para>
      Work through the document to:

      <itemizedlist>
       <listitem>
        <para>
         Adjust page breaks.
        </para>
       </listitem>

       <listitem>
        <para>
         Adjust table column widths.
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </step>

    <step performance="required">
     <para>
      Replace the right-justified page numbers in the Examples and
      Figures portions of the ToC with correct values. This only takes
      a few minutes.
     </para>
    </step>

    <step performance="optional">
     <para>
       Delete the index section from the document if it is empty.
     </para>
    </step>

    <step performance="required">
     <para>
       Regenerate and adjust the table of contents.
     </para>

      <substeps>
       <step>
        <para>
         Select the ToC field.
        </para>
       </step>

       <step>
        <para>
         Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
         Building</guisubmenu><guimenuitem>Create Table of
         Contents</guimenuitem></menuchoice>.
        </para>
       </step>

       <step>
        <para>
         Unbind the ToC by selecting
         <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
         Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
        </para>
       </step>

       <step>
        <para>
         Delete the first line in the ToC, which is an entry for the
         ToC itself.
        </para>
       </step>