manpages/arename.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ARENAME 1"
 132 .TH ARENAME 1 "2007-10-28" "perl v5.8.8" "User Contributed Perl Documentation"
 133 .SH "SYNOPSIS"
 134 .IX Header "SYNOPSIS"
 135 arename.pl [\s-1OPTION\s0(s)] \s-1FILE\s0(s)...
 136 .SH "OPTIONS AND ARGUMENTS"
 137 .IX Header "OPTIONS AND ARGUMENTS"
 138 .IP "\fB\-d\fR" 8
 139 .IX Item "-d"
 140 Go into dryrun mode.
 141 .IP "\fB\-f\fR" 8
 142 .IX Item "-f"
 143 Overwrite files if needed.
 144 .IP "\fB\-h\fR" 8
 145 .IX Item "-h"
 146 Display a short help text.
 147 .IP "\fB\-V\fR" 8
 148 .IX Item "-V"
 149 Display version infomation.
 150 .IP "\fB\-v\fR" 8
 151 .IX Item "-v"
 152 Enable verbose output.
 153 .IP "\fB\-p\fR <prefix>" 8
 154 .IX Item "-p <prefix>"
 155 Define a prefix for destination files.
 156 .IP "\fB\-T\fR <template>" 8
 157 .IX Item "-T <template>"
 158 Define a compilation template.
 159 .IP "\fB\-t\fR <template>" 8
 160 .IX Item "-t <template>"
 161 Define a generic template.
 162 .IP "\fI\s-1FILE\s0(s)...\fR" 8
 163 .IX Item "FILE(s)..."
 164 Input files, that are subject for renaming.
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 \&\fBarename.pl\fR is a tool that is able to rename audio files by looking at
 168 a file's tagging information, from which it will assemble a consistent
 169 destination file name. The format of that filename is configurable for the
 170 user by the use of template strings.
 171 .PP
 172 \&\fBarename.pl\fR currently supports two widely used audio formats, namely
 173 \&\s-1MPEG\s0 Layer3 and ogg vorbis. The format, that \fBarename.pl\fR will assume
 174 for each input file is determined by the file's filename-extension
 175 (\fI.mp3\fR vs. \fI.ogg\fR). The extension check is case\-insensitive.
 176 .PP
 177 By default, \fBarename.pl\fR will refuse to overwrite destination files,
 178 if the file in question already exists. You can force overwriting by
 179 supplying the \fB\-f\fR option.
 180 .SH "FILES"
 181 .IX Header "FILES"
 182 \&\fBarename.pl\fR uses up to two configuration files. As for most programs,
 183 the script will try to read a configuration file, that is located in the
 184 user's \fIhome directory\fR. In addition to that, it will try to load \fIlocal\fR
 185 configuration files, if it finds appropriately named files in the
 186 \&\fIcurrent directory\fR.
 187 .IP "\fB~/.arenamerc\fR" 8
 188 .IX Item "~/.arenamerc"
 189 per-user global configuration file.
 190 .IP "\fB./.arename.local\fR" 8
 191 .IX Item "./.arename.local"
 192 per-directory local configuration file.
 193 .Sh "File format"
 194 .IX Subsection "File format"
 195 The format of the aforementioned files is pretty simple.
 196 It is parsed line by line. Empty lines, lines only containing whitespace
 197 and lines, whose first non whitespace character is a hash character (\fI#\fR)
 198 are ignored.
 199 .PP
 200 Each line consists of one or two parts. If there are two parts,
 201 they are separated by whitespace. The first part of the line will be used
 202 as the identifier of a setting (eg. \fIverbose\fR). The second part (read: the
 203 rest of the line) is used as the value of the setting. (No quoting, or whatsoever
 204 is required.)
 205 .PP
 206 If a line consists of only one part, that means the setting is switched on.
 207 .Sh "Configuration file example"
 208 .IX Subsection "Configuration file example"
 209 .Vb 2
 210 \&  # switch on verbosity
 211 \&  verbose
 212 .Ve
 213 .PP
 214 .Vb 2
 215 \&  # the author is crazy! use a sane template by default. :\-)
 216 \&  template &artist \- &album (&year) \- &tracknumber. &tracktitle
 217 .Ve
 218 .SH "SETTINGS"
 219 .IX Header "SETTINGS"
 220 The following settings are supported in all configuration files:
 221 .IP "\fBcomp_template\fR" 8
 222 .IX Item "comp_template"
 223 Defines a template to use with files that provide a compilation tag
 224 (for 'various artist' CDs, for example). This setting can still be
 225 overwritten by the \fB\-T\fR command line option. (default value:
 226 \&\fIva/&album/&tracknumber \- &artist \- &tracktitle\fR)
 227 .IP "\fBdefault_year\fR" 8
 228 .IX Item "default_year"
 229 Defines a default year, for files, that lack this information.
 230 (default value: \fIundefined\fR)
 231 .IP "\fBprefix\fR" 8
 232 .IX Item "prefix"
 233 Defines a prefix for destination files. This setting can still be
 234 overwritten by the \fB\-p\fR command line option. (default value: \fI.\fR)
 235 .IP "\fBsepreplace\fR" 8
 236 .IX Item "sepreplace"
 237 Tagging information strings may contain slashes, which is a pretty bad
 238 idea on most filesystems. Therefore, you can define a string, that replaces
 239 slashes with the value of this setting. (default value: \fI_\fR)
 240 .IP "\fBtemplate\fR" 8
 241 .IX Item "template"
 242 Defines a template to use with files that do not provide a compilation tag
 243 (or where the compilation tag and the artist tag are exactly the same).
 244 This setting can still be overwritten by the \fB\-T\fR command line option.
 245 (default value: \fI&artist[1]/&artist/&album/&tracknumber \- &tracktitle\fR)
 246 .IP "\fBtnpad\fR" 8
 247 .IX Item "tnpad"
 248 This defines the width, to which the tracknumber field is padded with zeros
 249 on the left. (default value: \fI2\fR)
 250 .IP "\fBverbose\fR" 8
 251 .IX Item "verbose"
 252 Switches on verbosity by default. (default value: \fIoff\fR)
 253 .SH "TEMPLATE FORMAT"
 254 .IX Header "TEMPLATE FORMAT"
 255 \&\fBarename.pl\fR's templates are quite simple, yet powerful.
 256 .PP
 257 At simplest, a template is just a fixes character string. However, that would
 258 not be exactly useful. So, the script is able to expand certain expressions
 259 with information gathered from the file's tagging information.
 260 .PP
 261 The expressions can have two slightly different forms:
 262 .IP "\fB&\fR\fIidentifier\fR" 8
 263 .IX Item "&identifier"
 264 The simple form.
 265 .IP "\fB&\fR\fIidentifier\fR\fB[\fR\fIlength\fR\fB]\fR" 8
 266 .IX Item "&identifier[length]"
 267 The \*(L"complex\*(R" form. The \fIlength\fR argument in square brackets defines the
 268 maximum length, to which the expression should be expanded.
 269 .Sh "Available expression identifiers"
 270 .IX Subsection "Available expression identifiers"
 271 The data, that is expanded is derived from tagging information in
 272 the audio files. For \fI.ogg\fR files, the tag checking \fBarename.pl\fR does
 273 is case insensitive and the first matching tag will be used.
 274 .IP "\fBalbum\fR" 8
 275 .IX Item "album"
 276 Guess.
 277 .IP "\fBartist\fR" 8
 278 .IX Item "artist"
 279 Guess again.
 280 .IP "\fBcompilation\fR" 8
 281 .IX Item "compilation"
 282 For \fI.ogg\fR this is filled with information found in the 'albumartist' tag.
 283 For \fI.mp3\fR this is filled with information from the id3v2 \s-1TPE2\s0 frame.
 284 If the mp3 file only provides a id3v1 tag, this is not supported.
 285 .IP "\fBtracknumber\fR" 8
 286 .IX Item "tracknumber"
 287 The number of the position of the track on the disc. Obviously. However, this
 288 can be in the form of '12' or '12/23'. In the second form, only the part left
 289 of the slash is used. The tracknumber is a little special, as you can defined
 290 to what width it should be padded with zeros on the left (see \fItnpad\fR setting
 291 in \*(L"\s-1SETTINGS\s0\*(R" in \fIarename\fR\|(1)).
 292 .IP "\fBtracktitle\fR" 8
 293 .IX Item "tracktitle"
 294 Well...
 295 .IP "\fByear\fR" 8
 296 .IX Item "year"
 297 Year (id3v1), \s-1TYER\s0 (id3v2) or \s-1DATE\s0 tag (.ogg).
 298 .SH "SEE ALSO"
 299 .IX Header "SEE ALSO"
 300 \&\fIOgg::Vorbis::Header\fR\|(3) and \fIMP3::Tag\fR\|(3).
 301 .SH "AUTHOR"
 302 .IX Header "AUTHOR"
 303 Frank Terbeck <ft@bewatermyfriend.org>,
 304 .PP
 305 Please report bugs.
 306 .SH "LICENSE"
 307 .IX Header "LICENSE"
 308 .Vb 2
 309 \& Copyright 2007
 310 \& Frank Terbeck <ft@bewatermyfriend.org>, All rights reserved.
 311 .Ve
 312 .PP
 313 .Vb 3
 314 \& Redistribution and use in source and binary forms, with or without
 315 \& modification, are permitted provided that the following conditions
 316 \& are met:
 317 .Ve
 318 .PP
 319 .Vb 7
 320 \&   1. Redistributions of source code must retain the above
 321 \&      copyright notice, this list of conditions and the following
 322 \&      disclaimer.
 323 \&   2. Redistributions in binary form must reproduce the above
 324 \&      copyright notice, this list of conditions and the following
 325 \&      disclaimer in the documentation and/or other materials
 326 \&      provided with the distribution.
 327 .Ve
 328 .PP
 329 .Vb 11
 330 \&  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
 331 \&  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 332 \&  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 333 \&  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS OF THE
 334 \&  PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 335 \&  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 336 \&  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 337 \&  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 338 \&  OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 339 \&  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 340 \&  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 341 .Ve