man: Document WAFFLE_API_VERSION

Add new page, waffle_feature_test_macros(7) that mimics the standard
page feature_test_macros(7). Document that WAFFLE_CONTEXT_DEBUG and
WAFFLE_CONTEXT_FORWARD_COMPATIBLE require WAFFLE_API_VERSION>=0x0103.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>

5 files changed, 122 insertions, 0 deletions

diff --git a/man/html.cmake b/man/html.cmake
index dc6bb47..7005a71 100644
--- a/man/html.cmake
+++ b/man/html.cmake
@@ -46,6 +46,7 @@ set(html_outputs
     ${html_out_dir}/waffle_window.3.html
     ${html_out_dir}/waffle_x11_egl.3.html
     ${html_out_dir}/waffle.7.html
+    ${html_out_dir}/waffle_feature_test_macros.7.html
     )
 
 set(html_common_sources
@@ -82,6 +83,7 @@ waffle_add_html(3 waffle_wayland)
 waffle_add_html(3 waffle_window)
 waffle_add_html(3 waffle_x11_egl)
 waffle_add_html(7 waffle)
+waffle_add_html(7 waffle_feature_test_macros)
 
 add_custom_target(html
     ALL
diff --git a/man/manpages.cmake b/man/manpages.cmake
index 90170fd..402bbbc 100644
--- a/man/manpages.cmake
+++ b/man/manpages.cmake
@@ -47,6 +47,7 @@ set(man_outputs
     ${man_out_dir}/man3/waffle_window.3
     ${man_out_dir}/man3/waffle_x11_egl.3
     ${man_out_dir}/man7/waffle.7
+    ${man_out_dir}/man7/waffle_feature_test_macros.7
     )
 
 set(man_common_sources
@@ -81,6 +82,7 @@ waffle_add_manpage(3 waffle_wayland)
 waffle_add_manpage(3 waffle_window)
 waffle_add_manpage(3 waffle_x11_egl)
 waffle_add_manpage(7 waffle)
+waffle_add_manpage(7 waffle_feature_test_macros)
 
 add_custom_target(man
     ALL
diff --git a/man/waffle.7.xml b/man/waffle.7.xml
index d4ee215..ab116d5 100644
--- a/man/waffle.7.xml
+++ b/man/waffle.7.xml
@@ -92,6 +92,12 @@ Link with -lwaffle-1.
 
     <para>
       <simplelist>
+        <member><citerefentry><refentrytitle>waffle_feature_test_macros</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+      </simplelist>
+    </para>
+
+    <para>
+      <simplelist>
         <member><citerefentry><refentrytitle>waffle_attrib_list</refentrytitle><manvolnum>3</manvolnum></citerefentry>,</member>
         <member><citerefentry><refentrytitle>waffle_config</refentrytitle><manvolnum>3</manvolnum></citerefentry>,</member>
         <member><citerefentry><refentrytitle>waffle_context</refentrytitle><manvolnum>3</manvolnum></citerefentry>,</member>
diff --git a/man/waffle_config.3.xml b/man/waffle_config.3.xml
index 46b0aa2..479a3ce 100644
--- a/man/waffle_config.3.xml
+++ b/man/waffle_config.3.xml
@@ -347,6 +347,10 @@ struct waffle_config;
         <term><constant>WAFFLE_CONTEXT_FORWARD_COMPATIBLE</constant></term>
         <listitem>
           <para>
+            Feature test macro: <code>WAFFLE_API_VERSION >= 0x0103</code>.
+            (See <citerefentry><refentrytitle>waffle_feature_test_macros</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+          </para>
+          <para>
             This attribute, if true, instructs
             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
             to create a forward-compatible context.
@@ -379,6 +383,10 @@ struct waffle_config;
         <term><constant>WAFFLE_CONTEXT_DEBUG</constant></term>
         <listitem>
           <para>
+            Feature test macro: <code>WAFFLE_API_VERSION >= 0x0103</code>.
+            (See <citerefentry><refentrytitle>waffle_feature_test_macros</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+          </para>
+          <para>
             This attribute, if true, instructs
             <citerefentry><refentrytitle><function>waffle_context_create</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
             to create a debug context.
diff --git a/man/waffle_feature_test_macros.7.xml b/man/waffle_feature_test_macros.7.xml
new file mode 100644
index 0000000..4e4298c
--- /dev/null
+++ b/man/waffle_feature_test_macros.7.xml
@@ -0,0 +1,104 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  Copyright Intel 2013
+
+  This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
+  US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
+-->
+
+<refentry
+    id="waffle_feature_test_macros"
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
+
+  <refmeta>
+    <refentrytitle>waffle_feature_test_macros</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>waffle_feature_test_macros</refname>
+    <refpurpose>Macros to control definitions exposed by Waffle's headers</refpurpose>
+  </refnamediv>
+
+  <refentryinfo>
+    <title>Waffle Manual</title>
+    <productname>waffle</productname>
+    <xi:include href="common/author-chad.versace.xml"/>
+    <xi:include href="common/copyright.xml"/>
+    <xi:include href="common/legalnotice.xml"/>
+  </refentryinfo>
+
+  <refsynopsisdiv>
+    <synopsis>
+<constant>WAFFLE_API_VERSION</constant>
+    </synopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      Waffle's feature test macros allow the programmer to control the definitions that are exposed by Waffle's headers
+      when a program is compiled.
+      
+      Conversely, the macros allow the programmer to control which Waffle features a program's source relies on.
+    </para>
+    <para>
+      In order to be effective, a feature test macro must be defined before including any header files.  This can be done
+      either in the compilation command (cc -DMACRO=value) or by defining the macro within the source code before including
+      any headers.
+    </para>
+    <refsect2>
+      <title>Specification of feature test macro requirements in manual pages</title>
+      <para>
+        When a function requires that a feature test macro be defined, the manual page docments it in the SYNOPSIS.
+
+        When an enum or macro requires that a feature test macro be defined, the manual page documents it either in the
+        SYNOPSIS or where the enum or macro first appears in the page.
+      </para>
+    </refsect2>
+    <refsect2>
+      <title>List of feature test macros</title>
+      <variablelist>
+        <varlistentry>
+          <term><constant>WAFFLE_API_VERSION</constant> (since waffle 1.3)</term>
+          <listitem>
+            <para>
+              This macro controls the API version exposed by Waffle's headers.
+
+              The value
+              <code>((<parameter>major</parameter> &lt;&lt; 8) | <parameter>minor</parameter>)</code>
+              exposes the API of
+              Waffle <parameter>major</parameter>.<parameter>minor</parameter>.
+
+              For example, the value 0x0103 exposes the API of Waffle 1.3.
+
+              If this macro is undefined, then the headers expose the API of Waffle 1.2.
+            </para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <simplelist>
+        <member><citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>,
+        <member><citerefentry><refentrytitle>feature_test_macros</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+      </simplelist>
+    </para>
+  </refsect1>
+
+</refentry>
+
+<!--
+vim:tw=120 et ts=2 sw=2:
+-->