Thread: Docbook toolchain interfering with patch review?
All, Well, after an hour of tinkering with docbook DTDs and openjade I've given up on building docs for the patch I was reviewing on my Mac. If I'm encountering this difficulty building docs, so are many of the other new patch reviewers. Which means we're *not* reviewing docs for completeness, correctness, or correspondence to the actual feature syntax until beta time. This seems like a serious issue for development. Reviewers, how many of you are able to build docs with each patch? -- Josh Berkus PostgreSQL Experts Inc. www.pgexperts.com
On Thu, Jul 16, 2009 at 2:34 PM, Josh Berkus<josh@agliodbs.com> wrote: > All, > > Well, after an hour of tinkering with docbook DTDs and openjade I've given > up on building docs for the patch I was reviewing on my Mac. > > If I'm encountering this difficulty building docs, so are many of the other > new patch reviewers. Which means we're *not* reviewing docs for > completeness, correctness, or correspondence to the actual feature syntax > until beta time. > > This seems like a serious issue for development. Reviewers, how many of you > are able to build docs with each patch? Isn't it possible though to write and/or review the documentation patch without building it? merlin
On Thu, 16 Jul 2009, Josh Berkus wrote: > Well, after an hour of tinkering with docbook DTDs and openjade I've given up > on building docs for the patch I was reviewing on my Mac. It's easier to get the whole chain working under Linux, but even that isn't trivial. I think one useful step here would be to write up some practical docs on the package setup side here for various popular platforms on the wiki. I can probably find where I have the RedHat and Ubuntu recipies I use around here somewhere, to kick that off as part of the review I'm doing for the multi-threaded pgbench. It's been my experience that everybody runs into pretty much the same problems here getting standard, but said problems are unique to the OS. If someone write up something similar for OS X, so there's a recipe for getting the standard docs built on all the major development platforms where this could be straightforward (I shudder to think what a Cygwin guide would look like), that would make it much easier to push toward having more people do doc review. -- * Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD
Merlin Moncure escreveu: > Isn't it possible though to write and/or review the documentation > patch without building it? > cd pgsql/doc/src/sgml && gmake check -- Euler Taveira de Oliveira http://www.timbira.com/
Greg Smith <gsmith@gregsmith.com> writes:
> On Thu, 16 Jul 2009, Josh Berkus wrote:
>> Well, after an hour of tinkering with docbook DTDs and openjade I've given up
>> on building docs for the patch I was reviewing on my Mac.
> It's easier to get the whole chain working under Linux, but even that
> isn't trivial.
Really? It's "just worked" for me on the last several Fedora releases.
You do need to install the docbook packages of course ...
regards, tom lane
Tom Lane wrote: > Greg Smith <gsmith@gregsmith.com> writes: > >> On Thu, 16 Jul 2009, Josh Berkus wrote: >> >>> Well, after an hour of tinkering with docbook DTDs and openjade I've given up >>> on building docs for the patch I was reviewing on my Mac. >>> > > >> It's easier to get the whole chain working under Linux, but even that >> isn't trivial. >> > > Really? It's "just worked" for me on the last several Fedora releases. > You do need to install the docbook packages of course ... > > > Yes, that's my experience also. In any case, you really don't need to build the docs to read them. You might not like SGML, but it's not *that* hard to understand. Surely our patch reviewers can read the SGML text. Of course, we should check that the docs build cleanly after the patch is applied, but that's a different issue. As far as building goes, the CVS HEAD docs at <http://developer.postgresql.org/pgdocs/postgres/index.html> are rebuilt frequently, so we actually check as soon as the patch is applied. cheers andrew
2009/7/17 Josh Berkus <josh@agliodbs.com>: > This seems like a serious issue for development. Reviewers, how many of you > are able to build docs with each patch? Being able to build docs did require some fidgeting with the docbook packages (on Gentoo). The only trick was working out exactly which packages I needed to install. Since getting past that, I've not had any problems building the docs. Although it is pretty slow. As Merlin and Andrew have noted, being able to build the docs is a nice-to-have for documentation review, not a genuine requirement. You *can* review changes to SGML right there in the diff. Especially if the changes are not extensive and/or don't alter the structure of the document. Cheers, BJ
On Thu, Jul 16, 2009 at 8:07 PM, Brendan Jurd<direvus@gmail.com> wrote: > 2009/7/17 Josh Berkus <josh@agliodbs.com>: >> This seems like a serious issue for development. Reviewers, how many of you >> are able to build docs with each patch? > > Being able to build docs did require some fidgeting with the docbook > packages (on Gentoo). The only trick was working out exactly which > packages I needed to install. Since getting past that, I've not had > any problems building the docs. Although it is pretty slow. > > As Merlin and Andrew have noted, being able to build the docs is a > nice-to-have for documentation review, not a genuine requirement. You > *can* review changes to SGML right there in the diff. Especially if > the changes are not extensive and/or don't alter the structure of the > document. Yeah. I usually build the docs and read them if I'm making.... er proposing... an extensive change, but for simple stuff I just edit the SGML and figure that if it looks sane it probably is. I certainly don't test the doc portions of patches I review unless I see something sketchy in the markup. But I can't say I've ever had much trouble building the docs. I find it a bit odd that "make" in the doc directory does nothing; and "make" in doc/src does nothing, but "make" in doc/src/sgml does what you expect. I also find the slowness of openjade to be pretty annoying. But those are minor warts, not serious inconveniences that hinder reviewing. ...Robert
2009/7/17 Kevin Grittner <Kevin.Grittner@wicourts.gov>: > Brendan Jurd <direvus@gmail.com> wrote: > >> The only trick was working out exactly which >> packages I needed to install. > > Which were? > Currently I have: app-text/openjade 1.3.2-r1 app-text/docbook-sgml 1.0 app-text/docbook-sgml-dtd 4.2-r2 app-text/docbook-sgml-utils 0.6.14 app-text/docbook-dsssl-stylesheets 1.79 ... plus some other packages which were pulled in to satisfy dependencies on the above. The version is only a big deal for docbook-sgml-dtd -- you *must* specify the 4.2 slot when emerging the package or you might end up with 4.4 or some other slot, and that won't work with the Postgres docs as explained at http://www.postgresql.org/docs/current/static/docguide-toolsets.html. For example you should be able to get the whole toolset with emerge -av app-text/openjade \app-text/docbook-sgml \app-text/docbook-sgml-utils \app-text/docbook-dsssl-stylesheets \app-text/docbook-sgml-dtd:4.2 I set this up a long time ago, so I'm unsure whether the docbook-sgml and docbook-sgml-utils packages are genuinely required, but I *am* able to build the docs with this configuration. I usually build the HTML target and then view the docs in my browser. Cheers, BJ
Robert Haas escribió: > But I can't say I've ever had much trouble building the docs. I find > it a bit odd that "make" in the doc directory does nothing; and "make" > in doc/src does nothing, but "make" in doc/src/sgml does what you > expect. I also find the slowness of openjade to be pretty annoying. > But those are minor warts, not serious inconveniences that hinder > reviewing. Back when my machine took 45 mins to build the docs, what I did to review doc changes was a quick "make check" to verify that the SGML was not b0rked, then send the patch and look at the generated HTML in the developer docs. Nowadays the doc building process has been sped up inmensely by Peter's recent changes. And my machine has sped up too, as well. The only thing I lament is that I can't do openjade -j2 to use two cores to build (or should that be --workers=2 ?) -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.
Brendan Jurd <direvus@gmail.com> wrote: > The only trick was working out exactly which > packages I needed to install. Which were? -Kevin
Brendan Jurd wrote: > > app-text/openjade 1.3.2-r1 > app-text/docbook-sgml 1.0 > app-text/docbook-sgml-dtd 4.2-r2 > app-text/docbook-sgml-utils 0.6.14 > app-text/docbook-dsssl-stylesheets 1.79 > > ... plus some other packages which were pulled in to satisfy > dependencies on the above. > > The version is only a big deal for docbook-sgml-dtd -- you *must* > specify the 4.2 slot when emerging the package or you might end up > with 4.4 or some other slot, and that won't work with the Postgres > docs as explained at > http://www.postgresql.org/docs/current/static/docguide-toolsets.html. > For example you should be able to get the whole toolset with > > > I bet this is Josh's problem. He probably has the wrong DTD set. It would account for the error log he showed me. cheers andrew
On Thursday 16 July 2009 23:50:14 Greg Smith wrote: > On Thu, 16 Jul 2009, Josh Berkus wrote: > > Well, after an hour of tinkering with docbook DTDs and openjade I've > > given up on building docs for the patch I was reviewing on my Mac. > > It's easier to get the whole chain working under Linux, but even that > isn't trivial. I think one useful step here would be to write up some > practical docs on the package setup side here for various popular > platforms on the wiki. http://www.postgresql.org/docs/current/static/docguide-toolsets.html
On Friday 17 July 2009 03:51:31 Alvaro Herrera wrote: > Nowadays the doc building process has been sped up inmensely by Peter's > recent changes. And my machine has sped up too, as well. Also, for the "let's switch to XML" crowd: $ make html make html 62.50s user 0.37s system 98% cpu 1:03.72 total $ make xslthtml make xslthtml 809.50s user 0.90s system 99% cpu 13:31.98 total I'm a bit shocked and outraged about that myself.
Robert Haas wrote: > Yeah. I usually build the docs and read them if I'm making.... er > proposing... an extensive change, but for simple stuff I just edit the > SGML and figure that if it looks sane it probably is. > > I certainly don't test the doc portions of patches I review unless I > see something sketchy in the markup. > > But I can't say I've ever had much trouble building the docs. I find > it a bit odd that "make" in the doc directory does nothing; and "make" > in doc/src does nothing, but "make" in doc/src/sgml does what you > expect. I also find the slowness of openjade to be pretty annoying. > But those are minor warts, not serious inconveniences that hinder > reviewing. FYI, bulding PDFs used to take _days_; we finally found and worked around that openjade bug. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +