[PATCH] Flesh out oparchive procedure and fix other minor doc errors

Flesh out oparchive procedure and fix other minor doc errors

The oparchive man page does not do a very good job of documenting
how oparchive is intended to be used.  This patch addresses that
issue, in particular by directing the reader to the user manual
where there is much more detail to be found.

Additionally, this patch makes a few other minor doc fixups,
such as fixing an example shell script in the chapter on opimport
(a comment line did not have a "#" at the beginning of the line)
and removing a reference to qt stuff in the user manual. The patch
also cleans up the oprofile man page, updating it to reflect the
change from opcontrol operf.

Signed-off-by: Maynard Johnson <[email protected]>
---
 doc/oparchive.1.in |   24 ++++++++++++++++++------
 doc/oprofile.1.in  |   51 ++++++++++++++++++++++++++++++++++++---------------
 doc/oprofile.xml   |   24 ++++++++++++++++--------
 3 files changed, 70 insertions(+), 29 deletions(-)

diff --git a/doc/oparchive.1.in b/doc/oparchive.1.in
index 753d6d5..b188654 100644
--- a/doc/oparchive.1.in
+++ b/doc/oparchive.1.in
@@ -13,12 +13,21 @@ oparchive \- produce archive of oprofile data for offline analysis
 [directory]
 .SH DESCRIPTION
 
+The
 .B oparchive
-generates a directory populated with executable, debug, and oprofile sample
-files. This directory can be move to another machine via tar and analyzed
-without further use of the data collection machine. See oprofile(1) for how
-to write profile specifications.
-
+utility is commonly used for collecting profile data on a "target"
+system for future offline analysis on a different ("host") machine.
+.B oparchive
+creates a directory populated with executables, libraries, debuginfo files, and oprofile sample
+files. This directory can be tar'ed up and moved to another machine to be analyzed
+without further use of the target machine. Using
+.BI opreport
+and other post-profiling tools against archived data requires the use of the
+.I archive:<archived-dir>
+specification. See oprofile(1) for how to write profile specifications.
+A complete description of offline analysis can be found in the chapter titled
+.I Analyzing profile data on another system (oparchive)
+of the OProfile user manual. (See the user manual URL in the "SEE ALSO" section below.)
 .SH OPTIONS
 .TP
 .BI "--help / -? / --usage"
@@ -79,5 +88,8 @@ The location of the generated sample files.
 This man page is current for @PACKAGE@-@VERSION@.
 
 .SH SEE ALSO
-.BR @OP_DOCDIR@,
+.BR file://@[email protected]#oparchive
+.br
+.BR opimport(1)
+.br
 .BR oprofile(1)
diff --git a/doc/oprofile.1.in b/doc/oprofile.1.in
index 550954a..c477843 100644
--- a/doc/oprofile.1.in
+++ b/doc/oprofile.1.in
@@ -1,9 +1,21 @@
 .TH OPROFILE 1 "@DATE@" "oprofile @VERSION@"
 .UC 4
 .SH NAME
-oprofile \- a system-wide profiler
+oprofile \- a statistical profiler for Linux systems, capable of profiling all running code
+at low overhead; also included is a set of post-profiling analysis tools, as well as a simple
+event counting tool
 .SH SYNOPSIS
 .br
+.B operf
+[
+.I options
+]
+.br
+.B ocount
+[
+.I options
+]
+.br
 .B opreport
 [
 .I options
@@ -30,16 +42,21 @@ oprofile \- a system-wide profiler
 .br
 .SH DESCRIPTION
 OProfile is a profiling system for systems running Linux
-2.6 and greater. Profiling runs transparently in the background and profile
-data can be collected at any time. OProfile makes use of the hardware
-performance counters provided on Intel, AMD, and other processors,
-and uses a timer-interrupt based mechanism on CPUs without counters.
-OProfile can profile the whole system in high detail.
+2.6.31 and greater. OProfile makes use of the hardware
+performance counters provided on Intel, AMD, and other processors.
+OProfile can profile a selected program or process or the whole system.
+OProfile can also be used to collect cumulative event counts at the
+application, process, or system level.
 .br
 For a gentle guide to using OProfile, please read the HTML documentation
 listed in SEE ALSO.
 .br
-.SH OPCONTROL
+.SH OPERF
+.B operf
+is a performance profiler tool for Linux.
+.SH OCOUNT
+.B ocount
+is an event counting tool for Linux.
 .SH OPREPORT
 .B opreport
 gives image and symbol-based profile summaries for the whole system or
@@ -55,14 +72,16 @@ produces oprofile archive for offline analysis
 can produce a gprof-format profile for a single binary.
 
 .SH PROFILE SPECIFICATIONS
-All of the post-profiling tools can take profile specifications,
-which is some combination of the following parameters. Enclosing
-part of a profile specification in curly braces { } can be used
+Various optional profile specifications may be used with the
+post-profiling tools. A profile specification is some combination of the parameters
+listed below. (
+.BR Note :
+Enclosing part of a profile specification in curly braces { } can be used
 for differential profiles with
-.B opreport
-; the braces
+.BR opreport ,
+but the braces
 .B must
-be surrounded by whitespace.
+be surrounded by whitespace.)
 
 .TP
 .BI "archive:"archive
@@ -83,7 +102,7 @@ A comma-separated list of sessions to exclude.
 .BI "image:"imagelist
 A comma-separated list of image names to resolve. Each entry may be relative
 path, glob-style name, or full path, e.g.
-opreport 'image:/usr/bin/oprofiled,*op*,./oprofpp'
+opreport 'image:/usr/bin/operf,*op*,./oprofpp'
 .br
 .TP
 .BI "image-exclude:"imagelist
@@ -135,7 +154,7 @@ tgid: to restrict the results to particular threads within a process.
 This is only useful when using per-process profile separation.
 
 .SH ENVIRONMENT
-No special environment variables are recognized by oprofile.
+No special environment variables are recognized by OProfile.
 
 .SH FILES
 .TP
@@ -163,6 +182,8 @@ This man page is current for @PACKAGE@-@VERSION@.
 
 .SH SEE ALSO
 .BR @OP_DOCDIR@,
+.BR operf(1),
+.BR ocount(1),
 .BR opreport(1),
 .BR opannotate(1),
 .BR oparchive(1),
diff --git a/doc/oprofile.xml b/doc/oprofile.xml
index 01cd309..325ef6f 100644
--- a/doc/oprofile.xml
+++ b/doc/oprofile.xml
@@ -310,13 +310,6 @@ is often all you need, but note these arguments to <command>./configure</command
 			</note> 
 		</listitem>
 	</varlistentry>
-	<varlistentry>
-		<term><option>--with-qt-dir/includes/libraries</option></term>
-		<listitem><para>
-			Specify the location of Qt headers and libraries. It defaults to searching in
-			<constant>$QTDIR</constant> if these are not specified.
-		</para></listitem>
-	</varlistentry>
 	<varlistentry id="disable-werror">
 		<term><option>--disable-werror</option></term>
 		<listitem><para>
@@ -2187,7 +2180,7 @@ Show version.
     from the target system.
 <screen>
 #!/bin/bash
-Usage: my-import.sh &lt;input-abi-pathname&gt;
+#Usage: my-import.sh &lt;foreign-abi-fullpathname&gt;
 
 # NOTE: Start from the "samples" directory containing the "current" directory
 # to be imported
@@ -2207,6 +2200,21 @@ $cd profile1/var/lib/oprofile/samples
 $my-import.sh `pwd`/../abi
 </screen>
 </para>
+<para>
+If the OProfile ABI is truly different on host and target machines, then the end result of running the
+above script will place the converted (i.e., imported) files into the <filename>current-imported</filename>
+directory.  By default, <command>opreport</command> and other post-profiling tools will look for samples
+in <filename>samples/current</filename> of the specified session directory.  So you should either rename
+<filename>current-imported</filename> to <filename>current</filename> or specify the session specification of
+<command>session:current-imported</command> when running post-profiling tools.
+</para>
+<para>
+If the OProfile ABI is the same on the host and target machines, the <command>my-import.sh</command> script
+will print the following message for each sample file:
+<screen>
+input abi is identical to native. no conversion necessary.
+</screen>
+</para>
 <sect2 id="opimport-details">
 <title>Usage of <command>opimport</command></title>
 
-- 
1.7.1


------------------------------------------------------------------------------