Thread: Re: [PATCHES] SGML index build fix
Bruce Momjian <bruce@momjian.us> writes:
> Peter Eisentraut wrote:
>> The problem is that this requires two runs even to proof the documentation,
>> which I think no one wants.
> So what would the API be to signal you want a draft build?
> gmake DRAFT="Y" html
I'd vote for
gmake draft
regards, tom lane
Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: > > Peter Eisentraut wrote: > >> The problem is that this requires two runs even to proof the documentation, > >> which I think no one wants. > > > So what would the API be to signal you want a draft build? > > gmake DRAFT="Y" html > > I'd vote for > > gmake draft OK, I used that syntax (and needed another use of recursion to do it). Attached. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: doc/src/sgml/Makefile =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/Makefile,v retrieving revision 1.87 diff -c -c -r1.87 Makefile *** doc/src/sgml/Makefile 7 Jan 2007 08:49:31 -0000 1.87 --- doc/src/sgml/Makefile 9 Jan 2007 03:13:06 -0000 *************** *** 65,71 **** ## Man pages ## ! .PHONY: man DEFAULTSECTION := $(sqlmansect_dummy) --- 65,71 ---- ## Man pages ## ! .PHONY: man draft DEFAULTSECTION := $(sqlmansect_dummy) *************** *** 95,115 **** ifeq ($(vpath_build), yes) @cp $(srcdir)/stylesheet.css . endif COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g ! # If HTML.index does not exist, create a dummy bookindex.sgml. During the ! # next build, create bookindex.sgml with the proper index contents. A proper ! # bookindex.sgml is required to have an index in the output. ! ifeq (,$(wildcard HTML.index)) ! bookindex.sgml: ! $(COLLATEINDEX) -o $@ -N else ! bookindex.sgml: HTML.index ! $(COLLATEINDEX) -i 'bookindex' -o $@ $< endif version.sgml: $(top_builddir)/src/Makefile.global { \ echo "<!entity version \"$(VERSION)\">"; \ --- 95,132 ---- ifeq ($(vpath_build), yes) @cp $(srcdir)/stylesheet.css . endif + ifndef DRAFT + @cmp -s HTML.index.start HTML.index || $(MAKE) $* + endif COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g ! draft: ! ifndef DRAFT ! ifneq ($(MAKECMDGOALS), draft) ! # Call ourselves with the DRAFT value set. This seems to be the only ! # way to set gmake variables in a rule. ! @$(MAKE) DRAFT="Y" $(MAKECMDGOALS)) else ! # run default 'all' rule ! @$(MAKE) DRAFT="Y" html ! endif endif + 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. This + # is required so the output has a proper index. + test ! -s HTML.index || $(COLLATEINDEX) -i 'bookindex' -o $@ $< + # save copy of HTML.index for later comparison + @cp HTML.index HTML.index.start + + HTML.index: + # create HTML.index if it does not exist + @$(if $(wildcard HTML.index), , touch HTML.index) + version.sgml: $(top_builddir)/src/Makefile.global { \ echo "<!entity version \"$(VERSION)\">"; \ *************** *** 141,155 **** --- 158,184 ---- %-A4.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< + ifndef DRAFT + @cmp -s HTML.index.start HTML.index || $(MAKE) $* + endif %-US.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< + ifndef DRAFT + @cmp -s HTML.index.start HTML.index || $(MAKE) $* + endif %-A4.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< + ifndef DRAFT + @cmp -s HTML.index.start HTML.index || $(MAKE) $* + endif %-US.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< + ifndef DRAFT + @cmp -s HTML.index.start HTML.index || $(MAKE) $* + endif %.dvi: %.tex-ps @rm -f $*.aux $*.log *************** *** 291,297 **** # print rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.eps *.fot # index ! rm -f HTML.index $(GENERATED_SGML) # text rm -f INSTALL HISTORY regress_README # XSLT --- 320,326 ---- # print rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.eps *.fot # index ! rm -f HTML.index HTML.index.start $(GENERATED_SGML) # text rm -f INSTALL HISTORY regress_README # XSLT Index: doc/src/sgml/docguide.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v retrieving revision 1.63 diff -c -c -r1.63 docguide.sgml *** doc/src/sgml/docguide.sgml 15 Dec 2006 16:50:07 -0000 1.63 --- doc/src/sgml/docguide.sgml 9 Jan 2007 03:13:06 -0000 *************** *** 542,552 **** </para> <para> ! When the HTML documentation is built, the process also generates ! the linking information for the index entries. Thus, if you want ! your documentation to have a concept index at the end, you need to ! build the HTML documentation once, and then build the ! documentation again in whatever format you like. </para> <para> --- 542,553 ---- </para> <para> ! To create a proper index, the build might process several identical ! stages. If you do not care about an index, and just want to ! proof-read the output, use <literal>draft</>: ! <screen> ! <prompt>doc/src/sgml$ </prompt><userinput>gmake draft html</userinput> ! </screen> </para> <para>
Patch applied. --------------------------------------------------------------------------- Bruce Momjian wrote: > Tom Lane wrote: > > Bruce Momjian <bruce@momjian.us> writes: > > > Peter Eisentraut wrote: > > >> The problem is that this requires two runs even to proof the documentation, > > >> which I think no one wants. > > > > > So what would the API be to signal you want a draft build? > > > gmake DRAFT="Y" html > > > > I'd vote for > > > > gmake draft > > OK, I used that syntax (and needed another use of recursion to do it). > Attached. > > -- > Bruce Momjian bruce@momjian.us > EnterpriseDB http://www.enterprisedb.com > > + If your life is a hard drive, Christ can be your backup. + > Index: doc/src/sgml/Makefile > =================================================================== > RCS file: /cvsroot/pgsql/doc/src/sgml/Makefile,v > retrieving revision 1.87 > diff -c -c -r1.87 Makefile > *** doc/src/sgml/Makefile 7 Jan 2007 08:49:31 -0000 1.87 > --- doc/src/sgml/Makefile 9 Jan 2007 03:13:06 -0000 > *************** > *** 65,71 **** > ## Man pages > ## > > ! .PHONY: man > > DEFAULTSECTION := $(sqlmansect_dummy) > > --- 65,71 ---- > ## Man pages > ## > > ! .PHONY: man draft > > DEFAULTSECTION := $(sqlmansect_dummy) > > *************** > *** 95,115 **** > ifeq ($(vpath_build), yes) > @cp $(srcdir)/stylesheet.css . > endif > > > COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g > > ! # If HTML.index does not exist, create a dummy bookindex.sgml. During the > ! # next build, create bookindex.sgml with the proper index contents. A proper > ! # bookindex.sgml is required to have an index in the output. > ! ifeq (,$(wildcard HTML.index)) > ! bookindex.sgml: > ! $(COLLATEINDEX) -o $@ -N > else > ! bookindex.sgml: HTML.index > ! $(COLLATEINDEX) -i 'bookindex' -o $@ $< > endif > > version.sgml: $(top_builddir)/src/Makefile.global > { \ > echo "<!entity version \"$(VERSION)\">"; \ > --- 95,132 ---- > ifeq ($(vpath_build), yes) > @cp $(srcdir)/stylesheet.css . > endif > + ifndef DRAFT > + @cmp -s HTML.index.start HTML.index || $(MAKE) $* > + endif > > > COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g > > ! draft: > ! ifndef DRAFT > ! ifneq ($(MAKECMDGOALS), draft) > ! # Call ourselves with the DRAFT value set. This seems to be the only > ! # way to set gmake variables in a rule. > ! @$(MAKE) DRAFT="Y" $(MAKECMDGOALS)) > else > ! # run default 'all' rule > ! @$(MAKE) DRAFT="Y" html > ! endif > endif > > + 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. This > + # is required so the output has a proper index. > + test ! -s HTML.index || $(COLLATEINDEX) -i 'bookindex' -o $@ $< > + # save copy of HTML.index for later comparison > + @cp HTML.index HTML.index.start > + > + HTML.index: > + # create HTML.index if it does not exist > + @$(if $(wildcard HTML.index), , touch HTML.index) > + > version.sgml: $(top_builddir)/src/Makefile.global > { \ > echo "<!entity version \"$(VERSION)\">"; \ > *************** > *** 141,155 **** > --- 158,184 ---- > > %-A4.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml > $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< > + ifndef DRAFT > + @cmp -s HTML.index.start HTML.index || $(MAKE) $* > + endif > > %-US.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml > $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< > + ifndef DRAFT > + @cmp -s HTML.index.start HTML.index || $(MAKE) $* > + endif > > %-A4.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml > $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< > + ifndef DRAFT > + @cmp -s HTML.index.start HTML.index || $(MAKE) $* > + endif > > %-US.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml > $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< > + ifndef DRAFT > + @cmp -s HTML.index.start HTML.index || $(MAKE) $* > + endif > > %.dvi: %.tex-ps > @rm -f $*.aux $*.log > *************** > *** 291,297 **** > # print > rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.eps *.fot > # index > ! rm -f HTML.index $(GENERATED_SGML) > # text > rm -f INSTALL HISTORY regress_README > # XSLT > --- 320,326 ---- > # print > rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.eps *.fot > # index > ! rm -f HTML.index HTML.index.start $(GENERATED_SGML) > # text > rm -f INSTALL HISTORY regress_README > # XSLT > Index: doc/src/sgml/docguide.sgml > =================================================================== > RCS file: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v > retrieving revision 1.63 > diff -c -c -r1.63 docguide.sgml > *** doc/src/sgml/docguide.sgml 15 Dec 2006 16:50:07 -0000 1.63 > --- doc/src/sgml/docguide.sgml 9 Jan 2007 03:13:06 -0000 > *************** > *** 542,552 **** > </para> > > <para> > ! When the HTML documentation is built, the process also generates > ! the linking information for the index entries. Thus, if you want > ! your documentation to have a concept index at the end, you need to > ! build the HTML documentation once, and then build the > ! documentation again in whatever format you like. > </para> > > <para> > --- 542,553 ---- > </para> > > <para> > ! To create a proper index, the build might process several identical > ! stages. If you do not care about an index, and just want to > ! proof-read the output, use <literal>draft</>: > ! <screen> > ! <prompt>doc/src/sgml$ </prompt><userinput>gmake draft html</userinput> > ! </screen> > </para> > > <para> > > ---------------------------(end of broadcast)--------------------------- > TIP 9: In versions below 8.0, the planner will ignore your desire to > choose an index scan if your joining column's datatypes do not > match -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian wrote: > > %-A4.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml > > $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< > > + ifndef DRAFT > > + @cmp -s HTML.index.start HTML.index || $(MAKE) $* > > + endif What is the point of that? -- Peter Eisentraut http://developer.postgresql.org/~petere/
Bruce Momjian wrote: > > + ifndef DRAFT > > + @cmp -s HTML.index.start HTML.index || $(MAKE) $* > > + endif Why are you using $*? This isn't a pattern rule. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Bruce Momjian wrote: > > ! draft: > > ! ifndef DRAFT > > ! ifneq ($(MAKECMDGOALS), draft) How could this condition ever match? > > ! # Call ourselves with the DRAFT value set. This seems to be the only > > ! # way to set gmake variables in a rule. > > ! @$(MAKE) DRAFT="Y" $(MAKECMDGOALS)) > > else > > ! # run default 'all' rule > > ! @$(MAKE) DRAFT="Y" html > > ! endif > > endif -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut wrote: > Bruce Momjian wrote: > > > ? %-A4.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml > > > ? ????$(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< > > > + ifndef DRAFT > > > + ????@cmp -s HTML.index.start HTML.index || $(MAKE) $* > > > + endif > > What is the point of that? If HTML.index changed during the build, we need to rerun it until it is unchanged. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Peter Eisentraut wrote: > Bruce Momjian wrote: > > > + ifndef DRAFT > > > + ????@cmp -s HTML.index.start HTML.index || $(MAKE) $* > > > + endif > > Why are you using $*? This isn't a pattern rule. > Sorry, my mistake. Here is an patch to fix that. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: doc/src/sgml/Makefile =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/Makefile,v retrieving revision 1.88 diff -c -c -r1.88 Makefile *** doc/src/sgml/Makefile 9 Jan 2007 22:19:36 -0000 1.88 --- doc/src/sgml/Makefile 10 Jan 2007 01:23:40 -0000 *************** *** 96,102 **** @cp $(srcdir)/stylesheet.css . endif ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $* endif --- 96,102 ---- @cp $(srcdir)/stylesheet.css . endif ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $(MAKECMDGOALS) endif *************** *** 107,113 **** ifneq ($(MAKECMDGOALS), draft) # Call ourselves with the DRAFT value set. This seems to be the only # way to set gmake variables in a rule. ! @$(MAKE) DRAFT="Y" $(MAKECMDGOALS)) else # run default 'all' rule @$(MAKE) DRAFT="Y" all --- 107,113 ---- ifneq ($(MAKECMDGOALS), draft) # Call ourselves with the DRAFT value set. This seems to be the only # way to set gmake variables in a rule. ! @$(MAKE) DRAFT="Y" $(MAKECMDGOALS) else # run default 'all' rule @$(MAKE) DRAFT="Y" all *************** *** 159,183 **** %-A4.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $* endif %-US.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $* endif %-A4.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $* endif %-US.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $* endif %.dvi: %.tex-ps --- 159,183 ---- %-A4.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $@ endif %-US.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $@ endif %-A4.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $@ endif %-US.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< ifndef DRAFT ! @cmp -s HTML.index.start HTML.index || $(MAKE) $@ endif %.dvi: %.tex-ps
Peter Eisentraut wrote: > Bruce Momjian wrote: > > > ! draft: > > > ! ifndef DRAFT > > > ! ifneq ($(MAKECMDGOALS), draft) > > How could this condition ever match? On first call, 'draft' might be set, but in the recursive call, this code will not be reached because DRAFT iss set. --------------------------------------------------------------------------- > > > > ! # Call ourselves with the DRAFT value set. ?This seems to be the only > > > ! # way to set gmake variables in a rule. > > > ! ????@$(MAKE) DRAFT="Y" $(MAKECMDGOALS)) > > > ? else > > > ! # run default 'all' rule > > > ! ????@$(MAKE) DRAFT="Y" html > > > ! endif > > > ? endif > > -- > Peter Eisentraut > http://developer.postgresql.org/~petere/ > > ---------------------------(end of broadcast)--------------------------- > TIP 3: Have you checked our extensive FAQ? > > http://www.postgresql.org/docs/faq -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +