blib/man3/Reference::Output::Bibtex.3pm

   1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Reference::Output::Bibtex 3pm"
 127 .TH Reference::Output::Bibtex 3pm "2013-09-10" "perl v5.14.2" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Reference::Output::Bibtex \-\- Output references in BibTeX format
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&     print bibtex($reference);
 138 .Ve
 139 .PP
 140 Returns a reference formatted in bibtex format.
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 Knows how to handle the reference\-> bibtex field mapping for many
 144 reference types, but overridden types may need to provide their own
 145 mapping.
 146 .SH "BUGS"
 147 .IX Header "BUGS"
 148 None known.
 149 .SS "bibtex"
 150 .IX Subsection "bibtex"
 151 .Vb 3
 152 \&     print bibtex $reference;
 153 \&     %bibtex = bibtex $reference;
 154 \&     print bibtex($reference,mapping=>{...})
 155 .Ve
 156 .PP
 157 In scalar context, returns a formatted bibtex entry, suitable for
 158 printing. In list context, returns a hash of key, value pairs which
 159 can be used to print a formatted bibtex entry.
 160 .PP
 161 You can also pass an optional mapping to be used for making the bibtex
 162 entry. See \fBbibtex_mapping\fR for the details.
 163 .PP
 164 The mappings are obeyed in the following order, the first taking
 165 precedence over the last.
 166 .IP "Passed mapping" 4
 167 .IX Item "Passed mapping"
 168 .PD 0
 169 .IP "Object's bibtex_mapping" 4
 170 .IX Item "Object's bibtex_mapping"
 171 .IP "Internal bibtex_mapping (%Reference::Output::Bibtex::bibtex_mapping)" 4
 172 .IX Item "Internal bibtex_mapping (%Reference::Output::Bibtex::bibtex_mapping)"
 173 .PD
 174 .PP
 175 Returns a \s-1SCALAR\s0 bibtex reference in scalar context, a \s-1HASH\s0 bibtex
 176 reference in list context
 177 .SS "bibtex_mapping"
 178 .IX Subsection "bibtex_mapping"
 179 .Vb 11
 180 \&      $Reference::Output::Bibtex::bibtex_mapping{Article} =
 181 \&        {mapping => {author   => {field  => \*(Aqauthor\*(Aq,
 182 \&                                  join   => \*(Aq and \*(Aq,
 183 \&                                  params => [],
 184 \&                                 },
 185 \&                     volume   => \*(Aqvolume\*(Aq,
 186 \&                     Articlce => \*(Aqname\*(Aq,
 187 \&                     foo      => \*(Aqbar\*(Aq,
 188 \&                    },
 189 \&         order => [qw(name author volume foo)],
 190 \&        };
 191 .Ve
 192 .PP
 193 This variable holds the mapping to bibtex output.
 194 .PP
 195 Each type of reference has its own keys. Currently the following types
 196 are supported by the Bibtex output method:
 197 .IP "article" 4
 198 .IX Item "article"
 199 .PD 0
 200 .IP "collection" 4
 201 .IX Item "collection"
 202 .IP "book" 4
 203 .IX Item "book"
 204 .PD
 205 .PP
 206 If you wish to add support for your own custom reference type, you
 207 merely need to add a bibtex_mapping element to your class's hashref,
 208 or add to this variable. [Preferbly the former, as the latter should
 209 only be used by the end user.]
 210 .PP
 211 The mapping key in the reference type hashref is a hashref containing
 212 key value pairs according to the following metric:
 213 .ie n .IP "If the mapping key value is not a reference, the value is used as the name function to call via ""$reference\-""field>. [In the example above, the volume mapping is built by a call to ""$reference\-""volume>]." 4
 214 .el .IP "If the mapping key value is not a reference, the value is used as the name function to call via \f(CW$reference\-\fRfield>. [In the example above, the volume mapping is built by a call to \f(CW$reference\-\fRvolume>]." 4
 215 .IX Item "If the mapping key value is not a reference, the value is used as the name function to call via $reference-field>. [In the example above, the volume mapping is built by a call to $reference-volume>]."
 216 .PD 0
 217 .ie n .IP "If the mapping key value is a hashref, the hashref contains two keys. The ""field"" key contains the name of the function to call. The ""params"" key contains the parameters" 4
 218 .el .IP "If the mapping key value is a hashref, the hashref contains two keys. The \f(CWfield\fR key contains the name of the function to call. The \f(CWparams\fR key contains the parameters" 4
 219 .IX Item "If the mapping key value is a hashref, the hashref contains two keys. The field key contains the name of the function to call. The params key contains the parameters"
 220 .PD
 221 .PP
 222 The order key in the reference type hashref is an arrayref which
 223 defines the order in which keys are listed in the BibTeX
 224 output. Values in the arrayref should be the keys of the mapping
 225 hashref. [The first value listed is the type of reference/reference
 226 name pair.]
 227 .SS "convert_to_utf8"
 228 .IX Subsection "convert_to_utf8"
 229 .Vb 1
 230 \&    $utf8 = convert_to_utf8("text","charset");
 231 .Ve