diff options
author | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
commit | e5c6e6d9c56fbfc54508fa2c32b03a5a870b7553 (patch) | |
tree | 40fcc93aa383c1e45d31ddc42d03f15cbada7076 /Master/tlpkg/tlperl/lib/Locale | |
parent | 300c1eb6d37d46078d448d6d58938d5a80cd68ff (diff) |
oops, remove 5.16 tlperl files
git-svn-id: svn://tug.org/texlive/trunk@33649 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Locale')
18 files changed, 0 insertions, 5063 deletions
diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes.pod b/Master/tlpkg/tlperl/lib/Locale/Codes.pod deleted file mode 100644 index df10c849a1b..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes.pod +++ /dev/null @@ -1,285 +0,0 @@ -=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 it -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 FIPS 10 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 -FIPS 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::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-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/API.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/API.pod deleted file mode 100644 index 1a566d2b157..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/API.pod +++ /dev/null @@ -1,320 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::API - a description of the callable function in each module - -=head1 DESCRIPTION - -Although there are several modules in the Locale-Codes distribution, all of them -(as of version 3.10) use exactly the same API. As a matter of fact, each of the -main callable modules are just wrappers around a central module which does all -the real work. - -=head1 ROUTINES - -In order to maintain the documentation for the modules consistently, -the functions are all documented here, rather than in the documentation -for the separate modules. - -The name of the function depends on the module. For example, every module -contains a function "code2XXX" where XXX refers to the type of data. -The values of XXX are described in the following table: - - XXX MODULE - - country Locale::Codes::Country - language Locale::Codes::Language - currency Locale::Codes::Currency - script Locale::Codes::Script - langext Locale::Codes::LangExt - langvar Locale::Codes::LangVar - langfam Locale::Codes::LangFAM - -So, the Locale::Country module contains the function code2country, the -Locale::Language module contains the function code2language, etc. - -In all of the functions below, CODE refers to a code for one element in -the code set. For example, in the two-letter country codes from ISO 3166-1, -the code 'fi' is used to refer to the country Finland. CODE is always -case insensitive (though when a code is returned, it will always be in -the case as used in the standard), so 'fi', 'FI', and 'Fi' would all -be equivalent. - -CODESET refers to a constant specified in the documentation for each -module to label the various code sets. For example, in the -Locale::Language module, CODESET could be LOCALE_CODE_ALPHA_2 or -LOCALE_CODE_ALPHA_3 (among others). Most functions have a default one, -so they do not need to be specified. So the following calls are valid: - - code2country("fi"); - code2country("fi",LOCALE_CODE_ALPHA_2); - code2country("fin",LOCALE_CODE_ALPHA_3); - -Since LOCALE_CODE_ALPHA_2 is the default code set, the first two are -identical. - -=over 4 - -=item B<code2XXX ( CODE [,CODESET] [,'retired'] )> - -These functions take a code and returns a string which contains -the name of the element identified. If the code is not a valid -code in the CODESET specified then C<undef> will be returned. - -The name of the element is the name as specified in the standard, -and as a result, different variations of an element name may -be returned for different values of CODESET. - -For example, the B<alpha-2> country code set defines the two-letter -code "bo" to be "Bolivia, Plurinational State of", whereas the -B<alpha-3> code set defines the code 'bol' to be the country "Bolivia -(Plurinational State of)". So: - - code2country('bo',LOCALE_CODE_ALPHA_2); - => 'Bolivia, Plurinational State of' - - code2country('bol',LOCALE_CODE_ALPHA_3); - => 'Bolivia (Plurinational State of)' - -By default, only active codes will be used, but if the string -'retired' is passed in as an argument, both active and retired -codes will be examined. - -=item B<XXX2code ( NAME [,CODESET] [,'retired'] )> - -These functions takes the name of an element (or any of it's aliases) -and returns the code that corresponds to it, if it exists. If NAME -could not be identified as the name of one of the elements, then -C<undef> will be returned. - -The name is not case sensitive. Also, any known variation of a name -may be passed in. - -For example, even though the country name returned using -LOCALE_CODE_ALPHA_2 and LOCALE_CODE_ALPHA_3 country codes for Bolivia is different, -either country name may be passed in since for each code set, in addition to -the alias 'Bolivia'. So: - - country2code('Bolivia, Plurinational State of', - LOCALE_CODE_ALPHA_2); - => bo - - country2code('Bolivia (Plurinational State of)', - LOCALE_CODE_ALPHA_2); - => bo - - country2code('Bolivia',LOCALE_CODE_ALPHA_2); - => bo - -By default, only active names will be used, but if the string -'retired' is passed in as an argument, both active and retired -names will be examined. - -=item B<XXX_code2code ( CODE ,CODESET ,CODESET2 )> - -These functions takes a a code from one code set, and returns the -corresponding code from another code set. CODE must exists in the code -set specified by CODESET and must have a corresponding code in the -code set specified by CODESET2 or C<undef> will be returned. - -Both CODESETs must be explicitly entered. - - country_code2code('fin', LOCALE_CODE_ALPHA_3, - LOCALE_CODE_ALPHA_2); - => 'fi' - -Note that this function does NOT support retired codes. - -=item B<all_XXX_codes ( [CODESET] [,'retired'] )> - -These returns a list of all code in the code set. The codes will be -sorted. - -By default, only active codes will be returned, but if the string -'retired' is passed in as an argument, both active and retired -codes will be returned. - -=item B<all_XXX_names ( [CODESET] [,'retired'] )> - -These return a list of all elements names for which there is a -corresponding code in the specified code set. - -The names returned are exactly as they are specified in the standard, -and are sorted. - -Since not all elements are listed in all code sets, the list of -elements may differ depending on the code set specified. - -By default, only active names will be returned, but if the string -'retired' is passed in as an argument, both active and retired -names will be returned. - -=back - -=head1 SEMI-PRIVATE ROUTINES - -Additional semi-private routines which may be used to modify the -internal data are also available. Given their status, they aren't -exported, and so need to be called by prefixing the function name with -the package name. - -These routines do not currently work with retired codes. - -=over 4 - -=item B<MODULE::rename_XXX ( CODE ,NEW_NAME [,CODESET] )> - -These routines are used to change the official name of an element. At -that point, the name returned by the code2XXX routine would be -NEW_NAME instead of the name specified in the standard. - -The original name will remain as an alias. - -For example, the official country name for code 'gb' is 'United -Kingdom'. If you want to change that, you might call: - - Locale::Codes::Country::rename_country('gb', 'Great Britain'); - -This means that calling code2country('gb') will now return 'Great -Britain' instead of 'United Kingdom'. - -If any error occurs, a warning is issued and 0 is returned. An error -occurs if CODE doesn't exist in the specified code set, or if -NEW_NAME is already in use but for a different element. - -If the routine succeeds, 1 is returned. - -=item B<MODULE::add_XXX ( CODE ,NAME [,CODESET] )> - -These routines are used to add a new code and name to the data. - -Both CODE and NAME must be unused in the data set or an error -occurs (though NAME may be used in a different data set). - -For example, to create the fictitious country named "Duchy of -Grand Fenwick" with codes "gf" and "fen", use the following: - - Locale::Codes::Country::add_country("fe","Duchy of Grand Fenwick", - LOCALE_CODE_ALPHA_2); - - Locale::Codes::Country::add_country("fen","Duchy of Grand Fenwick", - LOCALE_CODE_ALPHA_3); - -The return value is 1 on success, 0 on an error. - -=item B<MODULE::delete_XXX ( CODE [,CODESET] )> - -These routines are used to delete a code from the data. - -CODE must refer to an existing code in the code set. - -The return value is 1 on success, 0 on an error. - -=item B<MODULE::add_XXX_alias ( NAME ,NEW_NAME )> - -These routines are used to add a new alias to the data. They do -not alter the return value of the code2XXX function. - -NAME must be an existing element name, and NEW_NAME must -be unused or an error occurs. - -The return value is 1 on success, 0 on an error. - -=item B<MODULE::delete_XXX_alias ( NAME )> - -These routines are used to delete an alias from the data. Once -removed, the element may not be referred to by NAME. - -NAME must be one of a list of at least two names that may be used to -specify an element. If the element may only be referred to by a single -name, you'll need to use the add_XXX_alias function to add a new alias -first, or the remove_XXX function to remove the element entirely. - -If the alias is used as the name in any code set, one of the other -names will be used instead. Predicting exactly which one will -be used requires you to know the order in which the standards -were read, which is not reliable, so you may want to use the -rename_XXX function to force one of the alternate names to be -used. - -The return value is 1 on success, 0 on an error. - -=item B<MODULE::rename_XXX_code ( CODE ,NEW_CODE [,CODESET] )> - -These routines are used to change the official code for an element. At -that point, the code returned by the XXX2code routine would be -NEW_CODE instead of the code specified in the standard. - -NEW_CODE may either be a code that is not in use, or it may be an -alias for CODE (in which case, CODE becomes and alias and NEW_CODE -becomes the "real" code). - -The original code is kept as an alias, so that the code2XXX routines -will work with either the code from the standard or the new code. - -However, the all_XXX_codes routine will only return the codes which -are considered "real" (which means that the list of codes will now -contain NEW_CODE, but will not contain CODE). - -=item B<MODULE::add_XXX_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -These routines add an alias for the code. At that point, NEW_CODE and CODE -will both work in the code2XXX routines. However, the XXX2code routines will -still return the original code. - -=item B<MODULE::delete_XXX_code_alias ( CODE [,CODESET] )> - -These routines delete an alias for the code. - -These will only work if CODE is actually an alias. If it is the "real" -code, it will not be deleted. You will need to use the rename_XXX_code -function to switch the real code with one of the aliases, and then -delete the alias. - -=back - -=head1 KNOWN BUGS AND LIMITATIONS - -=over 4 - -=item B<*> - -Because each code set uses a slightly different list of elements, and -they are not necessarily one-to-one, there may be some confusion -about the relationship between codes from different code sets. - -For example, ISO 3166 assigns one code to the country "United States -Minor Outlying Islands", but the FIPS 10 codes give different codes -to different islands (Baker Island, Howland Island, etc.). - -This may cause some confusion... I've done the best that I could do -to minimize it. - -=item B<*> - -Currently all names must be all ASCII. I plan on relaxing that -limitation in the future. - -=back - -=head1 SEE ALSO - -Locale::Codes - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Changes.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Changes.pod deleted file mode 100644 index 88e91c78488..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/Changes.pod +++ /dev/null @@ -1,570 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::Changes - details changes to Locale::Codes - -=head1 SYNOPSIS - -This describes the changes made to modules in the Locale-Codes -distribution. Major changes are marked with asterisks (*). For the -most part, all modules have remained backward compatible at every -release, but occasionally a change is made which is backward -incompatible. These are marked with an exclamation mark (!). - -As of 3.00, the codes are autogenerated from the standards. With each -release, codes will be re-generated and tested to see if any code -changed. Any time there are any changes to the codes, it will be -flagged below with a change: NEW CODE(s). - -I intend to check for new codes four times a year (March, June, -September, December). I will also check on request, so if a code -changes that you use, feel free to contact me. Any time there are new -codes, I will add them to the module and release a new version. - -=head1 VERSION 3.22 (yyyy-mm-dd; sbeck) - -=head1 VERSION 3.21 (2012-03-01; sbeck) - -NEW CODE(s) - -=head1 VERSION 3.20 (2011-12-01; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<Added limited support for deprecated codes> - -The code2XXX, XXX2code, all_XXX_codes, and all_XXX_names functions -now support retired codes. RT 71124 - -=item B<Fixed capitalization> - -The 'South Sudan' country was all caps. RT 71024 - -=item B<Pod tests off by default> - -The pod tests will not run at install time. RT 71122 - -=item B<Codesets may be specified by name> - -All codesets may be specified by a constant or by their name now. Previously, -they were specified only by a constant. - -=item B<alias_code deprecated> - -The alias_code function exists for backward compatibility. It has been replaced -by rename_country_code . The alias_code function will be removed sometime -after September, 2013 . - -=item B<Code cleanup> - -All work is now done in the central module (Locale::Codes). Previously, some -was still done in the wrapper modules (Locale::Codes::*) but that is gone now. - -=item B<Added LangFam module> - -Added Language Family codes (langfam) as defined in ISO 639-5. - -=back - -=head1 VERSION 3.18 (2011-08-31; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<No longer use CIA data> - -The CIA world added non-standard values, so I no longer use it as -a source of data. Based on a report by Michiel Beijen. - -=back - -=head1 VERSION 3.17 (2011-06-28; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<Added new types of codes> - -Added Language Extension codes (langext) and Language Variation codes -(langvar) as defined in the IANA language registry. - -=item B<Added new codeset(s)> - -Added language codes from ISO 639-5 - -Added language/script codes from the IANA language subtag -registry - -=item B<Bug fixes> - -Fixed an uninitialized value warning. RT 67438 - -Fixed the return value for the all_XXX_codes and all_XXX_names functions. RT 69100 - -=item B<Reorganized code> - -Reorganized modules to move Locale::MODULE to Locale::Codes::MODULE to -allow for cleaner future additions. The original four modules (Locale::Language, -Locale::Currency, Locale::Country, Locale::Script) will continue to work, but -all new sets of codes will be added in the Locale::Codes namespace. - -=back - -=head1 VERSION 3.16 (2011-03-01; sbeck) - -NEW CODE(s) - -=head1 VERSION 3.15 (2010-12-02; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<Minor fixes> - -Added version number to Makefile.PL/Build.PL requirement -for POD testing modules. RT 62247 - -Changed 'use vars' to 'our' - -=back - -=head1 VERSION 3.14 (2010-09-28; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<Bug fixes> - -Stripped out some HTML that got included with some codes. - -=back - -=head1 VERSION 3.13 (2010-06-04; sbeck) - -NEW CODE(s) - -=head1 VERSION 3.12 (2010-04-06; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<Reorganized code> - -Renamed test.pl to testfunc.pl to avoid causing an error -when built as part of perl. - -=back - -=head1 VERSION 3.11 (2010-03-01; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<Added new codeset(s)> - -Added the IANA domain names to Country - -=item B<Bug fixes> - -Fixed a problem that produced warnings with perl 5.11.5. -Jerry D. Hedden - -=back - -=head1 VERSION 3.10 (2010-02-18; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<Reorganized code> - -Moved support files into the Locale::Codes namespace. - -The work done in each of the Locale::XXX modules was virtually -identical to each other. It has all been moved to a central module and -the Locale::XXX modules are now just wrappers. - -=item B<(!) Changed XXX_code2code behavior slightly> - -In previous versions, passing in the same code set for both code set -arguments would automatically return undef. For example: - - country_code2code('bo',LOCALE_CODE_ALPHA_2,LOCALE_CODE_ALPHA_2); - => undef - -This doesn't seem like reasonable behavior, so it has been changed -to allow the same code set: - - country_code2code('bo',LOCALE_CODE_ALPHA_2,LOCALE_CODE_ALPHA_2); - => 'bo' - -Note that if an invalid code is passed in, undef will still be -returned: - - country_code2code('bol',LOCALE_CODE_ALPHA_2,LOCALE_CODE_ALPHA_2); - => undef - -=item B<Added many semi-private routines> - -Previous versions had only two semi-private routines: rename_country -and alias_code which had the ability to modify the internal data in -a couple very limited ways. It was requested (in an anonymous posting -by someone named Steve and also by Steve Hay) that better support -for modifying internal data, so a full set of routines were added. - -The full set of routines includes: - - rename_country - rename_language - rename_currency - rename_script - - add_country - add_language - add_currency - add_script - - delete_country - delete_language - delete_currency - delete_script - - add_country_alias - add_language_alias - add_currency_alias - add_script_alias - - delete_country_alias - delete_language_alias - delete_currency_alias - delete_script_alias - - rename_country_code - rename_language_code - rename_currency_code - rename_script_code - - add_country_code_alias - add_language_code_alias - add_currency_code_alias - add_script_code_alias - - delete_country_code_alias - delete_language_code_alias - delete_currency_code_alias - delete_script_code_alias - -=item B<New aliases> - -Added "UK" alias. Steve Hay - -=back - -=head1 VERSION 3.01 (2010-02-15; sbeck) - -=over 4 - -=item B<Fixed Makefile.PL and Build.PL> - -They now install as core modules as they are supposed to. Reported in -RT 54526 - -=back - -=head1 VERSION 3.00 (2010-02-10; sbeck) - -NEW CODE(s) - -=over 4 - -=item B<New maintainer> - -From 1997 to 2004, Locale::Codes was maintained by Neil -Bowers. Unfortunately, no updates were made from June 2004 to January -2010. During that time, a number of changes have been made to the -standards since then, so the data included was out-of-date. - -I contacted Neil to get his permission to assume maintenance of -the module, and he kindly agreed. - -=item B<(*) (!) All codes are generated from standards> - -All of the values returned by the various functions are now values -directly from the standards. This means that the values returned in -the 2.xx series are not necessarily the same as the values returned -here. - -As an example, the ISO 3166 standard which lists country codes refers -to the country associated with the code "bo" as "Bolivia, -Plurinational State of", so that is what is returned. In the 2.xx -series, "Bolivia" was returned. Also, the country names vary from one -standard to another. So the code "bol" which is maintained by the -United Nations returns the name of the country as "Bolivia -(Plurinational State of)". Some common aliases have been added, so you -can still request a code associated with a county name "Bolivia". - -Since the data comes from the standards, some "incorrect" values are -no longer supported. For example, 2.07 treated "Zaire" as an alias for -"Congo", but the country changed it's name, and "Zaire" is not in the -standard, so it has been dropped in 3.00. - -=item B<Added new codeset(s)> - -FIPS 10 country codes (requested in RT 1755) - -Alpha-3 and Term language codes (requested in RT 11730) - -Numeric currency codes (requested in RT 18797) - -=item B<(*) (!) Locale::Script changed> - -In 2.xx, Locale::Script assigned scripts to country codes, which is NOT -how it is done currently in the standards. It appears that an older version -of ISO 15924 did this, but I haven't found an old version to confirm -that, and in any case, that is not the case in the current standards. - -As a result, the Locale::Script module is completely incompatible with -the 2.xx version with respect to the types of codes it supports. None of -the old codes will work. - -=item B<Added missing functions> - -I've added in some functions which were "missing" previously (since there was -only one set of codes supported, the code2code functions didn't apply): - - language_code2code - currency_code2code - -so the interfaces for each type of codes are consistent. - -=item B<(!) Dropped support for _alias_code> - -In Locale::Country, _alias_code was an allowed, but deprecated function -which was documented to be supported in the 2.xx series. I've removed it. - -=item B<(!) All functions return the standard value> - -code2country (and other equivalent functions) now returns the name of -the country specified in the standard (if the different standards -refer to the country by different variations in the name, the results -will differ based on the CODESET) - -=item B<(!) rename_country function altered> - -The rename_country function from 2.07 would guess the CODESET (unlike -all other functions which used a default of LOCALE_CODE_ALPHA_2). The -guess can cause problems since (with the addition of FIPS) codes may -appear in different codesets for different countries. The behavior has -been changed to be the same as other functions (default to -LOCALE_CODE_ALPHA_2). - -=back - -=head1 VERSION 2.07 (2004-06-10; neilb) - -Made $_ local in the initialization code for each module -change back-propagated from Perl distribution - -Removed two non ISO-8859-1 characters from language names -change back-propagated from Perl distribution - -Added the following aliases, with a test case for each - - Burma added to Myanmar - - French Southern and Antarctic Lands to - French Southern Territories -patch from TJ Mather - -"Canadian Dollar" was misspelled as "Candian Dollar" - - noted by Nick Cabatoff, patch from Michael Hennecke - -Changes to Locale::Country reflecting changes in ISO 3166 - - added Aland Islands (ax, ala, 248) - - YUGOSLAVIA is now SERBIA AND MONTENEGRO - YU => CS - YUG => SCG - 891 => 891 (unchanged) - (YUGOSLAVIA retained as an alias) - - EAST TIMOR changed to TIMOR-LESTE - (old name retained as an alias) - - three letter code for Romania changed from ROM to ROU - -ZAIRE is now CONGO, THE DEMOCRATIC REPUBLIC OF THE - ZR => CD - ZAR => COD - 180 => 180 (unchanged) - (ZAIRE retained as alias) - -=head1 VERSION 2.06 (2002-07-15; neilb) - -The four modules which have data after __DATA__ weren't closing the -DATA filehandle after reading from it, which they should. Bug and -patch from Steve Hay. - -=head1 VERSION 2.05 (2002-07-08; neilb) - -Added three letter codes for the countries that were missing -them. Patch from TJ Mather. - -Documentation bug: one of the examples used => where the -lvalue was a constant, which isn't allowed, unless you -put the () with the constant to force the right interpretation. -Pointed out by TJ Mather and MYT. - -Updated the URL for the appendix in the CIA world factbook. -Patch from TJ Mather. - -=head1 VERSION 2.04 (2002-05-23; neilb) - -Updated according to changes in ISO 3166-1 described -in ISO 3166-1 newsletters V-4 and V-5, dated 2002-05-20: - - Kazakstan is now "Kazakhstan" - - Macau is now "Macao" -The old names are retained as aliases. - -The alpha-2 and alpha-3 codes for East Timor have changed: - tp -> tl - tmp -> tls -the numeric code stays 626. If you want to support the old -codes, you can use the semi-private function alias_code(). - -=head1 VERSION 2.03 (2002-03-24; neilb) - -Fixed a typo in the alias for the Vatican, reported (with patch) -by Philip Newton. - -Added "Moldova" as an alias for "Moldova, Republic of" - -Updated Makefile.PL to include AUTHOR and ABSTRACT - -=head1 VERSION 2.02 (2002-03-09; neilb) - -Added semi-private routine rename_country() to Locale::Country, -based on a patch from Iain Chalmers. - -Added test rename.t for the above function. - -Renamed _alias_code to be alias_code. Have retained the old -name for backwards compatibility. Will remove it when the -major version number next changes. - -=head1 VERSION 2.01 (2002-02-18; neilb) - -Split the documentation for all modules into separate pod files. - -Made sure all =over were =over 4; some were other values. - -The code2code() methods had one more shift than was needed. - -=head1 VERSION 2.00 (2002-02-17; neilb) - -Created Locale::Script which provides an interface to the ISO codes -for identification of scripts (writing scripts, rather than perl style -scripts). The codes are defined by ISO 15924, which is currently in -final draft. Thanks to Jarkko for pointing out this new standard. -All three code sets are supported, and a test-suite added. - -Added support for country name variants to Locale::Country, -so that - country2code('USA') - country2code('United States') - country2code('United States of America') -will all return 'us'. This had been in the LIMITATIONS section since -the first version. Patch from TJ Mather with additional variants from -me. Added test-cases for these. - -Added VERSION to Locale::Constants. Thanks to Jarkko for -pointing that it was missing. - -Should really have bumped major version with previous release, -since there was a change to the API. - -=head1 VERSION 1.06 (2001-03-04; neilb) - -Added Locale::Constants, which defines three symbols for identifying -which codeset is being used: - - LOCALE_CODE_ALPHA_2 - LOCALE_CODE_ALPHA_3 - LOCALE_CODE_NUMERIC - -Updated Locale::Country to support all three code sets defined by ISO -3166. This was requested by Keith Wall. I haven't added multiple -codeset support to the other modules yet - I'll wait until someone -asks for them. - -=head1 VERSION 1.05 (2001-02-13; neilb) - -Added Locale::Currency, contribution from Michael Hennecke. - -Added test suite for it (t/currency.t) and added test cases -to t/all.t for the all_* functions. - -=head1 VERSION 1.04 (2000-12-21; neilb) - -Fixed very minor typos from 1.03! - -=head1 VERSION 1.03 (2000-12-??; neilb) - -Updated Locale::Country: - - fixed spelling of a few countries - - added link to a relevant page from CIA world factbook - -Updated Locale::Language: - - fixed typo in the documentation (ISO 939 should be 639) - -=head1 VERSION 1.02 (2000-05-04; neilb) - -Updated Locale::Country and Locale::Language to reflect changes in the -relevant ISO standards. These mainly reflect languages which are new -to the relevant standard, and changes in the spelling of some country -names. - -Added official URLs for the standards to the SEE ALSO sections of the -doc for each module. - -Thanks to Jarkko Hietaniemi for pointing me at the pages with latest -versions of ISO 3166 and 639. - -=head1 VERSION 1.00 (1998-03-09; neilb) - -Added Locale::Country::_alias_code() so that 'uk' can be added as the -code for "United Kingdom", if you want it. This was prompted by Ed -Jordan. - -Added a new test suite for handling this case, and extended the -existing test-suite to include testing of the case where 'uk' hasn't -been defined as a valid code. - -=head1 VERSION 0.003 (1997-05-09; neilb) - -First public release to CPAN - -=head1 SEE ALSO - -Locale::Codes - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Constants.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Constants.pod deleted file mode 100644 index 78ded778e96..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/Constants.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::Constants - constants for Locale codes - -=head1 DESCRIPTION - -B<Locale::Codes::Constants> defines symbols which are used in the other -modules from the Locale-Codes distribution. - -You shouldn't have to C<use> this module directly yourself - it is -used by the other Locale modules, which in turn export the symbols. - -The constants are documented in each of the Locale modules. - -=head1 KNOWN BUGS AND LIMITATIONS - -None known. - -=head1 SEE ALSO - -Locale::Codes - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut - diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Country.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Country.pod deleted file mode 100644 index c559c37bf4e..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/Country.pod +++ /dev/null @@ -1,214 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::Country - standard codes for country identification - -=head1 SYNOPSIS - - use Locale::Codes::Country; - - $country = code2country('jp' [,CODESET]); # $country gets 'Japan' - $code = country2code('Norway' [,CODESET]); # $code gets 'no' - - @codes = all_country_codes( [CODESET]); - @names = all_country_names(); - - # semi-private routines - Locale::Codes::Country::alias_code('uk' => 'gb'); - Locale::Codes::Country::rename_country('gb' => 'Great Britain'); - -=head1 DESCRIPTION - -The C<Locale::Codes::Country> module provides access to several code sets -that can be used for identifying countries, such as those defined in -ISO 3166-1. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -3166-1 two-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -countries. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $country = code2country('jp','alpha-2'); - $country = code2country('jp',LOCALE_CODE_ALPHA_2); - -The codesets currently supported are: - -=over 4 - -=item B<alpha-2, LOCALE_CODE_ALPHA_2> - -This is the set of two-letter (lowercase) codes from ISO 3166-1, such -as 'tv' for Tuvalu. - -This is the default code set. - -=item B<alpha-3, LOCALE_CODE_ALPHA_3> - -This is the set of three-letter (lowercase) codes from ISO 3166-1, -such as 'brb' for Barbados. These codes are actually defined and -maintained by the U.N. Statistics division. - -=item B<numeric, LOCALE_CODE_NUMERIC> - -This is the set of three-digit numeric codes from ISO 3166-1, such as -064 for Bhutan. These codes are actually defined and maintained by the -U.N. Statistics division. - -If a 2-digit code is entered, it is converted to 3 digits by prepending -a 0. - -=item B<fips-10, LOCALE_CODE_FIPS> - -The FIPS 10 data are two-letter (uppercase) codes assigned by the -National Geospatial-Intelligence Agency. - -=item B<dom, LOCALE_CODE_DOM> - -The IANA is responsible for assigning two-letter (uppercase) top-level -domain names to each country. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2country ( CODE [,CODESET] )> - -=item B<country2code ( NAME [,CODESET] )> - -=item B<country_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_country_codes ( [CODESET] )> - -=item B<all_country_names ( [CODESET] )> - -=item B<Locale::Codes::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Codes::Country::add_country ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Codes::Country::delete_country ( CODE [,CODESET] )> - -=item B<Locale::Codes::Country::add_country_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Codes::Country::delete_country_alias ( NAME )> - -=item B<Locale::Codes::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Country::delete_country_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=item B<alias_code ( ALIAS, CODE [,CODESET] )> - -Version 2.07 included 2 functions for modifying the internal data: -rename_country and alias_code. Both of these could be used only to -modify the internal data for country codes. - -As of 3.10, the internal data for all types of codes can be modified. - -The alias_code function is preserved for backwards compatibility, but -the following two are identical: - - alias_code(ALIAS,CODE [,CODESET]); - rename_country_code(CODE,ALIAS [,CODESET]); - -and the latter should be used for consistency. - -The alias_code function is deprecated and will be removed at some point -in the future. - -B<Note:> this function was previously called _alias_code, but the -leading underscore has been dropped. The old name was supported for -all 2.X releases, but has been dropped as of 3.00. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<Locale::SubCountry> - -ISO codes for country sub-divisions (states, counties, provinces, -etc), as defined in ISO 3166-2. This module is not part of the -Locale-Codes distribution, but is available from CPAN in -CPAN/modules/by-module/Locale/ - -=item B<http://www.iso.org/iso/country_codes> - -Official home page for the ISO 3166 maintenance agency. - -Unfortunately, they do not make the actual ISO available for free, -so I cannot check the alpha-3 and numerical codes here. - -=item B<http://www.iso.org/iso/list-en1-semic-3.txt> - -The source of ISO 3166-1 two-letter codes used by this -module. - -=item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm> - -The source of the official ISO 3166-1 three-letter codes and -three-digit codes. - -For some reason, this table is incomplete! Several countries are -missing from it, and I cannot find them anywhere on the UN site. I -get as much of the data from here as I can. - -=item B<http://earth-info.nga.mil/gns/html/digraphs.htm> - -The official list of the FIPS 10 codes. - -=item B<http://www.iana.org/domains/> - -Official source of the top-level domain names. - -=item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html> - -The World Factbook maintained by the CIA is a potential source of -the data. Unfortunately, it adds/preserves non-standard codes, so it is no -longer used as a source of data. - -=item B<http://www.statoids.com/wab.html> - -Another unofficial source of data. Currently, it is not used to get -data, but the notes and explanatory material were very useful for -understanding discrepancies between the sources. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Currency.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Currency.pod deleted file mode 100644 index a79b811c1d0..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/Currency.pod +++ /dev/null @@ -1,127 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::Currency - standard codes for currency identification - -=head1 SYNOPSIS - - use Locale::Codes::Currency; - - $curr = code2currency('usd'); # $curr gets 'US Dollar' - $code = currency2code('Euro'); # $code gets 'eur' - - @codes = all_currency_codes(); - @names = all_currency_names(); - - -=head1 DESCRIPTION - -The C<Locale::Codes::Currency> module provides access to standard codes used -for identifying currencies and funds, such as those defined in ISO 4217. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -4217 three-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -currencies. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $curr = code2currency('usd','alpha'); - $curr = code2currency('usd',LOCALE_CURR_ALPHA); - -The codesets currently supported are: - -=over 4 - -=item B<alpha, LOCALE_CURR_ALPHA> - -This is a set of three-letter (uppercase) codes from ISO 4217 such -as EUR for Euro. - -Two of the codes specified by the standard (XTS which is reserved -for testing purposes and XXX which is for transactions where no -currency is involved) are omitted. - -This is the default code set. - -=item B<num, LOCALE_CURR_NUMERIC> - -This is the set of three-digit numeric codes from ISO 4217. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2currency ( CODE [,CODESET] )> - -=item B<currency2code ( NAME [,CODESET] )> - -=item B<currency_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_currency_codes ( [CODESET] )> - -=item B<all_currency_names ( [CODESET] )> - -=item B<Locale::Codes::Currency::rename_currency ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Codes::Currency::add_currency ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Codes::Currency::delete_currency ( CODE [,CODESET] )> - -=item B<Locale::Codes::Currency::add_currency_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Codes::Currency::delete_currency_alias ( NAME )> - -=item B<Locale::Codes::Currency::rename_currency_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Currency::add_currency_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Currency::delete_currency_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.iso.org/iso/support/currency_codes_list-1.htm> - -The ISO 4217 data. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001 Michael Hennecke - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/LangExt.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/LangExt.pod deleted file mode 100644 index da1421bcb36..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/LangExt.pod +++ /dev/null @@ -1,116 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::LangExt - standard codes for language extension identification - -=head1 SYNOPSIS - - use Locale::Codes::LangExt; - - $lext = code2langext('acm'); # $lext gets 'Mesopotamian Arabic' - $code = langext2code('Mesopotamian Arabic'); # $code gets 'acm' - - @codes = all_langext_codes(); - @names = all_langext_names(); - -=head1 DESCRIPTION - -The C<Locale::Codes::LangExt> module provides access to standard codes -used for identifying language extensions, such as those as defined in -the IANA language registry. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default IANA -language registry codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -language extensions. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $lext = code2langext('acm','alpha'); - $lext = code2langext('acm',LOCALE_LANGEXT_ALPHA); - -The codesets currently supported are: - -=over 4 - -=item B<alpha> - -This is the set of three-letter (lowercase) codes from the IANA -language registry, such as 'acm' for Mesopotamian Arabic. - -This is the default code set. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2langext ( CODE [,CODESET] )> - -=item B<langext2code ( NAME [,CODESET] )> - -=item B<langext_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_langext_codes ( [CODESET] )> - -=item B<all_langext_names ( [CODESET] )> - -=item B<Locale::Codes::LangExt::rename_langext ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Codes::LangExt::add_langext ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Codes::LangExt::delete_langext ( CODE [,CODESET] )> - -=item B<Locale::Codes::LangExt::add_langext_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Codes::LangExt::delete_langext_alias ( NAME )> - -=item B<Locale::Codes::LangExt::rename_langext_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::LangExt::add_langext_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::LangExt::delete_langext_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.iana.org/assignments/language-subtag-registry> - -The IANA language subtag registry. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 2011-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/LangFam.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/LangFam.pod deleted file mode 100644 index 7faabee5b10..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/LangFam.pod +++ /dev/null @@ -1,116 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::LangFam - standard codes for language extension identification - -=head1 SYNOPSIS - - use Locale::Codes::LangFam; - - $lext = code2langfam('apa'); # $lext gets 'Apache languages' - $code = langfam2code('Apache languages'); # $code gets 'apa' - - @codes = all_langfam_codes(); - @names = all_langfam_names(); - -=head1 DESCRIPTION - -The C<Locale::Codes::LangFam> module provides access to standard codes -used for identifying language families, such as those as defined in -ISO 639-5. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO 639-5 -language family codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -language families. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $lext = code2langfam('apa','alpha'); - $lext = code2langfam('apa',LOCALE_LANGFAM_ALPHA); - -The codesets currently supported are: - -=over 4 - -=item B<alpha> - -This is the set of three-letter (lowercase) codes from ISO 639-5 -such as 'apa' for Apache languages. - -This is the default code set. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2langfam ( CODE [,CODESET] )> - -=item B<langfam2code ( NAME [,CODESET] )> - -=item B<langfam_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_langfam_codes ( [CODESET] )> - -=item B<all_langfam_names ( [CODESET] )> - -=item B<Locale::Codes::LangFam::rename_langfam ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Codes::LangFam::add_langfam ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Codes::LangFam::delete_langfam ( CODE [,CODESET] )> - -=item B<Locale::Codes::LangFam::add_langfam_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Codes::LangFam::delete_langfam_alias ( NAME )> - -=item B<Locale::Codes::LangFam::rename_langfam_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::LangFam::add_langfam_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::LangFam::delete_langfam_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.loc.gov/standards/iso639-5/id.php> - -ISO 639-5 . - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 2011-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/LangVar.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/LangVar.pod deleted file mode 100644 index cb74ab7790d..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/LangVar.pod +++ /dev/null @@ -1,118 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::LangVar - standard codes for language variation identification - -=head1 SYNOPSIS - - use Locale::Codes::LangVar; - - $lvar = code2langvar('acm'); # $lvar gets 'Mesopotamian Arabic' - $code = langvar2code('Mesopotamian Arabic'); # $code gets 'acm' - - @codes = all_langvar_codes(); - @names = all_langvar_names(); - -=head1 DESCRIPTION - -The C<Locale::Codes::LangVar> module provides access to standard codes -used for identifying language variations, such as those as defined in -the IANA language registry. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default IANA -language registry codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -language variations. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $lvar = code2langvar('en','alpha-2'); - $lvar = code2langvar('en',LOCALE_CODE_ALPHA_2); - -The codesets currently supported are: - -=over 4 - -=item B<alpha> - -This is the set of alphanumeric codes from the IANA -language registry, such as 'arevela' for Eastern Armenian. - -This code set is identified with the symbol C<LOCALE_LANGVAR_ALPHA>. - -This is the default code set. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2langvar ( CODE [,CODESET] )> - -=item B<langvar2code ( NAME [,CODESET] )> - -=item B<langvar_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_langvar_codes ( [CODESET] )> - -=item B<all_langvar_names ( [CODESET] )> - -=item B<Locale::Codes::LangVar::rename_langvar ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Codes::LangVar::add_langvar ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Codes::LangVar::delete_langvar ( CODE [,CODESET] )> - -=item B<Locale::Codes::LangVar::add_langvar_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Codes::LangVar::delete_langvar_alias ( NAME )> - -=item B<Locale::Codes::LangVar::rename_langvar_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::LangVar::add_langvar_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::LangVar::delete_langvar_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.iana.org/assignments/language-subtag-registry> - -The IANA language subtag registry. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 2011-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Language.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Language.pod deleted file mode 100644 index 96c10884361..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/Language.pod +++ /dev/null @@ -1,137 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::Language - standard codes for language identification - -=head1 SYNOPSIS - - use Locale::Codes::Language; - - $lang = code2language('en'); # $lang gets 'English' - $code = language2code('French'); # $code gets 'fr' - - @codes = all_language_codes(); - @names = all_language_names(); - -=head1 DESCRIPTION - -The C<Locale::Codes::Language> module provides access to standard codes used -for identifying languages, such as those as defined in ISO 639. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -639 two-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -languages. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $lang = code2language('en','alpha-2'); - $lang = code2language('en',LOCALE_CODE_ALPHA_2); - -The codesets currently supported are: - -=over 4 - -=item B<alpha-2, LOCALE_LANG_ALPHA_2> - -This is the set of two-letter (lowercase) codes from ISO 639-1, such -as 'he' for Hebrew. It also includes additions to this set included -in the IANA language registry. - -This is the default code set. - -=item B<alpha-3, LOCALE_LANG_ALPHA_3> - -This is the set of three-letter (lowercase) bibliographic codes from -ISO 639-2 and 639-5, such as 'heb' for Hebrew. It also includes -additions to this set included in the IANA language registry. - -=item B<term, LOCALE_LANG_TERM> - -This is the set of three-letter (lowercase) terminologic codes from -ISO 639. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2language ( CODE [,CODESET] )> - -=item B<language2code ( NAME [,CODESET] )> - -=item B<language_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_language_codes ( [CODESET] )> - -=item B<all_language_names ( [CODESET] )> - -=item B<Locale::Codes::Language::rename_language ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Codes::Language::add_language ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Codes::Language::delete_language ( CODE [,CODESET] )> - -=item B<Locale::Codes::Language::add_language_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Codes::Language::delete_language_alias ( NAME )> - -=item B<Locale::Codes::Language::rename_language_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Language::add_language_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Language::delete_language_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.loc.gov/standards/iso639-2/> - -Source of the ISO 639-2 codes. - -=item B<http://www.loc.gov/standards/iso639-5/> - -Source of the ISO 639-5 codes. - -=item B<http://www.iana.org/assignments/language-subtag-registry> - -The IANA language subtag registry. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Codes/Script.pod b/Master/tlpkg/tlperl/lib/Locale/Codes/Script.pod deleted file mode 100644 index 7540c553acc..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Codes/Script.pod +++ /dev/null @@ -1,131 +0,0 @@ -=pod - -=head1 NAME - -Locale::Codes::Script - standard codes for script identification - -=head1 SYNOPSIS - - use Locale::Codes::Script; - - $script = code2script('phnx'); # 'Phoenician' - $code = script2code('Phoenician'); # 'Phnx' - $code = script2code('Phoenician', - LOCALE_CODE_NUMERIC); # 115 - - @codes = all_script_codes(); - @scripts = all_script_names(); - -=head1 DESCRIPTION - -The C<Locale::Codes::Script> module provides access to standards codes used -for identifying scripts, such as those defined in ISO 15924. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -15924 four-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -scripts. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $script = code2script('phnx','alpha'); - $script = code2script('phnx',LOCALE_SCRIPT_ALPHA); - -The codesets currently supported are: - -=over 4 - -=item B<alpha, LOCALE_SCRIPT_ALPHA> - -This is a set of four-letter (capitalized) codes from ISO 15924 -such as 'Phnx' for Phoenician. It also includes additions to this -set included in the IANA language registry. - -The Zxxx, Zyyy, and Zzzz codes are not used. - -This is the default code set. - -=item B<num, LOCALE_SCRIPT_NUMERIC> - -This is a set of three-digit numeric codes from ISO 15924 such as 115 -for Phoenician. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2script ( CODE [,CODESET] )> - -=item B<script2code ( NAME [,CODESET] )> - -=item B<script_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_script_codes ( [CODESET] )> - -=item B<all_script_names ( [CODESET] )> - -=item B<Locale::Codes::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Codes::Script::add_script ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Codes::Script::delete_script ( CODE [,CODESET] )> - -=item B<Locale::Codes::Script::add_script_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Codes::Script::delete_script_alias ( NAME )> - -=item B<Locale::Codes::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Codes::Script::delete_script_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.unicode.org/iso15924/> - -Home page for ISO 15924. - -=item B<http://www.iana.org/assignments/language-subtag-registry> - -The IANA language subtag registry. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Country.pod b/Master/tlpkg/tlperl/lib/Locale/Country.pod deleted file mode 100644 index b9ceff31476..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Country.pod +++ /dev/null @@ -1,214 +0,0 @@ -=pod - -=head1 NAME - -Locale::Country - standard codes for country identification - -=head1 SYNOPSIS - - use Locale::Country; - - $country = code2country('jp' [,CODESET]); # $country gets 'Japan' - $code = country2code('Norway' [,CODESET]); # $code gets 'no' - - @codes = all_country_codes( [CODESET]); - @names = all_country_names(); - - # semi-private routines - Locale::Country::alias_code('uk' => 'gb'); - Locale::Country::rename_country('gb' => 'Great Britain'); - -=head1 DESCRIPTION - -The C<Locale::Country> module provides access to several code sets -that can be used for identifying countries, such as those defined in -ISO 3166-1. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -3166-1 two-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -countries. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $country = code2country('jp','alpha-2'); - $country = code2country('jp',LOCALE_CODE_ALPHA_2); - -The codesets currently supported are: - -=over 4 - -=item B<alpha-2, LOCALE_CODE_ALPHA_2> - -This is the set of two-letter (lowercase) codes from ISO 3166-1, such -as 'tv' for Tuvalu. - -This is the default code set. - -=item B<alpha-3, LOCALE_CODE_ALPHA_3> - -This is the set of three-letter (lowercase) codes from ISO 3166-1, -such as 'brb' for Barbados. These codes are actually defined and -maintained by the U.N. Statistics division. - -=item B<numeric, LOCALE_CODE_NUMERIC> - -This is the set of three-digit numeric codes from ISO 3166-1, such as -064 for Bhutan. These codes are actually defined and maintained by the -U.N. Statistics division. - -If a 2-digit code is entered, it is converted to 3 digits by prepending -a 0. - -=item B<fips-10, LOCALE_CODE_FIPS> - -The FIPS 10 data are two-letter (uppercase) codes assigned by the -National Geospatial-Intelligence Agency. - -=item B<dom, LOCALE_CODE_DOM> - -The IANA is responsible for assigning two-letter (uppercase) top-level -domain names to each country. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2country ( CODE [,CODESET] )> - -=item B<country2code ( NAME [,CODESET] )> - -=item B<country_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_country_codes ( [CODESET] )> - -=item B<all_country_names ( [CODESET] )> - -=item B<Locale::Country::rename_country ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Country::add_country ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Country::delete_country ( CODE [,CODESET] )> - -=item B<Locale::Country::add_country_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Country::delete_country_alias ( NAME )> - -=item B<Locale::Country::rename_country_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Country::add_country_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Country::delete_country_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=item B<alias_code ( ALIAS, CODE [,CODESET] )> - -Version 2.07 included 2 functions for modifying the internal data: -rename_country and alias_code. Both of these could be used only to -modify the internal data for country codes. - -As of 3.10, the internal data for all types of codes can be modified. - -The alias_code function is preserved for backwards compatibility, but -the following two are identical: - - alias_code(ALIAS,CODE [,CODESET]); - rename_country_code(CODE,ALIAS [,CODESET]); - -and the latter should be used for consistency. - -The alias_code function is deprecated and will be removed at some point -in the future. - -B<Note:> this function was previously called _alias_code, but the -leading underscore has been dropped. The old name was supported for -all 2.X releases, but has been dropped as of 3.00. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<Locale::SubCountry> - -ISO codes for country sub-divisions (states, counties, provinces, -etc), as defined in ISO 3166-2. This module is not part of the -Locale-Codes distribution, but is available from CPAN in -CPAN/modules/by-module/Locale/ - -=item B<http://www.iso.org/iso/country_codes> - -Official home page for the ISO 3166 maintenance agency. - -Unfortunately, they do not make the actual ISO available for free, -so I cannot check the alpha-3 and numerical codes here. - -=item B<http://www.iso.org/iso/list-en1-semic-3.txt> - -The source of ISO 3166-1 two-letter codes used by this -module. - -=item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm> - -The source of the official ISO 3166-1 three-letter codes and -three-digit codes. - -For some reason, this table is incomplete! Several countries are -missing from it, and I cannot find them anywhere on the UN site. I -get as much of the data from here as I can. - -=item B<http://earth-info.nga.mil/gns/html/digraphs.htm> - -The official list of the FIPS 10 codes. - -=item B<http://www.iana.org/domains/> - -Official source of the top-level domain names. - -=item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html> - -The World Factbook maintained by the CIA is a potential source of -the data. Unfortunately, it adds/preserves non-standard codes, so it is no -longer used as a source of data. - -=item B<http://www.statoids.com/wab.html> - -Another unofficial source of data. Currently, it is not used to get -data, but the notes and explanatory material were very useful for -understanding discrepancies between the sources. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Currency.pod b/Master/tlpkg/tlperl/lib/Locale/Currency.pod deleted file mode 100644 index a4156eef4c3..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Currency.pod +++ /dev/null @@ -1,127 +0,0 @@ -=pod - -=head1 NAME - -Locale::Currency - standard codes for currency identification - -=head1 SYNOPSIS - - use Locale::Currency; - - $curr = code2currency('usd'); # $curr gets 'US Dollar' - $code = currency2code('Euro'); # $code gets 'eur' - - @codes = all_currency_codes(); - @names = all_currency_names(); - - -=head1 DESCRIPTION - -The C<Locale::Currency> module provides access to standard codes used -for identifying currencies and funds, such as those defined in ISO 4217. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -4217 three-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -currencies. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $curr = code2currency('usd','alpha'); - $curr = code2currency('usd',LOCALE_CURR_ALPHA); - -The codesets currently supported are: - -=over 4 - -=item B<alpha, LOCALE_CURR_ALPHA> - -This is a set of three-letter (uppercase) codes from ISO 4217 such -as EUR for Euro. - -Two of the codes specified by the standard (XTS which is reserved -for testing purposes and XXX which is for transactions where no -currency is involved) are omitted. - -This is the default code set. - -=item B<num, LOCALE_CURR_NUMERIC> - -This is the set of three-digit numeric codes from ISO 4217. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2currency ( CODE [,CODESET] )> - -=item B<currency2code ( NAME [,CODESET] )> - -=item B<currency_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_currency_codes ( [CODESET] )> - -=item B<all_currency_names ( [CODESET] )> - -=item B<Locale::Currency::rename_currency ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Currency::add_currency ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Currency::delete_currency ( CODE [,CODESET] )> - -=item B<Locale::Currency::add_currency_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Currency::delete_currency_alias ( NAME )> - -=item B<Locale::Currency::rename_currency_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Currency::add_currency_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Currency::delete_currency_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.iso.org/iso/support/currency_codes_list-1.htm> - -The ISO 4217 data. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001 Michael Hennecke - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Language.pod b/Master/tlpkg/tlperl/lib/Locale/Language.pod deleted file mode 100644 index c6a25032735..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Language.pod +++ /dev/null @@ -1,137 +0,0 @@ -=pod - -=head1 NAME - -Locale::Language - standard codes for language identification - -=head1 SYNOPSIS - - use Locale::Language; - - $lang = code2language('en'); # $lang gets 'English' - $code = language2code('French'); # $code gets 'fr' - - @codes = all_language_codes(); - @names = all_language_names(); - -=head1 DESCRIPTION - -The C<Locale::Language> module provides access to standard codes used -for identifying languages, such as those as defined in ISO 639. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -639 two-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -languages. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $lang = code2language('en','alpha-2'); - $lang = code2language('en',LOCALE_CODE_ALPHA_2); - -The codesets currently supported are: - -=over 4 - -=item B<alpha-2, LOCALE_LANG_ALPHA_2> - -This is the set of two-letter (lowercase) codes from ISO 639-1, such -as 'he' for Hebrew. It also includes additions to this set included -in the IANA language registry. - -This is the default code set. - -=item B<alpha-3, LOCALE_LANG_ALPHA_3> - -This is the set of three-letter (lowercase) bibliographic codes from -ISO 639-2 and 639-5, such as 'heb' for Hebrew. It also includes -additions to this set included in the IANA language registry. - -=item B<term, LOCALE_LANG_TERM> - -This is the set of three-letter (lowercase) terminologic codes from -ISO 639. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2language ( CODE [,CODESET] )> - -=item B<language2code ( NAME [,CODESET] )> - -=item B<language_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_language_codes ( [CODESET] )> - -=item B<all_language_names ( [CODESET] )> - -=item B<Locale::Language::rename_language ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Language::add_language ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Language::delete_language ( CODE [,CODESET] )> - -=item B<Locale::Language::add_language_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Language::delete_language_alias ( NAME )> - -=item B<Locale::Language::rename_language_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Language::add_language_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Language::delete_language_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.loc.gov/standards/iso639-2/> - -Source of the ISO 639-2 codes. - -=item B<http://www.loc.gov/standards/iso639-5/> - -Source of the ISO 639-5 codes. - -=item B<http://www.iana.org/assignments/language-subtag-registry> - -The IANA language subtag registry. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Maketext.pod b/Master/tlpkg/tlperl/lib/Locale/Maketext.pod deleted file mode 100644 index 3ef9c3a5a9b..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Maketext.pod +++ /dev/null @@ -1,1354 +0,0 @@ - -# Time-stamp: "2004-01-11 18:35:34 AST" - -=head1 NAME - -Locale::Maketext - framework for localization - -=head1 SYNOPSIS - - package MyProgram; - use strict; - use MyProgram::L10N; - # ...which inherits from Locale::Maketext - my $lh = MyProgram::L10N->get_handle() || die "What language?"; - ... - # And then any messages your program emits, like: - warn $lh->maketext( "Can't open file [_1]: [_2]\n", $f, $! ); - ... - -=head1 DESCRIPTION - -It is a common feature of applications (whether run directly, -or via the Web) for them to be "localized" -- i.e., for them -to a present an English interface to an English-speaker, a German -interface to a German-speaker, and so on for all languages it's -programmed with. Locale::Maketext -is a framework for software localization; it provides you with the -tools for organizing and accessing the bits of text and text-processing -code that you need for producing localized applications. - -In order to make sense of Maketext and how all its -components fit together, you should probably -go read L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>, and -I<then> read the following documentation. - -You may also want to read over the source for C<File::Findgrep> -and its constituent modules -- they are a complete (if small) -example application that uses Maketext. - -=head1 QUICK OVERVIEW - -The basic design of Locale::Maketext is object-oriented, and -Locale::Maketext is an abstract base class, from which you -derive a "project class". -The project class (with a name like "TkBocciBall::Localize", -which you then use in your module) is in turn the base class -for all the "language classes" for your project -(with names "TkBocciBall::Localize::it", -"TkBocciBall::Localize::en", -"TkBocciBall::Localize::fr", etc.). - -A language class is -a class containing a lexicon of phrases as class data, -and possibly also some methods that are of use in interpreting -phrases in the lexicon, or otherwise dealing with text in that -language. - -An object belonging to a language class is called a "language -handle"; it's typically a flyweight object. - -The normal course of action is to call: - - use TkBocciBall::Localize; # the localization project class - $lh = TkBocciBall::Localize->get_handle(); - # Depending on the user's locale, etc., this will - # make a language handle from among the classes available, - # and any defaults that you declare. - die "Couldn't make a language handle??" unless $lh; - -From then on, you use the C<maketext> function to access -entries in whatever lexicon(s) belong to the language handle -you got. So, this: - - print $lh->maketext("You won!"), "\n"; - -...emits the right text for this language. If the object -in C<$lh> belongs to class "TkBocciBall::Localize::fr" and -%TkBocciBall::Localize::fr::Lexicon contains C<("You won!" -=E<gt> "Tu as gagnE<eacute>!")>, then the above -code happily tells the user "Tu as gagnE<eacute>!". - -=head1 METHODS - -Locale::Maketext offers a variety of methods, which fall -into three categories: - -=over - -=item * - -Methods to do with constructing language handles. - -=item * - -C<maketext> and other methods to do with accessing %Lexicon data -for a given language handle. - -=item * - -Methods that you may find it handy to use, from routines of -yours that you put in %Lexicon entries. - -=back - -These are covered in the following section. - -=head2 Construction Methods - -These are to do with constructing a language handle: - -=over - -=item * - -$lh = YourProjClass->get_handle( ...langtags... ) || die "lg-handle?"; - -This tries loading classes based on the language-tags you give (like -C<("en-US", "sk", "kon", "es-MX", "ja", "i-klingon")>, and for the first class -that succeeds, returns YourProjClass::I<language>->new(). - -If it runs thru the entire given list of language-tags, and finds no classes -for those exact terms, it then tries "superordinate" language classes. -So if no "en-US" class (i.e., YourProjClass::en_us) -was found, nor classes for anything else in that list, we then try -its superordinate, "en" (i.e., YourProjClass::en), and so on thru -the other language-tags in the given list: "es". -(The other language-tags in our example list: -happen to have no superordinates.) - -If none of those language-tags leads to loadable classes, we then -try classes derived from YourProjClass->fallback_languages() and -then if nothing comes of that, we use classes named by -YourProjClass->fallback_language_classes(). Then in the (probably -quite unlikely) event that that fails, we just return undef. - -=item * - -$lh = YourProjClass->get_handleB<()> || die "lg-handle?"; - -When C<get_handle> is called with an empty parameter list, magic happens: - -If C<get_handle> senses that it's running in program that was -invoked as a CGI, then it tries to get language-tags out of the -environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that -those were the languages passed as parameters to C<get_handle>. - -Otherwise (i.e., if not a CGI), this tries various OS-specific ways -to get the language-tags for the current locale/language, and then -pretends that those were the value(s) passed to C<get_handle>. - -Currently this OS-specific stuff consists of looking in the environment -variables "LANG" and "LANGUAGE"; and on MSWin machines (where those -variables are typically unused), this also tries using -the module Win32::Locale to get a language-tag for whatever language/locale -is currently selected in the "Regional Settings" (or "International"?) -Control Panel. I welcome further -suggestions for making this do the Right Thing under other operating -systems that support localization. - -If you're using localization in an application that keeps a configuration -file, you might consider something like this in your project class: - - sub get_handle_via_config { - my $class = $_[0]; - my $chosen_language = $Config_settings{'language'}; - my $lh; - if($chosen_language) { - $lh = $class->get_handle($chosen_language) - || die "No language handle for \"$chosen_language\"" - . " or the like"; - } else { - # Config file missing, maybe? - $lh = $class->get_handle() - || die "Can't get a language handle"; - } - return $lh; - } - -=item * - -$lh = YourProjClass::langname->new(); - -This constructs a language handle. You usually B<don't> call this -directly, but instead let C<get_handle> find a language class to C<use> -and to then call ->new on. - -=item * - -$lh->init(); - -This is called by ->new to initialize newly-constructed language handles. -If you define an init method in your class, remember that it's usually -considered a good idea to call $lh->SUPER::init in it (presumably at the -beginning), so that all classes get a chance to initialize a new object -however they see fit. - -=item * - -YourProjClass->fallback_languages() - -C<get_handle> appends the return value of this to the end of -whatever list of languages you pass C<get_handle>. Unless -you override this method, your project class -will inherit Locale::Maketext's C<fallback_languages>, which -currently returns C<('i-default', 'en', 'en-US')>. -("i-default" is defined in RFC 2277). - -This method (by having it return the name -of a language-tag that has an existing language class) -can be used for making sure that -C<get_handle> will always manage to construct a language -handle (assuming your language classes are in an appropriate -@INC directory). Or you can use the next method: - -=item * - -YourProjClass->fallback_language_classes() - -C<get_handle> appends the return value of this to the end -of the list of classes it will try using. Unless -you override this method, your project class -will inherit Locale::Maketext's C<fallback_language_classes>, -which currently returns an empty list, C<()>. -By setting this to some value (namely, the name of a loadable -language class), you can be sure that -C<get_handle> will always manage to construct a language -handle. - -=back - -=head2 The "maketext" Method - -This is the most important method in Locale::Maketext: - - $text = $lh->maketext(I<key>, ...parameters for this phrase...); - -This looks in the %Lexicon of the language handle -$lh and all its superclasses, looking -for an entry whose key is the string I<key>. Assuming such -an entry is found, various things then happen, depending on the -value found: - -If the value is a scalarref, the scalar is dereferenced and returned -(and any parameters are ignored). - -If the value is a coderef, we return &$value($lh, ...parameters...). - -If the value is a string that I<doesn't> look like it's in Bracket Notation, -we return it (after replacing it with a scalarref, in its %Lexicon). - -If the value I<does> look like it's in Bracket Notation, then we compile -it into a sub, replace the string in the %Lexicon with the new coderef, -and then we return &$new_sub($lh, ...parameters...). - -Bracket Notation is discussed in a later section. Note -that trying to compile a string into Bracket Notation can throw -an exception if the string is not syntactically valid (say, by not -balancing brackets right.) - -Also, calling &$coderef($lh, ...parameters...) can throw any sort of -exception (if, say, code in that sub tries to divide by zero). But -a very common exception occurs when you have Bracket -Notation text that says to call a method "foo", but there is no such -method. (E.g., "You have [quaB<tn>,_1,ball]." will throw an exception -on trying to call $lh->quaB<tn>($_[1],'ball') -- you presumably meant -"quant".) C<maketext> catches these exceptions, but only to make the -error message more readable, at which point it rethrows the exception. - -An exception I<may> be thrown if I<key> is not found in any -of $lh's %Lexicon hashes. What happens if a key is not found, -is discussed in a later section, "Controlling Lookup Failure". - -Note that you might find it useful in some cases to override -the C<maketext> method with an "after method", if you want to -translate encodings, or even scripts: - - package YrProj::zh_cn; # Chinese with PRC-style glyphs - use base ('YrProj::zh_tw'); # Taiwan-style - sub maketext { - my $self = shift(@_); - my $value = $self->maketext(@_); - return Chineeze::taiwan2mainland($value); - } - -Or you may want to override it with something that traps -any exceptions, if that's critical to your program: - - sub maketext { - my($lh, @stuff) = @_; - my $out; - eval { $out = $lh->SUPER::maketext(@stuff) }; - return $out unless $@; - ...otherwise deal with the exception... - } - -Other than those two situations, I don't imagine that -it's useful to override the C<maketext> method. (If -you run into a situation where it is useful, I'd be -interested in hearing about it.) - -=over - -=item $lh->fail_with I<or> $lh->fail_with(I<PARAM>) - -=item $lh->failure_handler_auto - -These two methods are discussed in the section "Controlling -Lookup Failure". - -=back - -=head2 Utility Methods - -These are methods that you may find it handy to use, generally -from %Lexicon routines of yours (whether expressed as -Bracket Notation or not). - -=over - -=item $language->quant($number, $singular) - -=item $language->quant($number, $singular, $plural) - -=item $language->quant($number, $singular, $plural, $negative) - -This is generally meant to be called from inside Bracket Notation -(which is discussed later), as in - - "Your search matched [quant,_1,document]!" - -It's for I<quantifying> a noun (i.e., saying how much of it there is, -while giving the correct form of it). The behavior of this method is -handy for English and a few other Western European languages, and you -should override it for languages where it's not suitable. You can feel -free to read the source, but the current implementation is basically -as this pseudocode describes: - - if $number is 0 and there's a $negative, - return $negative; - elsif $number is 1, - return "1 $singular"; - elsif there's a $plural, - return "$number $plural"; - else - return "$number " . $singular . "s"; - # - # ...except that we actually call numf to - # stringify $number before returning it. - -So for English (with Bracket Notation) -C<"...[quant,_1,file]..."> is fine (for 0 it returns "0 files", -for 1 it returns "1 file", and for more it returns "2 files", etc.) - -But for "directory", you'd want C<"[quant,_1,directory,directories]"> -so that our elementary C<quant> method doesn't think that the -plural of "directory" is "directorys". And you might find that the -output may sound better if you specify a negative form, as in: - - "[quant,_1,file,files,No files] matched your query.\n" - -Remember to keep in mind verb agreement (or adjectives too, in -other languages), as in: - - "[quant,_1,document] were matched.\n" - -Because if _1 is one, you get "1 document B<were> matched". -An acceptable hack here is to do something like this: - - "[quant,_1,document was, documents were] matched.\n" - -=item $language->numf($number) - -This returns the given number formatted nicely according to -this language's conventions. Maketext's default method is -mostly to just take the normal string form of the number -(applying sprintf "%G" for only very large numbers), and then -to add commas as necessary. (Except that -we apply C<tr/,./.,/> if $language->{'numf_comma'} is true; -that's a bit of a hack that's useful for languages that express -two million as "2.000.000" and not as "2,000,000"). - -If you want anything fancier, consider overriding this with something -that uses L<Number::Format|Number::Format>, or does something else -entirely. - -Note that numf is called by quant for stringifying all quantifying -numbers. - -=item $language->numerate($number, $singular, $plural, $negative) - -This returns the given noun form which is appropriate for the quantity -C<$number> according to this language's conventions. C<numerate> is -used internally by C<quant> to quantify nouns. Use it directly -- -usually from bracket notation -- to avoid C<quant>'s implicit call to -C<numf> and output of a numeric quantity. - -=item $language->sprintf($format, @items) - -This is just a wrapper around Perl's normal C<sprintf> function. -It's provided so that you can use "sprintf" in Bracket Notation: - - "Couldn't access datanode [sprintf,%10x=~[%s~],_1,_2]!\n" - -returning... - - Couldn't access datanode Stuff=[thangamabob]! - -=item $language->language_tag() - -Currently this just takes the last bit of C<ref($language)>, turns -underscores to dashes, and returns it. So if $language is -an object of class Hee::HOO::Haw::en_us, $language->language_tag() -returns "en-us". (Yes, the usual representation for that language -tag is "en-US", but case is I<never> considered meaningful in -language-tag comparison.) - -You may override this as you like; Maketext doesn't use it for -anything. - -=item $language->encoding() - -Currently this isn't used for anything, but it's provided -(with default value of -C<(ref($language) && $language-E<gt>{'encoding'})) or "iso-8859-1"> -) as a sort of suggestion that it may be useful/necessary to -associate encodings with your language handles (whether on a -per-class or even per-handle basis.) - -=back - -=head2 Language Handle Attributes and Internals - -A language handle is a flyweight object -- i.e., it doesn't (necessarily) -carry any data of interest, other than just being a member of -whatever class it belongs to. - -A language handle is implemented as a blessed hash. Subclasses of yours -can store whatever data you want in the hash. Currently the only hash -entry used by any crucial Maketext method is "fail", so feel free to -use anything else as you like. - -B<Remember: Don't be afraid to read the Maketext source if there's -any point on which this documentation is unclear.> This documentation -is vastly longer than the module source itself. - -=over - -=back - -=head1 LANGUAGE CLASS HIERARCHIES - -These are Locale::Maketext's assumptions about the class -hierarchy formed by all your language classes: - -=over - -=item * - -You must have a project base class, which you load, and -which you then use as the first argument in -the call to YourProjClass->get_handle(...). It should derive -(whether directly or indirectly) from Locale::Maketext. -It B<doesn't matter> how you name this class, although assuming this -is the localization component of your Super Mega Program, -good names for your project class might be -SuperMegaProgram::Localization, SuperMegaProgram::L10N, -SuperMegaProgram::I18N, SuperMegaProgram::International, -or even SuperMegaProgram::Languages or SuperMegaProgram::Messages. - -=item * - -Language classes are what YourProjClass->get_handle will try to load. -It will look for them by taking each language-tag (B<skipping> it -if it doesn't look like a language-tag or locale-tag!), turning it to -all lowercase, turning dashes to underscores, and appending it -to YourProjClass . "::". So this: - - $lh = YourProjClass->get_handle( - 'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized' - ); - -will try loading the classes -YourProjClass::en_us (note lowercase!), YourProjClass::fr, -YourProjClass::kon, -YourProjClass::i_klingon -and YourProjClass::i_klingon_romanized. (And it'll stop at the -first one that actually loads.) - -=item * - -I assume that each language class derives (directly or indirectly) -from your project class, and also defines its @ISA, its %Lexicon, -or both. But I anticipate no dire consequences if these assumptions -do not hold. - -=item * - -Language classes may derive from other language classes (although they -should have "use I<Thatclassname>" or "use base qw(I<...classes...>)"). -They may derive from the project -class. They may derive from some other class altogether. Or via -multiple inheritance, it may derive from any mixture of these. - -=item * - -I foresee no problems with having multiple inheritance in -your hierarchy of language classes. (As usual, however, Perl will -complain bitterly if you have a cycle in the hierarchy: i.e., if -any class is its own ancestor.) - -=back - -=head1 ENTRIES IN EACH LEXICON - -A typical %Lexicon entry is meant to signify a phrase, -taking some number (0 or more) of parameters. An entry -is meant to be accessed by via -a string I<key> in $lh->maketext(I<key>, ...parameters...), -which should return a string that is generally meant for -be used for "output" to the user -- regardless of whether -this actually means printing to STDOUT, writing to a file, -or putting into a GUI widget. - -While the key must be a string value (since that's a basic -restriction that Perl places on hash keys), the value in -the lexicon can currently be of several types: -a defined scalar, scalarref, or coderef. The use of these is -explained above, in the section 'The "maketext" Method', and -Bracket Notation for strings is discussed in the next section. - -While you can use arbitrary unique IDs for lexicon keys -(like "_min_larger_max_error"), it is often -useful for if an entry's key is itself a valid value, like -this example error message: - - "Minimum ([_1]) is larger than maximum ([_2])!\n", - -Compare this code that uses an arbitrary ID... - - die $lh->maketext( "_min_larger_max_error", $min, $max ) - if $min > $max; - -...to this code that uses a key-as-value: - - die $lh->maketext( - "Minimum ([_1]) is larger than maximum ([_2])!\n", - $min, $max - ) if $min > $max; - -The second is, in short, more readable. In particular, it's obvious -that the number of parameters you're feeding to that phrase (two) is -the number of parameters that it I<wants> to be fed. (Since you see -_1 and a _2 being used in the key there.) - -Also, once a project is otherwise -complete and you start to localize it, you can scrape together -all the various keys you use, and pass it to a translator; and then -the translator's work will go faster if what he's presented is this: - - "Minimum ([_1]) is larger than maximum ([_2])!\n", - => "", # fill in something here, Jacques! - -rather than this more cryptic mess: - - "_min_larger_max_error" - => "", # fill in something here, Jacques - -I think that keys as lexicon values makes the completed lexicon -entries more readable: - - "Minimum ([_1]) is larger than maximum ([_2])!\n", - => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\n", - -Also, having valid values as keys becomes very useful if you set -up an _AUTO lexicon. _AUTO lexicons are discussed in a later -section. - -I almost always use keys that are themselves -valid lexicon values. One notable exception is when the value is -quite long. For example, to get the screenful of data that -a command-line program might return when given an unknown switch, -I often just use a brief, self-explanatory key such as "_USAGE_MESSAGE". At that point I then go -and immediately to define that lexicon entry in the -ProjectClass::L10N::en lexicon (since English is always my "project -language"): - - '_USAGE_MESSAGE' => <<'EOSTUFF', - ...long long message... - EOSTUFF - -and then I can use it as: - - getopt('oDI', \%opts) or die $lh->maketext('_USAGE_MESSAGE'); - -Incidentally, -note that each class's C<%Lexicon> inherits-and-extends -the lexicons in its superclasses. This is not because these are -special hashes I<per se>, but because you access them via the -C<maketext> method, which looks for entries across all the -C<%Lexicon> hashes in a language class I<and> all its ancestor classes. -(This is because the idea of "class data" isn't directly implemented -in Perl, but is instead left to individual class-systems to implement -as they see fit..) - -Note that you may have things stored in a lexicon -besides just phrases for output: for example, if your program -takes input from the keyboard, asking a "(Y/N)" question, -you probably need to know what the equivalent of "Y[es]/N[o]" is -in whatever language. You probably also need to know what -the equivalents of the answers "y" and "n" are. You can -store that information in the lexicon (say, under the keys -"~answer_y" and "~answer_n", and the long forms as -"~answer_yes" and "~answer_no", where "~" is just an ad-hoc -character meant to indicate to programmers/translators that -these are not phrases for output). - -Or instead of storing this in the language class's lexicon, -you can (and, in some cases, really should) represent the same bit -of knowledge as code in a method in the language class. (That -leaves a tidy distinction between the lexicon as the things we -know how to I<say>, and the rest of the things in the lexicon class -as things that we know how to I<do>.) Consider -this example of a processor for responses to French "oui/non" -questions: - - sub y_or_n { - return undef unless defined $_[1] and length $_[1]; - my $answer = lc $_[1]; # smash case - return 1 if $answer eq 'o' or $answer eq 'oui'; - return 0 if $answer eq 'n' or $answer eq 'non'; - return undef; - } - -...which you'd then call in a construct like this: - - my $response; - until(defined $response) { - print $lh->maketext("Open the pod bay door (y/n)? "); - $response = $lh->y_or_n( get_input_from_keyboard_somehow() ); - } - if($response) { $pod_bay_door->open() } - else { $pod_bay_door->leave_closed() } - -Other data worth storing in a lexicon might be things like -filenames for language-targetted resources: - - ... - "_main_splash_png" - => "/styles/en_us/main_splash.png", - "_main_splash_imagemap" - => "/styles/en_us/main_splash.incl", - "_general_graphics_path" - => "/styles/en_us/", - "_alert_sound" - => "/styles/en_us/hey_there.wav", - "_forward_icon" - => "left_arrow.png", - "_backward_icon" - => "right_arrow.png", - # In some other languages, left equals - # BACKwards, and right is FOREwards. - ... - -You might want to do the same thing for expressing key bindings -or the like (since hardwiring "q" as the binding for the function -that quits a screen/menu/program is useful only if your language -happens to associate "q" with "quit"!) - -=head1 BRACKET NOTATION - -Bracket Notation is a crucial feature of Locale::Maketext. I mean -Bracket Notation to provide a replacement for the use of sprintf formatting. -Everything you do with Bracket Notation could be done with a sub block, -but bracket notation is meant to be much more concise. - -Bracket Notation is a like a miniature "template" system (in the sense -of L<Text::Template|Text::Template>, not in the sense of C++ templates), -where normal text is passed thru basically as is, but text in special -regions is specially interpreted. In Bracket Notation, you use square brackets ("[...]"), -not curly braces ("{...}") to note sections that are specially interpreted. - -For example, here all the areas that are taken literally are underlined with -a "^", and all the in-bracket special regions are underlined with an X: - - "Minimum ([_1]) is larger than maximum ([_2])!\n", - ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^ - -When that string is compiled from bracket notation into a real Perl sub, -it's basically turned into: - - sub { - my $lh = $_[0]; - my @params = @_; - return join '', - "Minimum (", - ...some code here... - ") is larger than maximum (", - ...some code here... - ")!\n", - } - # to be called by $lh->maketext(KEY, params...) - -In other words, text outside bracket groups is turned into string -literals. Text in brackets is rather more complex, and currently follows -these rules: - -=over - -=item * - -Bracket groups that are empty, or which consist only of whitespace, -are ignored. (Examples: "[]", "[ ]", or a [ and a ] with returns -and/or tabs and/or spaces between them. - -Otherwise, each group is taken to be a comma-separated group of items, -and each item is interpreted as follows: - -=item * - -An item that is "_I<digits>" or "_-I<digits>" is interpreted as -$_[I<value>]. I.e., "_1" becomes with $_[1], and "_-3" is interpreted -as $_[-3] (in which case @_ should have at least three elements in it). -Note that $_[0] is the language handle, and is typically not named -directly. - -=item * - -An item "_*" is interpreted to mean "all of @_ except $_[0]". -I.e., C<@_[1..$#_]>. Note that this is an empty list in the case -of calls like $lh->maketext(I<key>) where there are no -parameters (except $_[0], the language handle). - -=item * - -Otherwise, each item is interpreted as a string literal. - -=back - -The group as a whole is interpreted as follows: - -=over - -=item * - -If the first item in a bracket group looks like a method name, -then that group is interpreted like this: - - $lh->that_method_name( - ...rest of items in this group... - ), - -=item * - -If the first item in a bracket group is "*", it's taken as shorthand -for the so commonly called "quant" method. Similarly, if the first -item in a bracket group is "#", it's taken to be shorthand for -"numf". - -=item * - -If the first item in a bracket group is the empty-string, or "_*" -or "_I<digits>" or "_-I<digits>", then that group is interpreted -as just the interpolation of all its items: - - join('', - ...rest of items in this group... - ), - -Examples: "[_1]" and "[,_1]", which are synonymous; and -"C<[,ID-(,_4,-,_2,)]>", which compiles as -C<join "", "ID-(", $_[4], "-", $_[2], ")">. - -=item * - -Otherwise this bracket group is invalid. For example, in the group -"[!@#,whatever]", the first item C<"!@#"> is neither the empty-string, -"_I<number>", "_-I<number>", "_*", nor a valid method name; and so -Locale::Maketext will throw an exception of you try compiling an -expression containing this bracket group. - -=back - -Note, incidentally, that items in each group are comma-separated, -not C</\s*,\s*/>-separated. That is, you might expect that this -bracket group: - - "Hoohah [foo, _1 , bar ,baz]!" - -would compile to this: - - sub { - my $lh = $_[0]; - return join '', - "Hoohah ", - $lh->foo( $_[1], "bar", "baz"), - "!", - } - -But it actually compiles as this: - - sub { - my $lh = $_[0]; - return join '', - "Hoohah ", - $lh->foo(" _1 ", " bar ", "baz"), # note the <space> in " bar " - "!", - } - -In the notation discussed so far, the characters "[" and "]" are given -special meaning, for opening and closing bracket groups, and "," has -a special meaning inside bracket groups, where it separates items in the -group. This begs the question of how you'd express a literal "[" or -"]" in a Bracket Notation string, and how you'd express a literal -comma inside a bracket group. For this purpose I've adopted "~" (tilde) -as an escape character: "~[" means a literal '[' character anywhere -in Bracket Notation (i.e., regardless of whether you're in a bracket -group or not), and ditto for "~]" meaning a literal ']', and "~," meaning -a literal comma. (Altho "," means a literal comma outside of -bracket groups -- it's only inside bracket groups that commas are special.) - -And on the off chance you need a literal tilde in a bracket expression, -you get it with "~~". - -Currently, an unescaped "~" before a character -other than a bracket or a comma is taken to mean just a "~" and that -character. I.e., "~X" means the same as "~~X" -- i.e., one literal tilde, -and then one literal "X". However, by using "~X", you are assuming that -no future version of Maketext will use "~X" as a magic escape sequence. -In practice this is not a great problem, since first off you can just -write "~~X" and not worry about it; second off, I doubt I'll add lots -of new magic characters to bracket notation; and third off, you -aren't likely to want literal "~" characters in your messages anyway, -since it's not a character with wide use in natural language text. - -Brackets must be balanced -- every openbracket must have -one matching closebracket, and vice versa. So these are all B<invalid>: - - "I ate [quant,_1,rhubarb pie." - "I ate [quant,_1,rhubarb pie[." - "I ate quant,_1,rhubarb pie]." - "I ate quant,_1,rhubarb pie[." - -Currently, bracket groups do not nest. That is, you B<cannot> say: - - "Foo [bar,baz,[quux,quuux]]\n"; - -If you need a notation that's that powerful, use normal Perl: - - %Lexicon = ( - ... - "some_key" => sub { - my $lh = $_[0]; - join '', - "Foo ", - $lh->bar('baz', $lh->quux('quuux')), - "\n", - }, - ... - ); - -Or write the "bar" method so you don't need to pass it the -output from calling quux. - -I do not anticipate that you will need (or particularly want) -to nest bracket groups, but you are welcome to email me with -convincing (real-life) arguments to the contrary. - -=head1 AUTO LEXICONS - -If maketext goes to look in an individual %Lexicon for an entry -for I<key> (where I<key> does not start with an underscore), and -sees none, B<but does see> an entry of "_AUTO" => I<some_true_value>, -then we actually define $Lexicon{I<key>} = I<key> right then and there, -and then use that value as if it had been there all -along. This happens before we even look in any superclass %Lexicons! - -(This is meant to be somewhat like the AUTOLOAD mechanism in -Perl's function call system -- or, looked at another way, -like the L<AutoLoader|AutoLoader> module.) - -I can picture all sorts of circumstances where you just -do not want lookup to be able to fail (since failing -normally means that maketext throws a C<die>, although -see the next section for greater control over that). But -here's one circumstance where _AUTO lexicons are meant to -be I<especially> useful: - -As you're writing an application, you decide as you go what messages -you need to emit. Normally you'd go to write this: - - if(-e $filename) { - go_process_file($filename) - } else { - print qq{Couldn't find file "$filename"!\n}; - } - -but since you anticipate localizing this, you write: - - use ThisProject::I18N; - my $lh = ThisProject::I18N->get_handle(); - # For the moment, assume that things are set up so - # that we load class ThisProject::I18N::en - # and that that's the class that $lh belongs to. - ... - if(-e $filename) { - go_process_file($filename) - } else { - print $lh->maketext( - qq{Couldn't find file "[_1]"!\n}, $filename - ); - } - -Now, right after you've just written the above lines, you'd -normally have to go open the file -ThisProject/I18N/en.pm, and immediately add an entry: - - "Couldn't find file \"[_1]\"!\n" - => "Couldn't find file \"[_1]\"!\n", - -But I consider that somewhat of a distraction from the work -of getting the main code working -- to say nothing of the fact -that I often have to play with the program a few times before -I can decide exactly what wording I want in the messages (which -in this case would require me to go changing three lines of code: -the call to maketext with that key, and then the two lines in -ThisProject/I18N/en.pm). - -However, if you set "_AUTO => 1" in the %Lexicon in, -ThisProject/I18N/en.pm (assuming that English (en) is -the language that all your programmers will be using for this -project's internal message keys), then you don't ever have to -go adding lines like this - - "Couldn't find file \"[_1]\"!\n" - => "Couldn't find file \"[_1]\"!\n", - -to ThisProject/I18N/en.pm, because if _AUTO is true there, -then just looking for an entry with the key "Couldn't find -file \"[_1]\"!\n" in that lexicon will cause it to be added, -with that value! - -Note that the reason that keys that start with "_" -are immune to _AUTO isn't anything generally magical about -the underscore character -- I just wanted a way to have most -lexicon keys be autoable, except for possibly a few, and I -arbitrarily decided to use a leading underscore as a signal -to distinguish those few. - -=head1 READONLY LEXICONS - -If your lexicon is a tied hash the simple act of caching the compiled value can be fatal. - -For example a L<GDBM_File> GDBM_READER tied hash will die with something like: - - gdbm store returned -1, errno 2, key "..." at ... - -All you need to do is turn on caching outside of the lexicon hash itself like so: - - sub init { - my ($lh) = @_; - ... - $lh->{'use_external_lex_cache'} = 1; - ... - } - -And then instead of storing the compiled value in the lexicon hash it will store it in $lh->{'_external_lex_cache'} - -=head1 CONTROLLING LOOKUP FAILURE - -If you call $lh->maketext(I<key>, ...parameters...), -and there's no entry I<key> in $lh's class's %Lexicon, nor -in the superclass %Lexicon hash, I<and> if we can't auto-make -I<key> (because either it starts with a "_", or because none -of its lexicons have C<_AUTO =E<gt> 1,>), then we have -failed to find a normal way to maketext I<key>. What then -happens in these failure conditions, depends on the $lh object's -"fail" attribute. - -If the language handle has no "fail" attribute, maketext -will simply throw an exception (i.e., it calls C<die>, mentioning -the I<key> whose lookup failed, and naming the line number where -the calling $lh->maketext(I<key>,...) was. - -If the language handle has a "fail" attribute whose value is a -coderef, then $lh->maketext(I<key>,...params...) gives up and calls: - - return $that_subref->($lh, $key, @params); - -Otherwise, the "fail" attribute's value should be a string denoting -a method name, so that $lh->maketext(I<key>,...params...) can -give up with: - - return $lh->$that_method_name($phrase, @params); - -The "fail" attribute can be accessed with the C<fail_with> method: - - # Set to a coderef: - $lh->fail_with( \&failure_handler ); - - # Set to a method name: - $lh->fail_with( 'failure_method' ); - - # Set to nothing (i.e., so failure throws a plain exception) - $lh->fail_with( undef ); - - # Get the current value - $handler = $lh->fail_with(); - -Now, as to what you may want to do with these handlers: Maybe you'd -want to log what key failed for what class, and then die. Maybe -you don't like C<die> and instead you want to send the error message -to STDOUT (or wherever) and then merely C<exit()>. - -Or maybe you don't want to C<die> at all! Maybe you could use a -handler like this: - - # Make all lookups fall back onto an English value, - # but only after we log it for later fingerpointing. - my $lh_backup = ThisProject->get_handle('en'); - open(LEX_FAIL_LOG, ">>wherever/lex.log") || die "GNAARGH $!"; - sub lex_fail { - my($failing_lh, $key, $params) = @_; - print LEX_FAIL_LOG scalar(localtime), "\t", - ref($failing_lh), "\t", $key, "\n"; - return $lh_backup->maketext($key,@params); - } - -Some users have expressed that they think this whole mechanism of -having a "fail" attribute at all, seems a rather pointless complication. -But I want Locale::Maketext to be usable for software projects of I<any> -scale and type; and different software projects have different ideas -of what the right thing is to do in failure conditions. I could simply -say that failure always throws an exception, and that if you want to be -careful, you'll just have to wrap every call to $lh->maketext in an -S<eval { }>. However, I want programmers to reserve the right (via -the "fail" attribute) to treat lookup failure as something other than -an exception of the same level of severity as a config file being -unreadable, or some essential resource being inaccessible. - -One possibly useful value for the "fail" attribute is the method name -"failure_handler_auto". This is a method defined in the class -Locale::Maketext itself. You set it with: - - $lh->fail_with('failure_handler_auto'); - -Then when you call $lh->maketext(I<key>, ...parameters...) and -there's no I<key> in any of those lexicons, maketext gives up with - - return $lh->failure_handler_auto($key, @params); - -But failure_handler_auto, instead of dying or anything, compiles -$key, caching it in - - $lh->{'failure_lex'}{$key} = $complied - -and then calls the compiled value, and returns that. (I.e., if -$key looks like bracket notation, $compiled is a sub, and we return -&{$compiled}(@params); but if $key is just a plain string, we just -return that.) - -The effect of using "failure_auto_handler" -is like an AUTO lexicon, except that it 1) compiles $key even if -it starts with "_", and 2) you have a record in the new hashref -$lh->{'failure_lex'} of all the keys that have failed for -this object. This should avoid your program dying -- as long -as your keys aren't actually invalid as bracket code, and as -long as they don't try calling methods that don't exist. - -"failure_auto_handler" may not be exactly what you want, but I -hope it at least shows you that maketext failure can be mitigated -in any number of very flexible ways. If you can formalize exactly -what you want, you should be able to express that as a failure -handler. You can even make it default for every object of a given -class, by setting it in that class's init: - - sub init { - my $lh = $_[0]; # a newborn handle - $lh->SUPER::init(); - $lh->fail_with('my_clever_failure_handler'); - return; - } - sub my_clever_failure_handler { - ...you clever things here... - } - -=head1 HOW TO USE MAKETEXT - -Here is a brief checklist on how to use Maketext to localize -applications: - -=over - -=item * - -Decide what system you'll use for lexicon keys. If you insist, -you can use opaque IDs (if you're nostalgic for C<catgets>), -but I have better suggestions in the -section "Entries in Each Lexicon", above. Assuming you opt for -meaningful keys that double as values (like "Minimum ([_1]) is -larger than maximum ([_2])!\n"), you'll have to settle on what -language those should be in. For the sake of argument, I'll -call this English, specifically American English, "en-US". - -=item * - -Create a class for your localization project. This is -the name of the class that you'll use in the idiom: - - use Projname::L10N; - my $lh = Projname::L10N->get_handle(...) || die "Language?"; - -Assuming you call your class Projname::L10N, create a class -consisting minimally of: - - package Projname::L10N; - use base qw(Locale::Maketext); - ...any methods you might want all your languages to share... - - # And, assuming you want the base class to be an _AUTO lexicon, - # as is discussed a few sections up: - - 1; - -=item * - -Create a class for the language your internal keys are in. Name -the class after the language-tag for that language, in lowercase, -with dashes changed to underscores. Assuming your project's first -language is US English, you should call this Projname::L10N::en_us. -It should consist minimally of: - - package Projname::L10N::en_us; - use base qw(Projname::L10N); - %Lexicon = ( - '_AUTO' => 1, - ); - 1; - -(For the rest of this section, I'll assume that this "first -language class" of Projname::L10N::en_us has -_AUTO lexicon.) - -=item * - -Go and write your program. Everywhere in your program where -you would say: - - print "Foobar $thing stuff\n"; - -instead do it thru maketext, using no variable interpolation in -the key: - - print $lh->maketext("Foobar [_1] stuff\n", $thing); - -If you get tired of constantly saying C<print $lh-E<gt>maketext>, -consider making a functional wrapper for it, like so: - - use Projname::L10N; - use vars qw($lh); - $lh = Projname::L10N->get_handle(...) || die "Language?"; - sub pmt (@) { print( $lh->maketext(@_)) } - # "pmt" is short for "Print MakeText" - $Carp::Verbose = 1; - # so if maketext fails, we see made the call to pmt - -Besides whole phrases meant for output, anything language-dependent -should be put into the class Projname::L10N::en_us, -whether as methods, or as lexicon entries -- this is discussed -in the section "Entries in Each Lexicon", above. - -=item * - -Once the program is otherwise done, and once its localization for -the first language works right (via the data and methods in -Projname::L10N::en_us), you can get together the data for translation. -If your first language lexicon isn't an _AUTO lexicon, then you already -have all the messages explicitly in the lexicon (or else you'd be -getting exceptions thrown when you call $lh->maketext to get -messages that aren't in there). But if you were (advisedly) lazy and are -using an _AUTO lexicon, then you've got to make a list of all the phrases -that you've so far been letting _AUTO generate for you. There are very -many ways to assemble such a list. The most straightforward is to simply -grep the source for every occurrence of "maketext" (or calls -to wrappers around it, like the above C<pmt> function), and to log the -following phrase. - -=item * - -You may at this point want to consider whether your base class -(Projname::L10N), from which all lexicons inherit from (Projname::L10N::en, -Projname::L10N::es, etc.), should be an _AUTO lexicon. It may be true -that in theory, all needed messages will be in each language class; -but in the presumably unlikely or "impossible" case of lookup failure, -you should consider whether your program should throw an exception, -emit text in English (or whatever your project's first language is), -or some more complex solution as described in the section -"Controlling Lookup Failure", above. - -=item * - -Submit all messages/phrases/etc. to translators. - -(You may, in fact, want to start with localizing to I<one> other language -at first, if you're not sure that you've properly abstracted the -language-dependent parts of your code.) - -Translators may request clarification of the situation in which a -particular phrase is found. For example, in English we are entirely happy -saying "I<n> files found", regardless of whether we mean "I looked for files, -and found I<n> of them" or the rather distinct situation of "I looked for -something else (like lines in files), and along the way I saw I<n> -files." This may involve rethinking things that you thought quite clear: -should "Edit" on a toolbar be a noun ("editing") or a verb ("to edit")? Is -there already a conventionalized way to express that menu option, separate -from the target language's normal word for "to edit"? - -In all cases where the very common phenomenon of quantification -(saying "I<N> files", for B<any> value of N) -is involved, each translator should make clear what dependencies the -number causes in the sentence. In many cases, dependency is -limited to words adjacent to the number, in places where you might -expect them ("I found the-?PLURAL I<N> -empty-?PLURAL directory-?PLURAL"), but in some cases there are -unexpected dependencies ("I found-?PLURAL ..."!) as well as long-distance -dependencies "The I<N> directory-?PLURAL could not be deleted-?PLURAL"!). - -Remind the translators to consider the case where N is 0: -"0 files found" isn't exactly natural-sounding in any language, but it -may be unacceptable in many -- or it may condition special -kinds of agreement (similar to English "I didN'T find ANY files"). - -Remember to ask your translators about numeral formatting in their -language, so that you can override the C<numf> method as -appropriate. Typical variables in number formatting are: what to -use as a decimal point (comma? period?); what to use as a thousands -separator (space? nonbreaking space? comma? period? small -middot? prime? apostrophe?); and even whether the so-called "thousands -separator" is actually for every third digit -- I've heard reports of -two hundred thousand being expressible as "2,00,000" for some Indian -(Subcontinental) languages, besides the less surprising "S<200 000>", -"200.000", "200,000", and "200'000". Also, using a set of numeral -glyphs other than the usual ASCII "0"-"9" might be appreciated, as via -C<tr/0-9/\x{0966}-\x{096F}/> for getting digits in Devanagari script -(for Hindi, Konkani, others). - -The basic C<quant> method that Locale::Maketext provides should be -good for many languages. For some languages, it might be useful -to modify it (or its constituent C<numerate> method) -to take a plural form in the two-argument call to C<quant> -(as in "[quant,_1,files]") if -it's all-around easier to infer the singular form from the plural, than -to infer the plural form from the singular. - -But for other languages (as is discussed at length -in L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>), simple -C<quant>/C<numf> is not enough. For the particularly problematic -Slavic languages, what you may need is a method which you provide -with the number, the citation form of the noun to quantify, and -the case and gender that the sentence's syntax projects onto that -noun slot. The method would then be responsible for determining -what grammatical number that numeral projects onto its noun phrase, -and what case and gender it may override the normal case and gender -with; and then it would look up the noun in a lexicon providing -all needed inflected forms. - -=item * - -You may also wish to discuss with the translators the question of -how to relate different subforms of the same language tag, -considering how this reacts with C<get_handle>'s treatment of -these. For example, if a user accepts interfaces in "en, fr", and -you have interfaces available in "en-US" and "fr", what should -they get? You may wish to resolve this by establishing that "en" -and "en-US" are effectively synonymous, by having one class -zero-derive from the other. - -For some languages this issue may never come up (Danish is rarely -expressed as "da-DK", but instead is just "da"). And for other -languages, the whole concept of a "generic" form may verge on -being uselessly vague, particularly for interfaces involving voice -media in forms of Arabic or Chinese. - -=item * - -Once you've localized your program/site/etc. for all desired -languages, be sure to show the result (whether live, or via -screenshots) to the translators. Once they approve, make every -effort to have it then checked by at least one other speaker of -that language. This holds true even when (or especially when) the -translation is done by one of your own programmers. Some -kinds of systems may be harder to find testers for than others, -depending on the amount of domain-specific jargon and concepts -involved -- it's easier to find people who can tell you whether -they approve of your translation for "delete this message" in an -email-via-Web interface, than to find people who can give you -an informed opinion on your translation for "attribute value" -in an XML query tool's interface. - -=back - -=head1 SEE ALSO - -I recommend reading all of these: - -L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13> -- my I<The Perl -Journal> article about Maketext. It explains many important concepts -underlying Locale::Maketext's design, and some insight into why -Maketext is better than the plain old approach of having -message catalogs that are just databases of sprintf formats. - -L<File::Findgrep|File::Findgrep> is a sample application/module -that uses Locale::Maketext to localize its messages. For a larger -internationalized system, see also L<Apache::MP3>. - -L<I18N::LangTags|I18N::LangTags>. - -L<Win32::Locale|Win32::Locale>. - -RFC 3066, I<Tags for the Identification of Languages>, -as at http://sunsite.dk/RFC/rfc/rfc3066.html - -RFC 2277, I<IETF Policy on Character Sets and Languages> -is at http://sunsite.dk/RFC/rfc/rfc2277.html -- much of it is -just things of interest to protocol designers, but it explains -some basic concepts, like the distinction between locales and -language-tags. - -The manual for GNU C<gettext>. The gettext dist is available in -C<ftp://prep.ai.mit.edu/pub/gnu/> -- get -a recent gettext tarball and look in its "doc/" directory, there's -an easily browsable HTML version in there. The -gettext documentation asks lots of questions worth thinking -about, even if some of their answers are sometimes wonky, -particularly where they start talking about pluralization. - -The Locale/Maketext.pm source. Obverse that the module is much -shorter than its documentation! - -=head1 COPYRIGHT AND DISCLAIMER - -Copyright (c) 1999-2004 Sean M. Burke. All rights reserved. - -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. - -This program is distributed in the hope that it will be useful, but -without any warranty; without even the implied warranty of -merchantability or fitness for a particular purpose. - -=head1 AUTHOR - -Sean M. Burke C<sburke@cpan.org> - -=cut diff --git a/Master/tlpkg/tlperl/lib/Locale/Maketext/Cookbook.pod b/Master/tlpkg/tlperl/lib/Locale/Maketext/Cookbook.pod deleted file mode 100644 index 3457f7ca12a..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Maketext/Cookbook.pod +++ /dev/null @@ -1,150 +0,0 @@ -# This document contains text in Perl "POD" format. -# Use a POD viewer like perldoc or perlman to render it. - -=encoding utf-8 - -=head1 NAME - -Locale::Maketext::Cookbook - recipes for using Locale::Maketext - -=head1 INTRODUCTION - -This is a work in progress. Not much progress by now :-) - -=head1 ONESIDED LEXICONS - -I<Adapted from a suggestion by Dan Muey> - -It may be common (for example at your main lexicon) that -the hash keys and values coincide. Like that - - q{Hello, tell me your name} - => q{Hello, tell me your name} - -It would be nice to just write: - - q{Hello, tell me your name} => '' - -and have this magically inflated to the first form. -Among the advantages of such representation, that would -lead to -smaller files, less prone to mistyping or mispasting, -and handy to someone translating it which can simply -copy the main lexicon and enter the translation -instead of having to remove the value first. - -That can be achieved by overriding C<init> -in your class and working on the main lexicon -with code like that: - - package My::I18N; - ... - - sub init { - my $lh = shift; # a newborn handle - $lh->SUPER::init(); - inflate_lexicon(\%My::I18N::en::Lexicon); - return; - } - - sub inflate_lexicon { - my $lex = shift; - while (my ($k, $v) = each %$lex) { - $v = $k if !defined $v || $v eq ''; - } - } - -Here we are assuming C<My::I18N::en> to own the -main lexicon. - -There are some downsides here: the size economy -will not stand at runtime after this C<init()> -runs. But it should not be that critical, since -if you don't have space for that, you won't have -space for any other language besides the main one -as well. You could do that too with ties, -expanding the value at lookup time which -should be more time expensive as an option. - -=head1 DECIMAL PLACES IN NUMBER FORMATTING - -I<After CPAN RT #36136 (https://rt.cpan.org/Ticket/Display.html?id=36136)> - -The documentation of L<Locale::Maketext> advises that -the standard bracket method C<numf> is limited and that -you must override that for better results. It even -suggests the use of L<Number::Format>. - -One such defect of standard C<numf> is to not be -able to use a certain decimal precision. -For example, - - $lh->maketext('pi is [numf,_1]', 355/113); - -outputs - - pi is 3.14159292035398 - -Since pi ≈ 355/116 is only accurate -to 6 decimal places, you would want to say: - - $lh->maketext('pi is [numf,_1,6]', 355/113); - -and get "pi is 3.141592". - -One solution for that could use C<Number::Format> -like that: - - package Wuu; - - use base qw(Locale::Maketext); - - use Number::Format; - - # can be overridden according to language conventions - sub _numf_params { - return ( - -thousands_sep => '.', - -decimal_point => ',', - -decimal_digits => 2, - ); - } - - # builds a Number::Format - sub _numf_formatter { - my ($lh, $scale) = @_; - my @params = $lh->_numf_params; - if ($scale) { # use explicit scale rather than default - push @params, (-decimal_digits => $scale); - } - return Number::Format->new(@params); - } - - sub numf { - my ($lh, $n, $scale) = @_; - # get the (cached) formatter - my $nf = $lh->{__nf}{$scale} ||= $lh->_numf_formatter($scale); - # format the number itself - return $nf->format_number($n); - } - - package Wuu::pt; - - use base qw(Wuu); - -and then - - my $lh = Wuu->get_handle('pt'); - $lh->maketext('A [numf,_1,3] km de distância', 1550.2222); - -would return "A 1.550,222 km de distância". - -Notice that the standard utility methods of -C<Locale::Maketext> are irremediably limited -because they could not aim to do everything -that could be expected from them in different languages, -cultures and applications. So extending C<numf>, -C<quant>, and C<sprintf> is natural as soon -as your needs exceed what the standard ones do. - - diff --git a/Master/tlpkg/tlperl/lib/Locale/Maketext/TPJ13.pod b/Master/tlpkg/tlperl/lib/Locale/Maketext/TPJ13.pod deleted file mode 100644 index b9586b2cbf4..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Maketext/TPJ13.pod +++ /dev/null @@ -1,775 +0,0 @@ -# This document contains text in Perl "POD" format. -# Use a POD viewer like perldoc or perlman to render it. - -=head1 NAME - -Locale::Maketext::TPJ13 -- article about software localization - -=head1 SYNOPSIS - - # This an article, not a module. - -=head1 DESCRIPTION - -The following article by Sean M. Burke and Jordan Lachler -first appeared in I<The Perl Journal> #13 -and is copyright 1999 The Perl Journal. It appears -courtesy of Jon Orwant and The Perl Journal. This document may be -distributed under the same terms as Perl itself. - -=head1 Localization and Perl: gettext breaks, Maketext fixes - -by Sean M. Burke and Jordan Lachler - -This article points out cases where gettext (a common system for -localizing software interfaces -- i.e., making them work in the user's -language of choice) fails because of basic differences between human -languages. This article then describes Maketext, a new system capable -of correctly treating these differences. - -=head2 A Localization Horror Story: It Could Happen To You - -=over - -"There are a number of languages spoken by human beings in this -world." - --- Harald Tveit Alvestrand, in RFC 1766, "Tags for the -Identification of Languages" - -=back - -Imagine that your task for the day is to localize a piece of software --- and luckily for you, the only output the program emits is two -messages, like this: - - I scanned 12 directories. - - Your query matched 10 files in 4 directories. - -So how hard could that be? You look at the code that -produces the first item, and it reads: - - printf("I scanned %g directories.", - $directory_count); - -You think about that, and realize that it doesn't even work right for -English, as it can produce this output: - - I scanned 1 directories. - -So you rewrite it to read: - - printf("I scanned %g %s.", - $directory_count, - $directory_count == 1 ? - "directory" : "directories", - ); - -...which does the Right Thing. (In case you don't recall, "%g" is for -locale-specific number interpolation, and "%s" is for string -interpolation.) - -But you still have to localize it for all the languages you're -producing this software for, so you pull Locale::gettext off of CPAN -so you can access the C<gettext> C functions you've heard are standard -for localization tasks. - -And you write: - - printf(gettext("I scanned %g %s."), - $dir_scan_count, - $dir_scan_count == 1 ? - gettext("directory") : gettext("directories"), - ); - -But you then read in the gettext manual (Drepper, Miller, and Pinard 1995) -that this is not a good idea, since how a single word like "directory" -or "directories" is translated may depend on context -- and this is -true, since in a case language like German or Russian, you'd may need -these words with a different case ending in the first instance (where the -word is the object of a verb) than in the second instance, which you haven't even -gotten to yet (where the word is the object of a preposition, "in %g -directories") -- assuming these keep the same syntax when translated -into those languages. - -So, on the advice of the gettext manual, you rewrite: - - printf( $dir_scan_count == 1 ? - gettext("I scanned %g directory.") : - gettext("I scanned %g directories."), - $dir_scan_count ); - -So, you email your various translators (the boss decides that the -languages du jour are Chinese, Arabic, Russian, and Italian, so you -have one translator for each), asking for translations for "I scanned -%g directory." and "I scanned %g directories.". When they reply, -you'll put that in the lexicons for gettext to use when it localizes -your software, so that when the user is running under the "zh" -(Chinese) locale, gettext("I scanned %g directory.") will return the -appropriate Chinese text, with a "%g" in there where printf can then -interpolate $dir_scan. - -Your Chinese translator emails right back -- he says both of these -phrases translate to the same thing in Chinese, because, in linguistic -jargon, Chinese "doesn't have number as a grammatical category" -- -whereas English does. That is, English has grammatical rules that -refer to "number", i.e., whether something is grammatically singular -or plural; and one of these rules is the one that forces nouns to take -a plural suffix (generally "s") when in a plural context, as they are when -they follow a number other than "one" (including, oddly enough, "zero"). -Chinese has no such rules, and so has just the one phrase where English -has two. But, no problem, you can have this one Chinese phrase appear -as the translation for the two English phrases in the "zh" gettext -lexicon for your program. - -Emboldened by this, you dive into the second phrase that your software -needs to output: "Your query matched 10 files in 4 directories.". You notice -that if you want to treat phrases as indivisible, as the gettext -manual wisely advises, you need four cases now, instead of two, to -cover the permutations of singular and plural on the two items, -$dir_count and $file_count. So you try this: - - printf( $file_count == 1 ? - ( $directory_count == 1 ? - gettext("Your query matched %g file in %g directory.") : - gettext("Your query matched %g file in %g directories.") ) : - ( $directory_count == 1 ? - gettext("Your query matched %g files in %g directory.") : - gettext("Your query matched %g files in %g directories.") ), - $file_count, $directory_count, - ); - -(The case of "1 file in 2 [or more] directories" could, I suppose, -occur in the case of symlinking or something of the sort.) - -It occurs to you that this is not the prettiest code you've ever -written, but this seems the way to go. You mail off to the -translators asking for translations for these four cases. The -Chinese guy replies with the one phrase that these all translate to in -Chinese, and that phrase has two "%g"s in it, as it should -- but -there's a problem. He translates it word-for-word back: "In %g -directories contains %g files match your query." The %g -slots are in an order reverse to what they are in English. You wonder -how you'll get gettext to handle that. - -But you put it aside for the moment, and optimistically hope that the -other translators won't have this problem, and that their languages -will be better behaved -- i.e., that they will be just like English. - -But the Arabic translator is the next to write back. First off, your -code for "I scanned %g directory." or "I scanned %g directories." -assumes there's only singular or plural. But, to use linguistic -jargon again, Arabic has grammatical number, like English (but unlike -Chinese), but it's a three-term category: singular, dual, and plural. -In other words, the way you say "directory" depends on whether there's -one directory, or I<two> of them, or I<more than two> of them. Your -test of C<($directory == 1)> no longer does the job. And it means -that where English's grammatical category of number necessitates -only the two permutations of the first sentence based on "directory -[singular]" and "directories [plural]", Arabic has three -- and, -worse, in the second sentence ("Your query matched %g file in %g -directory."), where English has four, Arabic has nine. You sense -an unwelcome, exponential trend taking shape. - -Your Italian translator emails you back and says that "I searched 0 -directories" (a possible English output of your program) is stilted, -and if you think that's fine English, that's your problem, but that -I<just will not do> in the language of Dante. He insists that where -$directory_count is 0, your program should produce the Italian text -for "I I<didn't> scan I<any> directories.". And ditto for "I didn't -match any files in any directories", although he says the last part -about "in any directories" should probably just be left off. - -You wonder how you'll get gettext to handle this; to accommodate the -ways Arabic, Chinese, and Italian deal with numbers in just these few -very simple phrases, you need to write code that will ask gettext for -different queries depending on whether the numerical values in -question are 1, 2, more than 2, or in some cases 0, and you still haven't -figured out the problem with the different word order in Chinese. - -Then your Russian translator calls on the phone, to I<personally> tell -you the bad news about how really unpleasant your life is about to -become: - -Russian, like German or Latin, is an inflectional language; that is, nouns -and adjectives have to take endings that depend on their case -(i.e., nominative, accusative, genitive, etc...) -- which is roughly a matter of -what role they have in syntax of the sentence -- -as well as on the grammatical gender (i.e., masculine, feminine, neuter) -and number (i.e., singular or plural) of the noun, as well as on the -declension class of the noun. But unlike with most other inflected languages, -putting a number-phrase (like "ten" or "forty-three", or their Arabic -numeral equivalents) in front of noun in Russian can change the case and -number that noun is, and therefore the endings you have to put on it. - -He elaborates: In "I scanned %g directories", you'd I<expect> -"directories" to be in the accusative case (since it is the direct -object in the sentence) and the plural number, -except where $directory_count is 1, then you'd expect the singular, of -course. Just like Latin or German. I<But!> Where $directory_count % -10 is 1 ("%" for modulo, remember), assuming $directory count is an -integer, and except where $directory_count % 100 is 11, "directories" -is forced to become grammatically singular, which means it gets the -ending for the accusative singular... You begin to visualize the code -it'd take to test for the problem so far, I<and still work for Chinese -and Arabic and Italian>, and how many gettext items that'd take, but -he keeps going... But where $directory_count % 10 is 2, 3, or 4 -(except where $directory_count % 100 is 12, 13, or 14), the word for -"directories" is forced to be genitive singular -- which means another -ending... The room begins to spin around you, slowly at first... But -with I<all other> integer values, since "directory" is an inanimate -noun, when preceded by a number and in the nominative or accusative -cases (as it is here, just your luck!), it does stay plural, but it is -forced into the genitive case -- yet another ending... And -you never hear him get to the part about how you're going to run into -similar (but maybe subtly different) problems with other Slavic -languages like Polish, because the floor comes up to meet you, and you -fade into unconsciousness. - - -The above cautionary tale relates how an attempt at localization can -lead from programmer consternation, to program obfuscation, to a need -for sedation. But careful evaluation shows that your choice of tools -merely needed further consideration. - -=head2 The Linguistic View - -=over - -"It is more complicated than you think." - --- The Eighth Networking Truth, from RFC 1925 - -=back - -The field of Linguistics has expended a great deal of effort over the -past century trying to find grammatical patterns which hold across -languages; it's been a constant process -of people making generalizations that should apply to all languages, -only to find out that, all too often, these generalizations fail -- -sometimes failing for just a few languages, sometimes whole classes of -languages, and sometimes nearly every language in the world except -English. Broad statistical trends are evident in what the "average -language" is like as far as what its rules can look like, must look -like, and cannot look like. But the "average language" is just as -unreal a concept as the "average person" -- it runs up against the -fact no language (or person) is, in fact, average. The wisdom of past -experience leads us to believe that any given language can do whatever -it wants, in any order, with appeal to any kind of grammatical -categories wants -- case, number, tense, real or metaphoric -characteristics of the things that words refer to, arbitrary or -predictable classifications of words based on what endings or prefixes -they can take, degree or means of certainty about the truth of -statements expressed, and so on, ad infinitum. - -Mercifully, most localization tasks are a matter of finding ways to -translate whole phrases, generally sentences, where the context is -relatively set, and where the only variation in content is I<usually> -in a number being expressed -- as in the example sentences above. -Translating specific, fully-formed sentences is, in practice, fairly -foolproof -- which is good, because that's what's in the phrasebooks -that so many tourists rely on. Now, a given phrase (whether in a -phrasebook or in a gettext lexicon) in one language I<might> have a -greater or lesser applicability than that phrase's translation into -another language -- for example, strictly speaking, in Arabic, the -"your" in "Your query matched..." would take a different form -depending on whether the user is male or female; so the Arabic -translation "your[feminine] query" is applicable in fewer cases than -the corresponding English phrase, which doesn't distinguish the user's -gender. (In practice, it's not feasible to have a program know the -user's gender, so the masculine "you" in Arabic is usually used, by -default.) - -But in general, such surprises are rare when entire sentences are -being translated, especially when the functional context is restricted -to that of a computer interacting with a user either to convey a fact -or to prompt for a piece of information. So, for purposes of -localization, translation by phrase (generally by sentence) is both the -simplest and the least problematic. - -=head2 Breaking gettext - -=over - -"It Has To Work." - --- First Networking Truth, RFC 1925 - -=back - -Consider that sentences in a tourist phrasebook are of two types: ones -like "How do I get to the marketplace?" that don't have any blanks to -fill in, and ones like "How much do these ___ cost?", where there's -one or more blanks to fill in (and these are usually linked to a -list of words that you can put in that blank: "fish", "potatoes", -"tomatoes", etc.) The ones with no blanks are no problem, but the -fill-in-the-blank ones may not be really straightforward. If it's a -Swahili phrasebook, for example, the authors probably didn't bother to -tell you the complicated ways that the verb "cost" changes its -inflectional prefix depending on the noun you're putting in the blank. -The trader in the marketplace will still understand what you're saying if -you say "how much do these potatoes cost?" with the wrong -inflectional prefix on "cost". After all, I<you> can't speak proper Swahili, -I<you're> just a tourist. But while tourists can be stupid, computers -are supposed to be smart; the computer should be able to fill in the -blank, and still have the results be grammatical. - -In other words, a phrasebook entry takes some values as parameters -(the things that you fill in the blank or blanks), and provides a value -based on these parameters, where the way you get that final value from -the given values can, properly speaking, involve an arbitrarily -complex series of operations. (In the case of Chinese, it'd be not at -all complex, at least in cases like the examples at the beginning of -this article; whereas in the case of Russian it'd be a rather complex -series of operations. And in some languages, the -complexity could be spread around differently: while the act of -putting a number-expression in front of a noun phrase might not be -complex by itself, it may change how you have to, for example, inflect -a verb elsewhere in the sentence. This is what in syntax is called -"long-distance dependencies".) - -This talk of parameters and arbitrary complexity is just another way -to say that an entry in a phrasebook is what in a programming language -would be called a "function". Just so you don't miss it, this is the -crux of this article: I<A phrase is a function; a phrasebook is a -bunch of functions.> - -The reason that using gettext runs into walls (as in the above -second-person horror story) is that you're trying to use a string (or -worse, a choice among a bunch of strings) to do what you really need a -function for -- which is futile. Preforming (s)printf interpolation -on the strings which you get back from gettext does allow you to do I<some> -common things passably well... sometimes... sort of; but, to paraphrase -what some people say about C<csh> script programming, "it fools you -into thinking you can use it for real things, but you can't, and you -don't discover this until you've already spent too much time trying, -and by then it's too late." - -=head2 Replacing gettext - -So, what needs to replace gettext is a system that supports lexicons -of functions instead of lexicons of strings. An entry in a lexicon -from such a system should I<not> look like this: - - "J'ai trouv\xE9 %g fichiers dans %g r\xE9pertoires" - -[\xE9 is e-acute in Latin-1. Some pod renderers would -scream if I used the actual character here. -- SB] - -but instead like this, bearing in mind that this is just a first stab: - - sub I_found_X1_files_in_X2_directories { - my( $files, $dirs ) = @_[0,1]; - $files = sprintf("%g %s", $files, - $files == 1 ? 'fichier' : 'fichiers'); - $dirs = sprintf("%g %s", $dirs, - $dirs == 1 ? "r\xE9pertoire" : "r\xE9pertoires"); - return "J'ai trouv\xE9 $files dans $dirs."; - } - -Now, there's no particularly obvious way to store anything but strings -in a gettext lexicon; so it looks like we just have to start over and -make something better, from scratch. I call my shot at a -gettext-replacement system "Maketext", or, in CPAN terms, -Locale::Maketext. - -When designing Maketext, I chose to plan its main features in terms of -"buzzword compliance". And here are the buzzwords: - -=head2 Buzzwords: Abstraction and Encapsulation - -The complexity of the language you're trying to output a phrase in is -entirely abstracted inside (and encapsulated within) the Maketext module -for that interface. When you call: - - print $lang->maketext("You have [quant,_1,piece] of new mail.", - scalar(@messages)); - -you don't know (and in fact can't easily find out) whether this will -involve lots of figuring, as in Russian (if $lang is a handle to the -Russian module), or relatively little, as in Chinese. That kind of -abstraction and encapsulation may encourage other pleasant buzzwords -like modularization and stratification, depending on what design -decisions you make. - -=head2 Buzzword: Isomorphism - -"Isomorphism" means "having the same structure or form"; in discussions -of program design, the word takes on the special, specific meaning that -your implementation of a solution to a problem I<has the same -structure> as, say, an informal verbal description of the solution, or -maybe of the problem itself. Isomorphism is, all things considered, -a good thing -- it's what problem-solving (and solution-implementing) -should look like. - -What's wrong the with gettext-using code like this... - - printf( $file_count == 1 ? - ( $directory_count == 1 ? - "Your query matched %g file in %g directory." : - "Your query matched %g file in %g directories." ) : - ( $directory_count == 1 ? - "Your query matched %g files in %g directory." : - "Your query matched %g files in %g directories." ), - $file_count, $directory_count, - ); - -is first off that it's not well abstracted -- these ways of testing -for grammatical number (as in the expressions like C<foo == 1 ? -singular_form : plural_form>) should be abstracted to each language -module, since how you get grammatical number is language-specific. - -But second off, it's not isomorphic -- the "solution" (i.e., the -phrasebook entries) for Chinese maps from these four English phrases to -the one Chinese phrase that fits for all of them. In other words, the -informal solution would be "The way to say what you want in Chinese is -with the one phrase 'For your question, in Y directories you would -find X files'" -- and so the implemented solution should be, -isomorphically, just a straightforward way to spit out that one -phrase, with numerals properly interpolated. It shouldn't have to map -from the complexity of other languages to the simplicity of this one. - -=head2 Buzzword: Inheritance - -There's a great deal of reuse possible for sharing of phrases between -modules for related dialects, or for sharing of auxiliary functions -between related languages. (By "auxiliary functions", I mean -functions that don't produce phrase-text, but which, say, return an -answer to "does this number require a plural noun after it?". Such -auxiliary functions would be used in the internal logic of functions -that actually do produce phrase-text.) - -In the case of sharing phrases, consider that you have an interface -already localized for American English (probably by having been -written with that as the native locale, but that's incidental). -Localizing it for UK English should, in practical terms, be just a -matter of running it past a British person with the instructions to -indicate what few phrases would benefit from a change in spelling or -possibly minor rewording. In that case, you should be able to put in -the UK English localization module I<only> those phrases that are -UK-specific, and for all the rest, I<inherit> from the American -English module. (And I expect this same situation would apply with -Brazilian and Continental Portugese, possibly with some I<very> -closely related languages like Czech and Slovak, and possibly with the -slightly different "versions" of written Mandarin Chinese, as I hear exist in -Taiwan and mainland China.) - -As to sharing of auxiliary functions, consider the problem of Russian -numbers from the beginning of this article; obviously, you'd want to -write only once the hairy code that, given a numeric value, would -return some specification of which case and number a given quantified -noun should use. But suppose that you discover, while localizing an -interface for, say, Ukranian (a Slavic language related to Russian, -spoken by several million people, many of whom would be relieved to -find that your Web site's or software's interface is available in -their language), that the rules in Ukranian are the same as in Russian -for quantification, and probably for many other grammatical functions. -While there may well be no phrases in common between Russian and -Ukranian, you could still choose to have the Ukranian module inherit -from the Russian module, just for the sake of inheriting all the -various grammatical methods. Or, probably better organizationally, -you could move those functions to a module called C<_E_Slavic> or -something, which Russian and Ukrainian could inherit useful functions -from, but which would (presumably) provide no lexicon. - -=head2 Buzzword: Concision - -Okay, concision isn't a buzzword. But it should be, so I decree that -as a new buzzword, "concision" means that simple common things should -be expressible in very few lines (or maybe even just a few characters) -of code -- call it a special case of "making simple things easy and -hard things possible", and see also the role it played in the -MIDI::Simple language, discussed elsewhere in this issue [TPJ#13]. - -Consider our first stab at an entry in our "phrasebook of functions": - - sub I_found_X1_files_in_X2_directories { - my( $files, $dirs ) = @_[0,1]; - $files = sprintf("%g %s", $files, - $files == 1 ? 'fichier' : 'fichiers'); - $dirs = sprintf("%g %s", $dirs, - $dirs == 1 ? "r\xE9pertoire" : "r\xE9pertoires"); - return "J'ai trouv\xE9 $files dans $dirs."; - } - -You may sense that a lexicon (to use a non-committal catch-all term for a -collection of things you know how to say, regardless of whether they're -phrases or words) consisting of functions I<expressed> as above would -make for rather long-winded and repetitive code -- even if you wisely -rewrote this to have quantification (as we call adding a number -expression to a noun phrase) be a function called like: - - sub I_found_X1_files_in_X2_directories { - my( $files, $dirs ) = @_[0,1]; - $files = quant($files, "fichier"); - $dirs = quant($dirs, "r\xE9pertoire"); - return "J'ai trouv\xE9 $files dans $dirs."; - } - -And you may also sense that you do not want to bother your translators -with having to write Perl code -- you'd much rather that they spend -their I<very costly time> on just translation. And this is to say -nothing of the near impossibility of finding a commercial translator -who would know even simple Perl. - -In a first-hack implementation of Maketext, each language-module's -lexicon looked like this: - - %Lexicon = ( - "I found %g files in %g directories" - => sub { - my( $files, $dirs ) = @_[0,1]; - $files = quant($files, "fichier"); - $dirs = quant($dirs, "r\xE9pertoire"); - return "J'ai trouv\xE9 $files dans $dirs."; - }, - ... and so on with other phrase => sub mappings ... - ); - -but I immediately went looking for some more concise way to basically -denote the same phrase-function -- a way that would also serve to -concisely denote I<most> phrase-functions in the lexicon for I<most> -languages. After much time and even some actual thought, I decided on -this system: - -* Where a value in a %Lexicon hash is a contentful string instead of -an anonymous sub (or, conceivably, a coderef), it would be interpreted -as a sort of shorthand expression of what the sub does. When accessed -for the first time in a session, it is parsed, turned into Perl code, -and then eval'd into an anonymous sub; then that sub replaces the -original string in that lexicon. (That way, the work of parsing and -evaling the shorthand form for a given phrase is done no more than -once per session.) - -* Calls to C<maketext> (as Maketext's main function is called) happen -thru a "language session handle", notionally very much like an IO -handle, in that you open one at the start of the session, and use it -for "sending signals" to an object in order to have it return the text -you want. - -So, this: - - $lang->maketext("You have [quant,_1,piece] of new mail.", - scalar(@messages)); - -basically means this: look in the lexicon for $lang (which may inherit -from any number of other lexicons), and find the function that we -happen to associate with the string "You have [quant,_1,piece] of new -mail" (which is, and should be, a functioning "shorthand" for this -function in the native locale -- English in this case). If you find -such a function, call it with $lang as its first parameter (as if it -were a method), and then a copy of scalar(@messages) as its second, -and then return that value. If that function was found, but was in -string shorthand instead of being a fully specified function, parse it -and make it into a function before calling it the first time. - -* The shorthand uses code in brackets to indicate method calls that -should be performed. A full explanation is not in order here, but a -few examples will suffice: - - "You have [quant,_1,piece] of new mail." - -The above code is shorthand for, and will be interpreted as, -this: - - sub { - my $handle = $_[0]; - my(@params) = @_; - return join '', - "You have ", - $handle->quant($params[1], 'piece'), - "of new mail."; - } - -where "quant" is the name of a method you're using to quantify the -noun "piece" with the number $params[0]. - -A string with no brackety calls, like this: - - "Your search expression was malformed." - -is somewhat of a degenerate case, and just gets turned into: - - sub { return "Your search expression was malformed." } - -However, not everything you can write in Perl code can be written in -the above shorthand system -- not by a long shot. For example, consider -the Italian translator from the beginning of this article, who wanted -the Italian for "I didn't find any files" as a special case, instead -of "I found 0 files". That couldn't be specified (at least not easily -or simply) in our shorthand system, and it would have to be written -out in full, like this: - - sub { # pretend the English strings are in Italian - my($handle, $files, $dirs) = @_[0,1,2]; - return "I didn't find any files" unless $files; - return join '', - "I found ", - $handle->quant($files, 'file'), - " in ", - $handle->quant($dirs, 'directory'), - "."; - } - -Next to a lexicon full of shorthand code, that sort of sticks out like a -sore thumb -- but this I<is> a special case, after all; and at least -it's possible, if not as concise as usual. - -As to how you'd implement the Russian example from the beginning of -the article, well, There's More Than One Way To Do It, but it could be -something like this (using English words for Russian, just so you know -what's going on): - - "I [quant,_1,directory,accusative] scanned." - -This shifts the burden of complexity off to the quant method. That -method's parameters are: the numeric value it's going to use to -quantify something; the Russian word it's going to quantify; and the -parameter "accusative", which you're using to mean that this -sentence's syntax wants a noun in the accusative case there, although -that quantification method may have to overrule, for grammatical -reasons you may recall from the beginning of this article. - -Now, the Russian quant method here is responsible not only for -implementing the strange logic necessary for figuring out how Russian -number-phrases impose case and number on their noun-phrases, but also -for inflecting the Russian word for "directory". How that inflection -is to be carried out is no small issue, and among the solutions I've -seen, some (like variations on a simple lookup in a hash where all -possible forms are provided for all necessary words) are -straightforward but I<can> become cumbersome when you need to inflect -more than a few dozen words; and other solutions (like using -algorithms to model the inflections, storing only root forms and -irregularities) I<can> involve more overhead than is justifiable for -all but the largest lexicons. - -Mercifully, this design decision becomes crucial only in the hairiest -of inflected languages, of which Russian is by no means the I<worst> case -scenario, but is worse than most. Most languages have simpler -inflection systems; for example, in English or Swahili, there are -generally no more than two possible inflected forms for a given noun -("error/errors"; "kosa/makosa"), and the -rules for producing these forms are fairly simple -- or at least, -simple rules can be formulated that work for most words, and you can -then treat the exceptions as just "irregular", at least relative to -your ad hoc rules. A simpler inflection system (simpler rules, fewer -forms) means that design decisions are less crucial to maintaining -sanity, whereas the same decisions could incur -overhead-versus-scalability problems in languages like Russian. It -may I<also> be likely that code (possibly in Perl, as with -Lingua::EN::Inflect, for English nouns) has already -been written for the language in question, whether simple or complex. - -Moreover, a third possibility may even be simpler than anything -discussed above: "Just require that all possible (or at least -applicable) forms be provided in the call to the given language's quant -method, as in:" - - "I found [quant,_1,file,files]." - -That way, quant just has to chose which form it needs, without having -to look up or generate anything. While possibly not optimal for -Russian, this should work well for most other languages, where -quantification is not as complicated an operation. - -=head2 The Devil in the Details - -There's plenty more to Maketext than described above -- for example, -there's the details of how language tags ("en-US", "i-pwn", "fi", -etc.) or locale IDs ("en_US") interact with actual module naming -("BogoQuery/Locale/en_us.pm"), and what magic can ensue; there's the -details of how to record (and possibly negotiate) what character -encoding Maketext will return text in (UTF8? Latin-1? KOI8?). There's -the interesting fact that Maketext is for localization, but nowhere -actually has a "C<use locale;>" anywhere in it. For the curious, -there's the somewhat frightening details of how I actually -implement something like data inheritance so that searches across -modules' %Lexicon hashes can parallel how Perl implements method -inheritance. - -And, most importantly, there's all the practical details of how to -actually go about deriving from Maketext so you can use it for your -interfaces, and the various tools and conventions for starting out and -maintaining individual language modules. - -That is all covered in the documentation for Locale::Maketext and the -modules that come with it, available in CPAN. After having read this -article, which covers the why's of Maketext, the documentation, -which covers the how's of it, should be quite straightforward. - -=head2 The Proof in the Pudding: Localizing Web Sites - -Maketext and gettext have a notable difference: gettext is in C, -accessible thru C library calls, whereas Maketext is in Perl, and -really can't work without a Perl interpreter (although I suppose -something like it could be written for C). Accidents of history (and -not necessarily lucky ones) have made C++ the most common language for -the implementation of applications like word processors, Web browsers, -and even many in-house applications like custom query systems. Current -conditions make it somewhat unlikely that the next one of any of these -kinds of applications will be written in Perl, albeit clearly more for -reasons of custom and inertia than out of consideration of what is the -right tool for the job. - -However, other accidents of history have made Perl a well-accepted -language for design of server-side programs (generally in CGI form) -for Web site interfaces. Localization of static pages in Web sites is -trivial, feasable either with simple language-negotiation features in -servers like Apache, or with some kind of server-side inclusions of -language-appropriate text into layout templates. However, I think -that the localization of Perl-based search systems (or other kinds of -dynamic content) in Web sites, be they public or access-restricted, -is where Maketext will see the greatest use. - -I presume that it would be only the exceptional Web site that gets -localized for English I<and> Chinese I<and> Italian I<and> Arabic -I<and> Russian, to recall the languages from the beginning of this -article -- to say nothing of German, Spanish, French, Japanese, -Finnish, and Hindi, to name a few languages that benefit from large -numbers of programmers or Web viewers or both. - -However, the ever-increasing internationalization of the Web (whether -measured in terms of amount of content, of numbers of content writers -or programmers, or of size of content audiences) makes it increasingly -likely that the interface to the average Web-based dynamic content -service will be localized for two or maybe three languages. It is my -hope that Maketext will make that task as simple as possible, and will -remove previous barriers to localization for languages dissimilar to -English. - - __END__ - -Sean M. Burke (sburkeE<64>cpan.org) has a Master's in linguistics -from Northwestern University; he specializes in language technology. -Jordan Lachler (lachlerE<64>unm.edu) is a PhD student in the Department of -Linguistics at the University of New Mexico; he specializes in -morphology and pedagogy of North American native languages. - -=head2 References - -Alvestrand, Harald Tveit. 1995. I<RFC 1766: Tags for the -Identification of Languages.> -C<http://www.ietf.org/rfc/rfc1766.txt> -[Now see RFC 3066.] - -Callon, Ross, editor. 1996. I<RFC 1925: The Twelve -Networking Truths.> -C<http://www.ietf.org/rfc/rfc1925.txt> - -Drepper, Ulrich, Peter Miller, -and FranE<ccedil>ois Pinard. 1995-2001. GNU -C<gettext>. Available in C<ftp://prep.ai.mit.edu/pub/gnu/>, with -extensive docs in the distribution tarball. [Since -I wrote this article in 1998, I now see that the -gettext docs are now trying more to come to terms with -plurality. Whether useful conclusions have come from it -is another question altogether. -- SMB, May 2001] - -Forbes, Nevill. 1964. I<Russian Grammar.> Third Edition, revised -by J. C. Dumbreck. Oxford University Press. - -=cut - -#End - diff --git a/Master/tlpkg/tlperl/lib/Locale/Script.pod b/Master/tlpkg/tlperl/lib/Locale/Script.pod deleted file mode 100644 index 0afb533601e..00000000000 --- a/Master/tlpkg/tlperl/lib/Locale/Script.pod +++ /dev/null @@ -1,131 +0,0 @@ -=pod - -=head1 NAME - -Locale::Script - standard codes for script identification - -=head1 SYNOPSIS - - use Locale::Script; - - $script = code2script('phnx'); # 'Phoenician' - $code = script2code('Phoenician'); # 'Phnx' - $code = script2code('Phoenician', - LOCALE_CODE_NUMERIC); # 115 - - @codes = all_script_codes(); - @scripts = all_script_names(); - -=head1 DESCRIPTION - -The C<Locale::Script> module provides access to standards codes used -for identifying scripts, such as those defined in ISO 15924. - -Most of the routines take an optional additional argument which -specifies the code set to use. If not specified, the default ISO -15924 four-letter codes will be used. - -=head1 SUPPORTED CODE SETS - -There are several different code sets you can use for identifying -scripts. A code set may be specified using either a name, or a -constant that is automatically exported by this module. - -For example, the two are equivalent: - - $script = code2script('phnx','alpha'); - $script = code2script('phnx',LOCALE_SCRIPT_ALPHA); - -The codesets currently supported are: - -=over 4 - -=item B<alpha, LOCALE_SCRIPT_ALPHA> - -This is a set of four-letter (capitalized) codes from ISO 15924 -such as 'Phnx' for Phoenician. It also includes additions to this -set included in the IANA language registry. - -The Zxxx, Zyyy, and Zzzz codes are not used. - -This is the default code set. - -=item B<num, LOCALE_SCRIPT_NUMERIC> - -This is a set of three-digit numeric codes from ISO 15924 such as 115 -for Phoenician. - -=back - -=head1 ROUTINES - -=over 4 - -=item B<code2script ( CODE [,CODESET] )> - -=item B<script2code ( NAME [,CODESET] )> - -=item B<script_code2code ( CODE ,CODESET ,CODESET2 )> - -=item B<all_script_codes ( [CODESET] )> - -=item B<all_script_names ( [CODESET] )> - -=item B<Locale::Script::rename_script ( CODE ,NEW_NAME [,CODESET] )> - -=item B<Locale::Script::add_script ( CODE ,NAME [,CODESET] )> - -=item B<Locale::Script::delete_script ( CODE [,CODESET] )> - -=item B<Locale::Script::add_script_alias ( NAME ,NEW_NAME )> - -=item B<Locale::Script::delete_script_alias ( NAME )> - -=item B<Locale::Script::rename_script_code ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Script::add_script_code_alias ( CODE ,NEW_CODE [,CODESET] )> - -=item B<Locale::Script::delete_script_code_alias ( CODE [,CODESET] )> - -These routines are all documented in the Locale::Codes::API man page. - -=back - -=head1 SEE ALSO - -=over 4 - -=item B<Locale::Codes> - -The Locale-Codes distribution. - -=item B<Locale::Codes::API> - -The list of functions supported by this module. - -=item B<http://www.unicode.org/iso15924/> - -Home page for ISO 15924. - -=item B<http://www.iana.org/assignments/language-subtag-registry> - -The IANA language subtag registry. - -=back - -=head1 AUTHOR - -See Locale::Codes for full author history. - -Currently maintained by Sullivan Beck (sbeck@cpan.org). - -=head1 COPYRIGHT - - Copyright (c) 1997-2001 Canon Research Centre Europe (CRE). - Copyright (c) 2001-2010 Neil Bowers - Copyright (c) 2010-2012 Sullivan Beck - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - -=cut |