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.

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 4e029732d7f71a7c3657c57ca80deb2d3413b49e..8ebd118e9c92beea59f86630535f9db660ab1b95 100644 (file)
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -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
+
+# 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 $<
 
-html: html-output
-# Re-run this target until HTML.index does not change
-       @cmp -s HTML.index.start HTML.index || $(MAKE) $@
+html: html-stamp
 
-# This is run for all output formats because we need bookindex.sgml
-html-output: postgres.sgml $(ALLSGML) stylesheet.dsl
+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 18046dcb2507517e3843dbece9045158a408085d..f4f60d175ca091da536cead165b64c9e8a5418b2 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -165,3 +165,9 @@
  -->
 <!entity % standalone-ignore  "INCLUDE">
 <!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">

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 86ffbe9ec2d5e1e3fe0d1347fe47b60d5dd523d4..9eaa86e84778e7ff67bfef3e328f65c29485db9d 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -262,6 +262,6 @@
  </part>
 
  &biblio;
- &bookindex;
+ <![%include-index;[&bookindex;]]>
 
 </book>

diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl
index af8a190646bbaf608522ad9b3089e86a3436a5b4..ae00f35201955e5dfb33e124382d3926fa353335 100644 (file)
--- a/doc/src/sgml/stylesheet.dsl
+++ b/doc/src/sgml/stylesheet.dsl
@@ -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