[cairo] Docs

[Russell Shaw]

Owen Taylor wrote:
> On Mon, 2005-08-15 at 00:26 +1000, Russell Shaw wrote:
> 
>>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.
> 
> The .c file are not the docbook files. They are used to generate 
> docbook files within the xml/ directory.

yes, that what i meant (scanned by gtk-doc)

>> 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?
> 
> Works for me.
> 
>  $ touch ../../src/cairo.c
>  $ make

I assume that touch was done in cairo/doc/public ?
If so, the doc build should happen whenever a .c file
is changed as demonstrated. The point is that the doc
build will not happen when running make from within cairo/src,
thus not impacting normal development times.

>  *** Scanning header files ***
>  [...] 
>  *** Building XML ***
>  [...]
> 
>  $ emacs ../../src/cairo.c
>  [ edit a doc comment ]
>  $ make
>  *** Scanning header files ***
>  [...]
>  *** Building XML ***
>  [...]
>  *** Building HTML ***
> 
> Maybe the change you were testing with simply didn't *need* to rebuild
> the HTML docs and cairo.devhelp?