Re: Docbook toolchain interfering with patch review?

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