Re: gtk-doc cleanification idea / patch

[Peter Williams <peter newton cx>]

On 14 May 2001 22:05:28 -0400, Owen Taylor wrote:
> Well, I'm not sure we are interested in _expanding_ gtk-doc in
> complexity, but if it can be made simpler to set up, I think we are
> definitely interested in ideas about doing that.

Unsurprisingly, I've found that there are tradeoffs to "simplifying".
What I have written so far makes using gtk-doc in a project this simple

    1. Run gtkdoc-ize (yeah, that sucks)
    2. Put AM_PATH_GTKDOC(0.6) in configure.in
    3. Add @GTKDOC_SGML_RULES@ and @GTKDOC_HTML_RULES@ to Makefiles
    somewhere (and some other unpleasant garbage that seems to be
    necessary)

In some ways, that's a lot nicer than the current setup, but in other
ways, it's a lot worse. (Whoa, deep.) I guess its worth noting that my
goal was fairly ambitious: take care of installation, cleaning, and all
that stuff, not only dependencies or "make scan templates sgml".

> 
> I haven't studied xml-i18n-tools so I can't really comment on how it does
> things; I'm a little hesitant to add more autogeneration into the process,
> but having fooled around a lot with similar stuff for Pango, could imagine
> ways of getting autoconf to substitute:
> 
>  @GTK_DOC_RULES@
> 
> For all the boilerplate at the bottom of, say, gtk+/docs/reference/gtk/Makefile.am

This is basically what I did. The boilerplate is basically equivalent to
the stuff you mentioned. The main issues I've run into are:

    1. Automake is not all that bright about substitions, so for
    instance if @GTK_DOC_RULES@ has an all-local target but the
    Makefile.am doesn't, automake won't hook up all-local and it won't
    work.

    2. The boilerplate needs to come from somewhere even if gtk-doc
    isn't installed.

I worked around (1) by having @GTK_DOC_RULES@ define a bunch of targets
along the lines of gtkdoc-sgml-maintainer-clean-hook. This would be used
like:

    GTKDOC_MODULE = foobar

    @GTKDOC_SGML_RULES@

    maintainer-clean-local: gtkdoc-sgml-maintainer-clean-hook
    ...

This is the best solution I can think of, because it lets you integrate
with whatever may already be in the Maekefile.am. However, once you get
into gtkdoc-{sgml.html}-{maintainer-clean,clean,all,install}-hook you
just get lots more boilerplate code.

(BTW, I split SGML and HTML rules because things like Evolution generate
SGML for each section separately then put it all into one glob of HTML.
Evolution seems to be the only package to do this but I think the split
is ok.)

(2) is the reason for the 'gtkdoc-ize' script. It was needed to copy
over the rules fragments into each project (otherwise gtk-doc would need
to be installed for the fragments). I guess I could have embedded them
in gtkdoc.m4 with some clever kind of AC_SUBST_FILE trick, maybe. (I'm
99% sure that the rules are too long to use with a regular AC_SUBST.)

> 
> I doubt that _simplifies_ things, since the hard part is knowing what
> files to put where and knowing how the process works. This just adds
> one more magic element. But it could reduce cut and paste quite a bit.

This was my main goal... I'm the kind of person that gets annoyed by
lots of cut-and-paste. And more justifiably, the generated files seem to
change between each version of gtk-doc, so it would be nice if you could
add @GTK_DOC_RULES@ once instead of constantly updating the boilerplate
code.

I'll certainly admit that my approach is complex but I think the results
are worthwile.

> 
> But please look at the Makefiles in GTK+/GLib/Pango head. I spent a
> lot of time making them correct and general.

Thanks, I'll use them as a reference for correctness if I get the
impression that I should keep on working on this.

--
Peter Williams     peter newton cx / peterw ximian com

"Why should I have to change my name? He's the one who 
sucks!"                              -- Michael Bolton