.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "Text::BibTeX::NameFormat 3pm"
.TH Text::BibTeX::NameFormat 3pm "2019-07-17" "perl v5.28.1" "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"
Text::BibTeX::NameFormat \- format BibTeX\-style author names
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Text::BibTeX::NameFormat;
\&
\&   $format = Text::BibTeX::NameFormat\->($parts, $abbrev_first);
\&
\&   $format\->set_text ($part,
\&                      $pre_part, $post_part,
\&                      $pre_token, $post_token);
\&
\&   $format\->set_options ($part, $abbrev, $join_tokens, $join_part
\&
\&   ## Uses the encoding/binmode and normalization form stored in $name
\&   $formatted_name = $format\->apply ($name);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
After splitting a name into its components parts (represented as a
\&\f(CW\*(C`Text::BibTeX::Name\*(C'\fR object), you often want to put it back together
again as a single string formatted in a consistent way.
\&\f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR provides a very flexible way to do this,
generally in two stages: first, you create a \*(L"name format\*(R" which
describes how to put the tokens and parts of any name back together, and
then you apply the format to a particular name.
.PP
The \*(L"name format\*(R" is encapsulated in a \f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR
object.  The constructor (\f(CW\*(C`new\*(C'\fR) includes some clever behind-the-scenes
trickery that means you can usually get away with calling it alone, and
not need to do any customization of the format object.  If you do need
to customize the format, though, the \f(CW\*(C`set_text()\*(C'\fR and \f(CW\*(C`set_options()\*(C'\fR
methods provide that capability.
.PP
Note that \f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR is a fairly direct translation of
the name-formatting C interface in the \fBbtparse\fR library.  This manual
page is meant to provide enough information to use the Perl class, but
for more details and examples, consult bt_format_names.
.SH "CONSTANTS"
.IX Header "CONSTANTS"
Two enumerated types for dealing with names and name formatting have
been brought from C into Perl.  In the \fBbtparse\fR documentation, you'll
see references to \f(CW\*(C`bt_namepart\*(C'\fR and \f(CW\*(C`bt_joinmethod\*(C'\fR.  The former lists
the four \*(L"parts\*(R" of a BibTeX name: first, von, last, and jr; its values
(in both C and Perl) are \f(CW\*(C`BTN_FIRST\*(C'\fR, \f(CW\*(C`BTN_VON\*(C'\fR, \f(CW\*(C`BTN_LAST\*(C'\fR, and
\&\f(CW\*(C`BTN_JR\*(C'\fR.  The latter lists the ways in which \f(CW\*(C`bt_format_name()\*(C'\fR (the
C function that corresponds to \f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR's \f(CW\*(C`apply\*(C'\fR
method) can join adjacent tokens together: \f(CW\*(C`BTJ_MAYTIE\*(C'\fR, \f(CW\*(C`BTJ_SPACE\*(C'\fR,
\&\f(CW\*(C`BTJ_FORCETIE\*(C'\fR, and \f(CW\*(C`BTJ_NOTHING\*(C'\fR.  Both sets of values may be
imported from the \f(CW\*(C`Text::BibTeX\*(C'\fR module, using the import tags
\&\f(CW\*(C`nameparts\*(C'\fR and \f(CW\*(C`joinmethods\*(C'\fR.  For instance:
.PP
.Vb 3
\&   use Text::BibTeX qw(:nameparts :joinmethods);
\&   use Text::BibTeX::Name;
\&   use Text::BibTeX::NameFormat;
.Ve
.PP
The \*(L"name part\*(R" constants are used to specify surrounding text or
formatting options on a per-part basis: for instance, you can supply the
\&\*(L"pre-token\*(R" text, or the \*(L"abbreviate\*(R" flag, for a single part without
affecting other parts.  The \*(L"join methods\*(R" are two of the three
formatting options that you can set for a part: you can control how to
join the individual tokens of a name (\f(CW"JR Smith"\fR, or \f(CW"J R Smith"\fR,
or \f(CW"J~R Smith"\fR, and you can control how the final token of one part
is joined to the next part (\f(CW"la Roche"\fR versus \f(CW"la~Roche"\fR).
.SH "METHODS"
.IX Header "METHODS"
.IP "new(\s-1PARTS, ABBREV_FIRST\s0)" 4
.IX Item "new(PARTS, ABBREV_FIRST)"
Creates a new name format, with the two most common customizations: which
parts to include (and in what order), and whether to abbreviate the first
name.  \s-1PARTS\s0 should be a string with at most four characters, one representing
each part that you want to occur in a formatted name (defaults to \f(CW"fvlj"\fR).
For example, \f(CW"fvlj"\fR means to format names in \*(L"first von last jr\*(R" order,
while \f(CW"vljf"\fR denotes \*(L"von last jr first.\*(R"  \s-1ABBREV_FIRST\s0 is just a boolean
value: false to print out the first name in full, and true to abbreviate it
with periods after each token and discretionary ties between tokens (defaults
to false).  All intra\- and inter-token punctuation and spacing is independently
controllable with the \f(CW\*(C`set_text\*(C'\fR and \f(CW\*(C`set_options\*(C'\fR methods, although these
will rarely be necessary\-\-\-sensible defaults are chosen for everything, based
on the \s-1PARTS\s0 and \s-1ABBREV_FIRST\s0 values that you supply.  See the description of
\&\f(CW\*(C`bt_create_name_format()\*(C'\fR in bt_format_names for full details of the
choices made.
.IP "set_text (\s-1PART, PRE_PART, POST_PART, PRE_TOKEN, POST_TOKEN\s0)" 4
.IX Item "set_text (PART, PRE_PART, POST_PART, PRE_TOKEN, POST_TOKEN)"
Allows you to customize some or all of the surrounding text for a single
name part.  Every name part has four possible chunks of text that go
around or within it: before/after the part as a whole, and before/after
each token in the part.  For instance, if you are abbreviating first
names and wish to control the punctuation after each token in the first
name, you would set the \*(L"post token\*(R" text:
.Sp
.Vb 1
\&   $format\->set_text (\*(Aqfirst\*(Aq, undef, undef, undef, \*(Aq\*(Aq);
.Ve
.Sp
would set the post-token text to the empty string, resulting in names
like \f(CW"J R Smith"\fR.  (Normally, abbreviated first names will have a
period after each token: \f(CW"J. R. Smith"\fR.)  Note that supplying
\&\f(CW\*(C`undef\*(C'\fR for the other three values leaves them unchanged.
.Sp
See bt_format_names for full information on formatting names.
.IP "set_options (\s-1PART, ABBREV, JOIN_TOKENS, JOIN_PART\s0)" 4
.IX Item "set_options (PART, ABBREV, JOIN_TOKENS, JOIN_PART)"
Allows further customization of a name format: you can set the
abbreviation flag and the two token-join methods.  Alas, there is no
mechanism for leaving a value unchanged; you must set everything with
\&\f(CW\*(C`set_options\*(C'\fR.
.Sp
For example, let's say that just dropping periods from abbreviated
tokens in the first name isn't enough; you \fIreally\fR want to save
space by jamming the abbreviated tokens together: \f(CW"JR Smith"\fR rather
than \f(CW"J R Smith"\fR  Assuming the two calls in the above example have
been done, the following will finish the job:
.Sp
.Vb 4
\&   $format\->set_options (BTN_FIRST,
\&                         1,             # keep same value for abbrev flag
\&                         BTJ_NOTHING,   # jam tokens together
\&                         BTJ_SPACE);    # space after final token of part
.Ve
.Sp
Note that we unfortunately had to know (and supply) the current values
for the abbreviation flag and post-part join method, even though we were
only setting the intra-part join method.
.IP "apply (\s-1NAME\s0)" 4
.IX Item "apply (NAME)"
Once a name format has been created and customized to your heart's
content, you can use it to format any number of names using the \f(CW\*(C`apply\*(C'\fR
method.  \s-1NAME\s0 must be a \f(CW\*(C`Text::BibTeX::Name\*(C'\fR object (i.e., a pre-split
name); \f(CW\*(C`apply\*(C'\fR returns a string containing the parts of the name
formatted according to the \f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR structure it is
called on.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Although the process of splitting and formatting names may sound
complicated and convoluted from reading the above (along with
Text::BibTeX::Name), it's actually quite simple.  There are really
only three steps to worry about: split the name (create a
\&\f(CW\*(C`Text::BibTeX::Name\*(C'\fR object), create and customize the format
(\f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR object), and apply the format to the name.
.PP
The first step is covered in Text::BibTeX::Name; here's a brief
example:
.PP
.Vb 2
\&   $orig_name = \*(AqCharles Louis Xavier Joseph de la Vall{\e\*(Aqe}e Poussin\*(Aq;
\&   $name = Text::BibTeX::Name\->new($orig_name);
.Ve
.PP
The various parts of the name can now be accessed through
\&\f(CW\*(C`Text::BibTeX::Name\*(C'\fR methods; for instance \f(CW\*(C`$name\->part(\*(Aqvon\*(Aq)\*(C'\fR
returns the list \f(CW\*(C`("de","la")\*(C'\fR.
.PP
Creating the name format is equally simple:
.PP
.Vb 1
\&   $format = Text::BibTeX::NameFormat\->new(\*(Aqvljf\*(Aq, 1);
.Ve
.PP
creates a format that will print the name in \*(L"von last jr first\*(R" order,
with the first name abbreviated.  And for no extra charge, you get the
right punctuation at the right place: a comma before any `jr' or `first'
tokens, and periods after each `first' token.
.PP
For instance, we can perform no further customization on this format,
and apply it immediately to \f(CW$name\fR.  There are in fact two ways to do
this, depending on whether you prefer to think of it in terms of
\&\*(L"Applying the format to a name\*(R" or \*(L"formatting a name\*(R".  The first is
done with \f(CW\*(C`Text::BibTeX::NameFormat\*(C'\fR's \f(CW\*(C`apply\*(C'\fR method:
.PP
.Vb 1
\&   $formatted_name = $format\->apply ($name);
.Ve
.PP
while the second uses \f(CW\*(C`Text::BibTeX::Name\*(C'\fR's \f(CW\*(C`format\*(C'\fR method:
.PP
.Vb 1
\&   $formatted_name = $name\->format ($format);
.Ve
.PP
which is just a wrapper around \f(CW\*(C`Text::BibTeX::NameFormat::apply\*(C'\fR.  In
either case, the result with the example name and format shown is
.PP
.Vb 1
\&   de~la Vall{\e\*(Aqe}e~Poussin, C.~L. X.~J.
.Ve
.PP
Note the strategic insertion of TeX \*(L"ties\*(R" (non-breakable spaces) at
sensitive spots in the name.  (The exact rules for insertion of
discretionary ties are given in bt_format_names.)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::BibTeX::Entry, Text::BibTeX::Name, bt_format_names.
.SH "AUTHOR"
.IX Header "AUTHOR"
Greg Ward <gward@python.net>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1997\-2000 by Gregory P. Ward.  All rights reserved.  This file
is part of the Text::BibTeX library.  This library is free software; you
may redistribute it and/or modify it under the same terms as Perl itself.