waffle utils: add wflinfo man page

v3:
 * Move description section up

Signed-off-by: Jordan Justen <jordan.l.justen@intel.com>
Signed-off-by: Chad Versace <chad.versace@linux.intel.com>

9 files changed, 211 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index 9d274bf..8bfa7cc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,6 +49,7 @@ Makefile
 /doc/html/man/waffle_wayland.3.html
 /doc/html/man/waffle_window.3.html
 /doc/html/man/waffle_x11_egl.3.html
+/doc/html/man/wflinfo.1.html
 /examples/gl_basic
 /examples/simple-x11-egl
 /lib/
diff --git a/doc/html/man/index.html b/doc/html/man/index.html
index 3167a8e..3d1b86e 100644
--- a/doc/html/man/index.html
+++ b/doc/html/man/index.html
@@ -65,6 +65,9 @@
       <li>
         <a href="waffle_x11_egl.3.html">waffle_x11_egl(3)</a>
       </li>
+      <li>
+        <a href="wflinfo.1.html">wflinfo(1)</a>
+      </li>
     </ul>
   </body>
 </html>
diff --git a/man/.gitignore b/man/.gitignore
index bb0ce59..840d33e 100644
--- a/man/.gitignore
+++ b/man/.gitignore
@@ -1,2 +1,3 @@
+man1/
 man3/
 man7/
diff --git a/man/common/author-jordan.l.justen.xml b/man/common/author-jordan.l.justen.xml
new file mode 100644
index 0000000..e2a422d
--- /dev/null
+++ b/man/common/author-jordan.l.justen.xml
@@ -0,0 +1,8 @@
+<?xml version='1.0'?>
+
+<author>
+  <firstname>Jordan</firstname>
+  <surname>Justen</surname>
+  <email>jordan.l.justen@intel.com</email>
+  <contrib>Contributor</contrib>
+</author>
diff --git a/man/html.cmake b/man/html.cmake
index 7005a71..6fd82b3 100644
--- a/man/html.cmake
+++ b/man/html.cmake
@@ -28,6 +28,7 @@ set(html_out_dir ${CMAKE_BINARY_DIR}/doc/html/man)
 file(MAKE_DIRECTORY ${html_out_dir})
 
 set(html_outputs
+    ${html_out_dir}/wflinfo.1.html
     ${html_out_dir}/waffle_attrib_list.3.html
     ${html_out_dir}/waffle_config.3.html
     ${html_out_dir}/waffle_context.3.html
@@ -65,6 +66,7 @@ function(waffle_add_html vol title)
         )
 endfunction()
 
+waffle_add_html(1 wflinfo)
 waffle_add_html(3 waffle_attrib_list)
 waffle_add_html(3 waffle_config)
 waffle_add_html(3 waffle_context)
diff --git a/man/html.xsl b/man/html.xsl
index 345bb2d..1c811bf 100644
--- a/man/html.xsl
+++ b/man/html.xsl
@@ -89,6 +89,14 @@
       </xsl:when>
 
       <!--
+       ! If a citation's title begins with "wflinfo", then link it with
+       ! href="wflinfo.$manvolnum.html".
+       !-->
+      <xsl:when test="starts-with(refentrytitle, 'wflinfo')">
+        <xsl:text>wflinfo.1.html</xsl:text>
+      </xsl:when>
+
+      <!--
        ! For citations that begin with "waffle" but were not matched above,
        ! we assume that the citation title is the refentrytitle of a
        ! manpage. Link with href="$refentrytitle.$manvolnum.html".
diff --git a/man/manpages.cmake b/man/manpages.cmake
index 402bbbc..f293275 100644
--- a/man/manpages.cmake
+++ b/man/manpages.cmake
@@ -25,10 +25,12 @@
 
 set(man_out_dir ${CMAKE_CURRENT_BINARY_DIR})
 
+file(MAKE_DIRECTORY ${man_out_dir}/man1)
 file(MAKE_DIRECTORY ${man_out_dir}/man3)
 file(MAKE_DIRECTORY ${man_out_dir}/man7)
 
 set(man_outputs
+    ${man_out_dir}/man1/wflinfo.1
     ${man_out_dir}/man3/waffle_attrib_list.3
     ${man_out_dir}/man3/waffle_config.3
     ${man_out_dir}/man3/waffle_context.3
@@ -64,6 +66,7 @@ function(waffle_add_manpage vol title)
         )
 endfunction()
 
+waffle_add_manpage(1 wflinfo)
 waffle_add_manpage(3 waffle_attrib_list)
 waffle_add_manpage(3 waffle_config)
 waffle_add_manpage(3 waffle_context)
@@ -89,6 +92,8 @@ add_custom_target(man
     DEPENDS ${man_outputs}
     )
 
