*** pgsql/doc/src/sgml/docguide.sgml	2009/06/17 21:58:49	1.76
--- pgsql/doc/src/sgml/docguide.sgml	2009/08/04 22:04:37	1.77
***************
*** 1,4 ****
! <!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.75 2009/04/27 16:27:35 momjian Exp $ -->
  
  <appendix id="docguide">
   <title>Documentation</title>
--- 1,4 ----
! <!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.76 2009/06/17 21:58:49 tgl Exp $ -->
  
  <appendix id="docguide">
   <title>Documentation</title>
***************
*** 83,95 ****
  
     <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>
--- 83,96 ----
  
     <variablelist>
      <varlistentry>
!      <term><ulink url="http://www.oasis-open.org/docbook/">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.  You
!        need the <acronym>SGML</acronym> variant of the DocBook DTD,
!        but to build man pages you also need the <acronym>XML</acronym>
!        variant of the same version.
        </para>
       </listitem>
      </varlistentry>
***************
*** 105,151 ****
      </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://wiki.docbook.org/topic/DocBookDssslStylesheets">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://search.cpan.org/dist/SGMLSpm/">SGMLSpm</ulink></term>
       <listitem>
        <para>
!        This optional package is used to create man pages.
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term><ulink url="http://docbook2x.sourceforge.net">DocBook2X</ulink></term>
       <listitem>
        <para>
!        This optional package is also used to create man pages.  You
!        want the <literal>docbook2man-sgmlspl</literal> package, not
!        the main <literal>docbook2x</literal> package.
        </para>
       </listitem>
      </varlistentry>
--- 106,156 ----
      </varlistentry>
  
      <varlistentry>
!      <term><ulink url="http://wiki.docbook.org/topic/DocBookDssslStylesheets">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://wiki.docbook.org/topic/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
       <listitem>
        <para>
!        This is another stylesheet for converting DocBook to other
!        formats.  We currently use this to produce man pages and
!        optionally HTMLHelp.  You can also use this toolchain to
!        produce HTML or PDF output, but official PostgreSQL releases
!        use the DSSSL stylesheets for that.
        </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://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
       <listitem>
        <para>
!        This is the processing tool to use with the XSLT stylesheets
!        (like <command>jade</command> is the processing tool for DSSSL
!        stylesheets).
        </para>
       </listitem>
      </varlistentry>
*************** CATALOG "docbook/4.2/catalog"
*** 263,275 ****
      available for <productname>Debian GNU/Linux</productname>.
      To install, simply use:
  <programlisting>
! apt-get install openjade1.3
! apt-get install docbook
! apt-get install docbook-dsssl
! apt-get install sgmlspl   # for the man pages
  </programlisting>
-     (The plain <literal>openjade</literal> package installs
-     OpenJade 1.4, which seems not to work.)
     </para>
    </sect2>
  
--- 268,275 ----
      available for <productname>Debian GNU/Linux</productname>.
      To install, simply use:
  <programlisting>
! apt-get install docbook docbook-dsssl docbook-xsl openjade xsltproc
  </programlisting>
     </para>
    </sect2>
  
*************** CATALOG "docbook-dsssl-1.<replaceable>xx
*** 511,523 ****
  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.  You can pass the environment variables
     <envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point
     to the programs if they are not found automatically.  If
--- 511,525 ----
  checking for onsgmls... onsgmls
  checking for openjade... openjade
  checking for DocBook V4.2... yes
! checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular
! checking for collateindex.pl... /usr/bin/collateindex.pl
! checking for xsltproc... xsltproc
! checking for osx... osx
  </computeroutput>
  </screen>
     If neither <filename>onsgmls</filename> nor
!    <filename>nsgmls</filename> were found then some of the following tests
!    will be skipped.  <filename>nsgmls</filename> is part of the Jade
     package.  You can pass the environment variables
     <envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point
     to the programs if they are not found automatically.  If
*************** gmake postgres.tar.gz
*** 583,590 ****
    <title>Manpages</title>
  
    <para>
!    We use the <application>docbook2man-sgmlspl</application> utility
!    from the <productname>DocBook2X</productname> project 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,
--- 585,591 ----
    <title>Manpages</title>
  
    <para>
!    We use the DocBook XSL stylesheets 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,
*************** gmake postgres.tar.gz
*** 592,623 ****
     pages, use the commands:
  <programlisting>
  cd doc/src/sgml
! gmake man D2MDIR=<replaceable>directory</replaceable>
  </programlisting>
-    Use the <varname>D2MDIR</varname> variable to specify the name of
-    the directory where the
-    file <filename>docbook2man-spec.pl</filename> from
-    the <application>docbook2man-sgmlspl</application> package resides.
-    There is no default for that.  Since that package is not available
-    or outdated in many packaging systems, you might want to just
-    download the source code tarball and unpack it.  No building is
-    required.  Then the path is something
-    like <literal>D2MDIR=/home/you/somewhere/docbook2man-sgmlspl-1.0/perl</literal>.
-    You may get warnings like this:
- <screen>
- Warning: unrecognized SDATA '[scaron]': please add definition to docbook2man-spec.pl
- Warning: unrecognized SDATA '[ouml  ]': please add definition to docbook2man-spec.pl
- </screen>
-    which can ignore if (and only if) you are using the latest version
-    of <filename>docbook2man-spec.pl</filename>
-    and you are not seeing any other SDATA warnings besides those.
    </para>
  
    <para>
     To create the man page package for a release, use the following commands:
  <programlisting>
  cd doc/src
! gmake man.tar.gz D2MDIR=<replaceable>directory</replaceable>
  </programlisting>
     which will result in a tar file being generated in the
     <filename>doc/src</filename> directory.
--- 593,607 ----
     pages, use the commands:
  <programlisting>
  cd doc/src/sgml
! gmake man
  </programlisting>
    </para>
  
    <para>
     To create the man page package for a release, use the following 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.