Locale::Maketext external cache support
[perl.git] / dist / Locale-Maketext / lib / Locale / Maketext.pod
1
2 # Time-stamp: "2004-01-11 18:35:34 AST"
3
4 =head1 NAME
5
6 Locale::Maketext - framework for localization
7
8 =head1 SYNOPSIS
9
10   package MyProgram;
11   use strict;
12   use MyProgram::L10N;
13    # ...which inherits from Locale::Maketext
14   my $lh = MyProgram::L10N->get_handle() || die "What language?";
15   ...
16   # And then any messages your program emits, like:
17   warn $lh->maketext( "Can't open file [_1]: [_2]\n", $f, $! );
18   ...
19
20 =head1 DESCRIPTION
21
22 It is a common feature of applications (whether run directly,
23 or via the Web) for them to be "localized" -- i.e., for them
24 to a present an English interface to an English-speaker, a German
25 interface to a German-speaker, and so on for all languages it's
26 programmed with.  Locale::Maketext
27 is a framework for software localization; it provides you with the
28 tools for organizing and accessing the bits of text and text-processing
29 code that you need for producing localized applications.
30
31 In order to make sense of Maketext and how all its
32 components fit together, you should probably
33 go read L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>, and
34 I<then> read the following documentation.
35
36 You may also want to read over the source for C<File::Findgrep>
37 and its constituent modules -- they are a complete (if small)
38 example application that uses Maketext.
39
40 =head1 QUICK OVERVIEW
41
42 The basic design of Locale::Maketext is object-oriented, and
43 Locale::Maketext is an abstract base class, from which you
44 derive a "project class".
45 The project class (with a name like "TkBocciBall::Localize",
46 which you then use in your module) is in turn the base class
47 for all the "language classes" for your project
48 (with names "TkBocciBall::Localize::it", 
49 "TkBocciBall::Localize::en",
50 "TkBocciBall::Localize::fr", etc.).
51
52 A language class is
53 a class containing a lexicon of phrases as class data,
54 and possibly also some methods that are of use in interpreting
55 phrases in the lexicon, or otherwise dealing with text in that
56 language.
57
58 An object belonging to a language class is called a "language
59 handle"; it's typically a flyweight object.
60
61 The normal course of action is to call:
62
63   use TkBocciBall::Localize;  # the localization project class
64   $lh = TkBocciBall::Localize->get_handle();
65    # Depending on the user's locale, etc., this will
66    # make a language handle from among the classes available,
67    # and any defaults that you declare.
68   die "Couldn't make a language handle??" unless $lh;
69
70 From then on, you use the C<maketext> function to access
71 entries in whatever lexicon(s) belong to the language handle
72 you got.  So, this:
73
74   print $lh->maketext("You won!"), "\n";
75
76 ...emits the right text for this language.  If the object
77 in C<$lh> belongs to class "TkBocciBall::Localize::fr" and
78 %TkBocciBall::Localize::fr::Lexicon contains C<("You won!"
79 =E<gt> "Tu as gagnE<eacute>!")>, then the above
80 code happily tells the user "Tu as gagnE<eacute>!".
81
82 =head1 METHODS
83
84 Locale::Maketext offers a variety of methods, which fall
85 into three categories:
86
87 =over
88
89 =item *
90
91 Methods to do with constructing language handles.
92
93 =item *
94
95 C<maketext> and other methods to do with accessing %Lexicon data
96 for a given language handle.
97
98 =item *
99
100 Methods that you may find it handy to use, from routines of
101 yours that you put in %Lexicon entries.
102
103 =back
104
105 These are covered in the following section.
106
107 =head2 Construction Methods
108
109 These are to do with constructing a language handle:
110
111 =over
112
113 =item *
114
115 $lh = YourProjClass->get_handle( ...langtags... ) || die "lg-handle?";
116
117 This tries loading classes based on the language-tags you give (like
118 C<("en-US", "sk", "kon", "es-MX", "ja", "i-klingon")>, and for the first class
119 that succeeds, returns YourProjClass::I<language>->new().
120
121 If it runs thru the entire given list of language-tags, and finds no classes
122 for those exact terms, it then tries "superordinate" language classes.
123 So if no "en-US" class (i.e., YourProjClass::en_us)
124 was found, nor classes for anything else in that list, we then try
125 its superordinate, "en" (i.e., YourProjClass::en), and so on thru 
126 the other language-tags in the given list: "es".
127 (The other language-tags in our example list: 
128 happen to have no superordinates.)
129
130 If none of those language-tags leads to loadable classes, we then
131 try classes derived from YourProjClass->fallback_languages() and
132 then if nothing comes of that, we use classes named by
133 YourProjClass->fallback_language_classes().  Then in the (probably
134 quite unlikely) event that that fails, we just return undef.
135
136 =item *
137
138 $lh = YourProjClass->get_handleB<()> || die "lg-handle?";
139
140 When C<get_handle> is called with an empty parameter list, magic happens:
141
142 If C<get_handle> senses that it's running in program that was
143 invoked as a CGI, then it tries to get language-tags out of the
144 environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that
145 those were the languages passed as parameters to C<get_handle>.
146
147 Otherwise (i.e., if not a CGI), this tries various OS-specific ways
148 to get the language-tags for the current locale/language, and then
149 pretends that those were the value(s) passed to C<get_handle>.
150
151 Currently this OS-specific stuff consists of looking in the environment
152 variables "LANG" and "LANGUAGE"; and on MSWin machines (where those
153 variables are typically unused), this also tries using
154 the module Win32::Locale to get a language-tag for whatever language/locale
155 is currently selected in the "Regional Settings" (or "International"?)
156 Control Panel.  I welcome further
157 suggestions for making this do the Right Thing under other operating
158 systems that support localization.
159
160 If you're using localization in an application that keeps a configuration
161 file, you might consider something like this in your project class:
162
163   sub get_handle_via_config {
164     my $class = $_[0];
165     my $chosen_language = $Config_settings{'language'};
166     my $lh;
167     if($chosen_language) {
168       $lh = $class->get_handle($chosen_language)
169        || die "No language handle for \"$chosen_language\" or the like";
170     } else {
171       # Config file missing, maybe?
172       $lh = $class->get_handle()
173        || die "Can't get a language handle";
174     }
175     return $lh;
176   }
177
178 =item *
179
180 $lh = YourProjClass::langname->new();
181
182 This constructs a language handle.  You usually B<don't> call this
183 directly, but instead let C<get_handle> find a language class to C<use>
184 and to then call ->new on.
185
186 =item *
187
188 $lh->init();
189
190 This is called by ->new to initialize newly-constructed language handles.
191 If you define an init method in your class, remember that it's usually
192 considered a good idea to call $lh->SUPER::init in it (presumably at the
193 beginning), so that all classes get a chance to initialize a new object
194 however they see fit.
195
196 =item *
197
198 YourProjClass->fallback_languages()
199
200 C<get_handle> appends the return value of this to the end of
201 whatever list of languages you pass C<get_handle>.  Unless
202 you override this method, your project class
203 will inherit Locale::Maketext's C<fallback_languages>, which
204 currently returns C<('i-default', 'en', 'en-US')>.
205 ("i-default" is defined in RFC 2277).
206
207 This method (by having it return the name
208 of a language-tag that has an existing language class)
209 can be used for making sure that
210 C<get_handle> will always manage to construct a language
211 handle (assuming your language classes are in an appropriate
212 @INC directory).  Or you can use the next method:
213
214 =item *
215
216 YourProjClass->fallback_language_classes()
217
218 C<get_handle> appends the return value of this to the end
219 of the list of classes it will try using.  Unless
220 you override this method, your project class
221 will inherit Locale::Maketext's C<fallback_language_classes>,
222 which currently returns an empty list, C<()>.
223 By setting this to some value (namely, the name of a loadable
224 language class), you can be sure that
225 C<get_handle> will always manage to construct a language
226 handle.
227
228 =back
229
230 =head2 The "maketext" Method
231
232 This is the most important method in Locale::Maketext:
233
234     $text = $lh->maketext(I<key>, ...parameters for this phrase...);
235
236 This looks in the %Lexicon of the language handle
237 $lh and all its superclasses, looking
238 for an entry whose key is the string I<key>.  Assuming such
239 an entry is found, various things then happen, depending on the
240 value found:
241
242 If the value is a scalarref, the scalar is dereferenced and returned
243 (and any parameters are ignored).
244
245 If the value is a coderef, we return &$value($lh, ...parameters...).
246
247 If the value is a string that I<doesn't> look like it's in Bracket Notation,
248 we return it (after replacing it with a scalarref, in its %Lexicon).
249
250 If the value I<does> look like it's in Bracket Notation, then we compile
251 it into a sub, replace the string in the %Lexicon with the new coderef,
252 and then we return &$new_sub($lh, ...parameters...).
253
254 Bracket Notation is discussed in a later section.  Note
255 that trying to compile a string into Bracket Notation can throw
256 an exception if the string is not syntactically valid (say, by not
257 balancing brackets right.)
258
259 Also, calling &$coderef($lh, ...parameters...) can throw any sort of
260 exception (if, say, code in that sub tries to divide by zero).  But
261 a very common exception occurs when you have Bracket
262 Notation text that says to call a method "foo", but there is no such
263 method.  (E.g., "You have [quaB<tn>,_1,ball]." will throw an exception
264 on trying to call $lh->quaB<tn>($_[1],'ball') -- you presumably meant
265 "quant".)  C<maketext> catches these exceptions, but only to make the
266 error message more readable, at which point it rethrows the exception.
267
268 An exception I<may> be thrown if I<key> is not found in any
269 of $lh's %Lexicon hashes.  What happens if a key is not found,
270 is discussed in a later section, "Controlling Lookup Failure".
271
272 Note that you might find it useful in some cases to override
273 the C<maketext> method with an "after method", if you want to
274 translate encodings, or even scripts:
275
276     package YrProj::zh_cn; # Chinese with PRC-style glyphs
277     use base ('YrProj::zh_tw');  # Taiwan-style
278     sub maketext {
279       my $self = shift(@_);
280       my $value = $self->maketext(@_);
281       return Chineeze::taiwan2mainland($value);
282     }
283
284 Or you may want to override it with something that traps
285 any exceptions, if that's critical to your program:
286
287   sub maketext {
288     my($lh, @stuff) = @_;
289     my $out;
290     eval { $out = $lh->SUPER::maketext(@stuff) };
291     return $out unless $@;
292     ...otherwise deal with the exception...
293   }
294
295 Other than those two situations, I don't imagine that
296 it's useful to override the C<maketext> method.  (If
297 you run into a situation where it is useful, I'd be
298 interested in hearing about it.)
299
300 =over
301
302 =item $lh->fail_with I<or> $lh->fail_with(I<PARAM>)
303
304 =item $lh->failure_handler_auto
305
306 These two methods are discussed in the section "Controlling
307 Lookup Failure".
308
309 =back
310
311 =head2 Utility Methods
312
313 These are methods that you may find it handy to use, generally
314 from %Lexicon routines of yours (whether expressed as
315 Bracket Notation or not).
316
317 =over
318
319 =item $language->quant($number, $singular)
320
321 =item $language->quant($number, $singular, $plural)
322
323 =item $language->quant($number, $singular, $plural, $negative)
324
325 This is generally meant to be called from inside Bracket Notation
326 (which is discussed later), as in 
327
328      "Your search matched [quant,_1,document]!"
329
330 It's for I<quantifying> a noun (i.e., saying how much of it there is,
331 while giving the correct form of it).  The behavior of this method is
332 handy for English and a few other Western European languages, and you
333 should override it for languages where it's not suitable.  You can feel
334 free to read the source, but the current implementation is basically
335 as this pseudocode describes:
336
337      if $number is 0 and there's a $negative,
338         return $negative;
339      elsif $number is 1,
340         return "1 $singular";
341      elsif there's a $plural,
342         return "$number $plural";
343      else
344         return "$number " . $singular . "s";
345      #
346      # ...except that we actually call numf to
347      #  stringify $number before returning it.
348
349 So for English (with Bracket Notation)
350 C<"...[quant,_1,file]..."> is fine (for 0 it returns "0 files",
351 for 1 it returns "1 file", and for more it returns "2 files", etc.)
352
353 But for "directory", you'd want C<"[quant,_1,directory,directories]">
354 so that our elementary C<quant> method doesn't think that the
355 plural of "directory" is "directorys".  And you might find that the
356 output may sound better if you specify a negative form, as in:
357
358      "[quant,_1,file,files,No files] matched your query.\n"
359
360 Remember to keep in mind verb agreement (or adjectives too, in
361 other languages), as in:
362
363      "[quant,_1,document] were matched.\n"
364
365 Because if _1 is one, you get "1 document B<were> matched".
366 An acceptable hack here is to do something like this:
367
368      "[quant,_1,document was, documents were] matched.\n"
369
370 =item $language->numf($number)
371
372 This returns the given number formatted nicely according to
373 this language's conventions.  Maketext's default method is
374 mostly to just take the normal string form of the number
375 (applying sprintf "%G" for only very large numbers), and then
376 to add commas as necessary.  (Except that
377 we apply C<tr/,./.,/> if $language->{'numf_comma'} is true;
378 that's a bit of a hack that's useful for languages that express
379 two million as "2.000.000" and not as "2,000,000").
380
381 If you want anything fancier, consider overriding this with something
382 that uses L<Number::Format|Number::Format>, or does something else
383 entirely.
384
385 Note that numf is called by quant for stringifying all quantifying
386 numbers.
387
388 =item $language->sprintf($format, @items)
389
390 This is just a wrapper around Perl's normal C<sprintf> function.
391 It's provided so that you can use "sprintf" in Bracket Notation:
392
393      "Couldn't access datanode [sprintf,%10x=~[%s~],_1,_2]!\n"
394
395 returning...
396
397      Couldn't access datanode      Stuff=[thangamabob]!
398
399 =item $language->language_tag()
400
401 Currently this just takes the last bit of C<ref($language)>, turns
402 underscores to dashes, and returns it.  So if $language is
403 an object of class Hee::HOO::Haw::en_us, $language->language_tag()
404 returns "en-us".  (Yes, the usual representation for that language
405 tag is "en-US", but case is I<never> considered meaningful in
406 language-tag comparison.)
407
408 You may override this as you like; Maketext doesn't use it for
409 anything.
410
411 =item $language->encoding()
412
413 Currently this isn't used for anything, but it's provided
414 (with default value of
415 C<(ref($language) && $language-E<gt>{'encoding'})) or "iso-8859-1">
416 ) as a sort of suggestion that it may be useful/necessary to
417 associate encodings with your language handles (whether on a
418 per-class or even per-handle basis.)
419
420 =back
421
422 =head2 Language Handle Attributes and Internals
423
424 A language handle is a flyweight object -- i.e., it doesn't (necessarily)
425 carry any data of interest, other than just being a member of
426 whatever class it belongs to.
427
428 A language handle is implemented as a blessed hash.  Subclasses of yours
429 can store whatever data you want in the hash.  Currently the only hash
430 entry used by any crucial Maketext method is "fail", so feel free to
431 use anything else as you like.
432
433 B<Remember: Don't be afraid to read the Maketext source if there's
434 any point on which this documentation is unclear.>  This documentation
435 is vastly longer than the module source itself.
436
437 =over
438
439 =back
440
441 =head1 LANGUAGE CLASS HIERARCHIES
442
443 These are Locale::Maketext's assumptions about the class
444 hierarchy formed by all your language classes:
445
446 =over
447
448 =item *
449
450 You must have a project base class, which you load, and
451 which you then use as the first argument in
452 the call to YourProjClass->get_handle(...).  It should derive
453 (whether directly or indirectly) from Locale::Maketext.
454 It B<doesn't matter> how you name this class, although assuming this
455 is the localization component of your Super Mega Program,
456 good names for your project class might be
457 SuperMegaProgram::Localization, SuperMegaProgram::L10N,
458 SuperMegaProgram::I18N, SuperMegaProgram::International,
459 or even SuperMegaProgram::Languages or SuperMegaProgram::Messages.
460
461 =item *
462
463 Language classes are what YourProjClass->get_handle will try to load.
464 It will look for them by taking each language-tag (B<skipping> it
465 if it doesn't look like a language-tag or locale-tag!), turning it to
466 all lowercase, turning dashes to underscores, and appending it
467 to YourProjClass . "::".  So this:
468
469   $lh = YourProjClass->get_handle(
470     'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized'
471   );
472
473 will try loading the classes 
474 YourProjClass::en_us (note lowercase!), YourProjClass::fr, 
475 YourProjClass::kon,
476 YourProjClass::i_klingon
477 and YourProjClass::i_klingon_romanized.  (And it'll stop at the
478 first one that actually loads.)
479
480 =item *
481
482 I assume that each language class derives (directly or indirectly)
483 from your project class, and also defines its @ISA, its %Lexicon,
484 or both.  But I anticipate no dire consequences if these assumptions
485 do not hold.
486
487 =item *
488
489 Language classes may derive from other language classes (although they
490 should have "use I<Thatclassname>" or "use base qw(I<...classes...>)").
491 They may derive from the project
492 class.  They may derive from some other class altogether.  Or via
493 multiple inheritance, it may derive from any mixture of these.
494
495 =item *
496
497 I foresee no problems with having multiple inheritance in
498 your hierarchy of language classes.  (As usual, however, Perl will
499 complain bitterly if you have a cycle in the hierarchy: i.e., if
500 any class is its own ancestor.)
501
502 =back
503
504 =head1 ENTRIES IN EACH LEXICON
505
506 A typical %Lexicon entry is meant to signify a phrase,
507 taking some number (0 or more) of parameters.  An entry
508 is meant to be accessed by via
509 a string I<key> in $lh->maketext(I<key>, ...parameters...),
510 which should return a string that is generally meant for
511 be used for "output" to the user -- regardless of whether
512 this actually means printing to STDOUT, writing to a file,
513 or putting into a GUI widget.
514
515 While the key must be a string value (since that's a basic
516 restriction that Perl places on hash keys), the value in
517 the lexicon can currently be of several types:
518 a defined scalar, scalarref, or coderef.  The use of these is
519 explained above, in the section 'The "maketext" Method', and
520 Bracket Notation for strings is discussed in the next section.
521
522 While you can use arbitrary unique IDs for lexicon keys
523 (like "_min_larger_max_error"), it is often
524 useful for if an entry's key is itself a valid value, like
525 this example error message:
526
527   "Minimum ([_1]) is larger than maximum ([_2])!\n",
528
529 Compare this code that uses an arbitrary ID...
530
531   die $lh->maketext( "_min_larger_max_error", $min, $max )
532    if $min > $max;
533
534 ...to this code that uses a key-as-value:
535
536   die $lh->maketext(
537    "Minimum ([_1]) is larger than maximum ([_2])!\n",
538    $min, $max
539   ) if $min > $max;
540
541 The second is, in short, more readable.  In particular, it's obvious
542 that the number of parameters you're feeding to that phrase (two) is
543 the number of parameters that it I<wants> to be fed.  (Since you see
544 _1 and a _2 being used in the key there.)
545
546 Also, once a project is otherwise
547 complete and you start to localize it, you can scrape together
548 all the various keys you use, and pass it to a translator; and then
549 the translator's work will go faster if what he's presented is this:
550
551  "Minimum ([_1]) is larger than maximum ([_2])!\n",
552   => "",   # fill in something here, Jacques!
553
554 rather than this more cryptic mess:
555
556  "_min_larger_max_error"
557   => "",   # fill in something here, Jacques
558
559 I think that keys as lexicon values makes the completed lexicon
560 entries more readable:
561
562  "Minimum ([_1]) is larger than maximum ([_2])!\n",
563   => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\n",
564
565 Also, having valid values as keys becomes very useful if you set
566 up an _AUTO lexicon.  _AUTO lexicons are discussed in a later
567 section.
568
569 I almost always use keys that are themselves
570 valid lexicon values.  One notable exception is when the value is
571 quite long.  For example, to get the screenful of data that
572 a command-line program might return when given an unknown switch,
573 I often just use a brief, self-explanatory key such as "_USAGE_MESSAGE".  At that point I then go
574 and immediately to define that lexicon entry in the
575 ProjectClass::L10N::en lexicon (since English is always my "project
576 language"):
577
578   '_USAGE_MESSAGE' => <<'EOSTUFF',
579   ...long long message...
580   EOSTUFF
581
582 and then I can use it as:
583
584   getopt('oDI', \%opts) or die $lh->maketext('_USAGE_MESSAGE');
585
586 Incidentally,
587 note that each class's C<%Lexicon> inherits-and-extends
588 the lexicons in its superclasses.  This is not because these are
589 special hashes I<per se>, but because you access them via the
590 C<maketext> method, which looks for entries across all the
591 C<%Lexicon> hashes in a language class I<and> all its ancestor classes.
592 (This is because the idea of "class data" isn't directly implemented
593 in Perl, but is instead left to individual class-systems to implement
594 as they see fit..)
595
596 Note that you may have things stored in a lexicon
597 besides just phrases for output:  for example, if your program
598 takes input from the keyboard, asking a "(Y/N)" question,
599 you probably need to know what the equivalent of "Y[es]/N[o]" is
600 in whatever language.  You probably also need to know what
601 the equivalents of the answers "y" and "n" are.  You can
602 store that information in the lexicon (say, under the keys
603 "~answer_y" and "~answer_n", and the long forms as
604 "~answer_yes" and "~answer_no", where "~" is just an ad-hoc
605 character meant to indicate to programmers/translators that
606 these are not phrases for output).
607
608 Or instead of storing this in the language class's lexicon,
609 you can (and, in some cases, really should) represent the same bit
610 of knowledge as code in a method in the language class.  (That
611 leaves a tidy distinction between the lexicon as the things we
612 know how to I<say>, and the rest of the things in the lexicon class
613 as things that we know how to I<do>.)  Consider
614 this example of a processor for responses to French "oui/non"
615 questions:
616
617   sub y_or_n {
618     return undef unless defined $_[1] and length $_[1];
619     my $answer = lc $_[1];  # smash case
620     return 1 if $answer eq 'o' or $answer eq 'oui';
621     return 0 if $answer eq 'n' or $answer eq 'non';
622     return undef;
623   }
624
625 ...which you'd then call in a construct like this:
626
627   my $response;
628   until(defined $response) {
629     print $lh->maketext("Open the pod bay door (y/n)? ");
630     $response = $lh->y_or_n( get_input_from_keyboard_somehow() );
631   }
632   if($response) { $pod_bay_door->open()         }
633   else          { $pod_bay_door->leave_closed() }
634
635 Other data worth storing in a lexicon might be things like
636 filenames for language-targetted resources:
637
638   ...
639   "_main_splash_png"
640     => "/styles/en_us/main_splash.png",
641   "_main_splash_imagemap"
642     => "/styles/en_us/main_splash.incl",
643   "_general_graphics_path"
644     => "/styles/en_us/",
645   "_alert_sound"
646     => "/styles/en_us/hey_there.wav",
647   "_forward_icon"
648    => "left_arrow.png",
649   "_backward_icon"
650    => "right_arrow.png",
651   # In some other languages, left equals
652   #  BACKwards, and right is FOREwards.
653   ...
654
655 You might want to do the same thing for expressing key bindings
656 or the like (since hardwiring "q" as the binding for the function
657 that quits a screen/menu/program is useful only if your language
658 happens to associate "q" with "quit"!)
659
660 =head1 BRACKET NOTATION
661
662 Bracket Notation is a crucial feature of Locale::Maketext.  I mean
663 Bracket Notation to provide a replacement for the use of sprintf formatting.
664 Everything you do with Bracket Notation could be done with a sub block,
665 but bracket notation is meant to be much more concise.
666
667 Bracket Notation is a like a miniature "template" system (in the sense
668 of L<Text::Template|Text::Template>, not in the sense of C++ templates),
669 where normal text is passed thru basically as is, but text in special
670 regions is specially interpreted.  In Bracket Notation, you use square brackets ("[...]"),
671 not curly braces ("{...}") to note sections that are specially interpreted.
672
673 For example, here all the areas that are taken literally are underlined with
674 a "^", and all the in-bracket special regions are underlined with an X:
675
676   "Minimum ([_1]) is larger than maximum ([_2])!\n",
677    ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^
678
679 When that string is compiled from bracket notation into a real Perl sub,
680 it's basically turned into:
681
682   sub {
683     my $lh = $_[0];
684     my @params = @_;
685     return join '',
686       "Minimum (",
687       ...some code here...
688       ") is larger than maximum (",
689       ...some code here...
690       ")!\n",
691   }
692   # to be called by $lh->maketext(KEY, params...)
693    
694 In other words, text outside bracket groups is turned into string
695 literals.  Text in brackets is rather more complex, and currently follows
696 these rules:
697
698 =over
699
700 =item *
701
702 Bracket groups that are empty, or which consist only of whitespace,
703 are ignored.  (Examples: "[]", "[    ]", or a [ and a ] with returns
704 and/or tabs and/or spaces between them.
705
706 Otherwise, each group is taken to be a comma-separated group of items,
707 and each item is interpreted as follows:
708
709 =item *
710
711 An item that is "_I<digits>" or "_-I<digits>" is interpreted as
712 $_[I<value>].  I.e., "_1" becomes with $_[1], and "_-3" is interpreted
713 as $_[-3] (in which case @_ should have at least three elements in it).
714 Note that $_[0] is the language handle, and is typically not named
715 directly.
716
717 =item *
718
719 An item "_*" is interpreted to mean "all of @_ except $_[0]".
720 I.e., C<@_[1..$#_]>.  Note that this is an empty list in the case
721 of calls like $lh->maketext(I<key>) where there are no
722 parameters (except $_[0], the language handle).
723
724 =item *
725
726 Otherwise, each item is interpreted as a string literal.
727
728 =back
729
730 The group as a whole is interpreted as follows:
731
732 =over
733
734 =item *
735
736 If the first item in a bracket group looks like a method name,
737 then that group is interpreted like this:
738
739   $lh->that_method_name(
740     ...rest of items in this group...
741   ),
742
743 =item *
744
745 If the first item in a bracket group is "*", it's taken as shorthand
746 for the so commonly called "quant" method.  Similarly, if the first
747 item in a bracket group is "#", it's taken to be shorthand for
748 "numf".
749
750 =item *
751
752 If the first item in a bracket group is the empty-string, or "_*"
753 or "_I<digits>" or "_-I<digits>", then that group is interpreted
754 as just the interpolation of all its items:
755
756   join('',
757     ...rest of items in this group...
758   ),
759
760 Examples:  "[_1]" and "[,_1]", which are synonymous; and
761 "C<[,ID-(,_4,-,_2,)]>", which compiles as
762 C<join "", "ID-(", $_[4], "-", $_[2], ")">.
763
764 =item *
765
766 Otherwise this bracket group is invalid.  For example, in the group
767 "[!@#,whatever]", the first item C<"!@#"> is neither the empty-string,
768 "_I<number>", "_-I<number>", "_*", nor a valid method name; and so
769 Locale::Maketext will throw an exception of you try compiling an
770 expression containing this bracket group.
771
772 =back
773
774 Note, incidentally, that items in each group are comma-separated,
775 not C</\s*,\s*/>-separated.  That is, you might expect that this
776 bracket group:
777
778   "Hoohah [foo, _1 , bar ,baz]!"
779
780 would compile to this:
781
782   sub {
783     my $lh = $_[0];
784     return join '',
785       "Hoohah ",
786       $lh->foo( $_[1], "bar", "baz"),
787       "!",
788   }
789
790 But it actually compiles as this:
791
792   sub {
793     my $lh = $_[0];
794     return join '',
795       "Hoohah ",
796       $lh->foo(" _1 ", " bar ", "baz"),  # note the <space> in " bar "
797       "!",
798   }
799
800 In the notation discussed so far, the characters "[" and "]" are given
801 special meaning, for opening and closing bracket groups, and "," has
802 a special meaning inside bracket groups, where it separates items in the
803 group.  This begs the question of how you'd express a literal "[" or
804 "]" in a Bracket Notation string, and how you'd express a literal
805 comma inside a bracket group.  For this purpose I've adopted "~" (tilde)
806 as an escape character:  "~[" means a literal '[' character anywhere
807 in Bracket Notation (i.e., regardless of whether you're in a bracket
808 group or not), and ditto for "~]" meaning a literal ']', and "~," meaning
809 a literal comma.  (Altho "," means a literal comma outside of
810 bracket groups -- it's only inside bracket groups that commas are special.)
811
812 And on the off chance you need a literal tilde in a bracket expression,
813 you get it with "~~".
814
815 Currently, an unescaped "~" before a character
816 other than a bracket or a comma is taken to mean just a "~" and that
817 character.  I.e., "~X" means the same as "~~X" -- i.e., one literal tilde,
818 and then one literal "X".  However, by using "~X", you are assuming that
819 no future version of Maketext will use "~X" as a magic escape sequence.
820 In practice this is not a great problem, since first off you can just
821 write "~~X" and not worry about it; second off, I doubt I'll add lots
822 of new magic characters to bracket notation; and third off, you
823 aren't likely to want literal "~" characters in your messages anyway,
824 since it's not a character with wide use in natural language text.
825
826 Brackets must be balanced -- every openbracket must have
827 one matching closebracket, and vice versa.  So these are all B<invalid>:
828
829   "I ate [quant,_1,rhubarb pie."
830   "I ate [quant,_1,rhubarb pie[."
831   "I ate quant,_1,rhubarb pie]."
832   "I ate quant,_1,rhubarb pie[."
833
834 Currently, bracket groups do not nest.  That is, you B<cannot> say:
835
836   "Foo [bar,baz,[quux,quuux]]\n";
837
838 If you need a notation that's that powerful, use normal Perl:
839
840   %Lexicon = (
841     ...
842     "some_key" => sub {
843       my $lh = $_[0];
844       join '',
845         "Foo ",
846         $lh->bar('baz', $lh->quux('quuux')),
847         "\n",
848     },
849     ...
850   );
851
852 Or write the "bar" method so you don't need to pass it the
853 output from calling quux.
854
855 I do not anticipate that you will need (or particularly want)
856 to nest bracket groups, but you are welcome to email me with
857 convincing (real-life) arguments to the contrary.
858
859 =head1 AUTO LEXICONS
860
861 If maketext goes to look in an individual %Lexicon for an entry
862 for I<key> (where I<key> does not start with an underscore), and
863 sees none, B<but does see> an entry of "_AUTO" => I<some_true_value>,
864 then we actually define $Lexicon{I<key>} = I<key> right then and there,
865 and then use that value as if it had been there all
866 along.  This happens before we even look in any superclass %Lexicons!
867
868 (This is meant to be somewhat like the AUTOLOAD mechanism in
869 Perl's function call system -- or, looked at another way,
870 like the L<AutoLoader|AutoLoader> module.)
871
872 I can picture all sorts of circumstances where you just
873 do not want lookup to be able to fail (since failing
874 normally means that maketext throws a C<die>, although
875 see the next section for greater control over that).  But
876 here's one circumstance where _AUTO lexicons are meant to
877 be I<especially> useful:
878
879 As you're writing an application, you decide as you go what messages
880 you need to emit.  Normally you'd go to write this:
881
882   if(-e $filename) {
883     go_process_file($filename)
884   } else {
885     print qq{Couldn't find file "$filename"!\n};
886   }
887
888 but since you anticipate localizing this, you write:
889
890   use ThisProject::I18N;
891   my $lh = ThisProject::I18N->get_handle();
892    # For the moment, assume that things are set up so
893    # that we load class ThisProject::I18N::en
894    # and that that's the class that $lh belongs to.
895   ...
896   if(-e $filename) {
897     go_process_file($filename)
898   } else {
899     print $lh->maketext(
900       qq{Couldn't find file "[_1]"!\n}, $filename
901     );
902   }
903
904 Now, right after you've just written the above lines, you'd
905 normally have to go open the file 
906 ThisProject/I18N/en.pm, and immediately add an entry:
907
908   "Couldn't find file \"[_1]\"!\n"
909   => "Couldn't find file \"[_1]\"!\n",
910
911 But I consider that somewhat of a distraction from the work
912 of getting the main code working -- to say nothing of the fact
913 that I often have to play with the program a few times before
914 I can decide exactly what wording I want in the messages (which
915 in this case would require me to go changing three lines of code:
916 the call to maketext with that key, and then the two lines in
917 ThisProject/I18N/en.pm).
918
919 However, if you set "_AUTO => 1" in the %Lexicon in,
920 ThisProject/I18N/en.pm (assuming that English (en) is
921 the language that all your programmers will be using for this
922 project's internal message keys), then you don't ever have to
923 go adding lines like this
924
925   "Couldn't find file \"[_1]\"!\n"
926   => "Couldn't find file \"[_1]\"!\n",
927
928 to ThisProject/I18N/en.pm, because if _AUTO is true there,
929 then just looking for an entry with the key "Couldn't find
930 file \"[_1]\"!\n" in that lexicon will cause it to be added,
931 with that value!
932
933 Note that the reason that keys that start with "_"
934 are immune to _AUTO isn't anything generally magical about
935 the underscore character -- I just wanted a way to have most
936 lexicon keys be autoable, except for possibly a few, and I
937 arbitrarily decided to use a leading underscore as a signal
938 to distinguish those few.
939
940 =head1 READONLY LEXICONS
941
942 If your lexicon is a tied hash the simple act of caching the compiled value can be fatal.
943
944 For example a L<GDBM_File> GDBM_READER tied hash will die with something like:
945
946    gdbm store returned -1, errno 2, key "..." at ...
947
948 All you need to do is turn on caching outside of the lexicon hash itself like so:
949
950    sub init {
951        my ($lh) = @_;
952        ...
953        $lh->{'use_external_lex_cache'} = 1;
954        ...
955    }
956
957 And then instead of storing the compiled value in the lexicon hash it will store it in $lh->{'_external_lex_cache'}
958
959 =head1 CONTROLLING LOOKUP FAILURE
960
961 If you call $lh->maketext(I<key>, ...parameters...),
962 and there's no entry I<key> in $lh's class's %Lexicon, nor
963 in the superclass %Lexicon hash, I<and> if we can't auto-make
964 I<key> (because either it starts with a "_", or because none
965 of its lexicons have C<_AUTO =E<gt> 1,>), then we have
966 failed to find a normal way to maketext I<key>.  What then
967 happens in these failure conditions, depends on the $lh object's
968 "fail" attribute.
969
970 If the language handle has no "fail" attribute, maketext
971 will simply throw an exception (i.e., it calls C<die>, mentioning
972 the I<key> whose lookup failed, and naming the line number where
973 the calling $lh->maketext(I<key>,...) was.
974
975 If the language handle has a "fail" attribute whose value is a
976 coderef, then $lh->maketext(I<key>,...params...) gives up and calls:
977
978   return $that_subref->($lh, $key, @params);
979
980 Otherwise, the "fail" attribute's value should be a string denoting
981 a method name, so that $lh->maketext(I<key>,...params...) can
982 give up with:
983
984   return $lh->$that_method_name($phrase, @params);
985
986 The "fail" attribute can be accessed with the C<fail_with> method:
987
988   # Set to a coderef:
989   $lh->fail_with( \&failure_handler );
990
991   # Set to a method name:
992   $lh->fail_with( 'failure_method' );
993   
994   # Set to nothing (i.e., so failure throws a plain exception)
995   $lh->fail_with( undef );
996   
997   # Get the current value
998   $handler = $lh->fail_with();
999
1000 Now, as to what you may want to do with these handlers:  Maybe you'd
1001 want to log what key failed for what class, and then die.  Maybe
1002 you don't like C<die> and instead you want to send the error message
1003 to STDOUT (or wherever) and then merely C<exit()>.
1004
1005 Or maybe you don't want to C<die> at all!  Maybe you could use a
1006 handler like this:
1007
1008   # Make all lookups fall back onto an English value,
1009   #  but only after we log it for later fingerpointing.
1010   my $lh_backup = ThisProject->get_handle('en');
1011   open(LEX_FAIL_LOG, ">>wherever/lex.log") || die "GNAARGH $!";
1012   sub lex_fail {
1013     my($failing_lh, $key, $params) = @_;
1014     print LEX_FAIL_LOG scalar(localtime), "\t",
1015        ref($failing_lh), "\t", $key, "\n";
1016     return $lh_backup->maketext($key,@params);
1017   }
1018
1019 Some users have expressed that they think this whole mechanism of
1020 having a "fail" attribute at all, seems a rather pointless complication.
1021 But I want Locale::Maketext to be usable for software projects of I<any>
1022 scale and type; and different software projects have different ideas
1023 of what the right thing is to do in failure conditions.  I could simply
1024 say that failure always throws an exception, and that if you want to be
1025 careful, you'll just have to wrap every call to $lh->maketext in an
1026 S<eval { }>.  However, I want programmers to reserve the right (via
1027 the "fail" attribute) to treat lookup failure as something other than
1028 an exception of the same level of severity as a config file being
1029 unreadable, or some essential resource being inaccessible.
1030
1031 One possibly useful value for the "fail" attribute is the method name
1032 "failure_handler_auto".  This is a method defined in the class
1033 Locale::Maketext itself.  You set it with:
1034
1035   $lh->fail_with('failure_handler_auto');
1036
1037 Then when you call $lh->maketext(I<key>, ...parameters...) and
1038 there's no I<key> in any of those lexicons, maketext gives up with
1039
1040   return $lh->failure_handler_auto($key, @params);
1041
1042 But failure_handler_auto, instead of dying or anything, compiles
1043 $key, caching it in
1044
1045     $lh->{'failure_lex'}{$key} = $complied
1046
1047 and then calls the compiled value, and returns that.  (I.e., if
1048 $key looks like bracket notation, $compiled is a sub, and we return
1049 &{$compiled}(@params); but if $key is just a plain string, we just
1050 return that.)
1051
1052 The effect of using "failure_auto_handler"
1053 is like an AUTO lexicon, except that it 1) compiles $key even if
1054 it starts with "_", and 2) you have a record in the new hashref
1055 $lh->{'failure_lex'} of all the keys that have failed for
1056 this object.  This should avoid your program dying -- as long
1057 as your keys aren't actually invalid as bracket code, and as
1058 long as they don't try calling methods that don't exist.
1059
1060 "failure_auto_handler" may not be exactly what you want, but I
1061 hope it at least shows you that maketext failure can be mitigated
1062 in any number of very flexible ways.  If you can formalize exactly
1063 what you want, you should be able to express that as a failure
1064 handler.  You can even make it default for every object of a given
1065 class, by setting it in that class's init:
1066
1067   sub init {
1068     my $lh = $_[0];  # a newborn handle
1069     $lh->SUPER::init();
1070     $lh->fail_with('my_clever_failure_handler');
1071     return;
1072   }
1073   sub my_clever_failure_handler {
1074     ...you clever things here...
1075   }
1076
1077 =head1 HOW TO USE MAKETEXT
1078
1079 Here is a brief checklist on how to use Maketext to localize
1080 applications:
1081
1082 =over
1083
1084 =item *
1085
1086 Decide what system you'll use for lexicon keys.  If you insist,
1087 you can use opaque IDs (if you're nostalgic for C<catgets>),
1088 but I have better suggestions in the
1089 section "Entries in Each Lexicon", above.  Assuming you opt for
1090 meaningful keys that double as values (like "Minimum ([_1]) is
1091 larger than maximum ([_2])!\n"), you'll have to settle on what
1092 language those should be in.  For the sake of argument, I'll
1093 call this English, specifically American English, "en-US".
1094
1095 =item *
1096
1097 Create a class for your localization project.  This is
1098 the name of the class that you'll use in the idiom:
1099
1100   use Projname::L10N;
1101   my $lh = Projname::L10N->get_handle(...) || die "Language?";
1102
1103 Assuming you call your class Projname::L10N, create a class
1104 consisting minimally of:
1105
1106   package Projname::L10N;
1107   use base qw(Locale::Maketext);
1108   ...any methods you might want all your languages to share...
1109   
1110   # And, assuming you want the base class to be an _AUTO lexicon,
1111   # as is discussed a few sections up:
1112   
1113   1;
1114
1115 =item *
1116
1117 Create a class for the language your internal keys are in.  Name
1118 the class after the language-tag for that language, in lowercase,
1119 with dashes changed to underscores.  Assuming your project's first
1120 language is US English, you should call this Projname::L10N::en_us.
1121 It should consist minimally of:
1122
1123   package Projname::L10N::en_us;
1124   use base qw(Projname::L10N);
1125   %Lexicon = (
1126     '_AUTO' => 1,
1127   );
1128   1;
1129
1130 (For the rest of this section, I'll assume that this "first
1131 language class" of Projname::L10N::en_us has
1132 _AUTO lexicon.)
1133
1134 =item *
1135
1136 Go and write your program.  Everywhere in your program where 
1137 you would say:
1138
1139   print "Foobar $thing stuff\n";
1140
1141 instead do it thru maketext, using no variable interpolation in
1142 the key:
1143
1144   print $lh->maketext("Foobar [_1] stuff\n", $thing);
1145
1146 If you get tired of constantly saying C<print $lh-E<gt>maketext>,
1147 consider making a functional wrapper for it, like so:
1148
1149   use Projname::L10N;
1150   use vars qw($lh);
1151   $lh = Projname::L10N->get_handle(...) || die "Language?";
1152   sub pmt (@) { print( $lh->maketext(@_)) }
1153    # "pmt" is short for "Print MakeText"
1154   $Carp::Verbose = 1;
1155    # so if maketext fails, we see made the call to pmt
1156
1157 Besides whole phrases meant for output, anything language-dependent
1158 should be put into the class Projname::L10N::en_us,
1159 whether as methods, or as lexicon entries -- this is discussed
1160 in the section "Entries in Each Lexicon", above.
1161
1162 =item *
1163
1164 Once the program is otherwise done, and once its localization for
1165 the first language works right (via the data and methods in
1166 Projname::L10N::en_us), you can get together the data for translation.
1167 If your first language lexicon isn't an _AUTO lexicon, then you already
1168 have all the messages explicitly in the lexicon (or else you'd be
1169 getting exceptions thrown when you call $lh->maketext to get
1170 messages that aren't in there).  But if you were (advisedly) lazy and are
1171 using an _AUTO lexicon, then you've got to make a list of all the phrases
1172 that you've so far been letting _AUTO generate for you.  There are very
1173 many ways to assemble such a list.  The most straightforward is to simply
1174 grep the source for every occurrence of "maketext" (or calls
1175 to wrappers around it, like the above C<pmt> function), and to log the
1176 following phrase.
1177
1178 =item *
1179
1180 You may at this point want to consider whether your base class 
1181 (Projname::L10N), from which all lexicons inherit from (Projname::L10N::en,
1182 Projname::L10N::es, etc.), should be an _AUTO lexicon.  It may be true
1183 that in theory, all needed messages will be in each language class;
1184 but in the presumably unlikely or "impossible" case of lookup failure,
1185 you should consider whether your program should throw an exception,
1186 emit text in English (or whatever your project's first language is),
1187 or some more complex solution as described in the section
1188 "Controlling Lookup Failure", above.
1189
1190 =item *
1191
1192 Submit all messages/phrases/etc. to translators.
1193
1194 (You may, in fact, want to start with localizing to I<one> other language
1195 at first, if you're not sure that you've properly abstracted the
1196 language-dependent parts of your code.)
1197
1198 Translators may request clarification of the situation in which a
1199 particular phrase is found.  For example, in English we are entirely happy
1200 saying "I<n> files found", regardless of whether we mean "I looked for files,
1201 and found I<n> of them" or the rather distinct situation of "I looked for
1202 something else (like lines in files), and along the way I saw I<n>
1203 files."  This may involve rethinking things that you thought quite clear:
1204 should "Edit" on a toolbar be a noun ("editing") or a verb ("to edit")?  Is
1205 there already a conventionalized way to express that menu option, separate
1206 from the target language's normal word for "to edit"?
1207
1208 In all cases where the very common phenomenon of quantification
1209 (saying "I<N> files", for B<any> value of N)
1210 is involved, each translator should make clear what dependencies the
1211 number causes in the sentence.  In many cases, dependency is
1212 limited to words adjacent to the number, in places where you might
1213 expect them ("I found the-?PLURAL I<N>
1214 empty-?PLURAL directory-?PLURAL"), but in some cases there are
1215 unexpected dependencies ("I found-?PLURAL ..."!) as well as long-distance
1216 dependencies "The I<N> directory-?PLURAL could not be deleted-?PLURAL"!).
1217
1218 Remind the translators to consider the case where N is 0:
1219 "0 files found" isn't exactly natural-sounding in any language, but it
1220 may be unacceptable in many -- or it may condition special
1221 kinds of agreement (similar to English "I didN'T find ANY files").
1222
1223 Remember to ask your translators about numeral formatting in their
1224 language, so that you can override the C<numf> method as
1225 appropriate.  Typical variables in number formatting are:  what to
1226 use as a decimal point (comma? period?); what to use as a thousands
1227 separator (space? nonbreaking space? comma? period? small
1228 middot? prime? apostrophe?); and even whether the so-called "thousands
1229 separator" is actually for every third digit -- I've heard reports of
1230 two hundred thousand being expressible as "2,00,000" for some Indian
1231 (Subcontinental) languages, besides the less surprising "S<200 000>",
1232 "200.000", "200,000", and "200'000".  Also, using a set of numeral
1233 glyphs other than the usual ASCII "0"-"9" might be appreciated, as via
1234 C<tr/0-9/\x{0966}-\x{096F}/> for getting digits in Devanagari script
1235 (for Hindi, Konkani, others).
1236
1237 The basic C<quant> method that Locale::Maketext provides should be
1238 good for many languages.  For some languages, it might be useful
1239 to modify it (or its constituent C<numerate> method)
1240 to take a plural form in the two-argument call to C<quant>
1241 (as in "[quant,_1,files]") if
1242 it's all-around easier to infer the singular form from the plural, than
1243 to infer the plural form from the singular.
1244
1245 But for other languages (as is discussed at length
1246 in L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>), simple
1247 C<quant>/C<numerify> is not enough.  For the particularly problematic
1248 Slavic languages, what you may need is a method which you provide
1249 with the number, the citation form of the noun to quantify, and
1250 the case and gender that the sentence's syntax projects onto that
1251 noun slot.  The method would then be responsible for determining
1252 what grammatical number that numeral projects onto its noun phrase,
1253 and what case and gender it may override the normal case and gender
1254 with; and then it would look up the noun in a lexicon providing
1255 all needed inflected forms.
1256
1257 =item *
1258
1259 You may also wish to discuss with the translators the question of
1260 how to relate different subforms of the same language tag,
1261 considering how this reacts with C<get_handle>'s treatment of
1262 these.  For example, if a user accepts interfaces in "en, fr", and
1263 you have interfaces available in "en-US" and "fr", what should
1264 they get?  You may wish to resolve this by establishing that "en"
1265 and "en-US" are effectively synonymous, by having one class
1266 zero-derive from the other.
1267
1268 For some languages this issue may never come up (Danish is rarely
1269 expressed as "da-DK", but instead is just "da").  And for other
1270 languages, the whole concept of a "generic" form may verge on
1271 being uselessly vague, particularly for interfaces involving voice
1272 media in forms of Arabic or Chinese.
1273
1274 =item *
1275
1276 Once you've localized your program/site/etc. for all desired
1277 languages, be sure to show the result (whether live, or via
1278 screenshots) to the translators.  Once they approve, make every
1279 effort to have it then checked by at least one other speaker of
1280 that language.  This holds true even when (or especially when) the
1281 translation is done by one of your own programmers.  Some
1282 kinds of systems may be harder to find testers for than others,
1283 depending on the amount of domain-specific jargon and concepts
1284 involved -- it's easier to find people who can tell you whether
1285 they approve of your translation for "delete this message" in an
1286 email-via-Web interface, than to find people who can give you
1287 an informed opinion on your translation for "attribute value"
1288 in an XML query tool's interface.
1289
1290 =back
1291
1292 =head1 SEE ALSO
1293
1294 I recommend reading all of these:
1295
1296 L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13> -- my I<The Perl
1297 Journal> article about Maketext.  It explains many important concepts
1298 underlying Locale::Maketext's design, and some insight into why
1299 Maketext is better than the plain old approach of having 
1300 message catalogs that are just databases of sprintf formats.
1301
1302 L<File::Findgrep|File::Findgrep> is a sample application/module
1303 that uses Locale::Maketext to localize its messages.  For a larger
1304 internationalized system, see also L<Apache::MP3>.
1305
1306 L<I18N::LangTags|I18N::LangTags>.
1307
1308 L<Win32::Locale|Win32::Locale>.
1309
1310 RFC 3066, I<Tags for the Identification of Languages>,
1311 as at http://sunsite.dk/RFC/rfc/rfc3066.html
1312
1313 RFC 2277, I<IETF Policy on Character Sets and Languages>
1314 is at http://sunsite.dk/RFC/rfc/rfc2277.html -- much of it is
1315 just things of interest to protocol designers, but it explains
1316 some basic concepts, like the distinction between locales and
1317 language-tags.
1318
1319 The manual for GNU C<gettext>.  The gettext dist is available in
1320 C<ftp://prep.ai.mit.edu/pub/gnu/> -- get
1321 a recent gettext tarball and look in its "doc/" directory, there's
1322 an easily browsable HTML version in there.  The
1323 gettext documentation asks lots of questions worth thinking
1324 about, even if some of their answers are sometimes wonky,
1325 particularly where they start talking about pluralization.
1326
1327 The Locale/Maketext.pm source.  Obverse that the module is much
1328 shorter than its documentation!
1329
1330 =head1 COPYRIGHT AND DISCLAIMER
1331
1332 Copyright (c) 1999-2004 Sean M. Burke.  All rights reserved.
1333
1334 This library is free software; you can redistribute it and/or modify
1335 it under the same terms as Perl itself.
1336
1337 This program is distributed in the hope that it will be useful, but
1338 without any warranty; without even the implied warranty of
1339 merchantability or fitness for a particular purpose.
1340
1341 =head1 AUTHOR
1342
1343 Sean M. Burke C<sburke@cpan.org>
1344
1345 =cut