Debian Codegraph @

upstream/mageia-cauldron/man3pm/Locale::Maketext::Simple.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Locale::Maketext::Simple 3pm"
61 .TH Locale::Maketext::Simple 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Locale::Maketext::Simple \- Simple interface to Locale::Maketext::Lexicon
68 .SH VERSION
69 .IX Header "VERSION"
70 This document describes version 0.18 of Locale::Maketext::Simple,
71 released Septermber 8, 2006.
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 Minimal setup (looks for \fIauto/Foo/*.po\fR and \fIauto/Foo/*.mo\fR):
75 .PP
76 .Vb 6
77 \& package Foo;
78 \& use Locale::Maketext::Simple; # exports \*(Aqloc\*(Aq
79 \& loc_lang(\*(Aqfr\*(Aq); # set language to French
80 \& sub hello {
81 \& print loc("Hello, [_1]!", "World");
82 \& }
83 .Ve
84 .PP
85 More sophisticated example:
86 .PP
87 .Vb 10
88 \& package Foo::Bar;
89 \& use Locale::Maketext::Simple (
90 \& Class => \*(AqFoo\*(Aq, # search in auto/Foo/
91 \& Style => \*(Aqgettext\*(Aq, # %1 instead of [_1]
92 \& Export => \*(Aqmaketext\*(Aq, # maketext() instead of loc()
93 \& Subclass => \*(AqL10N\*(Aq, # Foo::L10N instead of Foo::I18N
94 \& Decode => 1, # decode entries to unicode\-strings
95 \& Encoding => \*(Aqlocale\*(Aq, # but encode lexicons in current locale
96 \& # (needs Locale::Maketext::Lexicon 0.36)
97 \& );
98 \& sub japh {
99 \& print maketext("Just another %1 hacker", "Perl");
100 \& }
101 .Ve
102 .SH DESCRIPTION
103 .IX Header "DESCRIPTION"
104 This module is a simple wrapper around \fBLocale::Maketext::Lexicon\fR,
105 designed to alleviate the need of creating \fILanguage Classes\fR for
106 module authors.
107 .PP
108 The language used is chosen from the loc_lang call. If a lookup is not
109 possible, the i\-default language will be used. If the lookup is not in the
110 i\-default language, then the key will be returned.
111 .PP
112 If \fBLocale::Maketext::Lexicon\fR is not present, it implements a
113 minimal localization function by simply interpolating \f(CW\*(C`[_1]\*(C'\fR with
114 the first argument, \f(CW\*(C`[_2]\*(C'\fR with the second, etc. Interpolated
115 function like \f(CW\*(C`[quant,_1]\*(C'\fR are treated as \f(CW\*(C`[_1]\*(C'\fR, with the sole
116 exception of \f(CW\*(C`[tense,_1,X]\*(C'\fR, which will append \f(CW\*(C`ing\*(C'\fR to \f(CW\*(C`_1\*(C'\fR when
117 X is \f(CW\*(C`present\*(C'\fR, or appending \f(CW\*(C`ed\*(C'\fR to <_1> otherwise.
118 .SH OPTIONS
119 .IX Header "OPTIONS"
120 All options are passed either via the \f(CW\*(C`use\*(C'\fR statement, or via an
121 explicit \f(CW\*(C`import\*(C'\fR.
122 .SS Class
123 .IX Subsection "Class"
124 By default, \fBLocale::Maketext::Simple\fR draws its source from the
125 calling package\*(Aqs \fIauto/\fR directory; you can override this behaviour
126 by explicitly specifying another package as \f(CW\*(C`Class\*(C'\fR.
127 .SS Path
128 .IX Subsection "Path"
129 If your PO and MO files are under a path elsewhere than \f(CW\*(C`auto/\*(C'\fR,
130 you may specify it using the \f(CW\*(C`Path\*(C'\fR option.
131 .SS Style
132 .IX Subsection "Style"
133 By default, this module uses the \f(CW\*(C`maketext\*(C'\fR style of \f(CW\*(C`[_1]\*(C'\fR and
134 \&\f(CW\*(C`[quant,_1]\*(C'\fR for interpolation. Alternatively, you can specify the
135 \&\f(CW\*(C`gettext\*(C'\fR style, which uses \f(CW%1\fR and \f(CW%quant(%1)\fR for interpolation.
136 .PP
137 This option is case\-insensitive.
138 .SS Export
139 .IX Subsection "Export"
140 By default, this module exports a single function, \f(CW\*(C`loc\*(C'\fR, into its
141 caller\*(Aqs namespace. You can set it to another name, or set it to
142 an empty string to disable exporting.
143 .SS Subclass
144 .IX Subsection "Subclass"
145 By default, this module creates an \f(CW\*(C`::I18N\*(C'\fR subclass under the
146 caller\*(Aqs package (or the package specified by \f(CW\*(C`Class\*(C'\fR), and stores
147 lexicon data in its subclasses. You can assign a name other than
148 \&\f(CW\*(C`I18N\*(C'\fR via this option.
149 .SS Decode
150 .IX Subsection "Decode"
151 If set to a true value, source entries will be converted into
152 utf8\-strings (available in Perl 5.6.1 or later). This feature
153 needs the \fBEncode\fR or \fBEncode::compat\fR module.
154 .SS Encoding
155 .IX Subsection "Encoding"
156 Specifies an encoding to store lexicon entries, instead of
157 utf8\-strings. If set to \f(CW\*(C`locale\*(C'\fR, the encoding from the current
158 locale setting is used. Implies a true value for \f(CW\*(C`Decode\*(C'\fR.
159 .SH ACKNOWLEDGMENTS
160 .IX Header "ACKNOWLEDGMENTS"
161 Thanks to Jos I. Boumans for suggesting this module to be written.
162 .PP
163 Thanks to Chia\-Liang Kao for suggesting \f(CW\*(C`Path\*(C'\fR and \f(CW\*(C`loc_lang\*(C'\fR.
164 .SH "SEE ALSO"
165 .IX Header "SEE ALSO"
166 Locale::Maketext, Locale::Maketext::Lexicon
167 .SH AUTHORS
168 .IX Header "AUTHORS"
169 Audrey Tang <[email protected]>
170 .SH COPYRIGHT
171 .IX Header "COPYRIGHT"
172 Copyright 2003, 2004, 2005, 2006 by Audrey Tang <[email protected]>.
173 .PP
174 This software is released under the MIT license cited below. Additionally,
175 when this software is distributed with \fBPerl Kit, Version 5\fR, you may also
176 redistribute it and/or modify it under the same terms as Perl itself.
177 .SS "The ""MIT"" License"
178 .IX Subsection "The ""MIT"" License"
179 Permission is hereby granted, free of charge, to any person obtaining a copy
180 of this software and associated documentation files (the "Software"), to deal
181 in the Software without restriction, including without limitation the rights
182 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
183 copies of the Software, and to permit persons to whom the Software is
184 furnished to do so, subject to the following conditions:
185 .PP
186 The above copyright notice and this permission notice shall be included in
187 all copies or substantial portions of the Software.
188 .PP
189 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
190 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
191 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
192 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
193 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
194 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
195 DEALINGS IN THE SOFTWARE.