From 4ef8dc7a75a9a408b34338854dd0d412ea01c504 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Tue, 14 Jul 2009 22:16:38 +0000 Subject: [PATCH] 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. --- doc/src/sgml/Makefile | 49 ++++++++++++++++--------------------- doc/src/sgml/filelist.sgml | 8 +++++- doc/src/sgml/postgres.sgml | 4 +-- doc/src/sgml/stylesheet.dsl | 18 +++++++++++--- 4 files changed, 44 insertions(+), 35 deletions(-) diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 6b408f98db..b9d3925aed 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.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) +# Sometimes we don't want this one. +ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML)) + ifdef DOCBOOKSTYLE CATALOG = -c $(DOCBOOKSTYLE)/catalog endif @@ -94,37 +97,27 @@ man: postgres.sgml $(ALLSGML) all: html -# The draft target creates HTML output in draft mode -draft : JADEFLAGS += -V draft-mode -draft: html-output +JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html -html: html-output -# Re-run this target until HTML.index does not change - @cmp -s HTML.index.start HTML.index || $(MAKE) $@ +# The draft target creates HTML output in draft mode, without index (for faster build). +draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl + $(JADE.html.call) -V draft-mode $< -# This is run for all output formats because we need bookindex.sgml -html-output: postgres.sgml $(ALLSGML) stylesheet.dsl +html: html-stamp + +html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl @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) @cp $(srcdir)/stylesheet.css . 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 -# create a dummy bookindex.html - 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) + LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $< 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: %.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 # Regular TeX and pdfTeX have slightly differing requirements, so we # 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 $(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 # tools that can make use of this. %.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 -check: postgres.sgml $(ALLSGML) +check: postgres.sgml $(ALMOSTALLSGML) $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< @@ -302,7 +295,7 @@ check: postgres.sgml $(ALLSGML) clean distclean maintainer-clean: # HTML - rm -f HTML.manifest *.html + rm -f *.html html-stamp # man rm -rf *.1 *.7 *.$(DEFAULTSECTION) man1 man7 manpage.refs manpage.links manpage.log # print diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 385b8815f3..63c28bb00d 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -1,4 +1,4 @@ - + @@ -165,3 +165,9 @@ --> + + + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 19c76b8ec7..d4c4d40bbe 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,4 +1,4 @@ - + &biblio; - &bookindex; + diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl index 6b3199b0f0..432f3a7714 100644 --- a/doc/src/sgml/stylesheet.dsl +++ b/doc/src/sgml/stylesheet.dsl @@ -1,4 +1,4 @@ - + @@ -180,6 +180,19 @@ (define %body-attr% '()) (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. (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 "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 ;; HTML. With %fix-para-wrappers% turned on, the stylesheets attempt