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,