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