+install(DIRECTORY ${man_out_dir}/man1
+        DESTINATION ${CMAKE_INSTALL_FULL_MANDIR})
 install(DIRECTORY ${man_out_dir}/man3
         DESTINATION ${CMAKE_INSTALL_FULL_MANDIR})
 install(DIRECTORY ${man_out_dir}/man7
diff --git a/man/waffle.7.xml b/man/waffle.7.xml
index ab116d5..d89c984 100644
--- a/man/waffle.7.xml
+++ b/man/waffle.7.xml
@@ -115,6 +115,7 @@ Link with -lwaffle-1.
         <member><citerefentry><refentrytitle>waffle_wayland</refentrytitle><manvolnum>3</manvolnum></citerefentry>,</member>
         <member><citerefentry><refentrytitle>waffle_window</refentrytitle><manvolnum>3</manvolnum></citerefentry>,</member>
         <member><citerefentry><refentrytitle>waffle_x11_egl</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+        <member><citerefentry><refentrytitle>wflinfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>,</member>
       </simplelist>
     </para>
   </refsect1>
diff --git a/man/wflinfo.1.xml b/man/wflinfo.1.xml
new file mode 100644
index 0000000..47776b9
--- /dev/null
+++ b/man/wflinfo.1.xml
@@ -0,0 +1,182 @@
+<?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 2012 - 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="wflinfo"
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
+
+  <refmeta>
+    <refentrytitle>wflinfo</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>wflinfo</refname>
+    <refpurpose>a utility for printing OpenGL or OpenGL ES driver information</refpurpose>
+  </refnamediv>
+
+  <refentryinfo>
+    <title>wflinfo Manual</title>
+    <productname>waffle</productname>
+    <xi:include href="common/author-chad.versace.xml"/>
+    <xi:include href="common/author-jordan.l.justen.xml"/>
+    <xi:include href="common/copyright.xml"/>
+    <xi:include href="common/legalnotice.xml"/>
+  </refentryinfo>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>wflinfo</command>
+      <arg choice="plain">
+        <option>--platform=<replaceable class="parameter">platform</replaceable></option>
+      </arg>
+      <arg choice="plain">
+        <option>--api=<replaceable class="parameter">api</replaceable></option>
+      </arg>
+      <arg choice="opt">
+        <option><replaceable class="parameter">OPTIONS</replaceable></option>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      wflinfo is utility which creates an OpenGL or OpenGL ES context using the waffle library and
+      prints information about the context.
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Required Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>--platform=<replaceable class="parameter">platform</replaceable></option></term>
+        <listitem>
+          <para>
+            Where platform is
+            <simplelist type="inline">
+              <?dbchoice choice="or"?>
+              <member>android</member>
+              <member>cgl</member>
+              <member>gbm</member>
+              <member>glx</member>
+              <member>wayland</member>
+              <member>x11_egl</member>
+            </simplelist>
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--api=<replaceable class="parameter">api</replaceable></option></term>
+        <listitem>
+          <para>
+            Where api is
+            <simplelist type="inline">
+              <?dbchoice choice="or"?>
+              <member>gl</member>
+              <member>gles1</member>
+              <member>gles2</member>
+              <member>gles3</member>
+            </simplelist>
+
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+      <varlistentry>
+        <term><option>--version=<replaceable class="parameter">MAJOR.MINOR</replaceable></option></term>
+        <listitem>
+          <para>
+            For example --api=gl --version=3.2 would request OpenGL 3.2
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--profile=<replaceable class="parameter">profile</replaceable></option></term>
+        <listitem>
+          <para>
+            Where profile is core, compat or none
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--verbose</option></term>
+        <listitem>
+          <para>
+            Print more information
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--forward-compatible</option></term>
+        <listitem>
+          <para>
+            Request a forward compatible context be created
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--debug-context</option></term>
+        <listitem>
+          <para>
+            Request a debug context be created
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <para>
+      <simplelist>
+        <member>wflinfo --platform=glx --api=gl</member>
+        <member>wflinfo --platform=x11_egl --api=gl --version=3.2 --profile=core</member>
+        <member>wflinfo --platform=wayland --api=gles3</member>
+      </simplelist>
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <simplelist>
+        <member>Website: http://people.freedesktop.org/~chadversary/waffle</member>
+        <member>Source: git://people.freedesktop.org/~chadversary/waffle.git</member>
+      </simplelist>
+    </para>
+
+    <para>
+      <simplelist>
+        <member><citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>,</member>
+      </simplelist>
+    </para>
+  </refsect1>
+
+</refentry>
+
+<!--
+vim:tw=120 et ts=2 sw=2:
+-->