man: rewrite manual pages in reStructuredText

intel_reg.rst was the first man page written in reStructuredText. Follow
suit with the rest of the man pages.

Add a generated defs.rst include file for definitions such as
intel-gpu-tools version. This replaces the MAN_SUBSTS sed script
substitutions from xorg-macros for old man pages.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

33 files changed, 733 insertions, 418 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index 69742403..e40e2e93 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,41 +1,39 @@
 appmandir = $(APP_MAN_DIR)
-appman_PRE = 				\
-	intel_aubdump.man		\
-	intel_audio_dump.man		\
-	intel_bios_dumper.man		\
-	intel_bios_reader.man		\
-	intel_error_decode.man		\
-	intel_gpu_frequency.man		\
-	intel_gpu_top.man		\
-	intel_gtt.man			\
-	intel_infoframes.man		\
-	intel_lid.man			\
-	intel_panel_fitter.man		\
-	intel_stepping.man		\
-	intel_upload_blit_large.man	\
-	intel_upload_blit_large_gtt.man \
-	intel_upload_blit_large_map.man \
-	intel_upload_blit_small.man
-
-appman_DATA = $(appman_PRE:man=$(APP_MAN_SUFFIX))
-
-# man pages in rst, only used if we have rst2man
-appman_RST =				\
-	intel_reg.rst
+appman_RST = 				\
+	intel_aubdump.rst		\
+	intel_audio_dump.rst		\
+	intel_bios_dumper.rst		\
+	intel_bios_reader.rst		\
+	intel_error_decode.rst		\
+	intel_gpu_frequency.rst		\
+	intel_gpu_top.rst		\
+	intel_gtt.rst			\
+	intel_infoframes.rst		\
+	intel_lid.rst			\
+	intel_panel_fitter.rst		\
+	intel_reg.rst			\
+	intel_stepping.rst		\
+	intel_upload_blit_large.rst	\
+	intel_upload_blit_large_gtt.rst \
+	intel_upload_blit_large_map.rst \
+	intel_upload_blit_small.rst
 
 if HAVE_RST2MAN
-appman_DATA += $(appman_RST:rst=$(APP_MAN_SUFFIX))
+appman_DATA = $(appman_RST:rst=$(APP_MAN_SUFFIX))
 endif
 
-EXTRA_DIST = $(appman_PRE) $(appman_RST)
-CLEANFILES = $(appman_DATA)
+EXTRA_DIST = $(appman_RST)
+CLEANFILES = $(appman_DATA) defs.rst
 
-# String replacements in MAN_SUBSTS now come from xorg-macros.m4 via configure
-SUFFIXES = .$(APP_MAN_SUFFIX) .man
+SUFFIXES = .$(APP_MAN_SUFFIX)
 
-.man.$(APP_MAN_SUFFIX):
-	$(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
+# create some definitions useful in the man page rst sources
+defs.rst:
+	$(AM_V_GEN)echo ".. |PACKAGE_NAME| replace:: $(PACKAGE_NAME)" > $@
+	$(AM_V_GEN)echo ".. |PACKAGE_VERSION| replace:: $(PACKAGE_VERSION)" >> $@
+	$(AM_V_GEN)echo ".. |PACKAGE_STRING| replace:: $(PACKAGE_STRING)" >> $@
+	$(AM_V_GEN)echo ".. |MANUAL_SECTION| replace:: 1" >> $@
+	$(AM_V_GEN)echo ".. |MANUAL_GROUP| replace:: General Commands Manual" >> $@
 
-# FIXME: handle MAN_SUBST in rst
-.rst.$(APP_MAN_SUFFIX):
+%.$(APP_MAN_SUFFIX): %.rst defs.rst
 	$(AM_V_GEN)rst2man < $< > $@
diff --git a/man/intel_aubdump.man b/man/intel_aubdump.man
deleted file mode 100644
index a77947e7..00000000
--- a/man/intel_aubdump.man
+++ /dev/null
@@ -1,38 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_aubdump __appmansuffix__ __xorgversion__
-.SH NAME
-intel_aubdump \- Launch an application and capture rendering to an AUB file
-.SH SYNOPSIS
-.B intel_aubdump [\fIOPTION\fR]... \fI--\fR \fICOMMAND\fR [\fIARGUMENTS\fR]
-.SH DESCRIPTION
-.PP
-Run
-.IR COMMAND
-with
-.IR ARGUMENTS
-and dump an AUB file that captures buffer
-contents and execution of the i915 GEM application.
-.TP
-.B \-v
-Enable verbose mode.
-.TP
-.B \-\^\-help
-Output a usage message and exit.
-.TP
-.BI \-o " FILE" "\fR,\fP \-\^\-output=" FILE
-Write the trace output to the file
-.IR FILE .
-Default is 
-.IR COMMAND .aub.
-.TP
-.BI \-\^\-device= ID
-Override the PCI ID of the drm device. This is useful for getting an
-aub dump for a different generation of GPU. In this mode intel_aubdump
-will intercept but not forward the execbuffer2 ioctl, as that would
-typically cause a GPU hang.
-.SH EXAMPLES
-.TP
-intel_aubdump -v --output=stuff.aub -- glxgears -geometry 500x500
-Launches glxgears with its -geometry option and enables aub dumping
-with the -v and --output=stuff.aub options.
diff --git a/man/intel_aubdump.rst b/man/intel_aubdump.rst
new file mode 100644
index 00000000..c6a51676
--- /dev/null
+++ b/man/intel_aubdump.rst
@@ -0,0 +1,55 @@
+=============
+intel_aubdump
+=============
+
+-----------------------------------------------------
+Launch an application and capture rendering to an AUB
+-----------------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2015-2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_aubdump** [*OPTIONS*] -- *COMMAND* [*ARGUMENTS*]
+
+DESCRIPTION
+===========
+
+Run COMMAND with ARGUMENTS and dump an AUB file that captures buffer contents
+and execution of the i915 GEM application.
+
+OPTIONS
+=======
+
+-v
+    Enable verbose mode.
+
+--help
+    Output a usage message and exit.
+
+-o FILE, --output=FILE
+    Write the trace output to the file FILE. Default is COMMAND.aub.
+
+--device=ID
+    Override the PCI ID of the drm device. This is useful for getting an aub
+    dump for a different generation of GPU. In this mode **intel_aubdump** will
+    intercept but not forward the execbuffer2 ioctl, as that would typically
+    cause a GPU hang.
+
+EXAMPLES
+========
+
+intel_aubdump -v --output=stuff.aub -- glxgears -geometry 500x500
+    Launches glxgears with its -geometry option and enables aub dumping with
+    the -v and --output=stuff.aub options.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_audio_dump.man b/man/intel_audio_dump.man
deleted file mode 100644
index 89a81ec4..00000000
--- a/man/intel_audio_dump.man
+++ /dev/null
@@ -1,11 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_audio_dump __appmansuffix__ __xorgversion__
-.SH NAME
-intel_audio_dump \- Dumps the Intel GPU registers for HDMI audio setup.
-.SH SYNOPSIS
-.B intel_audio_dump
-.SH DESCRIPTION
-.B intel_audio_dump
-dumps and decodes registers containing the configuration of HDMI audio
-handling on Intel GPUs.
diff --git a/man/intel_audio_dump.rst b/man/intel_audio_dump.rst
new file mode 100644
index 00000000..78bbae44
--- /dev/null
+++ b/man/intel_audio_dump.rst
@@ -0,0 +1,30 @@
+================
+intel_audio_dump
+================
+
+-------------------------------------------------
+Dump the Intel GPU registers for HDMI audio setup
+-------------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2010,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_audio_dump**
+
+DESCRIPTION
+===========
+
+**intel_audio_dump** dumps and decodes registers containing the configuration of
+HDMI audio handling on Intel GPUs.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_bios_dumper.man b/man/intel_bios_dumper.man
deleted file mode 100644
index c9acaa46..00000000
--- a/man/intel_bios_dumper.man
+++ /dev/null
@@ -1,14 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_bios_dumper __appmansuffix__ __xorgversion__
-.SH NAME
-intel_bios_dumper \- Saves the Intel video BIOS contents to a file.
-.SH SYNOPSIS
-.B intel_bios_dumper \fIfilename\fR
-.SH DESCRIPTION
-.B intel_bios_dumper
-is a tool to save the contents of the Intel video BIOS to a file.  It
-can then be parsed offline for debugging issues with the video bios
-table handling.
-.SH SEE ALSO
-.BR intel_bios_reader(1)
diff --git a/man/intel_bios_dumper.rst b/man/intel_bios_dumper.rst
new file mode 100644
index 00000000..89e0001a
--- /dev/null
+++ b/man/intel_bios_dumper.rst
@@ -0,0 +1,36 @@
+=================
+intel_bios_dumper
+=================
+
+--------------------------------------------
+Save the Intel video BIOS contents to a file
+--------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2010,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_bios_dumper** *FILENAME*
+
+DESCRIPTION
+===========
+
+**intel_bios_dumper** is a tool to save the contents of the Intel video BIOS to
+a file. It can then be parsed offline for debugging issues with the video bios
+table handling.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
+
+SEE ALSO
+========
+
+**intel_bios_reader(1)**
diff --git a/man/intel_bios_reader.man b/man/intel_bios_reader.man
deleted file mode 100644
index 2f125fc9..00000000
--- a/man/intel_bios_reader.man
+++ /dev/null
@@ -1,15 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_bios_reader __appmansuffix__ __xorgversion__
-.SH NAME
-intel_bios_reader \- Parses an Intel BIOS and displays many of its tables
-.SH SYNOPSIS
-.B intel_bios_reader \fIfilename\fR
-.SH DESCRIPTION
-.B intel_bios_reader
-is a tool to parse the contents of an Intel video BIOS file.  The file
-can come from intel_bios_dumper.  This can be used for quick debugging
-of video bios table handling, which is harder when done inside of the
-kernel graphics driver.
-.SH SEE ALSO
-.BR intel_bios_dumper (1)
diff --git a/man/intel_bios_reader.rst b/man/intel_bios_reader.rst
new file mode 100644
index 00000000..7024f4de
--- /dev/null
+++ b/man/intel_bios_reader.rst
@@ -0,0 +1,37 @@
+=================
+intel_bios_reader
+=================
+
+--------------------------------------------------
+Parse an Intel BIOS and display many of its tables
+--------------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2010,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_bios_reader** *FILENAME*
+
+DESCRIPTION
+===========
+
+**intel_bios_reader** is a tool to parse the contents of an Intel video BIOS
+file. The file can come from **intel_bios_dumper(1)**. This can be used for
+quick debugging of video bios table handling, which is harder when done inside
+of the kernel graphics driver.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
+
+SEE ALSO
+========
+
+**intel_bios_dumper(1)**
diff --git a/man/intel_error_decode.man b/man/intel_error_decode.man
deleted file mode 100644
index e53d898d..00000000
--- a/man/intel_error_decode.man
+++ /dev/null
@@ -1,20 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_error_decode __appmansuffix__ __xorgversion__
-.SH NAME
-intel_error_decode \- Decodes an Intel GPU dump automatically captured by the kernel at the time of an error.
-.SH SYNOPSIS
-.nf
-.B intel_error_decode
-.B intel_error_decode [ filename ]
-.fi
-.SH DESCRIPTION
-.B intel_error_decode
-is a tool that decodes the instructions and state of the GPU at the time of
-an error. It requires kernel 2.6.34 or newer, and either debugfs mounted on
-/sys/kernel/debug or /debug containing a current i915_error_state or you can
-pass a file containing a saved error.
-.SS Options
-.TP
-.B filename
-Decodes a previously saved error.
diff --git a/man/intel_error_decode.rst b/man/intel_error_decode.rst
new file mode 100644
index 00000000..e7a54a6f
--- /dev/null
+++ b/man/intel_error_decode.rst
@@ -0,0 +1,38 @@
+==================
+intel_error_decode
+==================
+
+-------------------------------------------------------------------------------------
+Decode an Intel GPU dump automatically captured by the kernel at the time of an error
+-------------------------------------------------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2010,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_error_decode** [*FILENAME*]
+
+DESCRIPTION
+===========
+
+**intel_error_decode** is a tool that decodes the instructions and state of the
+GPU at the time of an error. It requires kernel 2.6.34 or newer, and either
+debugfs mounted on /sys/kernel/debug or /debug containing a current
+i915_error_state or you can pass a file containing a saved error.
+
+ARGUMENTS
+=========
+
+FILENAME
+    Decodes a previously saved error.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_gpu_frequency.man b/man/intel_gpu_frequency.man
deleted file mode 100644
index 71448481..00000000
--- a/man/intel_gpu_frequency.man
+++ /dev/null
@@ -1,58 +0,0 @@
-.TH INTEL_FREQUENCY: "1" "January 2015" "intel_gpu_frequency" "User Commands"
-.SH NAME
-intel_gpu_frequency: \- manual page for intel_gpu_frequency
-.SH SYNOPSIS
-.B intel_gpu_frequency
-[\fI\,-e\/\fR] [\fI\,--min | --max\/\fR] [\fI\,-g\/\fR] [\fI\,-s frequency_mhz\/\fR]
-.SH DESCRIPTION
-\&A program to manipulate Intel GPU frequencies. Intel GPUs
-will automatically throttle the frequencies based on system demands, up when
-needed, down when not. This tool should only be used for debugging performance
-problems, or trying to get a stable frequency while benchmarking.
-
-Intel GPUs only accept specific frequencies. The tool may, or may not attempt to
-adjust requests to the proper frequency if they aren't correct. This may lead to
-non-obvious failures when setting frequency. Multiples of 50MHz is usually a
-safe bet.
-.SH OPTIONS
-.TP
-\fB\-e\fR
-Lock frequency to the most efficient frequency
-.TP
-\fB\-g\fR, \fB\-\-get\fR
-Get all the current frequency settings
-.TP
-\fB\-s\fR, \fB\-\-set\fR
-Lock frequency to an absolute value (MHz)
-.TP
-\fB\-c\fR, \fB\-\-custom\fR
-Set a min, or max frequency "min=X | max=Y"
-.TP
-\fB\-m\fR  \fB\-\-max\fR
-Lock frequency to max frequency
-.TP
-\fB\-i\fR  \fB\-\-min\fR
-Lock frequency to min (never a good idea, DEBUG ONLY)
-.TP
-\fB\-d\fR  \fB\-\-defaults\fR
-Return the system to hardware defaults
-.TP
-\fB\-h\fR  \fB\-\-help\fR
-Returns this
-.HP
-\fB\-v\fR  \fB\-\-version\fR Version
-.SH EXAMPLES
-.TP
-\fbintel_gpu_frequency \-gmin,cur\fR
-Get the current and minimum frequency
-.TP
-\fbintel_gpu_frequency \-s 400\fR
-Lock frequency to 400Mhz
-.TP
-\fbintel_gpu_frequency \-c max=750\fR
-Set the max frequency to 750MHz
-.PP
-.SH "REPORTING BUGS"
-Report bugs to https://bugs.freedesktop.org
-.SH COPYRIGHT
-Copyright (C) 2015 Intel Corporation
diff --git a/man/intel_gpu_frequency.rst b/man/intel_gpu_frequency.rst
new file mode 100644
index 00000000..e4de602c
--- /dev/null
+++ b/man/intel_gpu_frequency.rst
@@ -0,0 +1,79 @@
+===================
+intel_gpu_frequency
+===================
+
+--------------------------------
+Manipulate Intel GPU frequencies
+--------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2015-2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_gpu_frequency** [*OPTIONS*]
+
+DESCRIPTION
+===========
+
+A program to manipulate Intel GPU frequencies. Intel GPUs will automatically
+throttle the frequencies based on system demands, up when needed, down when
+not. This tool should only be used for debugging performance problems, or trying
+to get a stable frequency while benchmarking.
+
+Intel GPUs only accept specific frequencies. The tool may, or may not attempt to
+adjust requests to the proper frequency if they aren't correct. This may lead to
+non-obvious failures when setting frequency. Multiples of 50MHz is usually a
+safe bet.
+
+OPTIONS
+=======
+
+-e
+    Lock frequency to the most efficient frequency.
+
+-g, --get
+    Get all the current frequency settings.
+
+-s FREQUENCY, --set=FREQUENCY
+    Lock frequency to an absolute value (MHz).
+
+-c, --custom
+    Set a min, or max frequency "min=X | max=Y".
+
+-m, --max
+    Lock frequency to max frequency.
+
+-i, --min
+    Lock frequency to min (never a good idea, DEBUG ONLY).
+
+-d, --defaults
+    Return the system to hardware defaults.
+
+-h, --help
+    Show help.
+
+-v, --version
+    Show version.
+
+EXAMPLES
+========
+
+intel_gpu_frequency -gmin,cur
+    Get the current and minimum frequency.
+
+intel_gpu_frequency -s 400
+    Lock frequency to 400Mhz.
+
+intel_gpu_frequency -c max=750
+    Set the max frequency to 750MHz
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_gpu_top.man b/man/intel_gpu_top.man
deleted file mode 100644
index b307a238..00000000
--- a/man/intel_gpu_top.man
+++ /dev/null
@@ -1,41 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_gpu_top __appmansuffix__ __xorgversion__
-.SH NAME
-intel_gpu_top \- Display a top-like summary of Intel GPU usage
-.SH SYNOPSIS
-.nf
-.B intel_gpu_top
-.B intel_gpu_top [ parameters ]
-.SH DESCRIPTION
-.B intel_gpu_top
-is a tool to display usage information of an Intel GPU.  It requires root
-privilege to map the graphics device.
-.SS Options
-.TP
-.B -s [samples per second]
-number of samples to acquire per second
-.TP
-.B -o [output file]
-collect usage statistics to [file]. If file is "-", run non-interactively
-and output statistics to stdout.
-.TP
-.B -e ["command to profile"]
-execute a command, and leave when it is finished. Note that the entire command
-with all parameters should be included as one parameter.
-.TP
-.B -h
-show usage notes
-.SH EXAMPLES
-.TP
-intel_gpu_top -o "cairo-trace-gvim.log" -s 100 -e "cairo-perf-trace /tmp/gvim"
-will run cairo-perf-trace with /tmp/gvim trace, non-interactively, saving the
-statistics into cairo-trace-gvim.log file, and collecting 100 samples per
-second.
-.PP
-Note that idle units are not
-displayed, so an entirely idle GPU will only display the ring status and
-header.
-.SH BUGS
-Some GPUs report some units as busy when they aren't, such that even when
-idle and not hung, it will show up as 100% busy.
diff --git a/man/intel_gpu_top.rst b/man/intel_gpu_top.rst
new file mode 100644
index 00000000..c9030e1e
--- /dev/null
+++ b/man/intel_gpu_top.rst
@@ -0,0 +1,64 @@
+=============
+intel_gpu_top
+=============
+
+---------------------------------------------
+Display a top-like summary of Intel GPU usage
+---------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2009,2011,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_gpu_top** [*OPTIONS*]
+
+DESCRIPTION
+===========
+
+**intel_gpu_top** is a tool to display usage information of an Intel GPU. It
+requires root privilege to map the graphics device.
+
+OPTIONS
+=======
+
+-s SAMPLES
+    Number of samples to acquire per second.
+
+-o FILE
+    Collect usage statistics to FILE. If file is "-", run non-interactively
+    and output statistics to stdout.
+
+-e COMMAND
+    Execute COMMAND to profile, and leave when it is finished. Note that the
+    entire command with all parameters should be included as one parameter.
+
+-h
+    Show usage notes.
+
+EXAMPLES
+========
+
+intel_gpu_top -o "cairo-trace-gvim.log" -s 100 -e "cairo-perf-trace /tmp/gvim"
+    Run cairo-perf-trace with /tmp/gvim trace, non-interactively, saving the
+    statistics into cairo-trace-gvim.log file, and collecting 100 samples per
+    second.
+
+Note that idle units are not displayed, so an entirely idle GPU will only
+display the ring status and header.
+
+BUGS
+====
+
+Some GPUs report some units as busy when they aren't, such that even when idle
+and not hung, it will show up as 100% busy.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_gtt.man b/man/intel_gtt.man
deleted file mode 100644
index 8b23f287..00000000
--- a/man/intel_gtt.man
+++ /dev/null
@@ -1,14 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_gtt __appmansuffix__ __xorgversion__
-.SH NAME
-intel_gtt \- Dump the contents of an Intel GPU's GTT
-.SH SYNOPSIS
-.B intel_gtt
-.SH DESCRIPTION
-.B intel_gtt
-is a tool to view the contents of the GTT on an Intel GPU.  The GTT is
-the page table that maps between GPU addresses and system memory.
-This tool can be useful in debugging the Linux AGP driver
-initialization of the chip or in debugging later overwriting of the
-GTT with garbage data.
diff --git a/man/intel_gtt.rst b/man/intel_gtt.rst
new file mode 100644
index 00000000..d14184fa
--- /dev/null
+++ b/man/intel_gtt.rst
@@ -0,0 +1,32 @@
+=========
+intel_gtt
+=========
+
+---------------------------------------
+Dump the contents of an Intel GPU's GTT
+---------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2010,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_gtt**
+
+DESCRIPTION
+===========
+
+**intel_gtt** is a tool to view the contents of the GTT on an Intel GPU. The GTT
+is the page table that maps between GPU addresses and system memory. This tool
+can be useful in debugging the Linux AGP driver initialization of the chip or in
+debugging later overwriting of the GTT with garbage data.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_infoframes.man b/man/intel_infoframes.man
deleted file mode 100644
index b0159492..00000000
--- a/man/intel_infoframes.man
+++ /dev/null
@@ -1,26 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_infoframes __appmansuffix__ __xorgversion__
-.SH NAME
-intel_infoframes \- View and change HDMI InfoFrames
-.SH SYNOPSIS
-.B intel_infoframes
-.SH DESCRIPTION
-.B intel_infoframes
-is a tool to view and change the HDMI InfoFrames sent by the GPU. Its main
-purpose is to be used as a debugging tool. In some cases (e.g., when
-changing modes) the Kernel will undo the changes made by this tool.
-
-Descriptions of the InfoFrame fields can be found on the HDMI and CEA-861
-specifications.
-
-Use the
-.B -h
-or
-.B --help
-options to learn how to use the command
-.SH LIMITATIONS
-Not all HDMI monitors respect the InfoFrames sent to them. Only GEN 4
-or newer hardware is supported yet.
-.SH SEE ALSO
-HDMI specification, CEA-861 specification.
diff --git a/man/intel_infoframes.rst b/man/intel_infoframes.rst
new file mode 100644
index 00000000..70372333
--- /dev/null
+++ b/man/intel_infoframes.rst
@@ -0,0 +1,51 @@
+================
+intel_infoframes
+================
+
+-------------------------------
+View and change HDMI InfoFrames
+-------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_infoframes** [*OPTIONS*]
+
+DESCRIPTION
+===========
+
+**intel_infoframes** is a tool to view and change the HDMI InfoFrames sent by
+the GPU. Its main purpose is to be used as a debugging tool. In some cases
+(e.g., when changing modes) the Kernel will undo the changes made by this tool.
+
+Descriptions of the InfoFrame fields can be found on the HDMI and CEA-861
+specifications.
+
+OPTIONS
+=======
+
+-h, --help
+    Display comprehensive help on the tool.
+
+LIMITATIONS
+===========
+
+Not all HDMI monitors respect the InfoFrames sent to them. Only GEN 4 or newer
+hardware is supported yet.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
+
+SEE ALSO
+========
+
+HDMI specification, CEA-861 specification.
diff --git a/man/intel_lid.man b/man/intel_lid.man
deleted file mode 100644
index fd554e8d..00000000
--- a/man/intel_lid.man
+++ /dev/null
@@ -1,12 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_lid __appmansuffix__ __xorgversion__
-.SH NAME
-intel_lid \- Polls the values of different reports about laptop lid state.
-.SH SYNOPSIS
-.B intel_lid
-.SH DESCRIPTION
-.B intel_lid
-is a tool to poll ACPI and the BIOS scratch register's reporting of
-laptop lid state.  This can be used for debugging issues with laptop
-modesetting for lid opening and closing.
diff --git a/man/intel_lid.rst b/man/intel_lid.rst
new file mode 100644
index 00000000..8b7fd3fc
--- /dev/null
+++ b/man/intel_lid.rst
@@ -0,0 +1,31 @@
+=========
+intel_lid
+=========
+
+-----------------------------------------------------------
+Poll the values of different reports about laptop lid state
+-----------------------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2010,2012-2013,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_lid**
+
+DESCRIPTION
+===========
+
+**intel_lid** is a tool to poll ACPI and the BIOS scratch register's reporting
+of laptop lid state. This can be used for debugging issues with laptop
+modesetting for lid opening and closing.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_panel_fitter.man b/man/intel_panel_fitter.man
deleted file mode 100644
index 9a46a2ed..00000000
--- a/man/intel_panel_fitter.man
+++ /dev/null
@@ -1,50 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_panel_fitter __appmansuffix__ __xorgversion__
-.SH NAME
-intel_panel_fitter \- Change the panel fitter settings
-.SH SYNOPSIS
-.B intel_panel_fitter [options]
-.SH DESCRIPTION
-.B intel_panel_fitter
-is a tool that allows you to change the panel fitter settings, so you can change
-the size of the screen being displayed on your monitor without changing the real
-pixel size of your desktop. The biggest use case for this tool is to work around
-overscan done by TVs and some monitors in interlaced mode.
-.SS Options
-.TP
-.B -p [pipe]
-pipe to be used (A, B or C, but C is only present on Ivy Bridge and newer).
-.TP
-.B -x [value]
-final screen width size in pixels (needs -p option).
-.TP
-.B -y [value]
-final screen height size in pixels (needs -p option).
-.TP
-.B -d
-disable panel fitter (needs -p option, ignores -x and -y options).
-.TP
-.B -l
-list current state of each pipe.
-.TP
-.B -h
-prints the help message.
-.SS
-
-.SH EXAMPLES
-.TP
-.B intel_panel_fitter -l
-will list the current status of each pipe, so you can decide what to do.
-.TP
-.B intel_panel_fitter -p A -x 1850 -y 1040
-will change the pipe A size to 1850x1040 pixels.
-.TP
-.B intel_panel_fitter -p A -d
-will disable the panel fitter for pipe A.
-
-.SH NOTES
-In the future, there will be support for this feature inside the Linux Kernel.
-
-Machines older than Ironlake are still not supported, but support may be
-possible to implement.
diff --git a/man/intel_panel_fitter.rst b/man/intel_panel_fitter.rst
new file mode 100644
index 00000000..d2af0d87
--- /dev/null
+++ b/man/intel_panel_fitter.rst
@@ -0,0 +1,77 @@
+==================
+intel_panel_fitter
+==================
+
+--------------------------------
+Change the panel fitter settings
+--------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_panel_fitter** [*OPTIONS*]
+
+DESCRIPTION
+===========
+
+**intel_panel_fitter** is a tool that allows you to change the panel fitter
+settings, so you can change the size of the screen being displayed on your
+monitor without changing the real pixel size of your desktop. The biggest use
+case for this tool is to work around overscan done by TVs and some monitors in
+interlaced mode.
+
+OPTIONS
+=======
+
+-p PIPE
+    Pipe to be used (A, B or C, but C is only present on Ivy Bridge and newer).
+
+-x WIDTH
+    Final screen width size in pixels (needs -p option).
+
+-y HEIGHT
+    Final screen height size in pixels (needs -p option).
+
+-d
+    Disable panel fitter (needs -p option, ignores -x and -y options).
+
+-l
+    List current state of each pipe.
+
+-h
+    Print the help message.
+
+EXAMPLES
+========
+
+intel_panel_fitter -l
+    List the current status of each pipe, so you can decide what to do.
+
+intel_panel_fitter -p A -x 1850 -y 1040
+    Change the pipe A size to 1850x1040 pixels.
+
+intel_panel_fitter -p A -d
+    Disable the panel fitter for pipe A.
+
+NOTES
+=====
+
+In the future, there will be support for this feature inside the Linux Kernel.
+
+LIMITATIONS
+===========
+
+Machines older than Ironlake are still not supported, but support may be
+possible to implement.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_stepping.man b/man/intel_stepping.man
deleted file mode 100644
index fe172107..00000000
--- a/man/intel_stepping.man
+++ /dev/null
@@ -1,15 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_stepping __appmansuffix__ __xorgversion__
-.SH NAME
-intel_stepping \- Display the stepping information for an Intel GPU
-.SH SYNOPSIS
-.B intel_stepping
-.SH DESCRIPTION
-.B intel_stepping
-is a tool to print the stepping information for an Intel GPU, along with
-the PCI ID and revision used to determine it.
-It requires root privilege to map the graphics device.
-.SH BUGS
-Not all the known stepping IDs or chipsets are included, so the output
-on some devices may not be as specific as possible.
diff --git a/man/intel_stepping.rst b/man/intel_stepping.rst
new file mode 100644
index 00000000..9ea7c198
--- /dev/null
+++ b/man/intel_stepping.rst
@@ -0,0 +1,37 @@
+==============
+intel_stepping
+==============
+
+-------------------------------------------------
+Display the stepping information for an Intel GPU
+-------------------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2009,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_stepping**
+
+DESCRIPTION
+===========
+
+**intel_stepping** is a tool to print the stepping information for an Intel GPU,
+along with the PCI ID and revision used to determine it. It requires root
+privilege to map the graphics device.
+
+BUGS
+====
+
+Not all the known stepping IDs or chipsets are included, so the output on some
+devices may not be as specific as possible.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_upload_blit_large.man b/man/intel_upload_blit_large.man
deleted file mode 100644
index 9c75e1a1..00000000
--- a/man/intel_upload_blit_large.man
+++ /dev/null
@@ -1,18 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_upload_blit_large __appmansuffix__ __xorgversion__
-.SH NAME
-intel_upload_blit_large \- microbenchmark of Intel GPU performance
-.SH SYNOPSIS
-.nf
-.B intel_upload_blit_large
-.fi
-.SH DESCRIPTION
-.B intel_upload_blit_large
-is a microbenchmark tool for DRM performance.  It should be run with kernel
-modesetting enabled, and may require root privilege for correct operation.
-It does not require X to be running.
-.PP
-Given that it is a microbenchmark, its utility is largely for regression
-testing of the kernel, and not for general conclusions on graphics
-performance.
diff --git a/man/intel_upload_blit_large.rst b/man/intel_upload_blit_large.rst
new file mode 100644
index 00000000..dc06d701
--- /dev/null
+++ b/man/intel_upload_blit_large.rst
@@ -0,0 +1,34 @@
+=======================
+intel_upload_blit_large
+=======================
+
+---------------------------------------
+Microbenchmark of Intel GPU performance
+---------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2009,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_upload_blit_large**
+
+DESCRIPTION
+===========
+
+**intel_upload_blit_large** is a microbenchmark tool for DRM performance. It
+should be run with kernel modesetting enabled, and may require root privilege
+for correct operation. It does not require X to be running.
+
+Given that it is a microbenchmark, its utility is largely for regression testing
+of the kernel, and not for general conclusions on graphics performance.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_upload_blit_large_gtt.man b/man/intel_upload_blit_large_gtt.man
deleted file mode 100644
index fbe4623c..00000000
--- a/man/intel_upload_blit_large_gtt.man
+++ /dev/null
@@ -1,18 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_upload_blit_large_gtt __appmansuffix__ __xorgversion__
-.SH NAME
-intel_upload_blit_large_gtt \- microbenchmark of Intel GPU performance
-.SH SYNOPSIS
-.nf
-.B intel_upload_blit_large_gtt
-.fi
-.SH DESCRIPTION
-.B intel_upload_blit_large_gtt
-is a microbenchmark tool for DRM performance.  It should be run with kernel
-modesetting enabled, and may require root privilege for correct operation.
-It does not require X to be running.
-.PP
-Given that it is a microbenchmark, its utility is largely for regression
-testing of the kernel, and not for general conclusions on graphics
-performance.
diff --git a/man/intel_upload_blit_large_gtt.rst b/man/intel_upload_blit_large_gtt.rst
new file mode 100644
index 00000000..331eb8dd
--- /dev/null
+++ b/man/intel_upload_blit_large_gtt.rst
@@ -0,0 +1,34 @@
+===========================
+intel_upload_blit_large_gtt
+===========================
+
+---------------------------------------
+Microbenchmark of Intel GPU performance
+---------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2009,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_upload_blit_large_gtt**
+
+DESCRIPTION
+===========
+
+**intel_upload_blit_large_gtt** is a microbenchmark tool for DRM performance.
+It should be run with kernel modesetting enabled, and may require root privilege
+for correct operation. It does not require X to be running.
+
+Given that it is a microbenchmark, its utility is largely for regression testing
+of the kernel, and not for general conclusions on graphics performance.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_upload_blit_large_map.man b/man/intel_upload_blit_large_map.man
deleted file mode 100644
index 04123f3d..00000000
--- a/man/intel_upload_blit_large_map.man
+++ /dev/null
@@ -1,18 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_upload_blit_large_map __appmansuffix__ __xorgversion__
-.SH NAME
-intel_upload_blit_large_map \- microbenchmark of Intel GPU performance
-.SH SYNOPSIS
-.nf
-.B intel_upload_blit_large_map
-.fi
-.SH DESCRIPTION
-.B intel_upload_blit_large_map
-is a microbenchmark tool for DRM performance.  It should be run with kernel
-modesetting enabled, and may require root privilege for correct operation.
-It does not require X to be running.
-.PP
-Given that it is a microbenchmark, its utility is largely for regression
-testing of the kernel, and not for general conclusions on graphics
-performance.
diff --git a/man/intel_upload_blit_large_map.rst b/man/intel_upload_blit_large_map.rst
new file mode 100644
index 00000000..32beb414
--- /dev/null
+++ b/man/intel_upload_blit_large_map.rst
@@ -0,0 +1,34 @@
+===========================
+intel_upload_blit_large_map
+===========================
+
+---------------------------------------
+Microbenchmark of Intel GPU performance
+---------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2009,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_upload_blit_large_map**
+
+DESCRIPTION
+===========
+
+**intel_upload_blit_large_map** is a microbenchmark tool for DRM performance.
+It should be run with kernel modesetting enabled, and may require root privilege
+for correct operation. It does not require X to be running.
+
+Given that it is a microbenchmark, its utility is largely for regression testing
+of the kernel, and not for general conclusions on graphics performance.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.
diff --git a/man/intel_upload_blit_small.man b/man/intel_upload_blit_small.man
deleted file mode 100644
index 478bbfc5..00000000
--- a/man/intel_upload_blit_small.man
+++ /dev/null
@@ -1,18 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH intel_upload_blit_small __appmansuffix__ __xorgversion__
-.SH NAME
-intel_upload_blit_small \- microbenchmark of Intel GPU performance
-.SH SYNOPSIS
-.nf
-.B intel_upload_blit_small
-.fi
-.SH DESCRIPTION
-.B intel_upload_blit_small
-is a microbenchmark tool for DRM performance.  It should be run with kernel
-modesetting enabled, and may require root privilege for correct operation.
-It does not require X to be running.
-.PP
-Given that it is a microbenchmark, its utility is largely for regression
-testing of the kernel, and not for general conclusions on graphics
-performance.
diff --git a/man/intel_upload_blit_small.rst b/man/intel_upload_blit_small.rst
new file mode 100644
index 00000000..2a8d80de
--- /dev/null
+++ b/man/intel_upload_blit_small.rst
@@ -0,0 +1,34 @@
+=======================
+intel_upload_blit_small
+=======================
+
+---------------------------------------
+Microbenchmark of Intel GPU performance
+---------------------------------------
+.. include:: defs.rst
+:Author: Intel Graphics for Linux <intel-gfx@lists.freedesktop.org>
+:Date: 2016-03-01
+:Version: |PACKAGE_STRING|
+:Copyright: 2009,2012,2016 Intel Corporation
+:Manual section: |MANUAL_SECTION|
+:Manual group: |MANUAL_GROUP|
+
+SYNOPSIS
+========
+
+**intel_upload_blit_small**
+
+DESCRIPTION
+===========
+
+**intel_upload_blit_small** is a microbenchmark tool for DRM performance. It
+should be run with kernel modesetting enabled, and may require root privilege
+for correct operation. It does not require X to be running.
+
+Given that it is a microbenchmark, its utility is largely for regression testing
+of the kernel, and not for general conclusions on graphics performance.
+
+REPORTING BUGS
+==============
+
+Report bugs to https://bugs.freedesktop.org.