From c29d7f02c27c72b01c4fa90e24c4d33b5078a169 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Tue, 4 Aug 2009 22:04:37 +0000 Subject: [PATCH] Use DocBook XSL stylesheets for man page building This switches the man page building process to use the DocBook XSL stylesheet toolchain. The previous targets for Docbook2X are removed. configure has been updated to look for the new tools. The Documentation appendix contains the new build instructions. There are also a few isolated tweaks in the documentation to improve places that came out strangely in the man pages. --- config/docbook.m4 | 31 +------ configure | 71 ++++++++------ configure.in | 6 +- doc/src/sgml/Makefile | 58 +++--------- doc/src/sgml/docguide.sgml | 92 ++++++++---------- doc/src/sgml/postgres.sgml | 4 +- doc/src/sgml/ref/analyze.sgml | 4 +- doc/src/sgml/stylesheet-man.xsl | 160 ++++++++++++++++++++++++++++++-- doc/src/sgml/trigger.sgml | 4 +- src/Makefile.global.in | 17 ++-- 10 files changed, 264 insertions(+), 183 deletions(-) diff --git a/config/docbook.m4 b/config/docbook.m4 index 491d329d53..0d8c1fad7e 100644 --- a/config/docbook.m4 +++ b/config/docbook.m4 @@ -1,4 +1,4 @@ -# $PostgreSQL: pgsql/config/docbook.m4,v 1.10 2008/11/26 11:26:54 petere Exp $ +# $PostgreSQL: pgsql/config/docbook.m4,v 1.11 2009/08/04 22:04:37 petere Exp $ # PGAC_PROG_JADE # -------------- @@ -97,32 +97,3 @@ if test -n "$DOCBOOKSTYLE"; then else AC_PATH_PROGS(COLLATEINDEX, collateindex.pl) fi])# PGAC_PATH_COLLATEINDEX - - -# PGAC_PATH_DOCBOOK2MAN -# --------------------- -# Find docbook2man program from the docbook2X package. Upstream calls -# this program docbook2man, but there is also a different docbook2man -# out there from the docbook-utils package. Thus, the program we want -# is called docbook2x-man on Debian and db2x_docbook2man on Fedora. -# -# (Consider rewriting this macro using AC_PATH_PROGS_FEATURE_CHECK -# when switching to Autoconf 2.62+.) -AC_DEFUN([PGAC_PATH_DOCBOOK2MAN], -[AC_CACHE_CHECK([for docbook2man], [ac_cv_path_DOCBOOK2MAN], -[if test -z "$DOCBOOK2MAN"; then - _AS_PATH_WALK([], - [for ac_prog in docbook2x-man db2x_docbook2man docbook2man; do - ac_path="$as_dir/$ac_prog" - AS_EXECUTABLE_P(["$ac_path"]) || continue - if "$ac_path" --version 2>/dev/null | $GREP docbook2x >/dev/null 2>&1; then - ac_cv_path_DOCBOOK2MAN=$ac_path - break - fi - done]) -else - ac_cv_path_DOCBOOK2MAN=$DOCBOOK2MAN -fi]) -DOCBOOK2MAN=$ac_cv_path_DOCBOOK2MAN -AC_SUBST(DOCBOOK2MAN) -])# PGAC_PATH_DOCBOOK2MAN diff --git a/configure b/configure index fb41c024e2..61b3c72e52 100755 --- a/configure +++ b/configure @@ -642,8 +642,8 @@ ac_includes_default="\ ac_subst_vars='LTLIBOBJS vpath_build -DOCBOOK2MAN -SGMLSPL +OSX +XSLTPROC COLLATEINDEX DOCBOOKSTYLE have_docbook @@ -28028,17 +28028,17 @@ fi done fi -for ac_prog in sgmlspl +for ac_prog in xsltproc do # Extract the first word of "$ac_prog", so it can be a program name with args. set dummy $ac_prog; ac_word=$2 { $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 $as_echo_n "checking for $ac_word... " >&6; } -if test "${ac_cv_prog_SGMLSPL+set}" = set; then +if test "${ac_cv_prog_XSLTPROC+set}" = set; then $as_echo_n "(cached) " >&6 else - if test -n "$SGMLSPL"; then - ac_cv_prog_SGMLSPL="$SGMLSPL" # Let the user override the test. + if test -n "$XSLTPROC"; then + ac_cv_prog_XSLTPROC="$XSLTPROC" # Let the user override the test. else as_save_IFS=$IFS; IFS=$PATH_SEPARATOR for as_dir in $PATH @@ -28047,7 +28047,7 @@ do test -z "$as_dir" && as_dir=. for ac_exec_ext in '' $ac_executable_extensions; do if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then - ac_cv_prog_SGMLSPL="$ac_prog" + ac_cv_prog_XSLTPROC="$ac_prog" $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 break 2 fi @@ -28057,49 +28057,60 @@ IFS=$as_save_IFS fi fi -SGMLSPL=$ac_cv_prog_SGMLSPL -if test -n "$SGMLSPL"; then - { $as_echo "$as_me:$LINENO: result: $SGMLSPL" >&5 -$as_echo "$SGMLSPL" >&6; } +XSLTPROC=$ac_cv_prog_XSLTPROC +if test -n "$XSLTPROC"; then + { $as_echo "$as_me:$LINENO: result: $XSLTPROC" >&5 +$as_echo "$XSLTPROC" >&6; } else { $as_echo "$as_me:$LINENO: result: no" >&5 $as_echo "no" >&6; } fi - test -n "$SGMLSPL" && break + test -n "$XSLTPROC" && break done -{ $as_echo "$as_me:$LINENO: checking for docbook2man" >&5 -$as_echo_n "checking for docbook2man... " >&6; } -if test "${ac_cv_path_DOCBOOK2MAN+set}" = set; then +for ac_prog in osx sgml2xml sx +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ $as_echo "$as_me:$LINENO: checking for $ac_word" >&5 +$as_echo_n "checking for $ac_word... " >&6; } +if test "${ac_cv_prog_OSX+set}" = set; then $as_echo_n "(cached) " >&6 else - if test -z "$DOCBOOK2MAN"; then - as_save_IFS=$IFS; IFS=$PATH_SEPARATOR + if test -n "$OSX"; then + ac_cv_prog_OSX="$OSX" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR for as_dir in $PATH do IFS=$as_save_IFS test -z "$as_dir" && as_dir=. - for ac_prog in docbook2x-man db2x_docbook2man docbook2man; do - ac_path="$as_dir/$ac_prog" - { test -f "$ac_path" && $as_test_x "$ac_path"; } || continue - if "$ac_path" --version 2>/dev/null | $GREP docbook2x >/dev/null 2>&1; then - ac_cv_path_DOCBOOK2MAN=$ac_path - break - fi - done + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_prog_OSX="$ac_prog" + $as_echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done done IFS=$as_save_IFS -else - ac_cv_path_DOCBOOK2MAN=$DOCBOOK2MAN fi fi -{ $as_echo "$as_me:$LINENO: result: $ac_cv_path_DOCBOOK2MAN" >&5 -$as_echo "$ac_cv_path_DOCBOOK2MAN" >&6; } -DOCBOOK2MAN=$ac_cv_path_DOCBOOK2MAN +OSX=$ac_cv_prog_OSX +if test -n "$OSX"; then + { $as_echo "$as_me:$LINENO: result: $OSX" >&5 +$as_echo "$OSX" >&6; } +else + { $as_echo "$as_me:$LINENO: result: no" >&5 +$as_echo "no" >&6; } +fi + + test -n "$OSX" && break +done # Thread testing diff --git a/configure.in b/configure.in index 79e1541e25..ba0dc1cb7d 100644 --- a/configure.in +++ b/configure.in @@ -1,5 +1,5 @@ dnl Process this file with autoconf to produce a configure script. -dnl $PostgreSQL: pgsql/configure.in,v 1.607 2009/07/24 15:03:07 tgl Exp $ +dnl $PostgreSQL: pgsql/configure.in,v 1.608 2009/08/04 22:04:36 petere Exp $ dnl dnl Developers, please strive to achieve this order: dnl @@ -1731,8 +1731,8 @@ PGAC_PROG_JADE PGAC_CHECK_DOCBOOK(4.2) PGAC_PATH_DOCBOOK_STYLESHEETS PGAC_PATH_COLLATEINDEX -AC_CHECK_PROGS(SGMLSPL, sgmlspl) -PGAC_PATH_DOCBOOK2MAN +AC_CHECK_PROGS(XSLTPROC, xsltproc) +AC_CHECK_PROGS(OSX, [osx sgml2xml sx]) # Thread testing diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 7e1e113f14..33bd247629 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -2,7 +2,7 @@ # # PostgreSQL documentation makefile # -# $PostgreSQL: pgsql/doc/src/sgml/Makefile,v 1.119 2009/07/20 18:34:58 petere Exp $ +# $PostgreSQL: pgsql/doc/src/sgml/Makefile,v 1.120 2009/08/04 22:04:37 petere Exp $ # #---------------------------------------------------------------------------- @@ -33,17 +33,15 @@ ifndef NSGMLS NSGMLS = nsgmls endif -ifndef SGMLSPL -SGMLSPL = sgmlspl +ifndef OSX +OSX = osx endif -ifndef DOCBOOK2MAN -DOCBOOK2MAN = docbook2man_is_missing +ifndef XSLTPROC +XSLTPROC = xsltproc endif -# docbook2man generates man pages from docbook refentry source code. -D2MSCRIPT= $(D2MDIR)/docbook2man-spec.pl -D2MLINKS = $(D2MDIR)/docbook2man-spec_makelinks +override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)' GENERATED_SGML = bookindex.sgml version.sgml \ @@ -70,25 +68,14 @@ override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged ## Man pages ## -.PHONY: html man draft clean +.PHONY: man -DEFAULTSECTION = l +man: man-stamp -fix_man_xrefs = $(PERL) -npi -e 's{\[XRef to GUC-([A-Z0-9-]*)\]}{($$l = $$1) =~ tr/A-Z-/a-z_/, $$l}ge || s{\[XRef to [A-Z0-9-]*\]}{in the documentation}g' -lowercase = tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz' - -man: postgres.sgml $(ALLSGML) - $(NSGMLS) $(NSGMLS_FLAGS) $(SGMLINCLUDE) $< | $(SGMLSPL) $(D2MSCRIPT) --lowercase --section $(DEFAULTSECTION) --date "`date '+%Y-%m-%d'`" -# One more time, to resolve cross-references - $(NSGMLS) $(NSGMLS_FLAGS) $(SGMLINCLUDE) $< | $(SGMLSPL) $(D2MSCRIPT) --lowercase --section $(DEFAULTSECTION) --date "`date '+%Y-%m-%d'`" - $(fix_man_xrefs) *.1 *.7 - $(mkinstalldirs) man1 man7 - $(D2MLINKS) < manpage.links - mv *.1 man1/ - mv *.7 man7/ - rm *.$(DEFAULTSECTION) -# manpage.links doesn't handle lowercase, needs fixups - cd man7 && for file in `awk '{ print $$2 }' ../manpage.links`; do $(lowercase) <$$file >`echo $$file | $(lowercase)` && rm $$file || exit; done +man-stamp: stylesheet-man.xsl postgres.xml + $(XSLTPROC) $(XSLTPROCFLAGS) $^ + rm man1/SPI* man1/dblink* + touch $@ ## @@ -97,6 +84,8 @@ man: postgres.sgml $(ALLSGML) all: html +.PHONY: html draft + JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html # The draft target creates HTML output in draft mode, without index (for faster build). @@ -222,9 +211,6 @@ regress_README.html: regress.sgml ## XSLT processing ## -OSX = osx # (may be called sx or sgml2xml on some systems) -XSLTPROC = xsltproc - postgres.xml: postgres.sgml $(ALMOSTALLSGML) $(OSX) -D. -x lower $< | \ $(PERL) -p -e 's/\[(amp|copy|egrave|gt|lt|mdash|nbsp|ouml|pi|quot|uuml) *\]/\&\1;/g;' \ @@ -232,8 +218,6 @@ postgres.xml: postgres.sgml $(ALMOSTALLSGML) >$@ # ' hello Emacs -override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)' - xslthtml: stylesheet.xsl postgres.xml $(XSLTPROC) $(XSLTPROCFLAGS) $^ @@ -268,18 +252,6 @@ MAKEINFO = makeinfo .SUFFIXES: -## -## Experimental man page building through docbook2x -## - -manx: postgres.xml stylesheet-man.xsl - $(DOCBOOK2MAN) --solinks -s $(srcdir)/stylesheet-man.xsl --string-param default-manpage-section=$(DEFAULTSECTION) $< - $(mkinstalldirs) man1 man7 - mv *.1 man1/ - mv *.7 man7/ - rm *.$(DEFAULTSECTION) - - ## ## Check ## @@ -297,7 +269,7 @@ clean distclean maintainer-clean: # HTML rm -f *.html html-stamp # man - rm -rf *.1 *.7 *.$(DEFAULTSECTION) man1 man7 manpage.refs manpage.links manpage.log + rm -rf man1 man7 man-stamp # print rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot # index diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 4aafc4e2a0..9e07f5a31a 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,4 +1,4 @@ - + Documentation @@ -83,13 +83,14 @@ - DocBook DTD + DocBook DTD 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 XML version of DocBook - — do not use that. + version 4.2; you cannot use later or earlier versions. You + need the SGML variant of the DocBook DTD, + but to build man pages you also need the XML + variant of the same version. @@ -105,47 +106,51 @@ - OpenJade + DocBook DSSSL Stylesheets - This is the base package of SGML processing. - It contains an SGML parser, a - DSSSL processor (that is, a program to - convert SGML to other formats using - DSSSL stylesheets), as well as a number of - related tools. Jade is now being - maintained by the OpenJade group, no longer by James Clark. + These contain the processing instructions for converting the + DocBook sources to other formats, such as + HTML. - DocBook DSSSL Stylesheets + DocBook XSL Stylesheets - These contain the processing instructions for converting the - DocBook sources to other formats, such as - HTML. + 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. - SGMLSpm + OpenJade - This optional package is used to create man pages. + This is the base package of SGML processing. + It contains an SGML parser, a + DSSSL processor (that is, a program to + convert SGML to other formats using + DSSSL stylesheets), as well as a number of + related tools. Jade is now being + maintained by the OpenJade group, no longer by James Clark. - DocBook2X + Libxslt for xsltproc - This optional package is also used to create man pages. You - want the docbook2man-sgmlspl package, not - the main docbook2x package. + This is the processing tool to use with the XSLT stylesheets + (like jade is the processing tool for DSSSL + stylesheets). @@ -263,13 +268,8 @@ CATALOG "docbook/4.2/catalog" available for Debian GNU/Linux. To install, simply use: -apt-get install openjade1.3 -apt-get install docbook -apt-get install docbook-dsssl -apt-get install sgmlspl # for the man pages +apt-get install docbook docbook-dsssl docbook-xsl openjade xsltproc - (The plain openjade package installs - OpenJade 1.4, which seems not to work.) @@ -511,13 +511,15 @@ CATALOG "docbook-dsssl-1.xx/catalog" 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 +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 If neither onsgmls nor - nsgmls were found then you will not see the - remaining 4 lines. nsgmls is part of the Jade + nsgmls were found then some of the following tests + will be skipped. nsgmls is part of the Jade package. You can pass the environment variables JADE and NSGMLS to configure to point to the programs if they are not found automatically. If @@ -583,8 +585,7 @@ gmake postgres.tar.gz Manpages - We use the docbook2man-sgmlspl utility - from the DocBook2X project to + We use the DocBook XSL stylesheets to convert DocBook refentry pages to *roff output suitable for man pages. The man pages are also distributed as a tar archive, @@ -592,32 +593,15 @@ gmake postgres.tar.gz pages, use the commands: cd doc/src/sgml -gmake man D2MDIR=directory +gmake man - 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 create the man page package for a release, use the following commands: cd doc/src -gmake man.tar.gz D2MDIR=directory +gmake man.tar.gz which will result in a tar file being generated in the doc/src directory. diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index d4c4d40bbe..caebed5444 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,4 +1,4 @@ - + The PostgreSQL Global Development Group + PostgreSQL + &version; &legal; diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index c0d2673dc5..cb9f20f3f5 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -1,5 +1,5 @@ @@ -94,7 +94,7 @@ ANALYZE [ VERBOSE ] [ table [ ( In the default PostgreSQL configuration, - + the autovacuum daemon (see ) takes care of automatic analyzing of tables when they are first loaded with data, and as they change throughout regular operation. When autovacuum is disabled, diff --git a/doc/src/sgml/stylesheet-man.xsl b/doc/src/sgml/stylesheet-man.xsl index 2d37a42f1a..842a9bd503 100644 --- a/doc/src/sgml/stylesheet-man.xsl +++ b/doc/src/sgml/stylesheet-man.xsl @@ -1,16 +1,158 @@ - + + xmlns:exsl="http://exslt.org/common" + version='1.0' + exclude-result-prefixes="exsl"> - + + - + + + + + +0 +0 + + + +40 + + + - - + + + + + + + + + + + + + + + + + + + ( + + + + + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Note: + (soelim stub) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml index 348434f917..50e5943401 100644 --- a/doc/src/sgml/trigger.sgml +++ b/doc/src/sgml/trigger.sgml @@ -1,4 +1,4 @@ - + Triggers @@ -541,7 +541,7 @@ typedef struct Trigger - A Complete Example + A Complete Trigger Example Here is a very simple example of a trigger function written in C. diff --git a/src/Makefile.global.in b/src/Makefile.global.in index 763bdc004a..04f3b1a7dd 100644 --- a/src/Makefile.global.in +++ b/src/Makefile.global.in @@ -1,5 +1,5 @@ # -*-makefile-*- -# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.254 2009/06/23 03:46:00 tgl Exp $ +# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.255 2009/08/04 22:04:37 petere Exp $ #------------------------------------------------------------------------------ # All PostgreSQL makefiles include this file and use the variables it sets, @@ -187,11 +187,6 @@ TCL_SHLIB_LD_LIBS = @TCL_SHLIB_LD_LIBS@ PTHREAD_CFLAGS = @PTHREAD_CFLAGS@ PTHREAD_LIBS = @PTHREAD_LIBS@ -have_docbook = @have_docbook@ -DOCBOOKSTYLE = @DOCBOOKSTYLE@ -COLLATEINDEX = @COLLATEINDEX@ -DOCBOOK2MAN = @DOCBOOK2MAN@ - ########################################################################## # @@ -298,9 +293,13 @@ STRIP_SHARED_LIB = @STRIP_SHARED_LIB@ # Documentation -JADE = @JADE@ -NSGMLS = @NSGMLS@ -SGMLSPL = @SGMLSPL@ +have_docbook = @have_docbook@ +COLLATEINDEX = @COLLATEINDEX@ +DOCBOOKSTYLE = @DOCBOOKSTYLE@ +JADE = @JADE@ +NSGMLS = @NSGMLS@ +OSX = @OSX@ +XSLTPROC = @XSLTPROC@ # Code coverage -- 2.40.0