Bug 2798

Summary: version-controlled files modified by make'ing cairo
Product: cairo Reporter: ellson
Component: generalAssignee: Carl Worth <cworth>
Status: RESOLVED WONTFIX QA Contact: cairo-bugs mailing list <cairo-bugs>
Severity: normal    
Priority: high CC: jwatt
Version: 0.9.3   
Hardware: x86 (IA32)   
OS: Linux (All)   
Whiteboard:
i915 platform: i915 features:

Description ellson 2005-03-24 12:04:44 UTC
The following files are modified (recreated perhaps) by make'ing cairo
resulting in 'M' flags when updating from CVS.
Perhaps they should not be in CVS at all?


doc/public/tmpl/cairo-atsui.sgml
doc/public/tmpl/cairo-ft.sgml
doc/public/tmpl/cairo-glitz.sgml
doc/public/tmpl/cairo-matrix.sgml
doc/public/tmpl/cairo-pattern.sgml
doc/public/tmpl/cairo-pdf.sgml
doc/public/tmpl/cairo-png.sgml
doc/public/tmpl/cairo-ps.sgml
doc/public/tmpl/cairo-quartz.sgml
doc/public/tmpl/cairo-surface.sgml
doc/public/tmpl/cairo-xcb.sgml
doc/public/tmpl/cairo-xlib.sgml
doc/public/tmpl/cairo.sgml
Comment 1 Owen Taylor 2005-08-18 17:48:51 UTC
This is blocking on fixing the --only-section-tmpl of gtk-doc to work.

(Another approach would be to move the section templates inline, but
having large chunks of docbook inline in the C files seems unattractive
to me.)

It's become less of a problem though, as the cairo API stabilizes.
Comment 2 Carl Worth 2005-08-22 17:14:16 UTC
Move bugs against "cvs" version to "0.9.3" so we can remove the "cvs" version.
Comment 3 Kalle Vahlman 2007-07-02 12:13:45 UTC
The docs are not built anymore unless specifically asked for by supplying --enable-gtk-doc *and* make'ing the 'doc' target so this is even less of a problem now.

Also, with git the empty modifications do not seem to bother normal updates.

Since this is more an issue of gtk-doc and not specifically Cairo, and also because it's not in-your-face anymore, I'm closing this as WONTFIX.

Please reopen if you feel this issue still poses significant trouble to Cairo development / building from git.
Comment 4 Behdad Esfahbod 2007-07-02 23:25:17 UTC
We do want to move the docs to .c files though.
Comment 5 Carl Worth 2007-07-03 08:30:43 UTC
(In reply to comment #4)
> We do want to move the docs to .c files though.

Or stop using gtk-doc altogether and move all documentation _out_ of the .c files....

-Carl
Comment 6 Behdad Esfahbod 2007-07-03 09:10:35 UTC
(In reply to comment #5)
> (In reply to comment #4)
> > We do want to move the docs to .c files though.
> 
> Or stop using gtk-doc altogether and move all documentation _out_ of the .c
> files....

And risk having them all outdated.
 
> -Carl
> 

Comment 7 Carl Worth 2007-07-03 09:20:56 UTC
(In reply to comment #6)
> And risk having them all outdated.

I don't buy that argument at all.

What's necessary is a culture that mandates that a change or addition
to the semantics of the library be accompanied with an update to the
documentation at the same time. I think we have that culture within
the cairo community now.

Something that helps that culture is a tool that allows a single
"commit" to show both changes to the code and changes to the
documentation as atomic. So that feature I would definitely like. But
I don't think that has anything to do with "documentation in .c
files".

And something that we've been entirely missing out on with the
documentation is a conversation with users of the library/consumers of
the documentation. These are people that might never need to look at
the implementation of cairo, but do very often read the documentation
and are the people most acutely aware of problems in that
documentation.

So I really want to move the documentation to "live" in something like
a wiki, where there is at least a "discuss" page where users can
freely comment on things that were unclear in the documentation, or
things they've learned elsewhere that should be added, etc.

I'll talk more about this on the mailing list soon.

-Carl

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.