[cairo] Docs

[Owen Taylor]

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.

>  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
 *** 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?

Regards,
							Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050814/2c561750/attachment.pgp