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. +

Bruce Momjian wrote:

The attached patch warns users when they create documentation output
that has no index, and suggests re-running 'gmake'.

! # for some reason $wildcard expands too early, so we use 'test'

$wildcard is expanded whenever you tell it to. What did you write?

! @test -f bookindex.valid || echo "Run 'gmake' again to generate output with a proper index"

The proper command to run is $(MAKE).

!

There is a redundant tab on that line.

+ @test -f bookindex.valid || echo "Run 'gmake' again to generate output with a proper index"

Probably better to capture that in a variable instead of copying it half a dozen times.

-e '1a\' -e '<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd&quot;&gt;&#39; \

$@

# ' hello Emacs
+ @test -f bookindex.valid || echo "Run 'gmake' again to generate output with a proper index"

When converting to XML, you probably don't want an index because it will
be built differently by the XSLT toolchain. It's not clear what we want
anyway.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

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/

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. +

Peter Eisentraut wrote:

Bruce Momjian wrote:

The attached patch warns users when they create documentation output
that has no index, and suggests re-running 'gmake'.

! # for some reason $wildcard expands too early, so we use 'test'

$wildcard is expanded whenever you tell it to. What did you write?

I wrote:

ifeq (,$(wildcard bookindex.valid))
echo "Run 'gmake' again to generate output with a proper index"
endif

but that warns on the first _two_ runs, meaning it expanded at the time
the rule started, not at the time it hit that line.

! @test -f bookindex.valid || echo "Run 'gmake' again to generate output with a proper index"

The proper command to run is $(MAKE).

OK, updated.

!

There is a redundant tab on that line.

OK, removed.

+ @test -f bookindex.valid || echo "Run 'gmake' again to generate output with a proper index"

Probably better to capture that in a variable instead of copying it half a dozen times.

-e '1a\' -e '<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd&quot;&gt;&#39; \

$@

# ' hello Emacs
+ @test -f bookindex.valid || echo "Run 'gmake' again to generate output with a proper index"

When converting to XML, you probably don't want an index because it will
be built differently by the XSLT toolchain. It's not clear what we want
anyway.

OK, removed.

--
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

Bruce Momjian wrote:

I wrote:

ifeq (,$(wildcard bookindex.valid))
echo "Run 'gmake' again to generate output with a proper index"
endif

but that warns on the first _two_ runs, meaning it expanded at the
time the rule started, not at the time it hit that line.

This expands at the time the makefile is read. You may get it to work
with

target:
$(if $(wildcard blah), this, that)

The following may be helpful:
http://www.gnu.org/software/make/manual/html_node/Reading-Makefiles.html#Reading-Makefiles

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

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. +

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/

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. +

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. +