docguide.sgml

关系型数据库 Postgresql 6.5.2

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:
--</sgmltag>
</programlisting>
</para>

<para>
     The <productname>Postgres</productname> distribution includes a
     parsed DTD definitions file <filename>reference.ced</filename>.
You may find that
</para>

<para>
When using <application>emacs</application>/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:

<programlisting>
<sgmltag>!doctype appendix PUBLIC "-//Davenport//DTD DocBook V3.0//EN"</sgmltag>
</programlisting>

This means that anything and everything that reads <acronym>SGML</acronym> will get it
right, and I can verify the document with "nsgmls -s docguide.sgml".
</para>

</sect3>
</sect2>
</sect1>

 <sect1>
  <title>Building Documentation</title>

  <para>
   GNU <application>make</application> is used to build documentation
   from the DocBook sources. There are a few environment definitions
   which may need to be set or modified for your installation.
   The <filename>Makefile</filename> looks for
   <filename>doc/../src/Makefile</filename> and (implicitly) for
   <filename>doc/../src/Makefile.custom</filename> to obtain
   environment information. On my system, the
   <filename>src/Makefile.custom</filename> looks like

   <programlisting>
# Makefile.custom
# Thomas Lockhart 1998-03-01

POSTGRESDIR= /opt/postgres/current
CFLAGS+= -m486
YFLAGS+= -v

# documentation

HSTYLE= /home/tgl/SGML/db107.d/docbook/html
PSTYLE= /home/tgl/SGML/db107.d/docbook/print
   </programlisting>

   where HSTYLE and PSTYLE determine the path to
   <filename>docbook.dsl</filename> for <acronym>HTML</acronym>
   and hardcopy (print) stylesheets, respectively. These stylesheet
   file names are for Norm Walsh's
   <productname>Modular Style Sheets</productname>; if other
   stylesheets are used then one can define HDSL and PDSL as the full path
   and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
   On many systems, these stylesheets will be found in packages installed in 
   <filename>/usr/lib/sgml/</filename>,
   <filename>/usr/share/lib/sgml/</filename>,
   or
   <filename>/usr/local/lib/sgml/</filename>.
  </para>

  <para>
   <acronym>HTML</acronym> documentation packages can be generated
   from the <acronym>SGML</acronym> source by typing
   <programlisting>
% cd doc/src
% make tutorial.tar.gz
% make user.tar.gz
% make admin.tar.gz
% make programmer.tar.gz
% make postgres.tar.gz
% make install
   </programlisting>
  </para>

  <para>
   These packages can be installed from the main documentation directory
   by typing
   <programlisting>
% cd doc
% make install
   </programlisting>
  </para>
 </sect1>

 <sect1>
  <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. At the time of writing, the utility required patching to
   successfully run on the <productname>Postgres</productname> markup, 
   and we added a small amount of new functionality to allow setting
   the man page section in the output file name.
  </para>

  <para>
   <application>docbook2man</application> is written in perl, and
   requires the CPAN package <literal>SGMLSpm</literal> to run. Also,
   it requires <application>nsgmls</application> to be available,
   which is included in the <application>jade</application>
   distribution. After installing these packages, then simply run

   <programlisting>
$ cd doc/src
$ make man
   </programlisting>

   which will result in a tar file being generated in the
   <filename>doc/src</filename> directory.
  </para>

  <procedure>
   <title>docbook2man Installation Procedure</title>

   <step performance="required">
    <para>
     Install the <application>docbook2man</application> package,
     available at
     <ulink url="http://shell.ipoline.com/~elmert/comp/docbook2X/">http://shell.ipoline.com/~elmert/comp/docbook2X/</ulink>
    </para>
   </step>

   <step performance="required">
    <para>
     Install the SGMLSpm perl module, available from CPAN mirrors.
    </para>
   </step>

   <step performance="required">
    <para>
     Install <application>nsgmls</application> if not already
     available from your <application>jade</application> installation.
    </para>
   </step>
  </procedure>
 </sect1>

 <sect1>
  <title>Hardcopy Generation for v6.5</title>

  <para>
   The hardcopy Postscript documentation is generated by converting the
   <acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
   importing into <productname>ApplixWare-4.4.1</productname>. 
   After a little cleanup (see the following
   section) the output is "printed" to a postscript file.
  </para>

<!--
  <para>
   Some figures were redrawn to avoid having bitmap
   <acronym>GIF</acronym> files in the hardcopy documentation. One
   figure, of the system catalogs, was sufficiently complex that there
   was  not time to redraw it. It was converted to fit using the
   following commands:

   <programlisting>
% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
   </programlisting>

  </para>
-->

  <sect2>
   <title>Text Hardcopy</title>

   <para>
    <filename>INSTALL</filename> and <filename>HISTORY</filename> are
    updated for each release. For historical reasons, these files are
    in plain text, but are derived from the newer
    <acronym>SGML</acronym> sources.
   </para>

   <procedure>
    <title>Plain Text Generation</title>

    <para>
     Both <filename>INSTALL</filename> and
     <filename>HISTORY</filename> are generated from existing
     <acronym>SGML</acronym> sources. They are extracted from the same 
     intermediate <acronym>RTF</acronym> file.
    </para>

    <step performance="required">
     <para>
      Generate <acronym>RTF</acronym> by typing:
      <programlisting>
% cd doc/src/sgml
% make installation.rtf
      </programlisting>
     </para>
    </step>
      
    <step performance="required">
     <para>
      Import <filename>installation.rtf</filename> into
      <productname>Applix Words</productname>.
     </para>
    </step>

    <step performance="required">
     <para>
      Set the page width and margins.
     </para>

     <substeps>
      <step performance="required">
       <para>
	Adjust the page width in File.PageSetup to 10 inches.
       </para>
      </step>

      <step performance="required">
       <para>
	Select all text.
	Adjust the right margin using the ruler to 9.5 inches. This
	will give a maximum column width of 79 characters, within the
	80 columns upper limit goal.
       </para>
      </step>
     </substeps>
    </step>

    <step performance="required">
     <para>
      Lop off the parts of the document which are not needed.
     </para>

     <para>
      For <filename>INSTALL</filename>, remove all release notes from
      the end of the text, except for those from the current release.
      For <filename>HISTORY</filename>, remove all text up to the
      release notes, preserving and modifying the title and ToC.
     </para>
    </step>

    <step performance="required">
     <para>
      Export the result as <quote>ASCII Layout</quote>.
     </para>
    </step>

    <step performance="required">
     <para>
      Using emacs or vi, clean up the tabular information in
      <filename>INSTALL</filename>. Remove the <quote>mailto</quote>
      <acronym>URLs</acronym> for the porting contributors to shrink
      the column heights.
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2>
   <title>Postscript Hardcopy</title>

   <para>
    Several items must be addressed in generating Postscript
    hardcopy:</para>

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

    <para>
     Applixware does not seem to do a complete job of importing <acronym>RTF</acronym>
     generated by jade/MSS. In particular, all text is given the
     <quote>Header1</quote> style attribute label, although the text
     formatting itself is acceptable. Also, the Table of Contents page
     numbers do not refer to the section listed in the table, but rather
     refer to the page of the ToC itself.</para>