From: Sami Kerola <kerolasa@iki.fi>
Date: Sat, 11 Jun 2011 21:42:45 +0000 (+0200)
Subject: docs: rename.1 verbose, long options and warning
X-Git-Tag: v2.20-rc1~138^2~21
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=03b3d715ded40c44c074300b704be430aafbc1ae;p=thirdparty%2Futil-linux.git

docs: rename.1 verbose, long options and warning

Add new verbose and long options to manual page. I also added
warning section which hopefully gets read by people who run the
command first time.

It might be good idea to make the rename such that it would not
overwrite by default, and have a --force option if an use wants
that. In current state the rename is somewhat dangerous.

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

diff --git a/misc-utils/rename.1 b/misc-utils/rename.1
index bd676a8dd6..d2c3d1421a 100644
--- a/misc-utils/rename.1
+++ b/misc-utils/rename.1
@@ -1,49 +1,57 @@
 .\" Written by Andries E. Brouwer (aeb@cwi.nl)
 .\" Placed in the public domain
 .\"
-.TH RENAME 1 "1 January 2000" "" "Linux Programmer's Manual"
+.TH RENAME "1" "June 2011" "util-linux" "User Commands"
 .SH NAME
 rename \- rename files
 .SH SYNOPSIS
 .B rename
-.IR  "from to file" ...
-.br
-.B rename -V
+[\fIoptions\fR] \fIexpression replacement file\fR...
 .SH DESCRIPTION
 .B rename
 will rename the specified files by replacing the first occurrence of
-.I from
+.I expression
 in their name by
-.IR to .
-
+.IR replacement .
+.SH OPTIONS
 .TP
-.BR \-V , " \-\-version"
+\fB\-v\fR, \fB\-\-verbose\fR
+Give visual feedback which files where renamed, if any.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
 Display version information and exit.
-
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display help screen and exit.
 .SH EXAMPLES
 Given the files
 .IR foo1 ", ..., " foo9 ", " foo10 ", ..., " foo278 ,
 the commands
-
 .RS
+.PP
 .nf
 rename foo foo0 foo?
 rename foo foo0 foo??
 .fi
+.PP
 .RE
-
 will turn them into
 .IR foo001 ", ..., " foo009 ", " foo010 ", ..., " foo278 .
-
 And
 .RS
+.PP
 .nf
 rename .htm .html *.htm
 .fi
+.PP
 .RE
-
 will fix the extension of your html files.
-
+.SH WARNING
+The rename has no safeguards. If user has permission to rewrite file names
+the command will perform the action without any questions. For example
+result can be quite drastic when the command is ran as root in /lib
+directory. Make always a backup before running the command, unless you truly
+know what you are doing.
 .SH "SEE ALSO"
 .BR mmv (1),
 .BR mv (1)