Re: Bonobo docs on d.g.o (was Re: Fix for broken API doc build)

["John R. Sheets" <dusk ravendusk org>]

On Feb 19, 2001, Federico Mena Quintero <federico ximian com> wrote:
> 
> Owen Taylor <otaylor redhat com> writes:
> 
> > I believe the Makefiles in glib/pango/gtk+ HEAD is just about
> > perfect, though rather arcane. It actually (using some recent changes
> > of Damon's to gtk-doc) has correct full dependencies so it always
> > rebuilds when necessary and never when not necessary.
> 
> Are these similar to my Makefiles in evolution/doc/devel?  Mine track
> SGML and source code dependencies, sort of by hand, but they seem to
> work fine.

They seem to be quite a bit different, and cutting over to them would
be a significant change in the way the docs are handled; thus, I don't
believe we'd be able to incrementally migrate to Owen's system.

Most of Owen's stuff is boilerplate, though, and would be very easy to
drop in.  (What's the policy/portability of using make's 'include'
directive?  Seems like it would be nice to have a single, centralized
version of this, which we could drop into a Makefile.am for quick doc
building support...then just define a few standardized variables.)

Federico, I was wondering why you install the .args, .hierarchy,
-sections.txt, and the other transient gtk-doc files.  Are these
useful on the end user's system?  Isn't it better to only install the
final HTML files (and arguably the generated DocBook files, for when
the Nautilus doc browser becomes more commonplace)?

Another maintenance issue, which is addressed by Owen's file globbing,
is keeping track of all the generated files.  In cal-client, you only
have a half-dozen, but Bonobo has over 60 SGML files.  Plus tons of
*.[hc] files.  We'd have to maintain long lists in $(SOURCE_FILES),
$(tmpl_sources), and $(sgml_generated).  These lists get pretty stale
over time (case in point, the property listener files were still
lurking in the Bonobo docs makefile until last week).  Whereas the
globs in glib/docs/reference/glib/Makefile.am grab them on the fly:

  # Used for dependencies
  HFILE_GLOB=$(top_srcdir)/*.h $(top_srcdir)/gmodule/*.h
  CFILE_GLOB=$(top_srcdir)/*.c $(top_srcdir)/gmodule/*.c

Although I'm sure it's there, I haven't grasped yet how Owen's
makefile detects manual changes to the tmpl/*.sgml files.  Perhaps one
of the recent changes to gtk-doc handles that...?  Hmm, is that what
tmpl.stamp is for?

In any case, I like Owen's stuff, and think we should be using it
more, especially since it will make it easier to maintain the online
versions of the docs.  What do the Bonobo/Evolution teams think?  And
what's the scoop on the 'include' makefile directive?  Barring
makefile portability issues, I think that would be the cleanest,
lowest impact solution.

Perhaps a new gnome-common/Makefile.GNOME file?  (c;  *flinch*

John

-- 
dusk ravendusk org                            http://www.gnome.org
jsheets codeweavers com                  http://www.worldforge.org
jsheets users sourceforge net     http://openbooks.sourceforge.net
               http://advogato.org/person/jsheets

                   Writing Gnome Applications
          http://www.aw.com/cseng/titles/0-201-65791-0/