Обсуждение: Rearrangement of the HTML docs build rules
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.
Peter Eisentraut <peter_e@gmx.net> writes:
> I think I have finally figured out a way to do this correctly now.
Yay. The existing method completely sucks --- I find that it *never*
does one run on a rebuild, but at least two and sometimes three.
I don't know whether it's feasible to implement "rebuild only if the
index changed" in make, but we definitely haven't got that now, so
eliminating the attempt is no hardship.
regards, tom lane
Tom Lane wrote: > Peter Eisentraut <peter_e@gmx.net> writes: > > I think I have finally figured out a way to do this correctly now. > > Yay. The existing method completely sucks --- I find that it *never* > does one run on a rebuild, but at least two and sometimes three. > I don't know whether it's feasible to implement "rebuild only if the > index changed" in make, but we definitely haven't got that now, so > eliminating the attempt is no hardship. Peter is spot-on when he says having a file name mean different things at different stages of the build process is a mess. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Tom Lane wrote: > Peter Eisentraut <peter_e@gmx.net> writes: > > I think I have finally figured out a way to do this correctly now. > > Yay. The existing method completely sucks --- I find that it *never* > does one run on a rebuild, but at least two and sometimes three. > I don't know whether it's feasible to implement "rebuild only if the > index changed" in make, but we definitely haven't got that now, so > eliminating the attempt is no hardship. BTW I discovered a couple of years ago that if you set the DSSSL stuff to build only the index and not output the HTML, the first pass is *very* fast. It required patching some lispy file however, so I'm not sure if we can usefully take advantage of that. I can find the details if you're interested. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Alvaro Herrera wrote: > BTW I discovered a couple of years ago that if you set the DSSSL stuff > to build only the index and not output the HTML, the first pass is > *very* fast. It required patching some lispy file however, so I'm not > sure if we can usefully take advantage of that. I can find the details > if you're interested. http://archives.postgresql.org/message-id/20080109054155.GG20913@alvh.no-ip.org -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
On Monday 13 July 2009 23:37:10 Alvaro Herrera wrote: > Alvaro Herrera wrote: > > BTW I discovered a couple of years ago that if you set the DSSSL stuff > > to build only the index and not output the HTML, the first pass is > > *very* fast. It required patching some lispy file however, so I'm not > > sure if we can usefully take advantage of that. I can find the details > > if you're interested. > > http://archives.postgresql.org/message-id/20080109054155.GG20913@alvh.no-ip >.org This is a fantastic idea. I've implemented this in addition to the patch I showed, and it saves a lot of time.