GTK+-2 Fails on compiling the Documentation branch

[alupu verizon net]

Hello,

I have a problem compiling the GTK+-2 sources which
has continued unabated for some time now.
Please see Bug 631910 of 2010-10-11,
but do not spend much time;  I'll update and 
summarize the problem/resolution for gtk+-2.24.0
in the following.

The good news is that with a very small change in two
Makefiles, I've been able to compile successfully quite
a few releases (up to and including 2.24.0).

The bad news is my confusion - what do the GTK
developers do differently so that they haven't been
bothered by this situation (or the Quality Control
not to detect any failure on compile, like me)

DETAILS

1. The problem manifests itself similarly on 'make' in
   two branches of the 'docs' subdirectory:
   'tutorial' and 'faq'.

2. The "offending" 'Makefile' code (stemming from
   'Makefile.in') is:

html: gtk-tut.sgml
        if test -w $(srcdir); then \
          (cd $(srcdir); \
           db2html gtk-tut.sgml; \
           test -d html && rm -r html; \
           mv gtk-tut html; \
           mkdir html/images; \
           cp images/*.png html/images); \
        fi

shown for 'tutorial'.  Makefile code if 'faq' is similar.

3.  On my system, this fails with error:

Using catalogs: /etc/sgml/catalog
Using stylesheet: /usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/src/gtk+-2.24.0/docs/tutorial/gtk-tut.sgml
Done.
mv: cannot stat `gtk-tut': No such file or directory
mkdir: cannot create directory `html/images': No such file or directory
cp: target `html/images' is not a directory

4. From the above, it's not hard to figure a workaround.
   Just add '-o gtk-tut' to the conversion line,
   'db2html gtk-tut.sgml'
   and everything will be hunky-dory.

5. Since, as I said, the original code above comes out
 with flying colors on quality control, I started to
 look for problems specific to my system.

5.1.  As usual (and recommended):
    db2hdml -> docbook2html

 The manual for 'docbook2html' is very clear(?),
 you want a different output directory you use "-o".
 (we're talking the latest, "docbook-utils-0.6.14", here)
  
5.2.  I've tried futzing around with the
      'docbook-utils.dsl' in
      '/usr/share/sgml/docbook/utils-0.6.14/'      
      
 To put it very delicately, I'm not an expert in
 style sheets.  I tried a few combinations on
 the original lines,
   (define use-output-dir #f)
   (define %output-dir% "HTML")  

 like
   (define %use-output-dir% #t)
 and
   (define %output-dir% "html") or
   (define %output-dir% "gtk-tut")

 without any success.

QUESTIONS

1.  Is there anything I can do on the existing
'docbook-utils.dsl' that will make the original
compilation work, especially on _both_ 'tutorial'
and 'faq'?

2.  More generally, what do the developers and
 QC's have/do differently than me?

NOTE
You cannot "escape" this branch of the compilation
(not that I want to) by saying, for example,
 configure --disable-gtk-doc-html

-- Alex

--------------

For reference:
SYSTEM
 (B)LFS i686-pc-linux-gnu, 2.6.37.1
 glib-2.28.1, atk-1.33.6, Xorg-7.6