diff options
Diffstat (limited to 'libs/cairo-1.16.0/doc/public/xml/cairo-version.xml')
| -rw-r--r-- | libs/cairo-1.16.0/doc/public/xml/cairo-version.xml | 278 |
1 files changed, 0 insertions, 278 deletions
diff --git a/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml b/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml deleted file mode 100644 index 7825ecd..0000000 --- a/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml +++ /dev/null @@ -1,278 +0,0 @@ -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ -<!ENTITY version SYSTEM "version.xml"> -]> -<refentry id="cairo-Version-Information"> -<refmeta> -<refentrytitle role="top_of_page" id="cairo-Version-Information.top_of_page">Version Information</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>CAIRO Library</refmiscinfo> -</refmeta> -<refnamediv> -<refname>Version Information</refname> -<refpurpose>Compile-time and run-time version checks.</refpurpose> -</refnamediv> - -<refsect1 id="cairo-Version-Information.functions" role="functions_proto"> -<title role="functions_proto.title">Functions</title> -<informaltable pgwide="1" frame="none"> -<tgroup cols="2"> -<colspec colname="functions_return" colwidth="150px"/> -<colspec colname="functions_name"/> -<tbody> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-ENCODE:CAPS">CAIRO_VERSION_ENCODE</link><phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-STRINGIZE:CAPS">CAIRO_VERSION_STRINGIZE</link><phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type"><link linkend="int"><returnvalue>int</returnvalue></link> -</entry><entry role="function_name"><link linkend="cairo-version">cairo_version</link> <phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link> * -</entry><entry role="function_name"><link linkend="cairo-version-string">cairo_version_string</link> <phrase role="c_punctuation">()</phrase></entry></row> - -</tbody> -</tgroup> -</informaltable> -</refsect1> -<refsect1 id="cairo-Version-Information.other" role="other_proto"> -<title role="other_proto.title">Types and Values</title> -<informaltable role="enum_members_table" pgwide="1" frame="none"> -<tgroup cols="2"> -<colspec colname="name" colwidth="150px"/> -<colspec colname="description"/> -<tbody> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION:CAPS">CAIRO_VERSION</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-MAJOR:CAPS">CAIRO_VERSION_MAJOR</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-MINOR:CAPS">CAIRO_VERSION_MINOR</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-MICRO:CAPS">CAIRO_VERSION_MICRO</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-STRING:CAPS">CAIRO_VERSION_STRING</link></entry></row> - -</tbody> -</tgroup> -</informaltable> -</refsect1> - - -<refsect1 id="cairo-Version-Information.description" role="desc"> -<title role="desc.title">Description</title> -<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 git instead of a tar file, -or as a "snapshot" tar file as opposed to a "release" tar file).</para> -<informalexample><screen> - _____ Major. Always 1, until we invent a new scheme. -/ ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (git) -| / _ Micro. Even/Odd = Tar-file/git -| | / -1.0.0 -</screen></informalexample> -<para>Here are a few examples of versions that one might see.</para> -<informalexample><screen> -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 git) --------------------------------------- -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) -</screen></informalexample> -<refsect2> -<title>Compatibility</title> - -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. - -</refsect2> -<refsect2> -<title>Examining the version</title> - -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 the -macro <link linkend="CAIRO-VERSION-ENCODE:CAPS"><function>CAIRO_VERSION_ENCODE()</function></link> to perform the encoding. - -<informalexample><screen> -Compile-time ------------- -<link linkend="CAIRO-VERSION-STRING:CAPS"><type>CAIRO_VERSION_STRING</type></link> Human-readable -<link linkend="CAIRO-VERSION:CAPS"><type>CAIRO_VERSION</type></link> Encoded, suitable for comparison - -Run-time --------- -<link linkend="cairo-version-string"><function>cairo_version_string()</function></link> Human-readable -<link linkend="cairo-version"><function>cairo_version()</function></link> Encoded, suitable for comparison -</screen></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> - -</refsect2> - -</refsect1> -<refsect1 id="cairo-Version-Information.functions_details" role="details"> -<title role="details.title">Functions</title> -<refsect2 id="CAIRO-VERSION-ENCODE:CAPS" role="macro" condition="since:1.0"> -<title>CAIRO_VERSION_ENCODE()</title> -<indexterm zone="CAIRO-VERSION-ENCODE:CAPS" role="1.0"><primary sortas="VERSION_ENCODE">CAIRO_VERSION_ENCODE</primary></indexterm> -<programlisting language="C">#define CAIRO_VERSION_ENCODE(major, minor, micro)</programlisting> -<para>This macro encodes the given cairo version into an integer. The numbers -returned by <link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link> and <link linkend="cairo-version"><function>cairo_version()</function></link> are encoded using this macro. -Two encoded version numbers can be compared as integers. The encoding ensures -that later versions compare greater than earlier versions.</para> -<refsect3 id="CAIRO-VERSION-ENCODE.parameters" role="parameters"> -<title>Parameters</title> -<informaltable role="parameters_table" pgwide="1" frame="none"> -<tgroup cols="3"> -<colspec colname="parameters_name" colwidth="150px"/> -<colspec colname="parameters_description"/> -<colspec colname="parameters_annotations" colwidth="200px"/> -<tbody> -<row><entry role="parameter_name"><para>major</para></entry> -<entry role="parameter_description"><para>the major component of the version number</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>minor</para></entry> -<entry role="parameter_description"><para>the minor component of the version number</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>micro</para></entry> -<entry role="parameter_description"><para>the micro component of the version number</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="CAIRO-VERSION-ENCODE.returns" role="returns"> -<title>Returns</title> -<para> the encoded version.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="CAIRO-VERSION-STRINGIZE:CAPS" role="macro" condition="since:1.8"> -<title>CAIRO_VERSION_STRINGIZE()</title> -<indexterm zone="CAIRO-VERSION-STRINGIZE:CAPS" role="1.8"><primary sortas="VERSION_STRINGIZE">CAIRO_VERSION_STRINGIZE</primary></indexterm> -<programlisting language="C">#define CAIRO_VERSION_STRINGIZE(major, minor, micro)</programlisting> -<para>This macro encodes the given cairo version into an string. The numbers -returned by <link linkend="CAIRO-VERSION-STRING:CAPS"><literal>CAIRO_VERSION_STRING</literal></link> and <link linkend="cairo-version-string"><function>cairo_version_string()</function></link> are encoded using this macro. -The parameters to this macro must expand to numerical literals.</para> -<refsect3 id="CAIRO-VERSION-STRINGIZE.parameters" role="parameters"> -<title>Parameters</title> -<informaltable role="parameters_table" pgwide="1" frame="none"> -<tgroup cols="3"> -<colspec colname="parameters_name" colwidth="150px"/> -<colspec colname="parameters_description"/> -<colspec colname="parameters_annotations" colwidth="200px"/> -<tbody> -<row><entry role="parameter_name"><para>major</para></entry> -<entry role="parameter_description"><para>the major component of the version number</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>minor</para></entry> -<entry role="parameter_description"><para>the minor component of the version number</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>micro</para></entry> -<entry role="parameter_description"><para>the micro component of the version number</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="CAIRO-VERSION-STRINGIZE.returns" role="returns"> -<title>Returns</title> -<para> a string literal containing the version.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.8">1.8</link></para></refsect2> -<refsect2 id="cairo-version" role="function" condition="since:1.0"> -<title>cairo_version ()</title> -<indexterm zone="cairo-version" role="1.0"><primary sortas="version">cairo_version</primary></indexterm> -<programlisting language="C"><link linkend="int"><returnvalue>int</returnvalue></link> -cairo_version (<parameter><type>void</type></parameter>);</programlisting> -<para>Returns the version of the cairo library encoded in a single -integer as per <link linkend="CAIRO-VERSION-ENCODE:CAPS"><literal>CAIRO_VERSION_ENCODE</literal></link>. The encoding ensures that -later versions compare greater than earlier versions.</para> -<para>A run-time comparison to check that cairo's version is greater than -or equal to version X.Y.Z could be performed as follows:</para> -<informalexample><programlisting> -if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...} -</programlisting></informalexample> -<para>See also <link linkend="cairo-version-string"><function>cairo_version_string()</function></link> as well as the compile-time -equivalents <link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link> and <link linkend="CAIRO-VERSION-STRING:CAPS"><literal>CAIRO_VERSION_STRING</literal></link>.</para> -<refsect3 id="cairo-version.returns" role="returns"> -<title>Returns</title> -<para> the encoded version.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-version-string" role="function" condition="since:1.0"> -<title>cairo_version_string ()</title> -<indexterm zone="cairo-version-string" role="1.0"><primary sortas="version_string">cairo_version_string</primary></indexterm> -<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link> * -cairo_version_string (<parameter><type>void</type></parameter>);</programlisting> -<para>Returns the version of the cairo library as a human-readable string -of the form "X.Y.Z".</para> -<para>See also <link linkend="cairo-version"><function>cairo_version()</function></link> as well as the compile-time equivalents -<link linkend="CAIRO-VERSION-STRING:CAPS"><literal>CAIRO_VERSION_STRING</literal></link> and <link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link>.</para> -<refsect3 id="cairo-version-string.returns" role="returns"> -<title>Returns</title> -<para> a string containing the version.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> - -</refsect1> -<refsect1 id="cairo-Version-Information.other_details" role="details"> -<title role="details.title">Types and Values</title> -<refsect2 id="CAIRO-VERSION:CAPS" role="macro" condition="since:1.0"> -<title>CAIRO_VERSION</title> -<indexterm zone="CAIRO-VERSION:CAPS" role="1.0"><primary sortas="VERSION">CAIRO_VERSION</primary></indexterm> -<programlisting language="C">#define CAIRO_VERSION</programlisting> -<para>The version of cairo available at compile-time, encoded using -<link linkend="CAIRO-VERSION-ENCODE:CAPS"><function>CAIRO_VERSION_ENCODE()</function></link>.</para> -<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="CAIRO-VERSION-MAJOR:CAPS" role="macro" condition="since:1.0"> -<title>CAIRO_VERSION_MAJOR</title> -<indexterm zone="CAIRO-VERSION-MAJOR:CAPS" role="1.0"><primary sortas="VERSION_MAJOR">CAIRO_VERSION_MAJOR</primary></indexterm> -<programlisting language="C">#define CAIRO_VERSION_MAJOR USE_cairo_version_OR_cairo_version_string_INSTEAD -</programlisting> -<para>The major component of the version of cairo available at compile-time.</para> -<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="CAIRO-VERSION-MINOR:CAPS" role="macro" condition="since:1.0"> -<title>CAIRO_VERSION_MINOR</title> -<indexterm zone="CAIRO-VERSION-MINOR:CAPS" role="1.0"><primary sortas="VERSION_MINOR">CAIRO_VERSION_MINOR</primary></indexterm> -<programlisting language="C">#define CAIRO_VERSION_MINOR USE_cairo_version_OR_cairo_version_string_INSTEAD -</programlisting> -<para>The minor component of the version of cairo available at compile-time.</para> -<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="CAIRO-VERSION-MICRO:CAPS" role="macro" condition="since:1.0"> -<title>CAIRO_VERSION_MICRO</title> -<indexterm zone="CAIRO-VERSION-MICRO:CAPS" role="1.0"><primary sortas="VERSION_MICRO">CAIRO_VERSION_MICRO</primary></indexterm> -<programlisting language="C">#define CAIRO_VERSION_MICRO USE_cairo_version_OR_cairo_version_string_INSTEAD -</programlisting> -<para>The micro component of the version of cairo available at compile-time.</para> -<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="CAIRO-VERSION-STRING:CAPS" role="macro" condition="since:1.8"> -<title>CAIRO_VERSION_STRING</title> -<indexterm zone="CAIRO-VERSION-STRING:CAPS" role="1.8"><primary sortas="VERSION_STRING">CAIRO_VERSION_STRING</primary></indexterm> -<programlisting language="C">#define CAIRO_VERSION_STRING</programlisting> -<para>A human-readable string literal containing the version of cairo available -at compile-time, in the form of "X.Y.Z".</para> -<para role="since">Since: <link linkend="api-index-1.8">1.8</link></para></refsect2> - -</refsect1> - -</refentry> |