diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Locale/Codes.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Locale/Codes.pod | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes.pod b/Master/tlpkg/tlperl/lib/Locale/Codes.pod new file mode 100644 index 00000000000..672cdf0e062 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Locale/Codes.pod @@ -0,0 +1,297 @@ +=pod + +=head1 NAME + +Locale::Codes - a distribution of modules to handle locale codes + +=head1 DESCRIPTION + +B<Locale-Codes> is a distribution containing a set of modules. The +modules each deal with different types of codes which identify parts +of the locale including languages, countries, currency, etc. + +Currently, the following modules are included: + +=over 4 + +=item B<Locale::Codes::Country, Locale::Country> + +This includes support for country codes (such as those listed in ISO-3166) +to specify the country. + +Because this module was originally distributed as Locale::Country, it is +also available under that name. + +=item B<Locale::Codes::Language, Locale::Language> + +This includes support for language codes (such as those listed in ISO-639) +to specify the language. + +Because this module was originally distributed as Locale::Language, it is +also available under that name. + +=item B<Locale::Codes::Currency, Locale::Currency> + +This includes support for currency codes (such as those listed in ISO-4217) +to specify the currency. + +Because this module was originally distributed as Locale::Currency, it is +also available under that name. + +=item B<Locale::Codes::Script, Locale::Script> + +This includes support for script codes (such as those listed in ISO-15924) +to specify the script. + +Because this module was originally distributed as Locale::Script, it is +also available under that name. + +=item B<Locale::Codes::LangExt> + +This includes support for language extension codes (such as those listed +in the IANA language registry) to specify the language extension. + +=item B<Locale::Codes::LangVar> + +This includes support for language variation codes (such as those listed +in the IANA language registry) to specify the language variation. + +=item B<Locale::Codes::LangFam> + +This includes support for language family codes (such as those listed +in ISO 639-5) to specify families of languages. + +=back + +Each module can support an arbitrary number of code sets, and it is +not required that the relationship between these code sets be +one-to-one. For example, the Locale::Codes::Country module supports +code sets from ISO-3166 and the IANA standard, and they do not +break the world down into exactly the same sets of countries. This +does not cause any problem (though converting codes from ISO-3166 to +IANA or back will not work except for countries that are one-to-one). + +All data in all of these modules comes directly from the original +standards (or as close to direct as possible), so it should be +up-to-date at the time of release. + +I plan on releasing a new version several times a year to incorporate +any changes made in the standards. However, I don't always know about +changes that occur, so if any of the standards change, and you want a +new release sooner, just email me and I'll get one out. + +In addition to the modules above, there are a number of support modules included +in the distribution including: + +=over 4 + +=item B<Locale::Codes> + +=item B<Locale::Codes::Constants> + +=item B<Locale::Codes::Country_codes> + +=item B<Locale::Codes::Language_codes> + +=item B<Locale::Codes::Currency_codes> + +=item B<Locale::Codes::Script_codes> + +=item B<Locale::Codes::LangExt_codes> + +=item B<Locale::Codes::LangVar_codes> + +=item B<Locale::Codes::LangFam_codes> + +=back + +These modules are not intended to be used by programmers. They contain functions +or data that are used by the modules listed above. + +=head1 NEW CODE SETS + +I'm always open to suggestions for new code sets. + +In order for me to add a code set, I want the following criteria +to be met: + +=over 4 + +=item B<General-use code set> + +If a code set is not general use, I'm not likely to spend the time +to add and support it. + +=item B<An official source of data> + +I require an official (or at least, a NEARLY official) source where I +can get the data on a regular basis. + +Ideally, I'd only get data from an official source, but sometimes that +is not possible. For example the ISO standards are not typically +available for free, so I may have to get some of that data from +alternate sources that I'm confident are getting their data from the +official source. However, I will always be hesitant to accept a +non-official source. + +As an example, I used to get some country data from the CIA World +Factbook. Given the nature of the source, I'm sure they're updating +data from the official sources and I consider it "nearly" official. +However, even in this case, I found that they were adding codes that +were not part of the standard, so I have stopped using them as a +source. + +There are many 3rd party sites which maintain lists (many of which are +actually in a more convenient form than the official sites). +Unfortunately, I will reject most of them since I have no feel for how +"official" they are. + +=item B<A free source of the data> + +Obviously, the data must be free-of-charge. I'm not interested in +paying for the data (and I'm not interested in the overhead of having +someone else pay for the data for me). + +=item B<A reliable source of data> + +The source of data must come from a source that I can reasonably expect +to exist for the foreseeable future since I will be extremely reluctant +to drop support for a data set once it's included. + +I am also reluctant to accept data sent to me by an individual. +Although I appreciate the offer, it is simply not practical to consider +an individual contribution as a reliable source of data. The source +should be an official agency of some sort. + +=back + +These requirements are open to discussion. If you have a code set +you'd like to see added, but which may not meet all of the above +requirements, feel free to email me and we'll discuss it. Depending +on circumstances, I may be willing to waive some of these criteria. + +=head1 COMMON ALIASES + +As of version 2.00, the modules supported common variants of names. + +For example, Locale::Country supports variant names for countries, and +a few of the most common ones are included in the data. The country +code for "United States" is "us", so: + + country2code('United States'); + => "us" + +Now the following will also return 'us': + + country2code('United States of America'); + country2code('USA'); + +Any number of common aliases may be included in the data, in addition +to the names that come directly from the standards. If you have a +common alias for a country, language, or any other of the types of +codes, let me know and I'll add it, with some restrictions. + +For example, the country name "North Korea" never appeared in any of +the official sources (instead, it was "Korea, North" or "Korea, +Democratic People's Republic of". I would honor a request to add an +alias "North Korea" since that's a very common way to specify the +country (please don't request this... I've already added it). + +On the other hand, a request to add Zaire as an alias for "Congo, The +Democratic Republic of" will not be honored. The country's official +name is no longer Zaire, so adding it as an alias violates the standard. +Zaire was kept as an alias in versions prior to 3.00, but it has been +removed. Other aliases (if any) which no longer appear in any standard +(and which are not common variations of the name in the standards) +have also been removed. + +=head1 DEPRECATED CODES + +Occasionally, a code is deprecated, but it may still be desirable to +have access to it. + +Although there is no way to see every code that has ever existed and +been deprecated (since most codesets do not have that information +available), as of version 3.20, every code which has ever been included +in these modules can be referenced. + +For more information, refer to the documentation on the code2XXX, XXX2code, +all_XXX_codes, and all_XXX_names function in the B<Locale::Codes::API> +documentation. + +=head1 SEE ALSO + +=over 4 + +=item B<Locale::Codes::API> + +The list of functions available in each of the modules listed below. +The APIs for each module are exactly identical. + +=item B<Locale::Codes::Country> + +Codes for identification of countries. + +=item B<Locale::Codes::Language> + +Codes for identification of languages. + +=item B<Locale::Codes::Script> + +Codes for identification of scripts. + +=item B<Locale::Codes::Currency> + +Codes for identification of currencies and funds. + +=item B<Locale::Codes::LangExt> + +Codes for identification of language extensions. + +=item B<Locale::Codes::LangVar> + +Codes for identification of language variations. + +=item B<Locale::Codes::LangFam> + +Codes for identification of language families. + +=item B<Locale::Codes::Changes> + +A history of changes made to this distribution. + +=back + +=head1 AUTHOR + +Locale::Country and Locale::Language were originally written by Neil +Bowers at the Canon Research Centre Europe (CRE). They maintained the +distribution from 1997 to 2001. + +Locale::Currency was originally written by Michael Hennecke and was +modified by Neil Bowers for inclusion in the distribution. + +From 2001 to 2004, maintenance was continued by Neil Bowers. He +modified Locale::Currency for inclusion in the distribution. He also +added Locale::Constants and Locale::Script. + +From 2004-2009, the module was unmaintained. + +In 2010, maintenance was taken over by Sullivan Beck (sbeck@cpan.org) +with Neil Bower's permission. All problems or comments should be +sent there. Alternately, problems can be reported using the +perl problem tracker at: + + https://rt.cpan.org/Dist/Display.html?Queue=Locale-Codes + +=head1 COPYRIGHT + + Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). + Copyright (c) 2001 Michael Hennecke (Locale::Currency) + Copyright (c) 2001-2010 Neil Bowers + Copyright (c) 2010-2014 Sullivan Beck + +This module is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + +=cut |