docs: add long options to readprofile.8

Additionally align with with howto-man-page.txt

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

1 files changed, 66 insertions, 82 deletions

diff --git a/sys-utils/readprofile.8 b/sys-utils/readprofile.8
index a27043590..308dba498 100644
--- a/sys-utils/readprofile.8
+++ b/sys-utils/readprofile.8
@@ -1,105 +1,94 @@
-.TH READPROFILE "8" "May 1996" "util-linux" "System Administration"
+.TH READPROFILE "8" "October 2011" "util-linux" "System Administration"
 .SH NAME
 readprofile - read kernel profiling information
 .SH SYNOPSIS
 .B readprofile
 .RI [ options ]
-
 .SH VERSION
 This manpage documents version 2.0 of the program.
-
 .SH DESCRIPTION
-
 .LP
 The
 .B readprofile
 command uses the
 .B /proc/profile
-information to print ascii data on standard output.
-The output is
+information to print ascii data on standard output.  The output is
 organized in three columns: the first is the number of clock ticks,
-the second is the name of the C function in the kernel where those many
-ticks occurred, and the third is the normalized `load' of the procedure,
-calculated as a ratio between the number of ticks and the length of
-the procedure. The output is filled with blanks to ease readability.
-
-.LP
-Available command line options are the following:
-
+the second is the name of the C function in the kernel where those
+many ticks occurred, and the third is the normalized `load' of the
+procedure, calculated as a ratio between the number of ticks and the
+length of the procedure.  The output is filled with blanks to ease
+readability.
+.SH OPTIONS
 .TP
-.BI \-m " mapfile"
+\fB\-m\fR, \fB\-\-mapfile\fR \fImapfile\fR
 Specify a mapfile, which by default is
-.B /usr/src/linux/System.map.
-You should specify the map file on cmdline if your current kernel isn't the
-last one you compiled, or if you keep System.map elsewhere. If the name of
-the map file ends with `.gz' it is decompressed on the fly.
-
+.BR /usr/src/linux/System.map .
+You should specify the map file on cmdline if your current kernel
+isn't the last one you compiled, or if you keep System.map elsewhere.
+If the name of the map file ends with `.gz' it is decompressed on the
+fly.
 .TP
-.BI \-p " pro-file"
+\fB\-p\fR, \fB\-\-profile\fR \fIpro-file\fR
 Specify a different profiling buffer, which by default is
 .B /proc/profile.
 Using a different pro-file is useful if you want to `freeze' the
-kernel profiling at some time and read it later. The
+kernel profiling at some time and read it later.  The
 .B /proc/profile
-file can be copied using `cat' or `cp'. There is no more support for
+file can be copied using `cat' or `cp'.  There is no more support for
 compressed profile buffers, like in
 .B readprofile-1.1,
 because the program needs to know the size of the buffer in advance.
-
 .TP
-.B \-i
-Info. This makes
+\fB\-i\fR, \fB\-\-info\fR
+Info.  This makes
 .B readprofile
-only print the profiling step used by the kernel.
-The profiling step is the resolution of the profiling buffer, and
-is chosen during kernel configuration (through `make config'),
-or in the kernel's command line.
-If the
+only print the profiling step used by the kernel.  The profiling step
+is the resolution of the profiling buffer, and is chosen during
+kernel configuration (through `make config'), or in the kernel's
+command line.  If the
 .B \-t
 (terse) switch is used together with
 .B \-i
 only the decimal number is printed.
-
 .TP
-.B \-a
-Print all symbols in the mapfile. By default the procedures with 0 reported
-ticks are not printed.
-
+\fB\-a\fR, \fB\-\-all\fR
+Print all symbols in the mapfile.  By default the procedures with
+reported ticks are not printed.
 .TP
-.B \-b
+\fB\-b\fR, \fB\-\-histbin\fR
 Print individual histogram-bin counts.
-
 .TP
-.B \-r
-Reset the profiling buffer. This can only be invoked by root, because
+\fB\-r\fR, \fB\-\-reset\fR
+Reset the profiling buffer.  This can only be invoked by root,
+because
 .B /proc/profile
-is readable by everybody but writable only by the superuser. However,
-you can make
+is readable by everybody but writable only by the superuser.
+However, you can make
 .B readprofile
 setuid 0, in order to reset the buffer without gaining privileges.
-
 .TP
-.BI \-M " multiplier"
+\fB\-M\fR, \fB\-\-multiplier\fR \fImultiplier\fR
 On some architectures it is possible to alter the frequency at which
-the kernel delivers profiling interrupts to each CPU.  This option allows you to
-set the frequency, as a multiplier of the system clock frequency, HZ.
-This is supported on i386-SMP (2.2 and 2.4 kernel) and also on sparc-SMP
-and sparc64-SMP (2.4 kernel).  This option also resets the profiling buffer,
-and requires superuser privileges.
-
+the kernel delivers profiling interrupts to each CPU.  This option
+allows you to set the frequency, as a multiplier of the system clock
+frequency, HZ.  This is supported on i386-SMP (2.2 and 2.4 kernel)
+and also on sparc-SMP and sparc64-SMP (2.4 kernel).  This option also
+resets the profiling buffer, and requires superuser privileges.
 .TP
-.B \-v
-Verbose. The output is organized in four columns and filled with blanks.
-The first column is the RAM address of a kernel function, the second is
-the name of the function, the third is the number of clock ticks and the
-last is the normalized load.
-
+\fB\-v\fR, \fB\-\-verbose\fR
+Verbose.  The output is organized in four columns and filled with
+blanks.  The first column is the RAM address of a kernel function,
+the second is the name of the function, the third is the number of
+clock ticks and the last is the normalized load.
 .TP
-.B \-V
-Version. This makes
+\fB\-V\fR, \fB\-\-version\fR
+This makes
 .B readprofile
 print its version number and exit.
-
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display help and exit.
 .SH EXAMPLES
 Browse the profiling buffer ordering by clock ticks:
 .nf
@@ -116,7 +105,7 @@ Print only filesystem profile:
    readprofile | grep _ext2
 
 .fi
-Look at all the kernel information, with ram addresses"
+Look at all the kernel information, with ram addresses:
 .nf
    readprofile -av | less
 
@@ -126,43 +115,38 @@ Browse a `freezed' profile buffer for a non current kernel:
    readprofile -p ~/profile.freeze -m /zImage.map.gz
 
 .fi
-Request profiling at 2kHz per CPU, and reset the profiling buffer
+Request profiling at 2kHz per CPU, and reset the profiling buffer:
 .nf
    sudo readprofile -M 20
-
 .fi
-
 .SH BUGS
-
 .LP
 .B readprofile
-only works with an 1.3.x or newer kernel,
-because
+only works with an 1.3.x or newer kernel, because
 .B /proc/profile
 changed in the step from 1.2 to 1.3
-
 .LP
-This program only works with ELF kernels. The change for a.out kernels
-is trivial, and left as an exercise to the a.out user.
-
+This program only works with ELF kernels.  The change for a.out
+kernels is trivial, and left as an exercise to the a.out user.
 .LP
-To enable profiling, the kernel must be rebooted, because no profiling module
-is available, and it wouldn't be easy to build. To enable profiling,
-you can specify "profile=2" (or another number) on the kernel commandline.
-The number you specify is the two-exponent used as profiling step.
-
+To enable profiling, the kernel must be rebooted, because no
+profiling module is available, and it wouldn't be easy to build.  To
+enable profiling, you can specify "profile=2" (or another number) on
+the kernel commandline.  The number you specify is the two-exponent
+used as profiling step.
 .LP
-Profiling is disabled when interrupts are inhibited. This means that many
-profiling ticks happen when interrupts are re-enabled. Watch out for
-misleading information.
-
+Profiling is disabled when interrupts are inhibited.  This means that
+many profiling ticks happen when interrupts are re-enabled.  Watch
+out for misleading information.
 .SH FILES
 .nf
 /proc/profile              A binary snapshot of the profiling buffer.
 /usr/src/linux/System.map  The symbol table for the kernel.
 /usr/src/linux/*           The program being profiled :-)
 .fi
-
 .SH AVAILABILITY
-The readprofile command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+The readprofile command is part of the util-linux package and is
+available from
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .