Lists: | pgsql-hackers |
---|
From: | Josh Berkus <josh(at)agliodbs(dot)com> |
---|---|
To: | PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Docbook toolchain interfering with patch review? |
Date: | 2009-07-16 18:34:48 |
Message-ID: | 4A5F72C8.5060900@agliodbs.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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
From: | Merlin Moncure <mmoncure(at)gmail(dot)com> |
---|---|
To: | Josh Berkus <josh(at)agliodbs(dot)com> |
Cc: | PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-16 20:31:23 |
Message-ID: | b42b73150907161331i777ec3a0xc50244db1e6a7110@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
On Thu, Jul 16, 2009 at 2:34 PM, Josh Berkus<josh(at)agliodbs(dot)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
From: | Greg Smith <gsmith(at)gregsmith(dot)com> |
---|---|
To: | Josh Berkus <josh(at)agliodbs(dot)com> |
Cc: | PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-16 20:50:14 |
Message-ID: | alpine.GSO.2.01.0907161600400.21429@westnet.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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(at)gregsmith(dot)com http://www.gregsmith.com Baltimore, MD
From: | Euler Taveira de Oliveira <euler(at)timbira(dot)com> |
---|---|
To: | Merlin Moncure <mmoncure(at)gmail(dot)com> |
Cc: | Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-16 20:54:10 |
Message-ID: | 4A5F9372.507@timbira.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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/
From: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> |
---|---|
To: | Greg Smith <gsmith(at)gregsmith(dot)com> |
Cc: | Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-16 23:25:52 |
Message-ID: | 17604.1247786752@sss.pgh.pa.us |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
Greg Smith <gsmith(at)gregsmith(dot)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
From: | Andrew Dunstan <andrew(at)dunslane(dot)net> |
---|---|
To: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> |
Cc: | Greg Smith <gsmith(at)gregsmith(dot)com>, Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-16 23:40:00 |
Message-ID: | 4A5FBA50.6010800@dunslane.net |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
Tom Lane wrote:
> Greg Smith <gsmith(at)gregsmith(dot)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
From: | Brendan Jurd <direvus(at)gmail(dot)com> |
---|---|
To: | Josh Berkus <josh(at)agliodbs(dot)com> |
Cc: | PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-17 00:07:31 |
Message-ID: | 37ed240d0907161707q1dcd348cjc99b8ee8c9616009@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
2009/7/17 Josh Berkus <josh(at)agliodbs(dot)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
From: | "Kevin Grittner" <Kevin(dot)Grittner(at)wicourts(dot)gov> |
---|---|
To: | "Josh Berkus" <josh(at)agliodbs(dot)com>, "Brendan Jurd" <direvus(at)gmail(dot)com> |
Cc: | "PostgreSQL-development" <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-17 00:19:51 |
Message-ID: | 4A5F7D5702000025000288CE@gw.wicourts.gov |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
Brendan Jurd <direvus(at)gmail(dot)com> wrote:
> The only trick was working out exactly which
> packages I needed to install.
Which were?
-Kevin
From: | Robert Haas <robertmhaas(at)gmail(dot)com> |
---|---|
To: | Brendan Jurd <direvus(at)gmail(dot)com> |
Cc: | Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-17 00:32:14 |
Message-ID: | 603c8f070907161732q2a44a0fci232be7a78119bd00@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
On Thu, Jul 16, 2009 at 8:07 PM, Brendan Jurd<direvus(at)gmail(dot)com> wrote:
> 2009/7/17 Josh Berkus <josh(at)agliodbs(dot)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
From: | Brendan Jurd <direvus(at)gmail(dot)com> |
---|---|
To: | Kevin Grittner <Kevin(dot)Grittner(at)wicourts(dot)gov> |
Cc: | Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-17 00:34:18 |
Message-ID: | 37ed240d0907161734n164f744dh60c393163556dd17@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
2009/7/17 Kevin Grittner <Kevin(dot)Grittner(at)wicourts(dot)gov>:
> Brendan Jurd <direvus(at)gmail(dot)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
From: | Alvaro Herrera <alvherre(at)commandprompt(dot)com> |
---|---|
To: | Robert Haas <robertmhaas(at)gmail(dot)com> |
Cc: | Brendan Jurd <direvus(at)gmail(dot)com>, Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-17 00:51:31 |
Message-ID: | 20090717005131.GF5203@alvh.no-ip.org |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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.
From: | Andrew Dunstan <andrew(at)dunslane(dot)net> |
---|---|
To: | Brendan Jurd <direvus(at)gmail(dot)com> |
Cc: | Kevin Grittner <Kevin(dot)Grittner(at)wicourts(dot)gov>, Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-17 00:58:47 |
Message-ID: | 4A5FCCC7.9020209@dunslane.net |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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
From: | Peter Eisentraut <peter_e(at)gmx(dot)net> |
---|---|
To: | pgsql-hackers(at)postgresql(dot)org |
Cc: | Greg Smith <gsmith(at)gregsmith(dot)com>, Josh Berkus <josh(at)agliodbs(dot)com> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-17 07:53:02 |
Message-ID: | 200907171053.02302.peter_e@gmx.net |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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
From: | Peter Eisentraut <peter_e(at)gmx(dot)net> |
---|---|
To: | pgsql-hackers(at)postgresql(dot)org |
Cc: | Alvaro Herrera <alvherre(at)commandprompt(dot)com>, Robert Haas <robertmhaas(at)gmail(dot)com>, Brendan Jurd <direvus(at)gmail(dot)com>, Josh Berkus <josh(at)agliodbs(dot)com> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-07-20 13:30:30 |
Message-ID: | 200907201630.31051.peter_e@gmx.net |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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.
From: | Bruce Momjian <bruce(at)momjian(dot)us> |
---|---|
To: | Robert Haas <robertmhaas(at)gmail(dot)com> |
Cc: | Brendan Jurd <direvus(at)gmail(dot)com>, Josh Berkus <josh(at)agliodbs(dot)com>, PostgreSQL-development <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Docbook toolchain interfering with patch review? |
Date: | 2009-08-09 01:10:37 |
Message-ID: | 200908090110.n791AbZ07851@momjian.us |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Lists: | pgsql-hackers |
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(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +