I have been looking at getting rid of the way we currently ship the
documentation as a tarball within the tarball.
The first issue I encountered is that when you ship prebuilt files in a
tarball, you want to make sure the make dependencies are correctly satisfied.
For example, we prebuild gram.c from gram.y in a way that it doesn't get
rebuild at the user's site.
This currently doesn't work well with the HTML docs. You can run "make html"
repeatedly, and it will rebuild the documentation every time. This is of
course the ancient problem with the index build requiring two runs.
I think I have finally figured out a way to do this correctly now. 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
I have implemented is that
- The first jade run produces HTML.index, but does not require bookindex.sgml
at all.
- 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.
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.
Patch attached.
*** a/doc/src/sgml/Makefile
--- b/doc/src/sgml/Makefile
***************
*** 94,130 **** man: postgres.sgml $(ALLSGML)
all: html
! # The draft target creates HTML output in draft mode
draft : JADEFLAGS += -V draft-mode
! draft: html-output
! html: html-output
! # Re-run this target until HTML.index does not change
! @cmp -s HTML.index.start HTML.index || $(MAKE) $@
! # This is run for all output formats because we need bookindex.sgml
! html-output: postgres.sgml $(ALLSGML) stylesheet.dsl
@rm -f *.html
! $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-html -t sgml $<
ifeq ($(vpath_build), yes)
@cp $(srcdir)/stylesheet.css .
endif
COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g
- # 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)
version.sgml: $(top_builddir)/src/Makefile.global
{ \
--- 94,120 ----
all: html
! # The draft target creates HTML output in draft mode, without index (for faster build).
draft : JADEFLAGS += -V draft-mode
! draft: HTML.index
! html: html-stamp
! html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl
@rm -f *.html
! $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-html -i include-index -t sgml $<
ifeq ($(vpath_build), yes)
@cp $(srcdir)/stylesheet.css .
endif
+ touch $@
+
+ HTML.index: postgres.sgml $(filter-out %bookindex.sgml,$(ALLSGML)) stylesheet.dsl
+ $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-html -V html-index -t sgml $<
COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g
bookindex.sgml: HTML.index
! $(COLLATEINDEX) -i 'bookindex' -o $@ $<
version.sgml: $(top_builddir)/src/Makefile.global
{ \
***************
*** 146,158 **** 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
# 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
%-A4.tex-ps: %.sgml $(ALLSGML) html
$(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $<
--- 136,148 ----
# 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 -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 -i include-index
%-A4.tex-ps: %.sgml $(ALLSGML) html
$(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $<
***************
*** 195,201 **** 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 $@ $<
##
--- 185,191 ----
# 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 -i include-index -o $@ $<
##
***************
*** 292,298 **** manx: postgres.xml stylesheet-man.xsl
##
# Quick syntax check without style processing
! check: postgres.sgml $(ALLSGML)
$(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $<
--- 282,288 ----
##
# Quick syntax check without style processing
! check: postgres.sgml $(filter-out %bookindex.sgml,$(ALLSGML))
$(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $<
***************
*** 302,308 **** check: postgres.sgml $(ALLSGML)
clean distclean maintainer-clean:
# HTML
! rm -f HTML.manifest *.html
# man
rm -rf *.1 *.7 *.$(DEFAULTSECTION) man1 man7 manpage.refs manpage.links manpage.log
# print
--- 292,298 ----
clean distclean maintainer-clean:
# HTML
! rm -f *.html html-stamp
# man
rm -rf *.1 *.7 *.$(DEFAULTSECTION) man1 man7 manpage.refs manpage.links manpage.log
# print
*** a/doc/src/sgml/filelist.sgml
--- b/doc/src/sgml/filelist.sgml
***************
*** 165,167 ****
--- 165,169 ----
-->
<!entity % standalone-ignore "INCLUDE">
<!entity % standalone-include "IGNORE">
+
+ <!entity % include-index "IGNORE">
*** a/doc/src/sgml/postgres.sgml
--- b/doc/src/sgml/postgres.sgml
***************
*** 262,267 ****
</part>
&biblio;
! &bookindex;
</book>
--- 262,267 ----
</part>
&biblio;
! <![%include-index;[&bookindex;]]>
</book>
*** a/doc/src/sgml/stylesheet.dsl
--- b/doc/src/sgml/stylesheet.dsl
***************
*** 202,210 ****
(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
--- 202,207 ----
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
