Re: XML API documentation

[Owen Taylor <otaylor redhat com>]

Malcolm Tredinnick <malcolm commsecure com au> writes:

> On Sat, Nov 09, 2002 at 01:14:55PM -0500, Owen Taylor wrote:
> > Malcolm Tredinnick <malcolm commsecure com au> writes:
> > > Modulo an official release, the work needing to be done to convert the
> > > API docs is all moderately routine, although it can be a bit fiddly in
> > > places.
> > 
> > Note that tarballs are supposed:
> > 
> >  - To include the generated HTML
> >  - To default to --disable-gtk-doc when configure is run
> > 
> > So, the gtk-doc release is not really that crucial; it's
> > only needed for people who want to hack the docs.
> 
> This isn't quite correct. A lot of packages use the configure.in from
> the gtk-doc examples/ directory, which only (and by default) runs
> gtk-doc if you have it installed.  Unfortunately, it is this "auto" mode
> that is going to break (gtk+ has tweaked things so that 'auto' == 'no'
> which is why you aren't seeing this, Owen). So we need a release and
> maybe fix the example as well -- I have a couple of tweaks in the docs
> and examples area that I'll send to the gtk-doc list.

Well, I _assume_ that when updating to XML, you'd put the 
right version checks into configure.in, so it would just
work even if you were defaulting to on.

[ The Glib/Pango/ATK/GTK+ are actually completely independent of
  anything from the gtk-doc examples, unless the gtk-doc examples
  have been updated to match ]

The reason that the GTK+ checks default to off is that there is no
reason for it to default to on, and by defaulting to off:

 - We don't have to worry about problems with people with
   broken SGML. (The #1 cause of GTK+ compilation problems
   until we defaulteed off)
 - The libraries compile 5-10 minutes faster for everybody.

Regards,
                                        Owen