.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Normalize::Text::Music_Fields 3pm"
.TH Normalize::Text::Music_Fields 3pm "2009-05-08" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Normalize::Text::Music_Fields \- normalize names of people's and (musical) works.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&   $name = $obj\->Normalize::Text::Music_Fields::normalize_person($name);
\&   $work = $obj\->Normalize::Text::Music_Fields::normalize_piece($work);
\& # $obj should have methods \`name_for_field_normalization\*(Aq, \*(Aqshorted_person\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Databases of names and of works-per-name are taken from plain-text
files (optionally in mail-header format).  Names are stored in \fI*.lst\fR files.
Works are stored in \fI.comp\fR files named after the shortened name
of the composer.
.PP
The directories of these files are looked in the environment variable
\&\f(CW\*(C`MUSIC_FIELDS_PATH\*(C'\fR (if defined, split the same way as \f(CW\*(C`PATH\*(C'\fR), or in
\&\f(CW\*(C`$ENV{HOME}/.music_fields\*(C'\fR, and \f(CW\*(C`\-\*(C'\fR (and \f(CW\*(C`\-\*(C'\fR is replaced by the directory
named as the module file with \fI.pm\fR dropped).  At runtime, one can
replace the list by calling function \fINormalize::Text::Music_Fields::set_path()\fR
with the list of directories as the argument.
.PP
(Since parsed files are cached, replacing the directory list should be done
as early as possible.)
.PP
Files may be managed with utility subroutines provided with the module:
.PP
.Vb 2
\& # Translate from one\-per\-line to mail\-header format:
\& perl \-wple "BEGIN {print q(# format = mail\-header)} s/#\es*normalized\es*$//; $_ = qq(Title: $_) unless /^\es*(#|$)/; $_ = qq(\en$_) if $p and not /^##/; $_ .= qq(\en) unless $p = /^##/" Normalize::Text::Music_Fields\-G_Gershwin.comp >Music_Fields\-G_Gershwin.comp\-mail
\&
\& # (inverse transformation:) Dump pieces listed in mail\-header format
\& perl \-MNormalize::Text::Music_Fields \-wle "print for Normalize::Text::Music_Fields::read_composer_file(shift, shift)" gershwin Music_Fields\-G_Gershwin.comp\-mail > o
\&
\& # Normalize data in 1\-line\-per piece format
\& perl \-MNormalize::Text::Music_Fields \-wle "Normalize::Text::Music_Fields::prepare_tag_object_comp(shift)\->Normalize::Text::Music_Fields::normalize_file_lines(shift)"
\&
\& # Create a mail\-header file from a semi\-processed (with "bold" fields)
\& # mail\-header file (with xml escapes, preceded by opus number)
\& perl \-MNormalize::Text::Music_Fields \-00wnle "BEGIN {$tag = Normalize::Text::Music_Fields::prepare_tag_object_comp(shift @ARGV); print q(# format = mail\-header)} print Normalize::Text::Music_Fields::emit_as_mail_header($tag,$_, q(bold,xml,opus),$pre)" shostakovich  o\-xslt\-better >Music_Fields\-D_Shostakovich.comp\-mail1
\&
\& # Likewise, from work\-per\-line with opus\-numbers:
\& perl \-MNormalize::Text::Music_Fields \-wnle "BEGIN {$tag = Normalize::Text::Music_Fields::prepare_tag_object_comp(shift @ARGV); print qq(# format = mail\-header\en)} print Normalize::Text::Music_Fields::emit_as_mail_header($tag,$_, q(opus), $pre)" schnittke  o\-schnittke\-better  >Music_Fields\-A_Schnittke.comp\-mail2
\&
\& # A primitive tool for merging additional info into the database:
\& perl \-MNormalize::Text::Music_Fields \-wnle "BEGIN {$tag = Normalize::Text::Music_Fields::prepare_tag_object_comp(shift @ARGV); print qq(# format = mail\-header\en)} next unless s/^\es*\e+\e+\es*//; print Normalize::Text::Music_Fields::merge_info($tag,$_, q(opus,xml), qr(^(58|70|76|116|118|119)($|\-)))" brahms o\-brahms\-op\-no1\-xslt
\&
\& # Minimal consistency check of persons database.
\& perl \-MNormalize::Text::Music_Fields \-wle "BEGIN{binmode $_, \*(Aq:encoding(cp866)\*(Aq for \e*STDIN, \e*STDOUT, \e*STDERR} print Normalize::Text::Music_Fields\->check_persons"
\&
\& # Minimal testing code:
\& perl \-MNormalize::Text::Music_Fields \-e Normalize::Text::Music_Fields::test_normalize_piece
.Ve
.PP
It may be easier to type these examples if one uses \f(CW\*(C`manage_M_N_F.pm\*(C'\fR, which
exports the mentioned subroutines to the main namespace (available in
\&\fIexamples\fR directory of a distribution of \f(CW\*(C`MP3::Tag\*(C'\fR).  E.g., the last
example becomes:
.PP
.Vb 1
\& perl \-Mmanage_M_N_F \-e test_normalize_piece
.Ve