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.
This commit is contained in:
Peter Eisentraut 2009-08-09 22:47:59 +00:00
parent 97e14f6e93
commit ed9208829a
8 changed files with 163 additions and 180 deletions

View File

@ -1,7 +1,7 @@
#
# 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 $@

View File

@ -1,108 +1,16 @@
#----------------------------------------------------------------------------
#
# 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 $@

View File

@ -1,18 +1,8 @@
# 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

View File

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

View File

@ -1,4 +1,4 @@
<!-- $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>

View File

@ -1,4 +1,4 @@
<!-- $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

View File

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

View File

@ -1,5 +1,5 @@
# -*-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