Rearrangement of the HTML docs build rules

Set up proper makefile dependencies in the documentation build rules,
especially around the HTML/index build.  The problem we've had with all
previous solutions is that we have used the same file name, such as HTML.index
or bookindex.sgml, to mean different things at different stages of the build,
and make can't distinguish that.  The solution here is that the first jade run
produces HTML.index, but does not require bookindex.sgml at all, and produces
no other html output (the latter an idea from Alvaro).  The second jade run
includes bookindex.sgml, but does not recreate HTML.index.  That way, when you
change an sgml file, jade is run twice and at the end all dependencies are
satisfied.  Omitting the html output in the first stage also makes the full
build a lot faster.

When you run one of the print format targets, only the first jade run is run,
then the print target-specific commands.  If an HTML build has completed
previously, the first jade run is skipped because the dependencies have
already been satisfied.

The draft and check targets for quick builds and syntax verification are still
there.
This commit is contained in:
Peter Eisentraut 2009-07-14 22:16:38 +00:00
parent 4baaaf7a81
commit 4ef8dc7a75
4 changed files with 44 additions and 35 deletions

View File

@ -2,7 +2,7 @@
# #
# PostgreSQL documentation makefile # PostgreSQL documentation makefile
# #
# $PostgreSQL: pgsql/doc/src/sgml/Makefile,v 1.117 2009/06/25 21:15:38 petere Exp $ # $PostgreSQL: pgsql/doc/src/sgml/Makefile,v 1.118 2009/07/14 22:16:38 petere Exp $
# #
#---------------------------------------------------------------------------- #----------------------------------------------------------------------------
@ -51,6 +51,9 @@ GENERATED_SGML = bookindex.sgml version.sgml \
ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
# Sometimes we don't want this one.
ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML))
ifdef DOCBOOKSTYLE ifdef DOCBOOKSTYLE
CATALOG = -c $(DOCBOOKSTYLE)/catalog CATALOG = -c $(DOCBOOKSTYLE)/catalog
endif endif
@ -94,37 +97,27 @@ man: postgres.sgml $(ALLSGML)
all: html all: html
# The draft target creates HTML output in draft mode JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html
draft : JADEFLAGS += -V draft-mode
draft: html-output
html: html-output # The draft target creates HTML output in draft mode, without index (for faster build).
# Re-run this target until HTML.index does not change draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
@cmp -s HTML.index.start HTML.index || $(MAKE) $@ $(JADE.html.call) -V draft-mode $<
# This is run for all output formats because we need bookindex.sgml html: html-stamp
html-output: postgres.sgml $(ALLSGML) stylesheet.dsl
html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl
@rm -f *.html @rm -f *.html
$(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-html -t sgml $< $(JADE.html.call) -i include-index $<
ifeq ($(vpath_build), yes) ifeq ($(vpath_build), yes)
@cp $(srcdir)/stylesheet.css . @cp $(srcdir)/stylesheet.css .
endif endif
touch $@
COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
$(JADE.html.call) -V html-index $<
# bookindex.sgml is required so there is a proper index for all output formats
bookindex.sgml: HTML.index bookindex.sgml: HTML.index
# create a dummy bookindex.html LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $<
test -s HTML.index || $(COLLATEINDEX) -o $@ -N
# If HTML.index is valid, create a valid bookindex.sgml.
test ! -s HTML.index || $(COLLATEINDEX) -i 'bookindex' -o $@ $<
# save copy of HTML.index for later comparison
@cp HTML.index HTML.index.start
# HTML.index is used to create bookindex.sgml
HTML.index:
# create an empty HTML.index if it does not exist
@$(if $(wildcard HTML.index), , touch HTML.index)
version.sgml: $(top_builddir)/src/Makefile.global version.sgml: $(top_builddir)/src/Makefile.global
{ \ { \
@ -146,13 +139,13 @@ features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_package
# RTF to allow minor editing for hardcopy # RTF to allow minor editing for hardcopy
%.rtf: %.sgml $(ALLSGML) html %.rtf: %.sgml $(ALLSGML) html
$(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print postgres.sgml $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print -i include-index postgres.sgml
# TeX # TeX
# Regular TeX and pdfTeX have slightly differing requirements, so we # Regular TeX and pdfTeX have slightly differing requirements, so we
# need to distinguish the path we're taking. # need to distinguish the path we're taking.
JADE.tex.call = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d $(srcdir)/stylesheet.dsl -t tex -V tex-backend -i output-print JADE.tex.call = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d $(srcdir)/stylesheet.dsl -t tex -V tex-backend -i output-print -i include-index
%-A4.tex-ps: %.sgml $(ALLSGML) html %-A4.tex-ps: %.sgml $(ALLSGML) html
$(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $<
@ -195,7 +188,7 @@ postgres.pdf:
# for debugging DSSSL code, and possibly to interface to some other # for debugging DSSSL code, and possibly to interface to some other
# tools that can make use of this. # tools that can make use of this.
%.fot: %.sgml $(ALLSGML) html %.fot: %.sgml $(ALLSGML) html
$(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t fot -i output-print -o $@ $< $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t fot -i output-print -i include-index -o $@ $<
## ##
@ -292,7 +285,7 @@ manx: postgres.xml stylesheet-man.xsl
## ##
# Quick syntax check without style processing # Quick syntax check without style processing
check: postgres.sgml $(ALLSGML) check: postgres.sgml $(ALMOSTALLSGML)
$(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $<
@ -302,7 +295,7 @@ check: postgres.sgml $(ALLSGML)
clean distclean maintainer-clean: clean distclean maintainer-clean:
# HTML # HTML
rm -f HTML.manifest *.html rm -f *.html html-stamp
# man # man
rm -rf *.1 *.7 *.$(DEFAULTSECTION) man1 man7 manpage.refs manpage.links manpage.log rm -rf *.1 *.7 *.$(DEFAULTSECTION) man1 man7 manpage.refs manpage.links manpage.log
# print # print

View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.61 2009/05/02 20:17:19 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.62 2009/07/14 22:16:38 petere Exp $ -->
<!entity history SYSTEM "history.sgml"> <!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml"> <!entity info SYSTEM "info.sgml">
@ -165,3 +165,9 @@
--> -->
<!entity % standalone-ignore "INCLUDE"> <!entity % standalone-ignore "INCLUDE">
<!entity % standalone-include "IGNORE"> <!entity % standalone-include "IGNORE">
<!--
By default, no index is included. Use -i include-index on the command line
to include it.
-->
<!entity % include-index "IGNORE">

View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.88 2009/06/17 21:58:49 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.89 2009/07/14 22:16:38 petere Exp $ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
@ -262,6 +262,6 @@
</part> </part>
&biblio; &biblio;
&bookindex; <![%include-index;[&bookindex;]]>
</book> </book>

View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/stylesheet.dsl,v 1.33 2007/12/28 11:14:19 petere Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/stylesheet.dsl,v 1.34 2009/07/14 22:16:38 petere Exp $ -->
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!-- must turn on one of these with -i on the jade command line --> <!-- must turn on one of these with -i on the jade command line -->
@ -180,6 +180,19 @@
(define %body-attr% '()) (define %body-attr% '())
(define ($generate-book-lot-list$) '()) (define ($generate-book-lot-list$) '())
;; Only build HTML.index or the actual HTML output, not both. Saves a
;; *lot* of time. (overrides docbook.dsl)
(root
(if (not html-index)
(make sequence
(process-children)
(with-mode manifest
(process-children)))
(with-mode htmlindex
(process-children))))
;; Do not combine first section into chapter chunk. ;; Do not combine first section into chapter chunk.
(define (chunk-skip-first-element-list) '()) (define (chunk-skip-first-element-list) '())
@ -202,9 +215,6 @@
(list (list "META" '("HTTP-EQUIV" "Content-Type") '("CONTENT" "text/html; charset=ISO-8859-1")) (list (list "META" '("HTTP-EQUIV" "Content-Type") '("CONTENT" "text/html; charset=ISO-8859-1"))
(list "META" '("NAME" "creation") (list "CONTENT" (time->string (time) #t))))) (list "META" '("NAME" "creation") (list "CONTENT" (time->string (time) #t)))))
;; Create an index
(define html-index #t)
;; Block elements are allowed in PARA in DocBook, but not in P in ;; Block elements are allowed in PARA in DocBook, but not in P in
;; HTML. With %fix-para-wrappers% turned on, the stylesheets attempt ;; HTML. With %fix-para-wrappers% turned on, the stylesheets attempt