Update man page build instructions.

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 3ae932e6afbe21a5a9e05ab5e4265f665db8ab3b..a04295aaacb2f04992b71bbc5764d59291b77386 100644 (file)
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Documentation
@@ -131,12 +131,21 @@
     
 
     
-     docbook2x.sourceforge.net">DocBook2X tools
+     search.cpan.org/dist/SGMLSpm/">SGMLSpm
      
       
-       This optional package is used to create man pages.  It has a
-       number of prerequisite packages of its own.  Check the web
-       site.
+       This optional package is used to create man pages.
+      
+     
+    
+
+    
+     DocBook2X
+     
+      
+       This optional package is also used to create man pages.  You
+       want the docbook2man-sgmlspl package, not
+       the main docbook2x package.
       
      
     
@@ -257,6 +266,7 @@ CATALOG "docbook/4.2/catalog"
 apt-get install openjade1.3
 apt-get install docbook
 apt-get install docbook-dsssl
+apt-get install sgmlspl   # for the man pages
 
     (The plain openjade package installs
     OpenJade 1.4, which seems not to work.)
@@ -573,25 +583,44 @@ gmake postgres.tar.gz
   Manpages
 
   
-   We use the docbook2man utility to
+   We use the docbook2man-sgmlspl utility
+   from the DocBook2X project to
    convert DocBook
    refentry pages to *roff output suitable for man
    pages.  The man pages are also distributed as a tar archive,
    similar to the HTML version.  To create the man
-   page package, use the commands:
+   pages, use the commands:
 
-cd doc/src
-gmake man.tar.gz
+cd doc/src/sgml
+gmake man D2MDIR=directory
 
-   which will result in a tar file being generated in the
-   doc/src directory.
+   Use the D2MDIR variable to specify the name of
+   the directory where the
+   file docbook2man-spec.pl from
+   the docbook2man-sgmlspl 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 D2MDIR=/home/you/somewhere/docbook2man-sgmlspl-1.0/perl.
+   You may get warnings like this:
+
+Warning: unrecognized SDATA '[scaron]': please add definition to docbook2man-spec.pl
+Warning: unrecognized SDATA '[ouml  ]': please add definition to docbook2man-spec.pl
+
+   which can ignore if (and only if) you are using the latest version
+   of docbook2man-spec.pl
+   and you are not seeing any other SDATA warnings besides those.
   
 
   
-   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.
+   To create the man page package for a release, use the following commands:
+
+cd doc/src
+gmake man.tar.gz D2MDIR=directory
+
+   which will result in a tar file being generated in the
+   doc/src directory.