[Owen Taylor <otaylor redhat com>] Re: gtk-doc cleanification idea / patch

[Peter Williams <peter newton cx>]

Hi everyone,

    Attached is an exchange I had with Owen Taylor about a weekend
    project that I've been working on for gtk-doc.

    Basically, I got annoyed by all the boilerplate code, and wrote some
    autoconf magic to do away with most of it. However, there's a
    tradeoff -- it adds a lot of gunk to gtk-doc. 

    I think I'll reply to Owen's mail separately and CC the list.

--
Peter Williams     peter newton cx / peterw ximian com

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

--- Begin Message ---

• From: Owen Taylor <otaylor redhat com>
• To: peter newton cx
• Cc: damon ximian com
• Subject: Re: gtk-doc cleanification idea / patch
• Date: 14 May 2001 22:05:28 -0400

Peter Williams <peterw ximian com> writes:

> Hi Damon and Owen,
> 
>     After getting frustrated by lots of indecipherable gunk in
>     evolution/doc/devel/Makefile.am, I decided to engage in a weekend
>     project of writing some new code for gtk-doc that will hopefully
>     remove the confusion that it seems to cause -- dependencies,
>     installing files, cleaning, all that stuff.
> 
>     Basically, my idea is something similar to xml-i18n-tools -- rules
>     that are substituted into the Makefile.am that take care of all the
>     dependency stuff and would hopefully provide a nice consistent way
>     for anyone to use gtk-doc.
> 
>     I've written almost everything that I need but have run into a few
>     stylistic issues that I would like to discuss with you, the
>     maintainers. However, I'm just checking that you would be interested
>     in expanding gtk-doc in this way before I barrage you with questions
>     :-) My patch is turning out to be quite lengthy and I can see why
>     you wouldn't want to modify it as thoroughly as I have.

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.

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

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.

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

Also, ideas, correspondance about gtk-doc should really go to
gtk-doc-list not to us personally. There are other people who have
been contributing patches recently, for one thing.

Regards,
                                        Owen

--- End Message ---