local-lib5/man/man3/Template::Provider::Encoding.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   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 "Template::Provider::Encoding 3"
 127 .TH Template::Provider::Encoding 3 "2007-08-01" "perl v5.8.7" "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 Template::Provider::Encoding \- Explicitly declare encodings of your templates
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&  use Template::Provider::Encoding;
 138 \&  use Template::Stash::ForceUTF8;
 139 \&  use Template;
 140 \&
 141 \&  my $tt = Template\->new(
 142 \&      LOAD_TEMPLATES => [ Template::Provider::Encoding\->new ],
 143 \&      STASH => Template::Stash::ForceUTF8\->new,
 144 \&  );
 145 \&
 146 \&  # Everything should be Unicode
 147 \&  # (but you can pass UTF\-8 bytes as well, thanks to Template::Stash::ForceUTF8)
 148 \&  my $author = "\ex{5bae}\ex{5ddd}";
 149 \&
 150 \&  # this will emit Unicode flagged string to STDOUT. You might
 151 \&  # probably want to binmode(STDOUT, ":encoding($enccoding)")
 152 \&  # before process() call
 153 \&  $tt\->process($template, { author => $author });
 154 \&
 155 \&  # in your templates
 156 \&  [% USE encoding \*(Aqutf\-8\*(Aq \-%]
 157 \&  My name is [% author %]. { ... whatever UTF\-8 bytes }
 158 .Ve
 159 .SH "DESCRIPTION"
 160 .IX Header "DESCRIPTION"
 161 Template::Provider::Encoding is a Template Provider subclass to decode
 162 template using its declaration. You have to declare encoding of the
 163 template in the head (1st line) of template using (fake) encoding \s-1TT\s0
 164 plugin. Otherwise the template is handled as utf\-8.
 165 .PP
 166 .Vb 2
 167 \&  [% USE encoding \*(Aqutf\-8\*(Aq %]
 168 \&  Here comes utf\-8 strings with [% variable %].
 169 .Ve
 170 .SH "DIFFERNCE WITH OTHER WAYS"
 171 .IX Header "DIFFERNCE WITH OTHER WAYS"
 172 .SS "\s-1UNICODE\s0 option and \s-1BOM\s0"
 173 .IX Subsection "UNICODE option and BOM"
 174 Recent \s-1TT\s0 allows \f(CW\*(C`UNICODE\*(C'\fR option to Template::Provider and by adding
 175 it Provider scans \s-1BOM\s0 (byte-order mark) to detect \s-1UTF\-8/UTF\-16\s0 encoded
 176 template files. This module does basically the same thing in a
 177 different way, but \s-1IMHO\s0 adding \s-1BOM\s0 to template files is a little
 178 painful especially for non-programmers.
 179 .SS "Template::Provider::Encode"
 180 .IX Subsection "Template::Provider::Encode"
 181 Template::Provider::Encode provides a very similar way to detect
 182 Template file encodings and output the template into various
 183 encodings.
 184 .PP
 185 This module doesn't touch output encoding of the template and instead
 186 it emits valid Unicode flagged string. I think the output encoding
 187 conversion should be done by other piece of code, especially in the
 188 framework.
 189 .PP
 190 This module doesn't require you to specify encoding in the code, nor
 191 doesn't \fIguess\fR encodings. Instead it forces you to put \f(CW\*(C`[% USE
 192 encoding \*(Aqfoo\-bar\*(Aq %]\*(C'\fR in the top of template files, which is
 193 explicit and, I think, is a good convention.
 194 .SH "AUTHOR"
 195 .IX Header "AUTHOR"
 196 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
 197 .PP
 198 This library is free software; you can redistribute it and/or modify
 199 it under the same terms as Perl itself.
 200 .SH "SEE ALSO"
 201 .IX Header "SEE ALSO"
 202 Template::Stash::ForceUTF8, Template::Provider::Encode