[Ocfs2-tools-devel] [PATCH 5/9] o2image: Refresh manpage

[Sunil Mushran]

Rewrite o2image's manpage.

Signed-off-by: Sunil Mushran <sunil.mushran at oracle.com>
---
 o2image/o2image.8.in |   67 +++++++++++++++++++++++++------------------------
 1 files changed, 34 insertions(+), 33 deletions(-)

diff --git a/o2image/o2image.8.in b/o2image/o2image.8.in
index db699b5..5641b74 100644
--- a/o2image/o2image.8.in
+++ b/o2image/o2image.8.in
@@ -1,52 +1,53 @@
-.TH "o2image" "8" "July 2008" "Version @VERSION@" "OCFS2 Manual Pages"
+.TH "o2image" "8" "April 2009" "Version @VERSION@" "OCFS2 Manual Pages"
 .SH "NAME"
-o2image \- Save/Restore critical ocfs2 filesystem data to a file.
+o2image \- Copy or restore \fIOCFS2\fR file system meta-data
 .SH "SYNOPSIS"
-\fBo2image\fR [\fB\-r\fR] [\fB\-I\fR] [\fIdevice\fR] [\fIimage-file\fR]
+\fBo2image\fR [\fB\-r\fR] [\fB\-I\fR] \fIdevice\fR \fIimage-file\fR
 .SH "DESCRIPTION"
 .PP
-\fBo2image\fR is an OCFS2 tool that can save critical OCFS2 filesystem data
-located on a device to a specified image-file. The image-file may be examined
-using debugfs.ocfs2 to analyze filesystem layout affecting performance. Image-
-file may also be used to analyze and/or restore data in catastrophic corrupted
-filesystems.
-(NOTE: Data may only be restored if it is intact and metadata hasn't
-changed since it's backup)
+\fBo2image\fR copies the \fIOCFS2\fR file system meta-data from the device to the specified image-file.
+This image file contains the file system skeleton that includes the inodes, directory names
+and file names. It does \fBnot\fR include any file data.
 
-Image-file format can be either packed(default) or raw.
+This image file can be useful to debug certain problems that are not reproducible otherwise.
+Like on-disk corruptions. It could also be used to analyse the file system layout in an aging
+file system with an eye towards improving performance.
 
-Packed format contains o2image header, filesystem data, and bitmap.
+As the image-file contains a copy of all the meta-data blocks, it can be a large file.
+By default, it is created in a packed format, in which all meta-data blocks are written
+back-to-back. With the \fB\-r\fR option, the user could choose to have the file in the
+raw (or sparse) format, in which the blocks are written to the same offset as they are
+on the device.
 
-Raw format is a sparse file which stores metadata at the same offsets
-as on the device. Since the raw image file is created as sparse it does not
-use space for files data (NOTE: It is critical to store image file on a
-different filesystem which support sparsefile otherwise the image file uses
-the same amount of space as the device). An image file stores metadata
-blocks sequentially and consumes little less space.
+\fIdebugfs.ocfs2\fR understands both formats.
 
-The -I option will cause o2image to install the metadata from image-file on
-to the device. This can be used to restore the filesystem metadata back
-to the device in emergency situations.
+\fBo2image\fR also has the option, \fI\-I\fR, to restore the meta-data from the image
+file onto the device. This option will rarely be useful to end-users and has been written
+specifically for developers and testers.
 
 .SH "OPTIONS"
 .TP
 \fB\-r\fR
-Backups the \fIOCFS2\fR volumes metadata to an image-file in a raw format.
+Copies the meta-data to the image-file in the raw format. Use this option only if
+the destination file system supports sparse files. If unsure, do not use this option
+and let the tool create the image-file in the packed format.
 
 .TP
 \fB\-I\fR
-Restores \fIOCFS2\fR volumes metadata from image-file to the device.
+Restores meta-data from the image-file onto the device. \fBCAUTION: This option could
+corrupt the file system.\fR
 
 .SH "EXAMPLES"
-.br
-\	\fBo2image \-r /dev/sda1 sda1.raw\fR
-.br
-Copies metadata blocks from /dev/sda1 device to sda1.raw file
-.br
-\	\fBo2image -rI /dev/sda1 sda1.raw\fR
-.br
-Installs metadata structures from sda.image file onto the device.
-.br
+
+.TS
+;
+L.
+[root at node1 ~]# o2image /dev/sda1 sda1.out
+Copies metadata blocks from /dev/sda1 device to sda1.out file
+
+[root at node1 ~] o2image -I /dev/sda1 sda1.out
+\fBUse with CAUTION\fR. Copies meta-data blocks from sda1.out onto the /dev/sda1 device.
+.TE
 
 .SH "SEE ALSO"
 .BR debugfs.ocfs2(8)
@@ -56,4 +57,4 @@ Installs metadata structures from sda.image file onto the device.
 Oracle Corporation
 
 .SH "COPYRIGHT"
-Copyright \(co 2007, 2008 Oracle. All rights reserved.
+Copyright \(co 2007, 2009 Oracle. All rights reserved.
-- 
1.5.6.3