.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 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.
.\"
.\" 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 "Net::IDN::Overview 3"
.TH Net::IDN::Overview 3 "2016-08-24" "perl v5.16.3" "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"
Net::IDN::Overwiew \- Internationalized Domain Names for Applications (IDNA)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Net::IDN::*\*(C'\fR modules provide a framework for the handling of
Internationalized Domain Names for Applications (\s-1IDNA\s0) in perl programmes.
.PP
This document provides an overview of the available modules in order to 
allow you to choose the best module for the task at hand.
.SS "\s-1AVAILABLE MODULES\s0"
.IX Subsection "AVAILABLE MODULES"
\fIHIGH-LEVEL (\s-1USE THIS\s0)\fR
.IX Subsection "HIGH-LEVEL (USE THIS)"
.IP "Net::IDN::Encode" 4
.IX Item "Net::IDN::Encode"
provides a high-level interface for converting domain names (and
for convenience, email addresses).
.Sp
Use this module if you just want to convert domain names and don't
care about how this is done internally.
.Sp
Currently, this module uses Net::IDN::UTS46. However, this
might change in the future if another specification (e.g. a
revision of \s-1IDNA2008\s0) becomes more appropriate.
.Sp
The author aims for Net::IDN::Encode to always use the specification that will
provide the \*(L"least surprising\*(R" results.
.PP
\fISTANDARD-SPECIFIC\fR
.IX Subsection "STANDARD-SPECIFIC"
.PP
These modules implement different versions of the the \s-1IDNA\s0
specifications. Use one of these modules only if you require
compatibility with a specific incarnation of \s-1IDNA.\s0
.IP "Net::IDN::IDNA2003" 4
.IX Item "Net::IDN::IDNA2003"
implements the orginal \s-1IDNA\s0 specification, released in 2003
(\s-1IDNA2003\s0), which is now obsolete.
.Sp
\&\s-1IDNA2003\s0 is defined in \s-1RFC\s0\ 3490 <http://tools.ietf.org/rfc/3490>
and related documents.
.IP "Net::IDN::UTS46" 4
.IX Item "Net::IDN::UTS46"
implements Unicode Technical Standard #46 (\s-1UTS\s0 #46
<http://unicode.org/reports/tr46/>), Unicode \s-1IDNA\s0 Compatibility
Processing.  This specification supports all domain names allowed
under either \s-1IDNA2003\s0 or \s-1IDNA2008. \s0
.PP
\fI\s-1ENCODING\s0\fR
.IX Subsection "ENCODING"
.IP "Net::IDN::Punycode" 4
.IX Item "Net::IDN::Punycode"
performs the actual conversion between the \s-1ASCII\s0 and Unicode form
of strings.  Punycode is defined in \s-1RFC\s0\ 3492
<http://tools.ietf.org/rfc/3492> and related documents.
.Sp
Usually, it is not a good idea to use this module directly. If you
convert domain labels (or other strings) without proper
prepration, you may end up with an \s-1ASCII\s0 encoding that is not
interoperable or poses security issues due to spoofing.
.Sp
Even if you think that your domain names are valid and in
already-mapped format, you might be fooled by different Unicode
normalization forms (for example, some environments might
automatically convert your data to \s-1NFD,\s0 which breaks \s-1IDNA\s0).
.PP
\fI\s-1DEPRECATED/COMPATIBILITY\s0\fR
.IX Subsection "DEPRECATED/COMPATIBILITY"
.PP
These modules are only maintained in order to not break
applications that might rely on them
.IP "Encode::Punycode" 4
.IX Item "Encode::Punycode"
provides an Encode plugin for Punycode. As Punycode is not a
general-purpose encoding, there are limited applications.
.IP "IDNA::Punycode" 4
.IX Item "IDNA::Punycode"
has an \s-1API\s0 depending on global variables. Don't use this module.
.SS "\s-1DISTRIBUTIONS\s0"
.IX Subsection "DISTRIBUTIONS"
.IP "Net-IDN-Encode" 4
.IX Item "Net-IDN-Encode"
is the main distribution covering the most common cases for
converting domain names between \s-1ASCII\s0 and Unicode.
.Sp
The author tries to keep the dependency chain as small as possible; currently
this distribution only depends on perl\ 5.8.5 (including the core module
Unicode::Normalize ).
.IP "Net\-IDN\-IDNA2003" 4
.IX Item "Net-IDN-IDNA2003"
provides the Net::IDN::IDNA2003 module. This is separate
because it has an dependency on Unicode::Stringprep (through
Net::IDN::Nameprep).
.IP "Encode-Punycode" 4
.IX Item "Encode-Punycode"
.PD 0
.IP "IDNA-Punycode" 4
.IX Item "IDNA-Punycode"
.PD
are separate because they are of limited use to the average
user/perl programmer.
.SH "AUTHOR"
.IX Header "AUTHOR"
Claus Fa\*:rber <CFAERBER@cpan.org>