Re: [HACKERS] SGML index build fix - Mailing list pgsql-patches

Peter Eisentraut wrote:
> Am Montag, 8. Januar 2007 05:10 schrieb Bruce Momjian:
> > Here is a patch that runs the build twice when HTML.index does not
> > exist, and once every time after that.  This is not ideal, but it is a
> > start.
>
> 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 can do that.

> > !     # If HTML.index is zero length, create a dummy bookindex.sgml
> > !     test -s HTML.index || $(COLLATEINDEX) -o $@ -N
> > !     # If HTML.index is valid, create valid bookindex.sgml.  This
> > !     # is required so the output has a proper index.
> > !     test ! -s HTML.index || $(COLLATEINDEX) -i 'bookindex' -o $@ $<
>
> Please indent the comments properly so they don't appear in the output.

Done.

>
> > ! HTML.index:
> > !     test -f HTML.index || (touch HTML.index && $(MAKE) $(MAKECMDGOALS))
>
> I think this is partially redundant.  If HTML.index exists, then this
> rule will never be called.

Uh, wouldn't HTML.index be newer than bookindex.sgml after a build?
Also, I need the HTML.index dependency and I can't use 'ifeq' to
add/remove it because the test condition result will change during the
Makefile execution.  So, HTML.index has to exist after the dependency
rule returns.  Am I missing something?

I did replace the test -f with $if.

> > !     rm -f HTML.manifest *.html *.gif bookindex.skip
>
> I don't see bookindex.skip mentioned anywhere else.  Left over from a
> previous version?

Sorry, removed.

Updated patch attached.  This is a more complete solution that saves off
HTML.index before each jade run, and checks after if the new HTML.index
differs from the original, and if so, run it again.  It also adds a
DRAFT 'make' option, and documents it.  It also removes the
documentation about running it multiple times.

--
  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    8 Jan 2007 23:58:27 -0000
***************
*** 95,114 ****
  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
      { \
--- 95,119 ----
  ifeq ($(vpath_build), yes)
      @cp $(srcdir)/stylesheet.css .
  endif
+ ifneq ($(DRAFT), "Y")
+     cmp -s HTML.index.start HTML.index || $(MAKE) $(MAKECMDGOALS)
+ endif


  COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g

  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
      { \
***************
*** 141,155 ****
--- 146,172 ----

  %-A4.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml
      $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $<
+ ifneq ($(DRAFT), "Y")
+     cmp -s HTML.index.start HTML.index || $(MAKE) $(MAKECMDGOALS)
+ endif

  %-US.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml
      $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $<
+ ifneq ($(DRAFT), "Y")
+     cmp -s HTML.index.start HTML.index || $(MAKE) $(MAKECMDGOALS)
+ endif

  %-A4.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml
      $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $<
+ ifneq ($(DRAFT), "Y")
+     cmp -s HTML.index.start HTML.index || $(MAKE) $(MAKECMDGOALS)
+ endif

  %-US.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl bookindex.sgml
      $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $<
+ ifneq ($(DRAFT), "Y")
+     cmp -s HTML.index.start HTML.index || $(MAKE) $(MAKECMDGOALS)
+ 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
--- 308,314 ----
  # 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    8 Jan 2007 23:58:27 -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="Y" html</userinput>
! </screen>
     </para>

     <para>