Thread: Re: [PATCHES] SGML index build fix
Bruce Momjian <bruce@momjian.us> writes: > The attached patch warns users when they create documentation output > that has no index, and suggests re-running 'gmake'. This is just useless noise. If it could tell the difference between an up-to-date index and a not-up-to-date one, there might be some value to it ... but as-is I think it's just getting in the user's face. Everyone using these tools knows about the two-pass behavior. I just got done reading an interesting comparison of MS Vista versus Mac OS X: http://www.informationweek.com/news/showArticle.jhtml?articleID=196800670 The guy's very first complaint about Vista is how it demands your attention constantly with trivial warning messages. This seems in much the same vein. regards, tom lane
Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: > > The attached patch warns users when they create documentation output > > that has no index, and suggests re-running 'gmake'. > > This is just useless noise. If it could tell the difference between an > up-to-date index and a not-up-to-date one, there might be some value > to it ... but as-is I think it's just getting in the user's face. > Everyone using these tools knows about the two-pass behavior. I certainly did not, and it warns only when an invalid HTML.index is used. -- 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: > Tom Lane wrote: > > Bruce Momjian <bruce@momjian.us> writes: > > > The attached patch warns users when they create documentation output > > > that has no index, and suggests re-running 'gmake'. > > > > This is just useless noise. If it could tell the difference between an > > up-to-date index and a not-up-to-date one, there might be some value > > to it ... but as-is I think it's just getting in the user's face. > > Everyone using these tools knows about the two-pass behavior. > > I certainly did not, and it warns only when an invalid HTML.index is > used. And the people creating our PDFs didn't know because we often have to update the web site with valid ones that have indexes. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Sat, 2007-01-06 at 23:38 -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > The attached patch warns users when they create documentation output
> > that has no index, and suggests re-running 'gmake'.
>
> This is just useless noise. If it could tell the difference between an
> up-to-date index and a not-up-to-date one, there might be some value
> to it ... but as-is I think it's just getting in the user's face.
> Everyone using these tools knows about the two-pass behavior.
No, not everyone knows. In fact I would argue that most do not know. It
isn't intuitive to the process. You *expect* that an index will be made.
Joshua D. Drake
--
=== The PostgreSQL Company: Command Prompt, Inc. ===
Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240
Providing the most comprehensive PostgreSQL solutions since 1997
http://www.commandprompt.com/
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate
Joshua D. Drake wrote: > On Sat, 2007-01-06 at 23:38 -0500, Tom Lane wrote: > > Bruce Momjian <bruce@momjian.us> writes: > > > The attached patch warns users when they create documentation output > > > that has no index, and suggests re-running 'gmake'. > > > > This is just useless noise. If it could tell the difference between an > > up-to-date index and a not-up-to-date one, there might be some value > > to it ... but as-is I think it's just getting in the user's face. > > Everyone using these tools knows about the two-pass behavior. > > No, not everyone knows. In fact I would argue that most do not know. It > isn't intuitive to the process. You *expect* that an index will be made. The idea for the warning message actually came from Peter. -- Bruce Momjian bruce@momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Sun, Jan 07, 2007 at 12:42:06AM -0500, Bruce Momjian wrote: > Joshua D. Drake wrote: > > On Sat, 2007-01-06 at 23:38 -0500, Tom Lane wrote: > > > Everyone using these tools knows about the two-pass behavior. > > > > No, not everyone knows. In fact I would argue that most do not know. It > > isn't intuitive to the process. You *expect* that an index will be made. > > The idea for the warning message actually came from Peter. FWIW, I have this problem with LaTeX also, which needs multiple passes occasionally to fix cross-references and idexes and stuff. The solution I have in the makefile is a fragment like the following: while egrep -q "^LaTeX Warning:.*Rerun to" logfile ; do rm logfile latex taxfile done I don't know enough about the relevent tool to know if they actually generate a warning about whether they need to be rerun. In any case it seems a much better approach to simply run it again when needed rather than printing a warning. Have a nice day, -- Martijn van Oosterhout <kleptog@svana.org> http://svana.org/kleptog/ > From each according to his ability. To each according to his ability to litigate.
Martijn van Oosterhout wrote:
-- Start of PGP signed section.
> On Sun, Jan 07, 2007 at 12:42:06AM -0500, Bruce Momjian wrote:
> > Joshua D. Drake wrote:
> > > On Sat, 2007-01-06 at 23:38 -0500, Tom Lane wrote:
> > > > Everyone using these tools knows about the two-pass behavior.
> > >
> > > No, not everyone knows. In fact I would argue that most do not know. It
> > > isn't intuitive to the process. You *expect* that an index will be made.
> >
> > The idea for the warning message actually came from Peter.
>
> FWIW, I have this problem with LaTeX also, which needs multiple passes
> occasionally to fix cross-references and idexes and stuff. The solution
> I have in the makefile is a fragment like the following:
>
> while egrep -q "^LaTeX Warning:.*Rerun to" logfile ; do
> rm logfile
> latex taxfile
> done
Our Makefile has:
%.dvi: %.tex-ps
@rm -f $*.aux $*.log
# multiple runs are necessary to create proper intra-document links
jadetex $<
jadetex $<
jadetex $<
so there should be no reason for you to have to rerun.
>
> I don't know enough about the relevent tool to know if they actually
> generate a warning about whether they need to be rerun. In any case it
> seems a much better approach to simply run it again when needed rather
> than printing a warning.
The problem is that there is no indication from the make (no warning)
that you have to rerun, and it isn't something people are used to doing
like with latex.
--
Bruce Momjian bruce@momjian.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Bruce Momjian <bruce@momjian.us> writes:
> Martijn van Oosterhout wrote:
>> I don't know enough about the relevent tool to know if they actually
>> generate a warning about whether they need to be rerun. In any case it
>> seems a much better approach to simply run it again when needed rather
>> than printing a warning.
> The problem is that there is no indication from the make (no warning)
> that you have to rerun, and it isn't something people are used to doing
> like with latex.
If the objective is to make it safe against people who do not understand
how the tools work, then I still complain that this method is
insufficient. All you are testing is whether an index was generated,
not whether it was correct (ie, up to date). A valid test would be
along the lines of comparing the pre-run and post-run copies of the
index data to see if they're the same.
Perhaps even more to the point, what makes you think that someone will
notice the warning? If the docs build is one step in an automated build
process, this seems unlikely.
regards, tom lane
Tom Lane wrote: > Perhaps even more to the point, what makes you think that someone > will notice the warning? If the docs build is one step in an > automated build process, this seems unlikely. Taking a closer look, it's pretty much guaranteed that no one will see them, because the targets they are attached to are intermediate, normally followed by latex runs. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane wrote:
>> Perhaps even more to the point, what makes you think that someone
>> will notice the warning? If the docs build is one step in an
>> automated build process, this seems unlikely.
> Taking a closer look, it's pretty much guaranteed that no one will see
> them, because the targets they are attached to are intermediate,
> normally followed by latex runs.
If we think this is a problem, ISTM the correct answer is to just force
a repeat jade run when doing "make all". The only objection to that
AFAICS is that when you're doing docs work and only need a draft to
look at, you'd rather it not run twice. But perhaps we could address
that by providing a separate target, "make draft" say, that runs jade
but once.
regards, tom lane
On Sun, 7 Jan 2007, Tom Lane wrote: > Peter Eisentraut <peter_e@gmx.net> writes: > > Tom Lane wrote: > >> Perhaps even more to the point, what makes you think that someone > >> will notice the warning? If the docs build is one step in an > >> automated build process, this seems unlikely. > > > Taking a closer look, it's pretty much guaranteed that no one will see > > them, because the targets they are attached to are intermediate, > > normally followed by latex runs. > > If we think this is a problem, ISTM the correct answer is to just force > a repeat jade run when doing "make all". The only objection to that > AFAICS is that when you're doing docs work and only need a draft to > look at, you'd rather it not run twice. But perhaps we could address > that by providing a separate target, "make draft" say, that runs jade > but once. That's a nice approach. Those working on the docs will know about the draft target and those just wanting to build the docs for publication will get the result. Gavin
Peter Eisentraut wrote: > Tom Lane wrote: > > Perhaps even more to the point, what makes you think that someone > > will notice the warning? If the docs build is one step in an > > automated build process, this seems unlikely. > > Taking a closer look, it's pretty much guaranteed that no one will see > them, because the targets they are attached to are intermediate, > normally followed by latex runs. 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. -- 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 04:02:45 -0000 *************** *** 99,114 **** 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 { \ --- 99,115 ---- COLLATEINDEX := LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g bookindex.sgml: HTML.index ! # 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 $@ $< ! ! # If HTML.index does not exist, create an empty file and recusively call ! # our own Makefile to create a valid bookindex.sgml. ! HTML.index: ! test -f HTML.index || (touch HTML.index && $(MAKE) $(MAKECMDGOALS)) version.sgml: $(top_builddir)/src/Makefile.global { \ *************** *** 285,291 **** clean distclean maintainer-clean: # HTML ! rm -f HTML.manifest *.html *.gif # man rm -rf *.1 *.$(DEFAULTSECTION) man1 man$(DEFAULTSECTION) manpage.refs manpage.links manpage.log # print --- 286,292 ---- clean distclean maintainer-clean: # HTML ! rm -f HTML.manifest *.html *.gif bookindex.skip # man rm -rf *.1 *.$(DEFAULTSECTION) man1 man$(DEFAULTSECTION) manpage.refs manpage.links manpage.log # print
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. > ! # 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. > ! 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. > ! rm -f HTML.manifest *.html *.gif bookindex.skip I don't see bookindex.skip mentioned anywhere else. Left over from a previous version? -- Peter Eisentraut http://developer.postgresql.org/~petere/