[prev in list] [next in list] [prev in thread] [next in thread] 

List:       cairo
Subject:    Re: [cairo] Rethinking cairo's build system
From:       Damon Chaplin <damon () karuna ! uklinux ! net>
Date:       2006-06-30 12:41:34
Message-ID: 1151671294.2528.33.camel () localhost ! localdomain
[Download RAW message or body]

On Sat, 2006-06-24 at 19:53 +0200, Carl Worth wrote:
> On Sat, 24 Jun 2006 18:43:16 +0100, Damon Chaplin wrote:
> > > 
> > > 4) Building the docs takes too long, (or perhaps it just needs to be
> > >    moved to "make doc" instead of "make)
> > 
> > Or you can use './configure --disable-gtk-doc' to skip building the
> > documentation.
> 
> But configure is slow, so I wouldn't want to have to go through it
> again (twice!) just to be able to build the docs and then turn them
> off again. So a separate make target is definitely what I want here.

OK. I've added a separate 'docs' target you can use in the documentation
directory, even if '--disable-gtk-doc' has been used.


> > > 6) Building the docs modifies (!) a bunch of files under version
> > >    control. This is worse than annoying.
> > 
> > It updates the template files, but should only do that if needed.
> > Is it updating anything else under version control?
> 
> It's just template files that I've seen. But there a couple problems
> here:
> 
> 	1) It generates output with trailing whitespace

Why is trailing whitespace a problem?


> 	2) Different versions of gtk-doc generate different template
>            results, (and often in fairly trivial ways, which makes the
>            change all the more annoying when they're under version
>            control).

Yes, unfortunately 2 minor bugs in the handling of template files turned
up recently, and the fixes tried to clean up the old errors, resulting
in minor changes.

If people use a recent gtk-doc that would help here (cvs would be best).

It also helps if people only commit docs if they have worked on them.


> > It is now possible to write all the gtk-doc documentation in the source
> > code, and not place the template files under version control. That might
> > help you a bit. (goocanvas does that.) If you want help with that, let
> > me know. (You just need to add an empty tmpl/dummy.sgml file to avoid
> > issues with make.)
> 
> That sounds like the perfect thing. And I would love help with that.

I've converted the existing section documentation to the inline versions
and attached it. You just need to place each part in the corresponding
file. (Or you could just put them in one .c file.)

You can then remove all the tmpl/*.sgml files from version control
(so long as there is no other documentation in the tmpl/* files.)
But place a special tmpl/dummy.sgml file there to avoid a problem with
make and globs.

But you'll need gtk-doc from cvs to build the docs, as I just fixed
another bug with inline section docs.

Damon


["cairo-docs.c" (cairo-docs.c)]

/**
 * SECTION:cairo-atsui
 * @Title: ATSUI Fonts
 * @Short_Description: 
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-beos
 * @Title: BeOS Surfaces
 * @Short_Description: BeOS surface support
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-font-options
 * @Title: Font Options
 * @Short_Description: How a font should be rendered
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-font
 * @Title: cairo_font_face_t
 * @Short_Description: Base class for fonts
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-ft
 * @Title: FreeType Fonts
 * @Short_Description: Font support for FreeType
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-glitz
 * @Title: Glitz Surfaces
 * @Short_Description: OpenGL accelerated rendering using the Glitz library
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-image
 * @Title: Image Surfaces
 * @Short_Description: Rendering to memory buffers
 * @Stability_Level: 
 * @See_Also: 
 *
 * Image surfaces provide the ability to render to memory buffers
 * either allocated by cairo or by the calling code.  The supported
 * image formats are those defined in #cairo_format_t.
 */

/**
 * SECTION:cairo-matrix
 * @Title: cairo_matrix_t
 * @Short_Description: Generic matrix operations
 * @Stability_Level: 
 * @See_Also: 
 *
 * <indexterm><primary>types</primary><secondary>cairo_matrix</secondary></indexterm><indexterm><primary/></indexterm>
                
 *  #cairo_matrix_t is used throughout cairo to convert between different
 *  coordinate spaces.  A #cairo_matrix_t holds an affine transformation,
 *  such as a scale, rotation, shear, or a combination of these.
 *  The transformation of a point (<literal>x</literal>,<literal>y</literal>)
 *  is given by:
 *
 * <programlisting>
 *  x_new = xx * x + xy * y + x0;
 *  y_new = yx * x + yy * y + y0;
 * </programlisting>
 *
 *  The current transformation matrix of a #cairo_t, represented as a
 *  #cairo_matrix_t, defines the transformation from user-space
 *  coordinates to device-space coordinates. See cairo_get_matrix() and
 *  cairo_set_matrix().
 */

/**
 * SECTION:cairo-paths
 * @Title: Paths
 * @Short_Description: Creating paths and manipulating path data
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-pattern
 * @Title: Patterns
 * @Short_Description: Gradients and filtered sources
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-pdf
 * @Title: PDF Surfaces
 * @Short_Description: Rendering PDF documents
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-png
 * @Title: PNG Support
 * @Short_Description: Reading and writing PNG images
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-ps
 * @Title: PostScript Surfaces
 * @Short_Description: Rendering PostScript documents
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-quartz
 * @Title: Quartz Surfaces
 * @Short_Description: Rendering to Quartz surfaces
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-scaled-font
 * @Title: Scaled Fonts
 * @Short_Description: Caching metrics for a particular font size
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo
 * @Title: cairo_t
 * @Short_Description: The cairo drawing context
 * @Stability_Level: 
 * @See_Also: 
 *
 * #cairo_t is the main object used when drawing with cairo. To
 * draw with cairo, you create a #cairo_t, set the target surface,
 * and drawing options for the #cairo_t, create shapes with
 * functions like cairo_move_to() and cairo_line_to(), and then
 * draw shapes with cairo_stroke() or cairo_fill().
 *
 * #cairo_t<!-- -->'s can be pushed to a stack via cairo_save().
 * They may then safely be changed, without loosing the current state.
 * Use cairo_restore() to restore to the saved state.
 */

/**
 * SECTION:cairo-status
 * @Title: Error handling
 * @Short_Description: Decoding cairo's status
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-surface
 * @Title: cairo_surface_t
 * @Short_Description: Base class for surfaces
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-svg
 * @Title: SVG Surfaces
 * @Short_Description: Rendering SVG documents
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-text
 * @Title: Text
 * @Short_Description: Rendering text and sets of glyphs
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-transforms
 * @Title: Transformations
 * @Short_Description: Manipulating the current transformation matrix
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-types
 * @Title: Types
 * @Short_Description: Generic data types used in the cairo API
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-version
 * @Title: Version Information
 * @Short_Description: Compile-time and run-time version checks.
 * @Stability_Level: 
 * @See_Also: 
 *
 * Cairo has a three-part version number scheme. In this scheme, we use
 * even vs. odd numbers to distinguish fixed points in the software
 * vs. in-progress development, (such as from CVS instead of a tar file,
 * or as a "snapshot" tar file as opposed to a "release" tar file).
 * 
 * <informalexample><programlisting>
 *  _____ Major. Always 1, until we invent a new scheme.
 * /  ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (CVS)
 * | /  _ Micro. Even/Odd = Tar-file/CVS
 * | | /
 * 1.0.0
 * </programlisting></informalexample>
 * 
 * Here are a few examples of versions that one might see.
 * <informalexample><programlisting>
 * Releases
 * --------
 * 1.0.0 - A major release
 * 1.0.2 - A subsequent maintenance release
 * 1.2.0 - Another major release
 *  
 * Snapshots
 * ---------
 * 1.1.2 - A snapshot (working toward the 1.2.0 release)
 *  
 * In-progress development (eg. from CVS)
 * --------------------------------------
 * 1.0.1 - Development on a maintenance branch (toward 1.0.2 release)
 * 1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release)
 * </programlisting></informalexample>
 * <refsect2>
 * <title>Compatibility</title>
 * <para>
 * The API/ABI compatibility guarantees for various versions are as
 * follows. First, let's assume some cairo-using application code that is
 * successfully using the API/ABI "from" one version of cairo. Then let's
 * ask the question whether this same code can be moved "to" the API/ABI
 * of another version of cairo.
 * 
 * Moving from a release to any later version (release, snapshot,
 * development) is always guaranteed to provide compatibility.
 * 
 * Moving from a snapshot to any later version is not guaranteed to
 * provide compatibility, since snapshots may introduce new API that ends
 * up being removed before the next release.
 * 
 * Moving from an in-development version (odd micro component) to any
 * later version is not guaranteed to provide compatibility. In fact,
 * there's not even a guarantee that the code will even continue to work
 * with the same in-development version number. This is because these
 * numbers don't correspond to any fixed state of the software, but
 * rather the many states between snapshots and releases.
 * </para>
 * </refsect2>
 * <refsect2>
 * <title>Examining the version</title>
 * <para>
 * Cairo provides the ability to examine the version at either
 * compile-time or run-time and in both a human-readable form as well as
 * an encoded form suitable for direct comparison. Cairo also provides a
 * macro (CAIRO_VERSION_ENCODE) to perform the encoding.
 * 
 * <informalexample><programlisting>
 * Compile-time
 * ------------
 * %CAIRO_VERSION_STRING	Human-readable
 * %CAIRO_VERSION		Encoded, suitable for comparison
 *  
 * Run-time
 * --------
 * cairo_version_string()	Human-readable
 * cairo_version()		Encoded, suitable for comparison
 * </programlisting></informalexample>
 * 
 * For example, checking that the cairo version is greater than or equal
 * to 1.0.0 could be achieved at compile-time or run-time as follows:
 * 
 * <informalexample><programlisting>
 * ##if %CAIRO_VERSION >= %CAIRO_VERSION_ENCODE(1, 0, 0)
 * printf ("Compiling with suitable cairo version: %%s\n", CAIRO_VERSION_STRING);
 * ##endif
 *  
 * if (cairo_version() >= %CAIRO_VERSION_ENCODE(1, 0, 0))
 *  *  printf ("Running with suitable cairo version: %%s\n", cairo_version_string \
                ());
 * </programlisting></informalexample>
 * </para>
 * </refsect2>
 */

/**
 * SECTION:cairo-win32-fonts
 * @Title: Win32 Fonts
 * @Short_Description: Font support for Microsoft Windows
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-win32
 * @Title: Win32 Surfaces
 * @Short_Description: Microsoft Windows surface support
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-xcb
 * @Title: XCB Surfaces
 * @Short_Description: X Window System rendering using the XCB library
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-xcb-xrender
 * @Title: XCB Surfaces
 * @Short_Description: X Window System rendering using the XCB library
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */

/**
 * SECTION:cairo-xlib
 * @Title: XLib Surfaces
 * @Short_Description: X Window System rendering using XLib
 * @Stability_Level: 
 * @See_Also: 
 *
 * 
 */



_______________________________________________
cairo mailing list
cairo@cairographics.org
http://cairographics.org/cgi-bin/mailman/listinfo/cairo

[prev in list] [next in list] [prev in thread] [next in thread]