Guile-Cairo Documentation README
================================


What's going on here?
---------------------

What's going on is that Guile-Cairo has a system that automatically
extracts documentation from the upstream Cairo reference manual, adapts
names to Scheme conventions, and then generates Texinfo.

Of course, the generated documentation is not perfect. It still contains
many C-isms, which are not relevant to the Scheme programmer. In the
end, fixing all erroneous documentation will have to be a human
endeavor.

For that reason, Guile-Cairo's documentation build allows users to
override the generated documentation, simply by adding definitions to
the `overrides.texi' file included in the source. Then, the next time
the documentation is autogenerated, those overrides will be used instead
of the automatically generated docs.


How can I help improve Guile-Cairo's documentation?
---------------------------------------------------

It's very simple, really. Just find the `deffn' in one of the
defuns-cairo*.texi files, copy and paste it into `overrides.texi', then
edit to your heart's content. Send a patch to the maintainer and your
docs will make everyone's lives better.

If it is the "overview" section whose documentation you want to fix, go
ahead and submit a patch to the section-foo.texi file or to
guile-cairo.texi. The intention is to not regenerate the section-*
files.


How can I regenerate the documentation?
---------------------------------------

The toolchain to regenerate the defuns-*.texi files is a bit
bleeding-edge; for that reason, the generated files are included in the
Guile-Cairo distribution, and the documentation is normally regenerated
by hand. If you want to do so yourself, you will need:

 * guile-lib > 0.1.4, or from bzr after 28 July 2007;
 * guile-gnome-platform > 2.15.93, or from bzr after 27 July 2007.
   (Really all you need is the glib module, which has gtk-doc.scm.)
 * guild, which is distributed with Guile.
 * guile-snarf-docs from Guile's build directory (should be in $PATH)

Then you simply type `make generate-defuns' in doc/.


What about a tutorial?
----------------------

That would be nice, yes, but for now you will have to look at the C
documentation on http://cairographics.org/.