Ship documentation without intermediate tarballs

Documentation files in HTML and man formats are now prepared for
distribution using the distprep make target, like everything else.  They
are placed in doc/src/sgml/html and manX and installed from there by
make install, if present.  The business with the tarballs in the tarball
is gone.

8 files changed, 156 insertions, 173 deletions

diff --git a/GNUmakefile.in b/GNUmakefile.in
index 342ac1a203..1f1232d37f 100644
--- a/GNUmakefile.in
+++ b/GNUmakefile.in
@@ -14,6 +14,9 @@ all:
 	$(MAKE) -C config all
 	@echo "All of PostgreSQL successfully made. Ready to install."
 
+html man:
+	$(MAKE) -C doc $@
+
 install:
 	$(MAKE) -C doc $@
 	$(MAKE) -C src $@
diff --git a/doc/Makefile b/doc/Makefile
index e7f763943e..48c1f3249b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,6 +1,6 @@
 #----------------------------------------------------------------------------
 #
-# PostgreSQL documentation installation makefile
+# PostgreSQL documentation top-level makefile
 #
 # Copyright (c) 1994, Regents of the University of California
 #
@@ -8,101 +8,9 @@
 #
 #----------------------------------------------------------------------------
 
-# This makefile is responsible for installing the documentation. The
-# files to be installed are prepared specially and are placed in this
-# directory during distribution bundling. In CVS-based trees these
-# files don't exist, so we skip the installation in that case.
-#
-# Before we install the man pages, we massage the section numbers to
-# follow the local conventions.
-#
-# To actually build the documenation, look into the src/ and src/sgml
-# subdirectories.
-
 subdir = doc
 top_builddir = ..
 include $(top_builddir)/src/Makefile.global
 
