Bug #16444 for Locale-Maketext: Locale/Maketext.POD amendment suggestions.

Below are some amendment suggestions to Locale/Maketext.POD, from the viewpoint of a novice, whom the pod presumably targets. Some are what I believe to be typos and some are only matters of style. ###################################################### (1) Minor typo: It runs thru the entire given list of language-tags, and finds no classes for those exact terms, it then tries should be *If it* runs thru the entire given list of language-tags and finds no classes for those exact terms, it then tries ###################################################### (2) Possible typo: It is probably my limited understanding, but in the example code following the sentence: If you're using localization in an application ... I am confused by $preferred_language and $chosen_language ###################################################### (3) The code following the sentence This is the most important method in Locale::Maketext: should be indented so that it looks like code, unless you did it this way on purpose. Actually, the structure of this entire section, titled The "maketext" Method looks a bit unbalanced to me, including the two methods at the bottom of it. ###################################################### (4) Style: The sentences in the paragraph that starts with: If the value is a scalarref, the scalar is dereferenced ... could be bullet-itemed for easier reading. ###################################################### (5) In the example code following the sentence Note that you might find it useful in some cases to override ... I do not understand calling $self->maketext(@_); from within sub maketext(). Is that supposed to be $self->SUPER::maketext(@_); ###################################################### (6) Minor typo: turning and dashes to underscores should be one of turning ** dashes to underscores turning *all* dashes to underscores ###################################################### (7) Perhaps it would be nice to say something about use base right after ... from your project class, and also defines its @ISA ... to the effect that use base is ok, too. ###################################################### (8) Minor typo: I think that keys as lexicon values makes the completed ... should be one of I think that *using* keys as lexicon values makes the completed I think that keys as lexicon values *make* the completed ###################################################### (9) Minor typo: data that a command-line program might returns when should be one of data that a command-line program might return ** when data that a command-line program ** returns when ###################################################### (10) The expression I often just use a key "_USAGE_MESSAGE". should be something like I often just use a *brief, self-explanatory and eye-catching* key *such as* "_USAGE_MESSAGE". because the former might give the impression to less bright souls such as myself that one could use the same key ( "_USAGE_MESSAGE" in this case ) more than once in the same Lexicon. ###################################################### (11) Can/Should we get rid of the single quote right after the code C<%Lexicon> in: entries across all the %Lexicon's in a language to get something like one of entries across all the "C<%Lexicon>"s in a language entries across all the C<%Lexicon>s in a language Separating s's is always troublesome ;-) ###################################################### (12) Minor typo: you probably need to know what equivalent of ... should be you probably need to know what *the* equivalent of ... ###################################################### (13) Is there a typo in as code is a method in the language class ###################################################### (14) It may help to qualify the phrase replacement for sprintf formatting. with something like replacement for *the use of* sprintf formatting *in L10N*. ###################################################### (15) Minor typo: but text is special regions is specially interpreted should be but text *in* special regions is specially interpreted ###################################################### (16) The expression brackets ("[...]" -- not "{...}"!) is somewhat hard on the eye, both the exclamation mark and the m-dash. Can we come up with something simpler, like one of brackets ( square brackets "[...]", not curly braces "{...}" ) brackets ( that is, "[...]", not "{...}", mind you ) Actually, it would probably be best to remove the double quotes and use C<> or something else to to make the bracket/brace characters discintive. The quotes really twist one's eyes X-( ###################################################### (17) Minor typo: as $_[value]. I.e., "_1" is becomes with $_[1], and should be one of as $_[value]*, i*.e., "_1" is replaced with $_[1], and as $_[value]*, i*.e., "_1" becomes $_[1], and I think i.e is always used in small letters. We could lose the double quotes here, too -- down with them! ###################################################### (18) Possibe typo: item in a bracket group is empty-string could be item in a bracket group is *the* empty-string Same stuff comes up a few lines below as is neither empty-string Maybe you want it that way, then. ###################################################### (19) In the sample code that comes after But it actually compiles as this: the comment #!!! could be replaced by something more informative, such as # note the <space> in " bar" ###################################################### (20) Several code examples have: "Couldn't find file \"$filename\"!\n"; can we change that as qq(Couldn't find file "$filename" ! \n); so the escaped double quotes don't hurt one's eyes? ###################################################### (21) Minor typo: depends on the $lh object "fail" attribute. should be depends on the $lh object*'s* "fail" attribute. ###################################################### (22) For clarity, we could replace return &{$that_subref}($lh, $key, @params); with return $that_coderef->($lh, $key, @params); ###################################################### (23) The following was a little confusing to me: # Simply read: Can we change it with something like: # Get the current value ###################################################### (24) For clarity, change # but after we log it for later fingerpointing. as # but *only* after we log it for later fingerpointing. Also in the same sample code, I would suggest that you show the actual use of fail_with, perhaps like one of the following: $lh->fail_with( 'lex_fail' ); $lh->fail_with( \&lex_fail ); ###################################################### (25) Minor typo: This is a method defined in class could be changed as This is a method defined in *the* class ###################################################### (26) I think stuff like the following is easier to read when placed within C<>: $lh->{'failure_lex'}{$key} = $complied ###################################################### (27) Minor typo: Assuming your call your class Projname::L10N should be Assuming you** call your class Projname::L10N ###################################################### (28) Style: I suggest changing the followning two lines: print "Foobar $thing stuff\n"; print $lh->maketext("Foobar [_1] stuff\n", $thing); so as to use the more standard (RFC 3092 =) print "Foo $bar baz\n"; print $lh->maketext("Foo [_1] baz\n", $bar); ###################################################### (29) Minor typo: consider whether the your base class should be consider whether ** your base class ###################################################### (30) Style: class (Projname::L10N) that all lexicons inherit from could be class (Projname::L10N) *from which* all lexicons inherit ** ###################################################### (31) Minor typo: if you're not sure that you've property abstracted should be if you're not sure that you've *properly* abstracted ###################################################### (32) I do not understand the following: by having one class zero-derive from the other. ###################################################### (33) Style: I suggest we change Some kinds of systems may be harder to find testers for than others as It may be harder to find testers for some systems than for others ###################################################### (34) Style: I suggest changing one of the "just" words in the following: old approach of just having message catalogs that are just databases of sprintf formats. into something like "simply" or just removing the just, as in old approach of ** having message catalogs that are just databases of sprintf formats. Just a thought. ###################################################### Thanks for all the good stuff. I will try the salad recipe. best, __Ali ISIK__