[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Re: Generated changes and patch systems

(Please cc me in any replies, I'm not subscribed.)

Neil Williams wrote:
> ??? That simply does not work. The problem is that running gtk-doc not
> only requires tmpl/*.sgml files to exist but it *then modifies them*!

Here's how gtk-doc *used to* work:

* gtk-doc parses source code and writes out skeletal tmpl/*.sgml
* svn ci -m 'initial version of gtkdoc templates' tmpl
* upstream doc author inserts content into tmpl/*.sgml
* svn ci -m 'wrote some docs' tmpl
* gtk-doc parses source code (to pick up any new functions) + tmpl/*.sgml,
  and merges them
* svn ci -m 'yay gtkdoc' tmpl
* ...

This is, as you've noticed, insane. Sane upstreams now write all the
content for the documentation in /** */ comments in the source code, so
the tmpl/*.sgml are purely generated and can safely be omitted from
source-code control. (I have no opinion on whether your upstream is sane
or not - please check.)

However, the "no rule to make tmpl/*.sgml" issue still exists, as a
relic of the old build process.

(This history is also why gtkdoc insists on running in $srcdir, even in an
otherwise out-of-tree build - it goes as far as to chmod +w $srcdir to
subvert automake's attempts to catch writes to $srcdir!)

In Telepathy and Farsight we avoid ridiculous conflicts in tmpl/ in our
source-code control as follows:

* put tmpl/*.sgml in .svnignore, .gitignore, the darcs boringfile, or whatever
* as an exception to that, check in an empty file "tmpl/dummy.sgml"
  which is not referenced by anything else, so that builds from a clean
  checkout will succeed

In theory you could do this to get rid of tmpl/*.sgml in the tarball
too, but gtkdoc.make is in control of "make dist", so you probably can't.

Hope this helps,

Reply to: