\cfg{man-identity}{multi}{1}{2004-11-20}{Simon Tatham}{Simon Tatham}
-\cfg{man-mindepth}{1}
-\C{multi-manpage} Man page for \cw{multi}
+\define{dash} \u2013{-}
-\H{multi-manpage-name} NAME
+\title Man page for \cw{multi}
-\cw{multi} - bulk file rename/copy utility using Perl regexps
+\U NAME
-\H{multi-manpage-synopsis} SYNOPSIS
+\cw{multi} \dash bulk file rename/copy utility using Perl regexps
+
+\U SYNOPSIS
\c multi [ -n | -q ] [ -r ] cmd perlfragment file [file...]
\e bbbbb bb bb bb iii iiiiiiiiiiii iiii iiii
\c multi [ -n | -q ] [ -r ] - cmd cmd - perlfragment file [file...]
\e bbbbb bb bb bb iii iii iiiiiiiiiiii iiii iiii
-\H{multi-manpage-description} DESCRIPTION
+\U DESCRIPTION
\cw{multi} is a utility which allows you to invoke a command
(typically, but not always, \cw{mv} or \cw{cp}) on a lot of files in
a complicated way.
The command-line arguments to \cw{multi} include a command, a set of
-filenames, and a fragment of Perl. for each of the filenames,
+filenames, and a fragment of Perl. For each of the filenames,
\cw{multi} will use the fragment of Perl to transform the filename
into a new filename, and will then invoke the given command, passing
the old and new filenames as arguments.
passing \cw{mv} or \cw{cp} as the command. However, it can have more
complex uses as well; see the examples below.
-\H{multi-manpage-args} ARGUMENTS
+\U ARGUMENTS
\dt \e{cmd}
to be transformed. Typically these will be generated by typing one
or more wildcard expressions on the shell command line.
-\H{multi-manpage-options} OPTIONS
+\U OPTIONS
By default, \cw{multi} will print every command it executes on
standard output, so that you can see what it has just done (in case
\dd Reverse the order of arguments to the subcommand, so that it
receives the transformed file name \e{before} the original one.
-\H{multi-manpage-examples} EXAMPLES
+\U EXAMPLES
The simplest use of \cw{multi} is to rename a large number of files.
Suppose, for example, you have a lot of text files with \cw{.txt}
\c svn mv winutils.c windows/winutils.c
Of course, your Perl fragment can be more complex than just a
-\cw{s///} command. Here's a means of tidying up after extracting a
+\cw{s///} command. Here's a means of tidying up after extracting an
MS-DOS zip file containing all filenames in upper case:
\c $ multi mv 'y/A-Z/a-z/' *[A-Z]*
\c mv MAIN.C main.c
\c mv STUFF.C stuff.c
-Here's an example using \cw{-r}. Suppose you have lots of small C
-programs and you want to quickly compile them all into binaries:
+Here's an example using \cw{-r}. Suppose you have lots of \c{.wav}
+sound files, and you want to encode them all into compressed Ogg
+Vorbis format. The \c{oggenc} command expects its destination file
+name as an argument to the \c{-o} parameter, so it's most convenient
+to put that \e{before} the input file name:
-\c $ multi -r - cc -o - 's/.c$//' *.c
-\c bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
-\c cc -o bar bar.c
-\c cc -o baz baz.c
-\c cc -o foo foo.c
+\c $ multi -r - oggenc -o - 's/.wav$/.ogg/' *.wav
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+\c oggenc -o bar.ogg bar.wav
+\c oggenc -o baz.ogg baz.wav
+\c oggenc -o foo.ogg foo.wav
Finally, here's a general technique for going beyond the limits of
\cw{multi}, in the case where you need to do something more
name as the target of a shell redirection operator, for example.
\c $ multi - sh -c 'grep foo $0 > $1' - 's/.txt$/.grepped/' *.txt
-\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c sh -c 'grep foo $0 > $1' bar.txt bar.grepped
\c sh -c 'grep foo $0 > $1' baz.txt baz.grepped
\c sh -c 'grep foo $0 > $1' foo.txt foo.grepped
\c grep foo baz.txt > baz.grepped
\c grep foo foo.txt > foo.grepped
-\H{multi-manpage-ack} ACKNOWLEDGEMENTS
+\U ACKNOWLEDGEMENTS
The O'Reilly book \q{Programming Perl} includes a simple example
script which contains the core idea of this program. It takes a
single Perl argument followed by filenames, and invokes Perl's
internal \cw{rename} function. \cw{multi} is a complete rewrite of
this basic idea, supplying more options and configurability.
+
+\U LICENCE
+
+\cw{multi} is free software, distributed under the MIT licence. Type
+\cw{multi --licence} to see the full licence text.
+
+\versionid $Id$
~mdw / sgt / utils / blobdiff