[cairo-commit] cairo/doc/public/tmpl cairo-version.sgml,1.2,1.3

[Carl Worth]

Committed by: cworth

Update of /cvs/cairo/cairo/doc/public/tmpl
In directory gabe:/tmp/cvs-serv29958/doc/public/tmpl

Modified Files:
	cairo-version.sgml 
Log Message:

2005-09-02  Carl Worth  <cworth at cworth.org>

        * doc/public/tmpl/cairo-version.sgml: Add description of cairo's
        versioning scheme.


Index: cairo-version.sgml
===================================================================
RCS file: /cvs/cairo/cairo/doc/public/tmpl/cairo-version.sgml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- cairo-version.sgml	25 Aug 2005 02:20:08 -0000	1.2
+++ cairo-version.sgml	2 Sep 2005 20:42:34 -0000	1.3
@@ -2,13 +2,113 @@
 Version Information
 
 <!-- ##### SECTION Short_Description ##### -->
-Compile and run time version checks
+Compile-time and run-time version checks.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+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).
+</para>
+<para>
+<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>
+</para>
+<para>
+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>
+</para>
+
+<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.
+</para>
+
+<para>
+Moving from a release to any later version (release, snapshot,
+development) is always guaranteed to provide compatibility.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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.
 </para>
 
+<para>
+<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>
+</para>
+
+<para>
+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 See_Also ##### -->
 <para>