Improve man pages.

4 files changed, 86 insertions, 34 deletions

diff --git a/doc/glmark2-es2.1 b/doc/glmark2-es2.1
deleted file mode 100644
index 253b5e3..0000000
--- a/doc/glmark2-es2.1
+++ /dev/null
@@ -1,15 +0,0 @@
-.TH GLMARK2-ES2 1 "2010-07-15"
-.SH NAME
-glmark2(-es2) \- OpenGL (ES) 2.0 benchmark
-.SH SYNOPSIS
-.B glmark2
-.br
-.B glmark2-es2
-.SH DESCRIPTION
-\fBglmark2(-es2)\fP is a benchmark for OpenGL (ES) 2.0. It only uses the subset of
-the OpenGL 2.0 API that is compatible with OpenGL ES 2.0.
-.SH AUTHOR
-glmark2 was written by Alexandros Frantzis based on the original glmark by Ben Smith.
-.PP
-This manual page was written by Alexandros Frantzis <alexandros.frantzis@linaro.org>,
-for the Debian project (and may be used by others).
diff --git a/doc/glmark2.1 b/doc/glmark2.1
deleted file mode 100644
index 4cf44b5..0000000
--- a/doc/glmark2.1
+++ /dev/null
@@ -1,15 +0,0 @@
-.TH GLMARK2 1 "2010-07-15"
-.SH NAME
-glmark2(-es2) \- OpenGL (ES) 2.0 benchmark
-.SH SYNOPSIS
-.B glmark2
-.br
-.B glmark2-es2
-.SH DESCRIPTION
-\fBglmark2(-es2)\fP is a benchmark for OpenGL (ES) 2.0. It only uses the subset of
-the OpenGL 2.0 API that is compatible with OpenGL ES 2.0.
-.SH AUTHOR
-glmark2 was written by Alexandros Frantzis based on the original glmark by Ben Smith.
-.PP
-This manual page was written by Alexandros Frantzis <alexandros.frantzis@linaro.org>,
-for the Debian project (and may be used by others).
diff --git a/doc/glmark2.1.in b/doc/glmark2.1.in
new file mode 100644
index 0000000..611ad30
--- /dev/null
+++ b/doc/glmark2.1.in
@@ -0,0 +1,70 @@
+.TH @APPNAME@ "1" "June 2011" "@appname@ 11.06"
+.SH NAME
+@appname@ \- OpenGL (ES) 2.0 benchmark suite
+.SH SYNOPSIS
+.B @appname@ [options]
+.SH DESCRIPTION
+\fB@appname@\fP is a benchmark for OpenGL (ES) 2.0. It only uses the subset of
+the OpenGL 2.0 API that is compatible with OpenGL ES 2.0.
+.SH OPTIONS
+.TP
+\fB\-b\fR, \fB\-\-benchmark\fR BENCH
+A benchmark to run: 'scene(:opt1=val1)*'
+(the option can be used multiple times)
+.TP
+\fB\-\-validate\fR
+Run a quick output validation test instead of
+running the benchmarks
+.TP
+\fB\-\-no\-swap\-buffers\fR
+Don't update the screen by swapping the front and
+back buffer, use glFinish() instead
+.TP
+\fB\-l\fR, \fB\-\-list\-scenes\fR
+Display information about the available scenes
+and their options
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+Display debug messages
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display help
+.SH BENCHMARKS
+@appname@ offers a suite of scenes that can be used to measure many aspects
+of OpenGL (ES) 2.0 performance. The way in which each scene is rendered is
+configurable through a set of options. To get the available scenes and their
+acceptable options you can use the \fB\-l\fR, \fB\-\-list\-scenes\fR command
+line option.
+
+In @appname@, a benchmark is defined as a scene plus a set of option values.
+You can specify the list and order of the benchmarks to run by using the
+\fB\-b\fR, \fB\-\-benchmark\fR command line option (possibly multiple times).
+If no benchmarks are specified, a default set of benchmarks is used. If a
+benchmark option is not specified it assumes its default value (listed with
+\fB\-l\fR, \fB\-\-list\-scenes\fR).
+
+.SH EXAMPLES
+To run the default benchmarks:
+.PP
+.RS
+\fB@appname@\fR
+.RE
+.PP
+To run a benchmark using scene 'shading' with a 'duration' of '5.0' seconds and
+ 'shading' of type 'phong':
+.PP
+.RS
+\fB@appname@ -b shading:duration=5.0:shading=phong\fR
+.RE
+.PP
+To run a series of benchmarks use the \fB\-b\fR, \fB\-\-benchmark\fR command
+line option multiple times:
+.PP
+.RS
+\fB@appname@ -b shading:duration=5.0 -b build:use-vbo=false -b texture\fR
+.RE
+.PP
+
+.SH AUTHOR
+@appname@ was written by Alexandros Frantzis based on the original glmark by
+Ben Smith.
diff --git a/doc/wscript_build b/doc/wscript_build
index c11ebe0..e204ae5 100644
--- a/doc/wscript_build
+++ b/doc/wscript_build
@@ -1,7 +1,19 @@
 if bld.env.USE_GL:
-    bld.install_files('${PREFIX}/share/man/man1',
-                      bld.path.ant_glob('glmark2.1'))
+    bld(
+        features = 'subst',
+        source = 'glmark2.1.in',
+        target = bld.path.find_or_declare('glmark2.1'),
+        APPNAME = 'GLMARK2',
+        appname = 'glmark2',
+        install_path = '${PREFIX}/share/man/man1'
+    )
 
 if bld.env.USE_GLESv2:
-    bld.install_files('${PREFIX}/share/man/man1',
-                      bld.path.ant_glob('glmark2-es2.1'))
+    bld(
+        features = 'subst',
+        source = 'glmark2.1.in',
+        target = bld.path.find_or_declare('glmark2-es2.1'),
+        APPNAME = 'GLMARK2-ES2',
+        appname = 'glmark2-es2',
+        install_path = '${PREFIX}/share/man/man1'
+    )