-.NOTPARALLEL:
-
-ifneq ($(wildcard $(srcdir)/postgres.tar.gz),)
-found_html = yes
-endif
-
-ifneq ($(wildcard $(srcdir)/man.tar.gz),)
-# SCO OpenServer's man system is sufficiently different to not bother.
-ifneq ($(PORTNAME), sco)
-found_man = yes
-endif
-endif
-
-
-ifdef found_man
-ifndef sqlmansect
-sqlmansect = 7
-endif
-sqlmansectnum = $(shell expr X'$(sqlmansect)' : X'\([0-9]\)')
-
-fix_sqlmansectnum = sed -e '/^\.TH/s/"7"/"$(sqlmansect)"/' \
-			-e 's/\\fR(7)/\\fR($(sqlmansectnum))/g' \
-			-e '1s/^\.so man7/.so man$(sqlmansectnum)/g;1s/^\(\.so.*\)\.7$$/\1.$(sqlmansect)/g'
-
-all: man1/.timestamp man3/.timestamp man$(sqlmansectnum)/.timestamp
-
-man1/.timestamp man3/.timestamp: man7/.timestamp
-	@echo timestamp >$@
-
-man7/.timestamp: man.tar.gz
-	gzip -d -c $< | $(TAR) xf -
-ifneq ($(sqlmansectnum),7)
-	for file in man1/*.1; do \
-	  mv $$file $$file.bak && \
-	  $(fix_sqlmansectnum) $$file.bak >$$file && \
-	  rm -f $$file.bak || exit; \
-	done
-endif
-	@echo timestamp >$@
-
-ifneq ($(sqlmansectnum),7)
-man$(sqlmansectnum)/.timestamp: man7/.timestamp
-	$(mkinstalldirs) man$(sqlmansectnum)
-	for file in man7/*.7; do \
-	  $(fix_sqlmansectnum) $$file >man$(sqlmansectnum)/`basename $$file | sed 's/.7$$/.$(sqlmansect)/'` || exit; \
-	done
-	@echo timestamp >$@
-endif
-endif # found_man
-
-
-install: all installdirs
-ifdef found_html
-	gzip -d -c $(srcdir)/postgres.tar.gz | ( cd $(DESTDIR)$(htmldir)/html && $(TAR) xf - )
-endif
-ifdef found_man
-	for file in man1/*.1 man3/*.3 man$(sqlmansectnum)/*.$(sqlmansect) ; do \
-	  $(INSTALL_DATA) $$file $(DESTDIR)$(mandir)/$$file || exit; \
-	done
-endif
-
-
-installdirs:
-ifdef found_html
-	$(mkinstalldirs) '$(DESTDIR)$(htmldir)'/html
-endif
-ifdef found_man
-	$(mkinstalldirs) $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
-endif
-
-
-uninstall:
-ifdef found_html
-	rm -f $(addprefix $(DESTDIR)$(htmldir)/html/, $(shell gunzip -c $(srcdir)/postgres.tar.gz | $(TAR) tf -))
-endif
-ifdef found_man
-	rm -f $(filter-out %/, $(addprefix $(DESTDIR)$(mandir)/, $(shell gunzip -c $(srcdir)/man.tar.gz | $(TAR) tf - | sed -e 's,man7/,man$(sqlmansectnum)/,' -e 's/.7$$/.$(sqlmansect)/')))
-endif
-
-
-clean distclean maintainer-clean:
-	rm -rf man1/ man3/ man7/ man$(sqlmansectnum)/
+all distprep html man install installdirs uninstall clean distclean maintainer-clean:
 	$(MAKE) -C src $@
diff --git a/doc/src/Makefile b/doc/src/Makefile
index e8734b792f..ea2730a57c 100644
--- a/doc/src/Makefile
+++ b/doc/src/Makefile
@@ -1,18 +1,8 @@
-# Postgres documentation makefile
 # $PostgreSQL$
 
 subdir = doc/src
 top_builddir = ../..
 include $(top_builddir)/src/Makefile.global
 
-clean distclean maintainer-clean:
-	rm -f *.tar *.gz
+all distprep html man install installdirs uninstall clean distclean maintainer-clean:
 	$(MAKE) -C sgml $@
-
-postgres.tar:
-	$(MAKE) -C sgml html JADEFLAGS='-V html-manifest'
-	cd sgml && $(TAR) -cf ../$@ `cat HTML.manifest` `echo *.gif | grep -v '\*'` *.css
-
-man.tar:
-	$(MAKE) -C sgml man
-	$(TAR) -cf $@ -C sgml man1 man3 man7
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index c860b713f5..6020206fd7 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -6,12 +6,24 @@
 #
 #----------------------------------------------------------------------------
 
+# This makefile is for building and installing the documentation.
+# When a release tarball is created, the documentation files are
+# prepared using the distprep target.  In CVS-based trees these files
+# don't exist, unless explicitly built, so we skip the installation in
+# that case.
+
+
+# Make "html" the default target, since that is what most people tend
+# to want to use.
+html:
+
 subdir = doc/src/sgml
 top_builddir = ../../..
 include $(top_builddir)/src/Makefile.global
 
-.NOTPARALLEL:
-.PRECIOUS: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf
+
+distprep: html man
+
 
 ifndef COLLATEINDEX
 COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl
@@ -22,13 +34,6 @@ JADE = jade
 endif
 SGMLINCLUDE = -D $(srcdir)
 
-# If this is a vpath build, some generated SGML will be in the build
-# tree, so we need to make sure we look there as well as in the
-# source tree
-ifeq ($(vpath_build), yes)
-SGMLINCLUDE += -D .
-endif
-
 ifndef NSGMLS
 NSGMLS = nsgmls
 endif
@@ -68,13 +73,15 @@ override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged
 ## Man pages
 ##
 
-.PHONY: man
-
 man: man-stamp
 
-man-stamp: stylesheet-man.xsl postgres.xml
-	$(XSLTPROC) $(XSLTPROCFLAGS) $^
-	rm man1/dblink*
+ifeq ($(vpath_build),yes)
+XSLTPROC_MAN_FLAGS = --stringparam man.output.base.dir '$(srcdir)/'
+endif
+
+$(srcdir)/man-stamp: stylesheet-man.xsl postgres.xml
+	$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^
+	rm $(srcdir)/man1/dblink*
 	touch $@
 
 
@@ -82,42 +89,45 @@ man-stamp: stylesheet-man.xsl postgres.xml
 ## HTML
 ##
 
-all: html
-
-.PHONY: html draft
+.PHONY: draft
 
 JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html
+ifeq ($(vpath_build),yes)
+# This only works with openjade, not with the older jade.
+JADE.html.call += -V '(define %output-dir% "$(srcdir)/html")'
+endif
 
 # The draft target creates HTML output in draft mode, without index (for faster build).
 draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
+	$(mkinstalldirs) $(srcdir)/html
 	$(JADE.html.call) -V draft-mode $<
+	cp $(srcdir)/stylesheet.css $(srcdir)/html/
 
 html: html-stamp
 
-html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl
-	@rm -f *.html
+$(srcdir)/html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl
+	$(mkinstalldirs) $(srcdir)/html
 	$(JADE.html.call) -i include-index $<
-ifeq ($(vpath_build), yes)
-	@cp $(srcdir)/stylesheet.css .
-endif
+	cp $(srcdir)/stylesheet.css $(srcdir)/html/
 	touch $@
 
-HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
+$(srcdir)/HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
+	@$(mkinstalldirs) $(srcdir)/html
 	$(JADE.html.call) -V html-index $<
 
-bookindex.sgml: HTML.index
+$(srcdir)/bookindex.sgml: HTML.index
 	LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $<
 
-version.sgml: $(top_builddir)/src/Makefile.global
+$(srcdir)/version.sgml: $(top_builddir)/src/Makefile.global
 	{ \
 	  echo "<!entity version \"$(VERSION)\">"; \
 	  echo "<!entity majorversion \"$(MAJORVERSION)\">"; \
 	} >$@
 
-features-supported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
+$(srcdir)/features-supported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
 	$(PERL) $(srcdir)/mk_feature_tables.pl YES $^ > $@
 
-features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
+$(srcdir)/features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt
 	$(PERL) $(srcdir)/mk_feature_tables.pl NO $^ > $@
 
 
@@ -172,6 +182,11 @@ postgres.pdf:
 	pdfjadetex $<
 	pdfjadetex $<
 
+.PRECIOUS: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf
+
+# Cancel built-in suffix rules, interfering with PS building
+.SUFFIXES:
+
 
 # This generates an XML version of the flow-object tree.  It's useful
 # for debugging DSSSL code, and possibly to interface to some other
@@ -211,6 +226,10 @@ regress_README.html: regress.sgml
 ## XSLT processing
 ##
 
+# This allows removing postgres.xml in the distribution tarballs while
+# keeping the dependencies satisfied.
+.SECONDARY: postgres.xml
+
 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;' \
@@ -218,8 +237,12 @@ postgres.xml: postgres.sgml $(ALMOSTALLSGML)
 	  >$@
 # ' hello Emacs
 
+ifeq ($(vpath_build),yes)
+XSLTPROC_HTML_FLAGS = --stringparam base.dir '$(srcdir)/html'
+endif
+
 xslthtml: stylesheet.xsl postgres.xml
-	$(XSLTPROC) $(XSLTPROCFLAGS) $^
+	$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^
 
 htmlhelp: stylesheet-hh.xsl postgres.xml
 	$(XSLTPROC) $(XSLTPROCFLAGS) $^
@@ -248,9 +271,6 @@ MAKEINFO = makeinfo
 %.info: %.texi
 	$(MAKEINFO) --enable-encoding --no-split --no-validate $< -o $@
 
-# Cancel built-in suffix rules, interfering with PS building
-.SUFFIXES:
-
 
 ##
 ## Check
@@ -262,24 +282,105 @@ check: postgres.sgml $(ALMOSTALLSGML)
 
 
 ##
+## Install
+##
+
+found_html = $(wildcard $(srcdir)/html-stamp)
+
+ifneq ($(wildcard $(srcdir)/man-stamp),)
+# SCO OpenServer's man system is sufficiently different to not bother.
+ifneq ($(PORTNAME), sco)
+found_man = yes
+endif
+endif
+
+install: $(if $(found_html),install-html) $(if $(found_man),install-man)
+
+installdirs:
+	$(mkinstalldirs) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
+
+uninstall:
+	rm -f '$(DESTDIR)$(htmldir)/html/'* $(addprefix  '$(DESTDIR)$(mandir)'/man, 1/* 3/* $(sqlmansectnum)/*)
+
+
+## Install html
+
+install-html: html installdirs
+	cp -R $(srcdir)/html '$(DESTDIR)$(htmldir)'
+
+
+## Install man
+
+sqlmansect ?= 7
+sqlmansectnum = $(shell expr X'$(sqlmansect)' : X'\([0-9]\)')
+
+define install-man-func
+for file in $(1); do \
+  $(INSTALL_DATA) $$file $(DESTDIR)$(mandir)/`echo $$file | sed 's,^$(2),,'` || exit; \
+done
+endef
+
+# Before we install the man pages, we massage the section numbers to
+# follow the local conventions.
+#
+ifeq ($(sqlmansectnum),7)
+install-man:
+	$(call install-man-func,$(addprefix $(srcdir)/,man1/*.1 man3/*.3 man$(sqlmansectnum)/*.$(sqlmansect)),$(srcdir)/)
+
+else # sqlmansectnum != 7
+fix_sqlmansectnum = sed -e '/^\.TH/s/"7"/"$(sqlmansect)"/' \
+			-e 's/\\fR(7)/\\fR($(sqlmansectnum))/g' \
+			-e '1s/^\.so man7/.so man$(sqlmansectnum)/g;1s/^\(\.so.*\)\.7$$/\1.$(sqlmansect)/g'
+
+nonsql_manpage_files := $(wildcard $(srcdir)/man1/*.1 $(srcdir)/man3/*.3)
+sql_manpage_files := $(wildcard $(srcdir)/man7/*.7)
+
+fixed_nonsql_manpage_files = $(patsubst $(srcdir)/%,fixedman/%,$(nonsql_manpage_files))
+fixed_sql_manpage_files = $(patsubst $(srcdir)/man7/%.7,fixedman/man$(sqlmansectnum)/%.$(sqlmansect),$(sql_manpage_files))
+
+fixed_manpage_files = $(fixed_nonsql_manpage_files) $(fixed_sql_manpage_files)
+
+all: all-man
+all-man: $(fixed_manpage_files)
+
+$(fixed_nonsql_manpage_files): fixedman/%: %
+	@$(mkinstalldirs) $(dir $@)
+	$(fix_sqlmansectnum) $< >$@
+
+$(fixed_sql_manpage_files): fixedman/man$(sqlmansectnum)/%.$(sqlmansect): man7/%.7
+	@$(mkinstalldirs) $(dir $@)
+	$(fix_sqlmansectnum) $< >$@
+
+install-man: all-man
+	$(call install-man-func,$(fixed_manpage_files),fixedman/)
+
+clean: clean-man
+.PHONY: clean-man
+clean-man:
+	rm -rf fixedman/
+
+endif # sqlmansectnum != 7
+
+
+##
 ## Clean
 ##
 
-clean distclean maintainer-clean:
+distclean:
+	rm -f postgres.xml
+
+maintainer-clean: distclean
 # HTML
-	rm -f *.html html-stamp
+	rm -rf $(addprefix $(srcdir)/,html/ html-stamp)
 # man
-	rm -rf man1 man3 man7 man-stamp
+	rm -rf $(addprefix $(srcdir)/,man1/ man3/ man7/ man-stamp)
 # print
-	rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot
+	rm -f $(addprefix $(srcdir)/,*.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot)
 # index
-	rm -f HTML.index $(GENERATED_SGML)
+	rm -f $(addprefix $(srcdir)/,HTML.index $(GENERATED_SGML))
 # text
-	rm -f INSTALL HISTORY regress_README
+	rm -f $(addprefix $(srcdir)/,INSTALL HISTORY regress_README)
 # XSLT
-	rm -f postgres.xml htmlhelp.hhp toc.hhc index.hhk *.fo
+	rm -f $(addprefix $(srcdir)/,htmlhelp.hhp toc.hhc index.hhk *.fo)
 # Texinfo
-	rm -f *.texixml *.texi *.info db2texi.refs
-ifeq ($(vpath_build), yes)
-	rm -f stylesheet.css
-endif
+	rm -f $(addprefix $(srcdir)/,*.texixml *.texi *.info db2texi.refs)
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index e03cd10241..c1e27b3400 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -554,7 +554,8 @@ checking for osx... osx
 <screen>
 <prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
 </screen>
-    This is also the default target.
+    This is also the default target.  The output appears in the
+    subdirectory <filename>html</filename>.
    </para>
 
    <para>
@@ -565,20 +566,6 @@ checking for osx... osx
 <prompt>doc/src/sgml$ </prompt><userinput>gmake draft</userinput>
 </screen>
    </para>
-
-   <para>
-    To allow for easier handling in the final distribution, the files
-    comprising the HTML documentation can be 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>
@@ -596,16 +583,6 @@ 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.
-  </para>
  </sect2>
 
   <sect2>
diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl
index ae00f35201..476b4128b5 100644
--- a/doc/src/sgml/stylesheet.dsl
+++ b/doc/src/sgml/stylesheet.dsl
@@ -179,6 +179,9 @@
 (define %gentext-nav-use-ff%    #t)
 (define %body-attr%             '())
 (define ($generate-book-lot-list$) '())
+(define use-output-dir          #t)
+(define %output-dir%            "html")
+(define html-index-filename     "../HTML.index")
 
 
 ;; Only build HTML.index or the actual HTML output, not both.  Saves a
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index faee9d0e04..19cb5b0f64 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -9,6 +9,7 @@
 
 
 <!-- Parameters -->
+<xsl:param name="base.dir" select="'html'"></xsl:param>
 <xsl:param name="html.stylesheet" select="'stylesheet.css'"></xsl:param>
 <xsl:param name="use.id.as.filename" select="'1'"></xsl:param>
 <xsl:param name="make.valid.html" select="1"></xsl:param>
diff --git a/src/Makefile.global.in b/src/Makefile.global.in
index ab1f49332f..eb046fa9c4 100644
--- a/src/Makefile.global.in
+++ b/src/Makefile.global.in
@@ -18,7 +18,7 @@
 #
 # Meta configuration
 
-.PHONY: all install install-strip installdirs uninstall clean distclean maintainer-clean distprep check installcheck maintainer-check coverage
+.PHONY: all install install-strip installdirs uninstall clean distclean maintainer-clean distprep check installcheck maintainer-check coverage html man
 .SILENT: installdirs
 
 # make `all' the default target