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.

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.
ed920882 · Peter Eisentraut · 97e14f6e · ed920882 · ed920882 · ed920882
Commit ed920882 authored Aug 09, 2009 by Peter Eisentraut
8 changed files
--- a/GNUmakefile.in
+++ b/GNUmakefile.in
 #
 # PostgreSQL top level makefile
 #
-# $PostgreSQL: pgsql/GNUmakefile.in,v 1.51 2009/08/07 20:50:21 petere Exp $
+# $PostgreSQL: pgsql/GNUmakefile.in,v 1.52 2009/08/09 22:47:58 petere Exp $
 #

 subdir =
@@ -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 $@

--- a/doc/Makefile
+++ b/doc/Makefile
 #----------------------------------------------------------------------------
 #
-# PostgreSQL documentation installation makefile
+# PostgreSQL documentation top-level makefile
 #
 # Copyright (c) 1994, Regents of the University of California
 #
-# $PostgreSQL: pgsql/doc/Makefile,v 1.38 2009/08/05 19:31:49 alvherre Exp $
+# $PostgreSQL: pgsql/doc/Makefile,v 1.39 2009/08/09 22:47:59 petere Exp $
 #
 #----------------------------------------------------------------------------

-# 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 $@
--- a/doc/src/Makefile
+++ b/doc/src/Makefile
-# Postgres documentation makefile
-# $PostgreSQL: pgsql/doc/src/Makefile,v 1.36 2009/08/05 19:31:50 alvherre Exp $
+# $PostgreSQL: pgsql/doc/src/Makefile,v 1.37 2009/08/09 22:47:59 petere Exp $

 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
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -2,16 +2,28 @@
 #
 # PostgreSQL documentation makefile
 #
-# $PostgreSQL: pgsql/doc/src/sgml/Makefile,v 1.121 2009/08/05 19:31:50 alvherre Exp $
+# $PostgreSQL: pgsql/doc/src/sgml/Makefile,v 1.122 2009/08/09 22:47:59 petere Exp $
 #
 #----------------------------------------------------------------------------

+# 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
@@ -261,25 +281,106 @@ check: postgres.sgml $(ALMOSTALLSGML)
 	$(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $<


+##
+## 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)
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
-<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.77 2009/08/04 22:04:37 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.78 2009/08/09 22:47:59 petere Exp $ -->

 <appendix id="docguide">
 <title>Documentation</title>
@@ -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>

--- a/doc/src/sgml/stylesheet.dsl
+++ b/doc/src/sgml/stylesheet.dsl
-<!-- $PostgreSQL: pgsql/doc/src/sgml/stylesheet.dsl,v 1.34 2009/07/14 22:16:38 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/stylesheet.dsl,v 1.35 2009/08/09 22:47:59 petere Exp $ -->
 <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [

 <!-- must turn on one of these with -i on the jade command line -->
@@ -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

--- 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>

--- a/src/Makefile.global.in
+++ b/src/Makefile.global.in
 # -*-makefile-*-
-# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.256 2009/08/07 20:50:22 petere Exp $
+# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.257 2009/08/09 22:47:59 petere Exp $

 #------------------------------------------------------------------------------
 # All PostgreSQL makefiles include this file and use the variables it sets,
@@ -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