[cairo] Docs

[Russell Shaw]

Owen Taylor wrote:
> On Sun, 2005-08-14 at 14:04 +1000, Russell Shaw wrote:
> 
>>Russell Shaw wrote:
>>
>>>Hi,
>>>When i change a .c file in cairo/src and rebuild, 
>>>cairo/doc/public/html/cairo.devhelp
>>>doesn't get updated. How do i do that? I have done ./configure 
>>>--enable-gtk-doc.
>>
>>The second part makes cairo.devhelp get rebuilt whenever a .c
>>file changes, only when you run make from the top level or
>>within the doc/public directory.
>>
>>Don't know the precise effect of the first half, but it looked
>>like a similar problem. Also, the doc stuff seems to get rebuilt
>>regardless of whether --enable-gtk-doc was done.
> 
> 
>>diff -u  gtk-doc.make  gtk-doc.make-new
>>--- gtk-doc.make        2005-08-14 13:11:04.000000000 +1000
>>+++ gtk-doc.make-new    2005-08-14 13:11:52.000000000 +1000
>>@@ -72,7 +72,7 @@
>>         touch tmpl-build.stamp
>>
>>  tmpl.stamp: tmpl-build.stamp
>>-       @true
>>+       touch tmpl.stamp
>>
>>  #### xml ####
>>
>>@@ -84,7 +84,7 @@
>>         touch sgml-build.stamp
>>
>>  sgml.stamp: sgml-build.stamp
>>-       @true
>>+       touch sgml.stamp
> 
> 
> This defeats the logic that makes stuff only get rebuilt as
> needed ... it's not *so* important to have that logic for Cairo
> as it is for GTK+, since the HTML docs build a lot faster 
> (GTK+ takes 10 minutes or more), but still useful, and 
> gtk-doc.make is a shared file.
> 
> Is your claim that cairo.devhelp needs to be rebuilt even when
> nothing has changed in the docbook files? That seems strange to me -
> cairo.devhelp is just another output of the XSL file.

The .c files in cairo/src *are* the docbook files. When you change
an embedded comment in one of those files, you want the relevant docs
in cairo/docs to be rebuilt when you run make in cairo/docs. Running
make in cairo/src will *not* cause a doc build no matter what you
change (i've tried that). Running make at the top level will cause a
doc build too, but shouldn't you be running it from within cairo/src?