svn-gvsig-desktop / trunk / install / launcher / izpack-launcher-1.3 / src / gettext / share / doc / gettext / gettext_12.html @ 7940
History | View | Annotate | Download (56.5 KB)
1 |
<HTML>
|
---|---|
2 |
<HEAD>
|
3 |
<!-- This HTML file has been created by texi2html 1.52a
|
4 |
from gettext.texi on 9 December 2003 -->
|
5 |
|
6 |
<TITLE>GNU gettext utilities - 12 The Maintainer's View</TITLE> |
7 |
</HEAD>
|
8 |
<BODY>
|
9 |
Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_11.html">previous</A>, <A HREF="gettext_13.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. |
10 |
<P><HR><P> |
11 |
|
12 |
|
13 |
<H1><A NAME="SEC189" HREF="gettext_toc.html#TOC189">12 The Maintainer's View</A></H1> |
14 |
<P>
|
15 |
<A NAME="IDX1001"></A> |
16 |
|
17 |
</P>
|
18 |
<P>
|
19 |
The maintainer of a package has many responsibilities. One of them |
20 |
is ensuring that the package will install easily on many platforms, |
21 |
and that the magic we described earlier (see section <A HREF="gettext_9.html#SEC153">9 The User's View</A>) will work |
22 |
for installers and end users. |
23 |
|
24 |
</P>
|
25 |
<P>
|
26 |
Of course, there are many possible ways by which GNU <CODE>gettext</CODE> |
27 |
might be integrated in a distribution, and this chapter does not cover |
28 |
them in all generality. Instead, it details one possible approach which |
29 |
is especially adequate for many free software distributions following GNU |
30 |
standards, or even better, Gnits standards, because GNU <CODE>gettext</CODE> |
31 |
is purposely for helping the internationalization of the whole GNU |
32 |
project, and as many other good free packages as possible. So, the |
33 |
maintainer's view presented here presumes that the package already has |
34 |
a <TT>`configure.in´</TT> file and uses GNU Autoconf. |
35 |
|
36 |
</P>
|
37 |
<P>
|
38 |
Nevertheless, GNU <CODE>gettext</CODE> may surely be useful for free packages |
39 |
not following GNU standards and conventions, but the maintainers of such |
40 |
packages might have to show imagination and initiative in organizing |
41 |
their distributions so <CODE>gettext</CODE> work for them in all situations. |
42 |
There are surely many, out there. |
43 |
|
44 |
</P>
|
45 |
<P>
|
46 |
Even if <CODE>gettext</CODE> methods are now stabilizing, slight adjustments |
47 |
might be needed between successive <CODE>gettext</CODE> versions, so you |
48 |
should ideally revise this chapter in subsequent releases, looking |
49 |
for changes. |
50 |
|
51 |
</P>
|
52 |
|
53 |
|
54 |
|
55 |
<H2><A NAME="SEC190" HREF="gettext_toc.html#TOC190">12.1 Flat or Non-Flat Directory Structures</A></H2> |
56 |
|
57 |
<P>
|
58 |
Some free software packages are distributed as <CODE>tar</CODE> files which unpack |
59 |
in a single directory, these are said to be <EM>flat</EM> distributions. |
60 |
Other free software packages have a one level hierarchy of subdirectories, using |
61 |
for example a subdirectory named <TT>`doc/´</TT> for the Texinfo manual and |
62 |
man pages, another called <TT>`lib/´</TT> for holding functions meant to |
63 |
replace or complement C libraries, and a subdirectory <TT>`src/´</TT> for |
64 |
holding the proper sources for the package. These other distributions |
65 |
are said to be <EM>non-flat</EM>. |
66 |
|
67 |
</P>
|
68 |
<P>
|
69 |
We cannot say much about flat distributions. A flat |
70 |
directory structure has the disadvantage of increasing the difficulty |
71 |
of updating to a new version of GNU <CODE>gettext</CODE>. Also, if you have |
72 |
many PO files, this could somewhat pollute your single directory. |
73 |
Also, GNU <CODE>gettext</CODE>'s libintl sources consist of C sources, shell |
74 |
scripts, <CODE>sed</CODE> scripts and complicated Makefile rules, which don't |
75 |
fit well into an existing flat structure. For these reasons, we |
76 |
recommend to use non-flat approach in this case as well. |
77 |
|
78 |
</P>
|
79 |
<P>
|
80 |
Maybe because GNU <CODE>gettext</CODE> itself has a non-flat structure, |
81 |
we have more experience with this approach, and this is what will be |
82 |
described in the remaining of this chapter. Some maintainers might |
83 |
use this as an opportunity to unflatten their package structure. |
84 |
|
85 |
</P>
|
86 |
|
87 |
|
88 |
<H2><A NAME="SEC191" HREF="gettext_toc.html#TOC191">12.2 Prerequisite Works</A></H2> |
89 |
<P>
|
90 |
<A NAME="IDX1002"></A> |
91 |
<A NAME="IDX1003"></A> |
92 |
<A NAME="IDX1004"></A> |
93 |
|
94 |
</P>
|
95 |
<P>
|
96 |
There are some works which are required for using GNU <CODE>gettext</CODE> |
97 |
in one of your package. These works have some kind of generality |
98 |
that escape the point by point descriptions used in the remainder |
99 |
of this chapter. So, we describe them here. |
100 |
|
101 |
</P>
|
102 |
|
103 |
<UL>
|
104 |
<LI>
|
105 |
|
106 |
Before attempting to use <CODE>gettextize</CODE> you should install some |
107 |
other packages first. |
108 |
Ensure that recent versions of GNU <CODE>m4</CODE>, GNU Autoconf and GNU |
109 |
<CODE>gettext</CODE> are already installed at your site, and if not, proceed |
110 |
to do this first. If you get to install these things, beware that |
111 |
GNU <CODE>m4</CODE> must be fully installed before GNU Autoconf is even |
112 |
<EM>configured</EM>. |
113 |
|
114 |
To further ease the task of a package maintainer the <CODE>automake</CODE> |
115 |
package was designed and implemented. GNU <CODE>gettext</CODE> now uses this |
116 |
tool and the <TT>`Makefile´</TT>s in the <TT>`intl/´</TT> and <TT>`po/´</TT> |
117 |
therefore know about all the goals necessary for using <CODE>automake</CODE> |
118 |
and <TT>`libintl´</TT> in one project. |
119 |
|
120 |
Those four packages are only needed by you, as a maintainer; the |
121 |
installers of your own package and end users do not really need any of |
122 |
GNU <CODE>m4</CODE>, GNU Autoconf, GNU <CODE>gettext</CODE>, or GNU <CODE>automake</CODE> |
123 |
for successfully installing and running your package, with messages |
124 |
properly translated. But this is not completely true if you provide |
125 |
internationalized shell scripts within your own package: GNU |
126 |
<CODE>gettext</CODE> shall then be installed at the user site if the end users |
127 |
want to see the translation of shell script messages. |
128 |
|
129 |
<LI>
|
130 |
|
131 |
Your package should use Autoconf and have a <TT>`configure.in´</TT> or |
132 |
<TT>`configure.ac´</TT> file. |
133 |
If it does not, you have to learn how. The Autoconf documentation |
134 |
is quite well written, it is a good idea that you print it and get |
135 |
familiar with it. |
136 |
|
137 |
<LI>
|
138 |
|
139 |
Your C sources should have already been modified according to |
140 |
instructions given earlier in this manual. See section <A HREF="gettext_3.html#SEC13">3 Preparing Program Sources</A>. |
141 |
|
142 |
<LI>
|
143 |
|
144 |
Your <TT>`po/´</TT> directory should receive all PO files submitted to you |
145 |
by the translator teams, each having <TT>`<VAR>ll</VAR>.po´</TT> as a name. |
146 |
This is not usually easy to get translation |
147 |
work done before your package gets internationalized and available! |
148 |
Since the cycle has to start somewhere, the easiest for the maintainer |
149 |
is to start with absolutely no PO files, and wait until various |
150 |
translator teams get interested in your package, and submit PO files. |
151 |
|
152 |
</UL>
|
153 |
|
154 |
<P>
|
155 |
It is worth adding here a few words about how the maintainer should |
156 |
ideally behave with PO files submissions. As a maintainer, your role is |
157 |
to authenticate the origin of the submission as being the representative |
158 |
of the appropriate translating teams of the Translation Project (forward |
159 |
the submission to <TT>`translation@iro.umontreal.ca´</TT> in case of doubt), |
160 |
to ensure that the PO file format is not severely broken and does not |
161 |
prevent successful installation, and for the rest, to merely put these |
162 |
PO files in <TT>`po/´</TT> for distribution. |
163 |
|
164 |
</P>
|
165 |
<P>
|
166 |
As a maintainer, you do not have to take on your shoulders the |
167 |
responsibility of checking if the translations are adequate or |
168 |
complete, and should avoid diving into linguistic matters. Translation |
169 |
teams drive themselves and are fully responsible of their linguistic |
170 |
choices for the Translation Project. Keep in mind that translator teams are <EM>not</EM> |
171 |
driven by maintainers. You can help by carefully redirecting all |
172 |
communications and reports from users about linguistic matters to the |
173 |
appropriate translation team, or explain users how to reach or join |
174 |
their team. The simplest might be to send them the <TT>`ABOUT-NLS´</TT> file. |
175 |
|
176 |
</P>
|
177 |
<P>
|
178 |
Maintainers should <EM>never ever</EM> apply PO file bug reports |
179 |
themselves, short-cutting translation teams. If some translator has |
180 |
difficulty to get some of her points through her team, it should not be |
181 |
an option for her to directly negotiate translations with maintainers. |
182 |
Teams ought to settle their problems themselves, if any. If you, as |
183 |
a maintainer, ever think there is a real problem with a team, please |
184 |
never try to <EM>solve</EM> a team's problem on your own. |
185 |
|
186 |
</P>
|
187 |
|
188 |
|
189 |
<H2><A NAME="SEC192" HREF="gettext_toc.html#TOC192">12.3 Invoking the <CODE>gettextize</CODE> Program</A></H2> |
190 |
|
191 |
<P>
|
192 |
The <CODE>gettextize</CODE> program is an interactive tool that helps the |
193 |
maintainer of a package internationalized through GNU <CODE>gettext</CODE>. |
194 |
It is used for two purposes: |
195 |
|
196 |
</P>
|
197 |
|
198 |
<UL>
|
199 |
<LI>
|
200 |
|
201 |
As a wizard, when a package is modified to use GNU <CODE>gettext</CODE> for |
202 |
the first time. |
203 |
|
204 |
<LI>
|
205 |
|
206 |
As a migration tool, for upgrading the GNU <CODE>gettext</CODE> support in |
207 |
a package from a previous to a newer version of GNU <CODE>gettext</CODE>. |
208 |
</UL>
|
209 |
|
210 |
<P>
|
211 |
This program performs the following tasks: |
212 |
|
213 |
</P>
|
214 |
|
215 |
<UL>
|
216 |
<LI>
|
217 |
|
218 |
It copies into the package some files that are consistently and |
219 |
identically needed in every package internationalized through |
220 |
GNU <CODE>gettext</CODE>. |
221 |
|
222 |
<LI>It performs as many of the tasks mentioned in the next section
|
223 |
|
224 |
section <A HREF="gettext_12.html#SEC193">12.4 Files You Must Create or Alter</A> as can be performed automatically. |
225 |
|
226 |
<LI>It removes obsolete files and idioms used for previous GNU
|
227 |
|
228 |
<CODE>gettext</CODE> versions to the form recommended for the current GNU |
229 |
<CODE>gettext</CODE> version. |
230 |
|
231 |
<LI>It prints a summary of the tasks that ought to be done manually
|
232 |
|
233 |
and could not be done automatically by <CODE>gettextize</CODE>. |
234 |
</UL>
|
235 |
|
236 |
<P>
|
237 |
It can be invoked as follows: |
238 |
|
239 |
</P>
|
240 |
<P>
|
241 |
<A NAME="IDX1005"></A> |
242 |
<A NAME="IDX1006"></A> |
243 |
|
244 |
<PRE>
|
245 |
gettextize [ <VAR>option</VAR>... ] [ <VAR>directory</VAR> ] |
246 |
</PRE>
|
247 |
|
248 |
<P>
|
249 |
and accepts the following options: |
250 |
|
251 |
</P>
|
252 |
<DL COMPACT> |
253 |
|
254 |
<DT><SAMP>`-c´</SAMP> |
255 |
<DD>
|
256 |
<DT><SAMP>`--copy´</SAMP> |
257 |
<DD>
|
258 |
<A NAME="IDX1007"></A> |
259 |
<A NAME="IDX1008"></A> |
260 |
Copy the needed files instead of making symbolic links. Using links |
261 |
would allow the package to always use the latest <CODE>gettext</CODE> code |
262 |
available on the system, but it might disturb some mechanism the |
263 |
maintainer is used to apply to the sources. Because running |
264 |
<CODE>gettextize</CODE> is easy there shouldn't be problems with using copies. |
265 |
|
266 |
<DT><SAMP>`-f´</SAMP> |
267 |
<DD>
|
268 |
<DT><SAMP>`--force´</SAMP> |
269 |
<DD>
|
270 |
<A NAME="IDX1009"></A> |
271 |
<A NAME="IDX1010"></A> |
272 |
Force replacement of files which already exist. |
273 |
|
274 |
<DT><SAMP>`--intl´</SAMP> |
275 |
<DD>
|
276 |
<A NAME="IDX1011"></A> |
277 |
Install the libintl sources in a subdirectory named <TT>`intl/´</TT>. |
278 |
This libintl will be used to provide internationalization on systems |
279 |
that don't have GNU libintl installed. If this option is omitted, |
280 |
the call to <CODE>AM_GNU_GETTEXT</CODE> in <TT>`configure.in´</TT> should read: |
281 |
<SAMP>`AM_GNU_GETTEXT([external])´</SAMP>, and internationalization will not |
282 |
be enabled on systems lacking GNU gettext. |
283 |
|
284 |
<DT><SAMP>`--no-changelog´</SAMP> |
285 |
<DD>
|
286 |
<A NAME="IDX1012"></A> |
287 |
Don't update or create ChangeLog files. By default, <CODE>gettextize</CODE> |
288 |
logs all changes (file additions, modifications and removals) in a |
289 |
file called <SAMP>`ChangeLog´</SAMP> in each affected directory. |
290 |
|
291 |
<DT><SAMP>`-n´</SAMP> |
292 |
<DD>
|
293 |
<DT><SAMP>`--dry-run´</SAMP> |
294 |
<DD>
|
295 |
<A NAME="IDX1013"></A> |
296 |
<A NAME="IDX1014"></A> |
297 |
Print modifications but don't perform them. All actions that |
298 |
<CODE>gettextize</CODE> would normally execute are inhibited and instead only |
299 |
listed on standard output. |
300 |
|
301 |
<DT><SAMP>`--help´</SAMP> |
302 |
<DD>
|
303 |
<A NAME="IDX1015"></A> |
304 |
Display this help and exit. |
305 |
|
306 |
<DT><SAMP>`--version´</SAMP> |
307 |
<DD>
|
308 |
<A NAME="IDX1016"></A> |
309 |
Output version information and exit. |
310 |
|
311 |
</DL>
|
312 |
|
313 |
<P>
|
314 |
If <VAR>directory</VAR> is given, this is the top level directory of a |
315 |
package to prepare for using GNU <CODE>gettext</CODE>. If not given, it |
316 |
is assumed that the current directory is the top level directory of |
317 |
such a package. |
318 |
|
319 |
</P>
|
320 |
<P>
|
321 |
The program <CODE>gettextize</CODE> provides the following files. However, |
322 |
no existing file will be replaced unless the option <CODE>--force</CODE> |
323 |
(<CODE>-f</CODE>) is specified. |
324 |
|
325 |
</P>
|
326 |
|
327 |
<OL>
|
328 |
<LI>
|
329 |
|
330 |
The <TT>`ABOUT-NLS´</TT> file is copied in the main directory of your package, |
331 |
the one being at the top level. This file gives the main indications |
332 |
about how to install and use the Native Language Support features |
333 |
of your program. You might elect to use a more recent copy of this |
334 |
<TT>`ABOUT-NLS´</TT> file than the one provided through <CODE>gettextize</CODE>, |
335 |
if you have one handy. You may also fetch a more recent copy of file |
336 |
<TT>`ABOUT-NLS´</TT> from Translation Project sites, and from most GNU |
337 |
archive sites. |
338 |
|
339 |
<LI>
|
340 |
|
341 |
A <TT>`po/´</TT> directory is created for eventually holding |
342 |
all translation files, but initially only containing the file |
343 |
<TT>`po/Makefile.in.in´</TT> from the GNU <CODE>gettext</CODE> distribution |
344 |
(beware the double <SAMP>`.in´</SAMP> in the file name) and a few auxiliary |
345 |
files. If the <TT>`po/´</TT> directory already exists, it will be preserved |
346 |
along with the files it contains, and only <TT>`Makefile.in.in´</TT> and |
347 |
the auxiliary files will be overwritten. |
348 |
|
349 |
<LI>
|
350 |
|
351 |
Only if <SAMP>`--intl´</SAMP> has been specified: |
352 |
A <TT>`intl/´</TT> directory is created and filled with most of the files |
353 |
originally in the <TT>`intl/´</TT> directory of the GNU <CODE>gettext</CODE> |
354 |
distribution. Also, if option <CODE>--force</CODE> (<CODE>-f</CODE>) is given, |
355 |
the <TT>`intl/´</TT> directory is emptied first. |
356 |
|
357 |
<LI>
|
358 |
|
359 |
The files <TT>`config.rpath´</TT> and <TT>`mkinstalldirs´</TT> are copied into |
360 |
the directory containing configuration support files. It is needed by |
361 |
the <CODE>AM_GNU_GETTEXT</CODE> autoconf macro. |
362 |
|
363 |
<LI>
|
364 |
|
365 |
Only if the project is using GNU <CODE>automake</CODE>: |
366 |
A set of <CODE>autoconf</CODE> macro files is copied into the package's |
367 |
<CODE>autoconf</CODE> macro repository, usually in a directory called <TT>`m4/´</TT>. |
368 |
</OL>
|
369 |
|
370 |
<P>
|
371 |
If your site support symbolic links, <CODE>gettextize</CODE> will not |
372 |
actually copy the files into your package, but establish symbolic |
373 |
links instead. This avoids duplicating the disk space needed in |
374 |
all packages. Merely using the <SAMP>`-h´</SAMP> option while creating the |
375 |
<CODE>tar</CODE> archive of your distribution will resolve each link by an |
376 |
actual copy in the distribution archive. So, to insist, you really |
377 |
should use <SAMP>`-h´</SAMP> option with <CODE>tar</CODE> within your <CODE>dist</CODE> |
378 |
goal of your main <TT>`Makefile.in´</TT>. |
379 |
|
380 |
</P>
|
381 |
<P>
|
382 |
Furthermore, <CODE>gettextize</CODE> will update all <TT>`Makefile.am´</TT> files |
383 |
in each affected directory, as well as the top level <TT>`configure.in´</TT> |
384 |
or <TT>`configure.ac´</TT> file. |
385 |
|
386 |
</P>
|
387 |
<P>
|
388 |
It is interesting to understand that most new files for supporting |
389 |
GNU <CODE>gettext</CODE> facilities in one package go in <TT>`intl/´</TT>, |
390 |
<TT>`po/´</TT> and <TT>`m4/´</TT> subdirectories. One distinction between |
391 |
<TT>`intl/´</TT> and the two other directories is that <TT>`intl/´</TT> is |
392 |
meant to be completely identical in all packages using GNU <CODE>gettext</CODE>, |
393 |
while the other directories will mostly contain package dependent |
394 |
files. |
395 |
|
396 |
</P>
|
397 |
<P>
|
398 |
The <CODE>gettextize</CODE> program makes backup files for all files it |
399 |
replaces or changes, and also write ChangeLog entries about these |
400 |
changes. This way, the careful maintainer can check after running |
401 |
<CODE>gettextize</CODE> whether its changes are acceptable to him, and |
402 |
possibly adjust them. An exception to this rule is the <TT>`intl/´</TT> |
403 |
directory, which is added or replaced or removed as a whole. |
404 |
|
405 |
</P>
|
406 |
<P>
|
407 |
It is important to understand that <CODE>gettextize</CODE> can not do the |
408 |
entire job of adapting a package for using GNU <CODE>gettext</CODE>. The |
409 |
amount of remaining work depends on whether the package uses GNU |
410 |
<CODE>automake</CODE> or not. But in any case, the maintainer should still |
411 |
read the section section <A HREF="gettext_12.html#SEC193">12.4 Files You Must Create or Alter</A> after invoking <CODE>gettextize</CODE>. |
412 |
|
413 |
</P>
|
414 |
<P>
|
415 |
It is also important to understand that <CODE>gettextize</CODE> is not part |
416 |
of the GNU build system, in the sense that it should not be invoked |
417 |
automatically, and not be invoked by someone who doesn't assume the |
418 |
responsibilities of a package maintainer. For the latter purpose, a |
419 |
separate tool is provided, see section <A HREF="gettext_12.html#SEC214">12.6.3 Invoking the <CODE>autopoint</CODE> Program</A>. |
420 |
|
421 |
</P>
|
422 |
|
423 |
|
424 |
<H2><A NAME="SEC193" HREF="gettext_toc.html#TOC193">12.4 Files You Must Create or Alter</A></H2> |
425 |
<P>
|
426 |
<A NAME="IDX1017"></A> |
427 |
|
428 |
</P>
|
429 |
<P>
|
430 |
Besides files which are automatically added through <CODE>gettextize</CODE>, |
431 |
there are many files needing revision for properly interacting with |
432 |
GNU <CODE>gettext</CODE>. If you are closely following GNU standards for |
433 |
Makefile engineering and auto-configuration, the adaptations should |
434 |
be easier to achieve. Here is a point by point description of the |
435 |
changes needed in each. |
436 |
|
437 |
</P>
|
438 |
<P>
|
439 |
So, here comes a list of files, each one followed by a description of |
440 |
all alterations it needs. Many examples are taken out from the GNU |
441 |
<CODE>gettext</CODE> 0.13.1 distribution itself, or from the GNU |
442 |
<CODE>hello</CODE> distribution (<A HREF="http://www.franken.de/users/gnu/ke/hello">http://www.franken.de/users/gnu/ke/hello</A> |
443 |
or <A HREF="http://www.gnu.franken.de/ke/hello/">http://www.gnu.franken.de/ke/hello/</A>) You may indeed |
444 |
refer to the source code of the GNU <CODE>gettext</CODE> and GNU <CODE>hello</CODE> |
445 |
packages, as they are intended to be good examples for using GNU |
446 |
gettext functionality. |
447 |
|
448 |
</P>
|
449 |
|
450 |
|
451 |
|
452 |
<H3><A NAME="SEC194" HREF="gettext_toc.html#TOC194">12.4.1 <TT>`POTFILES.in´</TT> in <TT>`po/´</TT></A></H3> |
453 |
<P>
|
454 |
<A NAME="IDX1018"></A> |
455 |
|
456 |
</P>
|
457 |
<P>
|
458 |
The <TT>`po/´</TT> directory should receive a file named |
459 |
<TT>`POTFILES.in´</TT>. This file tells which files, among all program |
460 |
sources, have marked strings needing translation. Here is an example |
461 |
of such a file: |
462 |
|
463 |
</P>
|
464 |
|
465 |
<PRE>
|
466 |
# List of source files containing translatable strings. |
467 |
# Copyright (C) 1995 Free Software Foundation, Inc. |
468 |
|
469 |
# Common library files |
470 |
lib/error.c |
471 |
lib/getopt.c |
472 |
lib/xmalloc.c |
473 |
|
474 |
# Package source files |
475 |
src/gettext.c |
476 |
src/msgfmt.c |
477 |
src/xgettext.c |
478 |
</PRE>
|
479 |
|
480 |
<P>
|
481 |
Hash-marked comments and white lines are ignored. All other lines |
482 |
list those source files containing strings marked for translation |
483 |
(see section <A HREF="gettext_3.html#SEC16">3.3 How Marks Appear in Sources</A>), in a notation relative to the top level |
484 |
of your whole distribution, rather than the location of the |
485 |
<TT>`POTFILES.in´</TT> file itself. |
486 |
|
487 |
</P>
|
488 |
<P>
|
489 |
When a C file is automatically generated by a tool, like <CODE>flex</CODE> or |
490 |
<CODE>bison</CODE>, that doesn't introduce translatable strings by itself, |
491 |
it is recommended to list in <TT>`po/POTFILES.in´</TT> the real source file |
492 |
(ending in <TT>`.l´</TT> in the case of <CODE>flex</CODE>, or in <TT>`.y´</TT> in the |
493 |
case of <CODE>bison</CODE>), not the generated C file. |
494 |
|
495 |
</P>
|
496 |
|
497 |
|
498 |
<H3><A NAME="SEC195" HREF="gettext_toc.html#TOC195">12.4.2 <TT>`LINGUAS´</TT> in <TT>`po/´</TT></A></H3> |
499 |
<P>
|
500 |
<A NAME="IDX1019"></A> |
501 |
|
502 |
</P>
|
503 |
<P>
|
504 |
The <TT>`po/´</TT> directory should also receive a file named |
505 |
<TT>`LINGUAS´</TT>. This file contains the list of available translations. |
506 |
It is a whitespace separated list. Hash-marked comments and white lines |
507 |
are ignored. Here is an example file: |
508 |
|
509 |
</P>
|
510 |
|
511 |
<PRE>
|
512 |
# Set of available languages. |
513 |
de fr |
514 |
</PRE>
|
515 |
|
516 |
<P>
|
517 |
This example means that German and French PO files are available, so |
518 |
that these languages are currently supported by your package. If you |
519 |
want to further restrict, at installation time, the set of installed |
520 |
languages, this should not be done by modifying the <TT>`LINGUAS´</TT> file, |
521 |
but rather by using the <CODE>LINGUAS</CODE> environment variable |
522 |
(see section <A HREF="gettext_9.html#SEC155">9.2 Magic for Installers</A>). |
523 |
|
524 |
</P>
|
525 |
<P>
|
526 |
It is recommended that you add the "languages" <SAMP>`en@quot´</SAMP> and |
527 |
<SAMP>`en@boldquot´</SAMP> to the <CODE>LINGUAS</CODE> file. <CODE>en@quot</CODE> is a |
528 |
variant of English message catalogs (<CODE>en</CODE>) which uses real quotation |
529 |
marks instead of the ugly looking asymmetric ASCII substitutes <SAMP>``´</SAMP> |
530 |
and <SAMP>`'´</SAMP>. <CODE>en@boldquot</CODE> is a variant of <CODE>en@quot</CODE> that |
531 |
additionally outputs quoted pieces of text in a bold font, when used in |
532 |
a terminal emulator which supports the VT100 escape sequences (such as |
533 |
<CODE>xterm</CODE> or the Linux console, but not Emacs in <KBD>M-x shell</KBD> mode). |
534 |
|
535 |
</P>
|
536 |
<P>
|
537 |
These extra message catalogs <SAMP>`en@quot´</SAMP> and <SAMP>`en@boldquot´</SAMP> |
538 |
are constructed automatically, not by translators; to support them, you |
539 |
need the files <TT>`Rules-quot´</TT>, <TT>`quot.sed´</TT>, <TT>`boldquot.sed´</TT>, |
540 |
<TT>`en@quot.header´</TT>, <TT>`en@boldquot.header´</TT>, <TT>`insert-header.sin´</TT> |
541 |
in the <TT>`po/´</TT> directory. You can copy them from GNU gettext's <TT>`po/´</TT> |
542 |
directory; they are also installed by running <CODE>gettextize</CODE>. |
543 |
|
544 |
</P>
|
545 |
|
546 |
|
547 |
<H3><A NAME="SEC196" HREF="gettext_toc.html#TOC196">12.4.3 <TT>`Makefile´</TT> pieces in <TT>`po/´</TT></A></H3> |
548 |
<P>
|
549 |
<A NAME="IDX1020"></A> |
550 |
|
551 |
</P>
|
552 |
<P>
|
553 |
The <TT>`po/´</TT> directory also has a file named <TT>`Makevars´</TT>. |
554 |
It can be left unmodified if your package has a single message domain |
555 |
and, accordingly, a single <TT>`po/´</TT> directory. Only packages which |
556 |
have multiple <TT>`po/´</TT> directories at different locations need to |
557 |
adjust the three variables defined in <TT>`Makevars´</TT>. |
558 |
|
559 |
</P>
|
560 |
<P>
|
561 |
<TT>`po/Makevars´</TT> gets inserted into the <TT>`po/Makefile´</TT> when the |
562 |
latter is created. At the same time, all files called <TT>`Rules-*´</TT> in the |
563 |
<TT>`po/´</TT> directory get appended to the <TT>`po/Makefile´</TT>. They present |
564 |
an opportunity to add rules for special PO files to the Makefile, without |
565 |
needing to mess with <TT>`po/Makefile.in.in´</TT>. |
566 |
|
567 |
</P>
|
568 |
<P>
|
569 |
<A NAME="IDX1021"></A> |
570 |
<A NAME="IDX1022"></A> |
571 |
GNU gettext comes with a <TT>`Rules-quot´</TT> file, containing rules for |
572 |
building catalogs <TT>`en@quot.po´</TT> and <TT>`en@boldquot.po´</TT>. The |
573 |
effect of <TT>`en@quot.po´</TT> is that people who set their <CODE>LANGUAGE</CODE> |
574 |
environment variable to <SAMP>`en@quot´</SAMP> will get messages with proper |
575 |
looking symmetric Unicode quotation marks instead of abusing the ASCII |
576 |
grave accent and the ASCII apostrophe for indicating quotations. To |
577 |
enable this catalog, simply add <CODE>en@quot</CODE> to the <TT>`po/LINGUAS´</TT> |
578 |
file. The effect of <TT>`en@boldquot.po´</TT> is that people who set |
579 |
<CODE>LANGUAGE</CODE> to <SAMP>`en@boldquot´</SAMP> will get not only proper quotation |
580 |
marks, but also the quoted text will be shown in a bold font on terminals |
581 |
and consoles. This catalog is useful only for command-line programs, not |
582 |
GUI programs. To enable it, similarly add <CODE>en@boldquot</CODE> to the |
583 |
<TT>`po/LINGUAS´</TT> file. |
584 |
|
585 |
</P>
|
586 |
|
587 |
|
588 |
<H3><A NAME="SEC197" HREF="gettext_toc.html#TOC197">12.4.4 <TT>`configure.in´</TT> at top level</A></H3> |
589 |
|
590 |
<P>
|
591 |
<TT>`configure.in´</TT> or <TT>`configure.ac´</TT> - this is the source from which |
592 |
<CODE>autoconf</CODE> generates the <TT>`configure´</TT> script. |
593 |
|
594 |
</P>
|
595 |
|
596 |
<OL>
|
597 |
<LI>Declare the package and version.
|
598 |
|
599 |
<A NAME="IDX1023"></A> |
600 |
|
601 |
This is done by a set of lines like these: |
602 |
|
603 |
|
604 |
<PRE>
|
605 |
PACKAGE=gettext |
606 |
VERSION=0.13.1 |
607 |
AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") |
608 |
AC_DEFINE_UNQUOTED(VERSION, "$VERSION") |
609 |
AC_SUBST(PACKAGE) |
610 |
AC_SUBST(VERSION) |
611 |
</PRE>
|
612 |
|
613 |
or, if you are using GNU <CODE>automake</CODE>, by a line like this: |
614 |
|
615 |
|
616 |
<PRE>
|
617 |
AM_INIT_AUTOMAKE(gettext, 0.13.1) |
618 |
</PRE>
|
619 |
|
620 |
Of course, you replace <SAMP>`gettext´</SAMP> with the name of your package, |
621 |
and <SAMP>`0.13.1´</SAMP> by its version numbers, exactly as they |
622 |
should appear in the packaged <CODE>tar</CODE> file name of your distribution |
623 |
(<TT>`gettext-0.13.1.tar.gz´</TT>, here). |
624 |
|
625 |
<LI>Check for internationalization support.
|
626 |
|
627 |
Here is the main <CODE>m4</CODE> macro for triggering internationalization |
628 |
support. Just add this line to <TT>`configure.in´</TT>: |
629 |
|
630 |
|
631 |
<PRE>
|
632 |
AM_GNU_GETTEXT |
633 |
</PRE>
|
634 |
|
635 |
This call is purposely simple, even if it generates a lot of configure |
636 |
time checking and actions. |
637 |
|
638 |
If you have suppressed the <TT>`intl/´</TT> subdirectory by calling |
639 |
<CODE>gettextize</CODE> without <SAMP>`--intl´</SAMP> option, this call should read |
640 |
|
641 |
|
642 |
<PRE>
|
643 |
AM_GNU_GETTEXT([external]) |
644 |
</PRE>
|
645 |
|
646 |
<LI>Have output files created.
|
647 |
|
648 |
The <CODE>AC_OUTPUT</CODE> directive, at the end of your <TT>`configure.in´</TT> |
649 |
file, needs to be modified in two ways: |
650 |
|
651 |
|
652 |
<PRE>
|
653 |
AC_OUTPUT([<VAR>existing configuration files</VAR> intl/Makefile po/Makefile.in], |
654 |
[<VAR>existing additional actions</VAR>]) |
655 |
</PRE>
|
656 |
|
657 |
The modification to the first argument to <CODE>AC_OUTPUT</CODE> asks |
658 |
for substitution in the <TT>`intl/´</TT> and <TT>`po/´</TT> directories. |
659 |
Note the <SAMP>`.in´</SAMP> suffix used for <TT>`po/´</TT> only. This is because |
660 |
the distributed file is really <TT>`po/Makefile.in.in´</TT>. |
661 |
|
662 |
If you have suppressed the <TT>`intl/´</TT> subdirectory by calling |
663 |
<CODE>gettextize</CODE> without <SAMP>`--intl´</SAMP> option, then you don't need to |
664 |
add <CODE>intl/Makefile</CODE> to the <CODE>AC_OUTPUT</CODE> line. |
665 |
|
666 |
</OL>
|
667 |
|
668 |
|
669 |
|
670 |
<H3><A NAME="SEC198" HREF="gettext_toc.html#TOC198">12.4.5 <TT>`config.guess´</TT>, <TT>`config.sub´</TT> at top level</A></H3> |
671 |
|
672 |
<P>
|
673 |
If you haven't suppressed the <TT>`intl/´</TT> subdirectory, |
674 |
you need to add the GNU <TT>`config.guess´</TT> and <TT>`config.sub´</TT> files |
675 |
to your distribution. They are needed because the <TT>`intl/´</TT> directory |
676 |
has platform dependent support for determining the locale's character |
677 |
encoding and therefore needs to identify the platform. |
678 |
|
679 |
</P>
|
680 |
<P>
|
681 |
You can obtain the newest version of <TT>`config.guess´</TT> and |
682 |
<TT>`config.sub´</TT> from <TT>`ftp://ftp.gnu.org/pub/gnu/config/´</TT>. |
683 |
Less recent versions are also contained in the GNU <CODE>automake</CODE> and |
684 |
GNU <CODE>libtool</CODE> packages. |
685 |
|
686 |
</P>
|
687 |
<P>
|
688 |
Normally, <TT>`config.guess´</TT> and <TT>`config.sub´</TT> are put at the |
689 |
top level of a distribution. But it is also possible to put them in a |
690 |
subdirectory, altogether with other configuration support files like |
691 |
<TT>`install-sh´</TT>, <TT>`ltconfig´</TT>, <TT>`ltmain.sh´</TT>, |
692 |
<TT>`mkinstalldirs´</TT> or <TT>`missing´</TT>. All you need to do, other than |
693 |
moving the files, is to add the following line to your |
694 |
<TT>`configure.in´</TT>. |
695 |
|
696 |
</P>
|
697 |
|
698 |
<PRE>
|
699 |
AC_CONFIG_AUX_DIR([<VAR>subdir</VAR>]) |
700 |
</PRE>
|
701 |
|
702 |
|
703 |
|
704 |
<H3><A NAME="SEC199" HREF="gettext_toc.html#TOC199">12.4.6 <TT>`mkinstalldirs´</TT> at top level</A></H3> |
705 |
<P>
|
706 |
<A NAME="IDX1024"></A> |
707 |
|
708 |
</P>
|
709 |
<P>
|
710 |
If <CODE>gettextize</CODE> has not already done it, you need to add the GNU |
711 |
<TT>`mkinstalldirs´</TT> script to your distribution. It is needed because |
712 |
<SAMP>`mkdir -p´</SAMP> is not portable enough. You find this script in the |
713 |
GNU <CODE>automake</CODE> distribution. |
714 |
|
715 |
</P>
|
716 |
<P>
|
717 |
Normally, <TT>`mkinstalldirs´</TT> is put at the top level of a distribution. |
718 |
But it is also possible to put it in a subdirectory, altogether with other |
719 |
configuration support files like <TT>`install-sh´</TT>, <TT>`ltconfig´</TT>, |
720 |
<TT>`ltmain.sh´</TT> or <TT>`missing´</TT>. All you need to do, other than |
721 |
moving the files, is to add the following line to your <TT>`configure.in´</TT>. |
722 |
|
723 |
</P>
|
724 |
|
725 |
<PRE>
|
726 |
AC_CONFIG_AUX_DIR([<VAR>subdir</VAR>]) |
727 |
</PRE>
|
728 |
|
729 |
|
730 |
|
731 |
<H3><A NAME="SEC200" HREF="gettext_toc.html#TOC200">12.4.7 <TT>`aclocal.m4´</TT> at top level</A></H3> |
732 |
<P>
|
733 |
<A NAME="IDX1025"></A> |
734 |
|
735 |
</P>
|
736 |
<P>
|
737 |
If you do not have an <TT>`aclocal.m4´</TT> file in your distribution, |
738 |
the simplest is to concatenate the files <TT>`codeset.m4´</TT>, |
739 |
<TT>`gettext.m4´</TT>, <TT>`glibc21.m4´</TT>, <TT>`iconv.m4´</TT>, <TT>`intdiv0.m4´</TT>, |
740 |
<TT>`intmax.m4´</TT>, <TT>`inttypes.m4´</TT>, <TT>`inttypes_h.m4´</TT>, |
741 |
<TT>`inttypes-pri.m4´</TT>, <TT>`isc-posix.m4´</TT>, <TT>`lcmessage.m4´</TT>, |
742 |
<TT>`lib-ld.m4´</TT>, <TT>`lib-link.m4´</TT>, <TT>`lib-prefix.m4´</TT>, |
743 |
<TT>`longdouble.m4´</TT>, <TT>`longlong.m4´</TT>, <TT>`printf-posix.m4´</TT>, |
744 |
<TT>`progtest.m4´</TT>, <TT>`signed.m4´</TT>, <TT>`size_max.m4´</TT>, |
745 |
<TT>`stdint_h.m4´</TT>, <TT>`uintmax_t.m4´</TT>, <TT>`ulonglong.m4´</TT>, |
746 |
<TT>`wchar_t.m4´</TT>, <TT>`wint_t.m4´</TT>, <TT>`xsize.m4´</TT> |
747 |
from GNU <CODE>gettext</CODE>'s |
748 |
<TT>`m4/´</TT> directory into a single file. If you have suppressed the |
749 |
<TT>`intl/´</TT> directory, only <TT>`gettext.m4´</TT>, <TT>`iconv.m4´</TT>, |
750 |
<TT>`lib-ld.m4´</TT>, <TT>`lib-link.m4´</TT>, <TT>`lib-prefix.m4´</TT>, |
751 |
<TT>`progtest.m4´</TT> need to be concatenated. |
752 |
|
753 |
</P>
|
754 |
<P>
|
755 |
If you already have an <TT>`aclocal.m4´</TT> file, then you will have |
756 |
to merge the said macro files into your <TT>`aclocal.m4´</TT>. Note that if |
757 |
you are upgrading from a previous release of GNU <CODE>gettext</CODE>, you |
758 |
should most probably <EM>replace</EM> the macros (<CODE>AM_GNU_GETTEXT</CODE>, |
759 |
etc.), as they usually |
760 |
change a little from one release of GNU <CODE>gettext</CODE> to the next. |
761 |
Their contents may vary as we get more experience with strange systems |
762 |
out there. |
763 |
|
764 |
</P>
|
765 |
<P>
|
766 |
If you are using GNU <CODE>automake</CODE> 1.5 or newer, it is enough to put |
767 |
these macro files into a subdirectory named <TT>`m4/´</TT> and add the line |
768 |
|
769 |
</P>
|
770 |
|
771 |
<PRE>
|
772 |
ACLOCAL_AMFLAGS = -I m4 |
773 |
</PRE>
|
774 |
|
775 |
<P>
|
776 |
to your top level <TT>`Makefile.am´</TT>. |
777 |
|
778 |
</P>
|
779 |
<P>
|
780 |
These macros check for the internationalization support functions |
781 |
and related informations. Hopefully, once stabilized, these macros |
782 |
might be integrated in the standard Autoconf set, because this |
783 |
piece of <CODE>m4</CODE> code will be the same for all projects using GNU |
784 |
<CODE>gettext</CODE>. |
785 |
|
786 |
</P>
|
787 |
|
788 |
|
789 |
<H3><A NAME="SEC201" HREF="gettext_toc.html#TOC201">12.4.8 <TT>`acconfig.h´</TT> at top level</A></H3> |
790 |
<P>
|
791 |
<A NAME="IDX1026"></A> |
792 |
|
793 |
</P>
|
794 |
<P>
|
795 |
Earlier GNU <CODE>gettext</CODE> releases required to put definitions for |
796 |
<CODE>ENABLE_NLS</CODE>, <CODE>HAVE_GETTEXT</CODE> and <CODE>HAVE_LC_MESSAGES</CODE>, |
797 |
<CODE>HAVE_STPCPY</CODE>, <CODE>PACKAGE</CODE> and <CODE>VERSION</CODE> into an |
798 |
<TT>`acconfig.h´</TT> file. This is not needed any more; you can remove |
799 |
them from your <TT>`acconfig.h´</TT> file unless your package uses them |
800 |
independently from the <TT>`intl/´</TT> directory. |
801 |
|
802 |
</P>
|
803 |
|
804 |
|
805 |
<H3><A NAME="SEC202" HREF="gettext_toc.html#TOC202">12.4.9 <TT>`config.h.in´</TT> at top level</A></H3> |
806 |
<P>
|
807 |
<A NAME="IDX1027"></A> |
808 |
|
809 |
</P>
|
810 |
<P>
|
811 |
The include file template that holds the C macros to be defined by |
812 |
<CODE>configure</CODE> is usually called <TT>`config.h.in´</TT> and may be |
813 |
maintained either manually or automatically. |
814 |
|
815 |
</P>
|
816 |
<P>
|
817 |
If it is maintained automatically, by use of the <SAMP>`autoheader´</SAMP> |
818 |
program, you need to do nothing about it. This is the case in particular |
819 |
if you are using GNU <CODE>automake</CODE>. |
820 |
|
821 |
</P>
|
822 |
<P>
|
823 |
If it is maintained manually, and if <CODE>gettextize</CODE> has created an |
824 |
<TT>`intl/´</TT> directory, you should switch to using <SAMP>`autoheader´</SAMP>. |
825 |
The list of C macros to be added for the sake of the <TT>`intl/´</TT> |
826 |
directory is just too long to be maintained manually; it also changes |
827 |
between different versions of GNU <CODE>gettext</CODE>. |
828 |
|
829 |
</P>
|
830 |
<P>
|
831 |
If it is maintained manually, and if on the other hand you have |
832 |
suppressed the <TT>`intl/´</TT> directory by calling <CODE>gettextize</CODE> |
833 |
without <SAMP>`--intl´</SAMP> option, then you can get away by adding the |
834 |
following lines to <TT>`config.h.in´</TT>: |
835 |
|
836 |
</P>
|
837 |
|
838 |
<PRE>
|
839 |
/* Define to 1 if translation of program messages to the user's |
840 |
native language is requested. */ |
841 |
#undef ENABLE_NLS |
842 |
</PRE>
|
843 |
|
844 |
|
845 |
|
846 |
<H3><A NAME="SEC203" HREF="gettext_toc.html#TOC203">12.4.10 <TT>`Makefile.in´</TT> at top level</A></H3> |
847 |
|
848 |
<P>
|
849 |
Here are a few modifications you need to make to your main, top-level |
850 |
<TT>`Makefile.in´</TT> file. |
851 |
|
852 |
</P>
|
853 |
|
854 |
<OL>
|
855 |
<LI>
|
856 |
|
857 |
Add the following lines near the beginning of your <TT>`Makefile.in´</TT>, |
858 |
so the <SAMP>`dist:´</SAMP> goal will work properly (as explained further down): |
859 |
|
860 |
|
861 |
<PRE>
|
862 |
PACKAGE = @PACKAGE@ |
863 |
VERSION = @VERSION@ |
864 |
</PRE>
|
865 |
|
866 |
<LI>
|
867 |
|
868 |
Add file <TT>`ABOUT-NLS´</TT> to the <CODE>DISTFILES</CODE> definition, so the file gets |
869 |
distributed. |
870 |
|
871 |
<LI>
|
872 |
|
873 |
Wherever you process subdirectories in your <TT>`Makefile.in´</TT>, be sure |
874 |
you also process the subdirectories <SAMP>`intl´</SAMP> and <SAMP>`po´</SAMP>. Special |
875 |
rules in the <TT>`Makefiles´</TT> take care for the case where no |
876 |
internationalization is wanted. |
877 |
|
878 |
If you are using Makefiles, either generated by automake, or hand-written |
879 |
so they carefully follow the GNU coding standards, the effected goals for |
880 |
which the new subdirectories must be handled include <SAMP>`installdirs´</SAMP>, |
881 |
<SAMP>`install´</SAMP>, <SAMP>`uninstall´</SAMP>, <SAMP>`clean´</SAMP>, <SAMP>`distclean´</SAMP>. |
882 |
|
883 |
Here is an example of a canonical order of processing. In this |
884 |
example, we also define <CODE>SUBDIRS</CODE> in <CODE>Makefile.in</CODE> for it |
885 |
to be further used in the <SAMP>`dist:´</SAMP> goal. |
886 |
|
887 |
|
888 |
<PRE>
|
889 |
SUBDIRS = doc intl lib src po |
890 |
</PRE>
|
891 |
|
892 |
Note that you must arrange for <SAMP>`make´</SAMP> to descend into the |
893 |
<CODE>intl</CODE> directory before descending into other directories containing |
894 |
code which make use of the <CODE>libintl.h</CODE> header file. For this |
895 |
reason, here we mention <CODE>intl</CODE> before <CODE>lib</CODE> and <CODE>src</CODE>. |
896 |
|
897 |
<LI>
|
898 |
|
899 |
A delicate point is the <SAMP>`dist:´</SAMP> goal, as both |
900 |
<TT>`intl/Makefile´</TT> and <TT>`po/Makefile´</TT> will later assume that the |
901 |
proper directory has been set up from the main <TT>`Makefile´</TT>. Here is |
902 |
an example at what the <SAMP>`dist:´</SAMP> goal might look like: |
903 |
|
904 |
|
905 |
<PRE>
|
906 |
distdir = $(PACKAGE)-$(VERSION) |
907 |
dist: Makefile |
908 |
rm -fr $(distdir) |
909 |
mkdir $(distdir) |
910 |
chmod 777 $(distdir) |
911 |
for file in $(DISTFILES); do \ |
912 |
ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
|
913 |
done |
914 |
for subdir in $(SUBDIRS); do \ |
915 |
mkdir $(distdir)/$$subdir || exit 1; \ |
916 |
chmod 777 $(distdir)/$$subdir; \ |
917 |
(cd $$subdir && $(MAKE) $@) || exit 1; \ |
918 |
done |
919 |
tar chozf $(distdir).tar.gz $(distdir) |
920 |
rm -fr $(distdir) |
921 |
</PRE>
|
922 |
|
923 |
</OL>
|
924 |
|
925 |
<P>
|
926 |
Note that if you are using GNU <CODE>automake</CODE>, <TT>`Makefile.in´</TT> is |
927 |
automatically generated from <TT>`Makefile.am´</TT>, and all needed changes |
928 |
to <TT>`Makefile.am´</TT> are already made by running <SAMP>`gettextize´</SAMP>. |
929 |
|
930 |
</P>
|
931 |
|
932 |
|
933 |
<H3><A NAME="SEC204" HREF="gettext_toc.html#TOC204">12.4.11 <TT>`Makefile.in´</TT> in <TT>`src/´</TT></A></H3> |
934 |
|
935 |
<P>
|
936 |
Some of the modifications made in the main <TT>`Makefile.in´</TT> will |
937 |
also be needed in the <TT>`Makefile.in´</TT> from your package sources, |
938 |
which we assume here to be in the <TT>`src/´</TT> subdirectory. Here are |
939 |
all the modifications needed in <TT>`src/Makefile.in´</TT>: |
940 |
|
941 |
</P>
|
942 |
|
943 |
<OL>
|
944 |
<LI>
|
945 |
|
946 |
In view of the <SAMP>`dist:´</SAMP> goal, you should have these lines near the |
947 |
beginning of <TT>`src/Makefile.in´</TT>: |
948 |
|
949 |
|
950 |
<PRE>
|
951 |
PACKAGE = @PACKAGE@ |
952 |
VERSION = @VERSION@ |
953 |
</PRE>
|
954 |
|
955 |
<LI>
|
956 |
|
957 |
If not done already, you should guarantee that <CODE>top_srcdir</CODE> |
958 |
gets defined. This will serve for <CODE>cpp</CODE> include files. Just add |
959 |
the line: |
960 |
|
961 |
|
962 |
<PRE>
|
963 |
top_srcdir = @top_srcdir@ |
964 |
</PRE>
|
965 |
|
966 |
<LI>
|
967 |
|
968 |
You might also want to define <CODE>subdir</CODE> as <SAMP>`src´</SAMP>, later |
969 |
allowing for almost uniform <SAMP>`dist:´</SAMP> goals in all your |
970 |
<TT>`Makefile.in´</TT>. At list, the <SAMP>`dist:´</SAMP> goal below assume that |
971 |
you used: |
972 |
|
973 |
|
974 |
<PRE>
|
975 |
subdir = src |
976 |
</PRE>
|
977 |
|
978 |
<LI>
|
979 |
|
980 |
The <CODE>main</CODE> function of your program will normally call |
981 |
<CODE>bindtextdomain</CODE> (see see section <A HREF="gettext_3.html#SEC14">3.1 Triggering <CODE>gettext</CODE> Operations</A>), like this: |
982 |
|
983 |
|
984 |
<PRE>
|
985 |
bindtextdomain (<VAR>PACKAGE</VAR>, LOCALEDIR); |
986 |
textdomain (<VAR>PACKAGE</VAR>); |
987 |
</PRE>
|
988 |
|
989 |
To make LOCALEDIR known to the program, add the following lines to |
990 |
Makefile.in: |
991 |
|
992 |
|
993 |
<PRE>
|
994 |
datadir = @datadir@ |
995 |
localedir = $(datadir)/locale |
996 |
DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ |
997 |
</PRE>
|
998 |
|
999 |
Note that <CODE>@datadir@</CODE> defaults to <SAMP>`$(prefix)/share´</SAMP>, thus |
1000 |
<CODE>$(localedir)</CODE> defaults to <SAMP>`$(prefix)/share/locale´</SAMP>. |
1001 |
|
1002 |
<LI>
|
1003 |
|
1004 |
You should ensure that the final linking will use <CODE>@LIBINTL@</CODE> or |
1005 |
<CODE>@LTLIBINTL@</CODE> as a library. <CODE>@LIBINTL@</CODE> is for use without |
1006 |
<CODE>libtool</CODE>, <CODE>@LTLIBINTL@</CODE> is for use with <CODE>libtool</CODE>. An |
1007 |
easy way to achieve this is to manage that it gets into <CODE>LIBS</CODE>, like |
1008 |
this: |
1009 |
|
1010 |
|
1011 |
<PRE>
|
1012 |
LIBS = @LIBINTL@ @LIBS@ |
1013 |
</PRE>
|
1014 |
|
1015 |
In most packages internationalized with GNU <CODE>gettext</CODE>, one will |
1016 |
find a directory <TT>`lib/´</TT> in which a library containing some helper |
1017 |
functions will be build. (You need at least the few functions which the |
1018 |
GNU <CODE>gettext</CODE> Library itself needs.) However some of the functions |
1019 |
in the <TT>`lib/´</TT> also give messages to the user which of course should be |
1020 |
translated, too. Taking care of this, the support library (say |
1021 |
<TT>`libsupport.a´</TT>) should be placed before <CODE>@LIBINTL@</CODE> and |
1022 |
<CODE>@LIBS@</CODE> in the above example. So one has to write this: |
1023 |
|
1024 |
|
1025 |
<PRE>
|
1026 |
LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ |
1027 |
</PRE>
|
1028 |
|
1029 |
<LI>
|
1030 |
|
1031 |
You should also ensure that directory <TT>`intl/´</TT> will be searched for |
1032 |
C preprocessor include files in all circumstances. So, you have to |
1033 |
manage so both <SAMP>`-I../intl´</SAMP> and <SAMP>`-I$(top_srcdir)/intl´</SAMP> will |
1034 |
be given to the C compiler. |
1035 |
|
1036 |
<LI>
|
1037 |
|
1038 |
Your <SAMP>`dist:´</SAMP> goal has to conform with others. Here is a |
1039 |
reasonable definition for it: |
1040 |
|
1041 |
|
1042 |
<PRE>
|
1043 |
distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) |
1044 |
dist: Makefile $(DISTFILES) |
1045 |
for file in $(DISTFILES); do \ |
1046 |
ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
|
1047 |
done |
1048 |
</PRE>
|
1049 |
|
1050 |
</OL>
|
1051 |
|
1052 |
|
1053 |
|
1054 |
<H3><A NAME="SEC205" HREF="gettext_toc.html#TOC205">12.4.12 <TT>`gettext.h´</TT> in <TT>`lib/´</TT></A></H3> |
1055 |
<P>
|
1056 |
<A NAME="IDX1028"></A> |
1057 |
<A NAME="IDX1029"></A> |
1058 |
<A NAME="IDX1030"></A> |
1059 |
|
1060 |
</P>
|
1061 |
<P>
|
1062 |
Internationalization of packages, as provided by GNU <CODE>gettext</CODE>, is |
1063 |
optional. It can be turned off in two situations: |
1064 |
|
1065 |
</P>
|
1066 |
|
1067 |
<UL>
|
1068 |
<LI>
|
1069 |
|
1070 |
When the installer has specified <SAMP>`./configure --disable-nls´</SAMP>. This |
1071 |
can be useful when small binaries are more important than features, for |
1072 |
example when building utilities for boot diskettes. It can also be useful |
1073 |
in order to get some specific C compiler warnings about code quality with |
1074 |
some older versions of GCC (older than 3.0). |
1075 |
|
1076 |
<LI>
|
1077 |
|
1078 |
When the package does not include the <CODE>intl/</CODE> subdirectory, and the |
1079 |
libintl.h header (with its associated libintl library, if any) is not |
1080 |
already installed on the system, it is preferrable that the package builds |
1081 |
without internationalization support, rather than to give a compilation |
1082 |
error. |
1083 |
</UL>
|
1084 |
|
1085 |
<P>
|
1086 |
A C preprocessor macro can be used to detect these two cases. Usually, |
1087 |
when <CODE>libintl.h</CODE> was found and not explicitly disabled, the |
1088 |
<CODE>ENABLE_NLS</CODE> macro will be defined to 1 in the autoconf generated |
1089 |
configuration file (usually called <TT>`config.h´</TT>). In the two negative |
1090 |
situations, however, this macro will not be defined, thus it will evaluate |
1091 |
to 0 in C preprocessor expressions. |
1092 |
|
1093 |
</P>
|
1094 |
<P>
|
1095 |
<A NAME="IDX1031"></A> |
1096 |
<TT>`gettext.h´</TT> is a convenience header file for conditional use of |
1097 |
<TT>`<libintl.h>´</TT>, depending on the <CODE>ENABLE_NLS</CODE> macro. If |
1098 |
<CODE>ENABLE_NLS</CODE> is set, it includes <TT>`<libintl.h>´</TT>; otherwise it |
1099 |
defines no-op substitutes for the libintl.h functions. We recommend |
1100 |
the use of <CODE>"gettext.h"</CODE> over direct use of <TT>`<libintl.h>´</TT>, |
1101 |
so that portability to older systems is guaranteed and installers can |
1102 |
turn off internationalization if they want to. In the C code, you will |
1103 |
then write |
1104 |
|
1105 |
</P>
|
1106 |
|
1107 |
<PRE>
|
1108 |
#include "gettext.h" |
1109 |
</PRE>
|
1110 |
|
1111 |
<P>
|
1112 |
instead of |
1113 |
|
1114 |
</P>
|
1115 |
|
1116 |
<PRE>
|
1117 |
#include <libintl.h> |
1118 |
</PRE>
|
1119 |
|
1120 |
<P>
|
1121 |
The location of <CODE>gettext.h</CODE> is usually in a directory containing |
1122 |
auxiliary include files. In many GNU packages, there is a directory |
1123 |
<TT>`lib/´</TT> containing helper functions; <TT>`gettext.h´</TT> fits there. |
1124 |
In other packages, it can go into the <TT>`src´</TT> directory. |
1125 |
|
1126 |
</P>
|
1127 |
<P>
|
1128 |
Do not install the <CODE>gettext.h</CODE> file in public locations. Every |
1129 |
package that needs it should contain a copy of it on its own. |
1130 |
|
1131 |
</P>
|
1132 |
|
1133 |
|
1134 |
<H2><A NAME="SEC206" HREF="gettext_toc.html#TOC206">12.5 Autoconf macros for use in <TT>`configure.in´</TT></A></H2> |
1135 |
<P>
|
1136 |
<A NAME="IDX1032"></A> |
1137 |
|
1138 |
</P>
|
1139 |
<P>
|
1140 |
GNU <CODE>gettext</CODE> installs macros for use in a package's |
1141 |
<TT>`configure.in´</TT> or <TT>`configure.ac´</TT>. |
1142 |
See section `Introduction' in <CITE>The Autoconf Manual</CITE>. |
1143 |
The primary macro is, of course, <CODE>AM_GNU_GETTEXT</CODE>. |
1144 |
|
1145 |
</P>
|
1146 |
|
1147 |
|
1148 |
|
1149 |
<H3><A NAME="SEC207" HREF="gettext_toc.html#TOC207">12.5.1 AM_GNU_GETTEXT in <TT>`gettext.m4´</TT></A></H3> |
1150 |
|
1151 |
<P>
|
1152 |
<A NAME="IDX1033"></A> |
1153 |
The <CODE>AM_GNU_GETTEXT</CODE> macro tests for the presence of the GNU gettext |
1154 |
function family in either the C library or a separate <CODE>libintl</CODE> |
1155 |
library (shared or static libraries are both supported) or in the package's |
1156 |
<TT>`intl/´</TT> directory. It also invokes <CODE>AM_PO_SUBDIRS</CODE>, thus preparing |
1157 |
the <TT>`po/´</TT> directories of the package for building. |
1158 |
|
1159 |
</P>
|
1160 |
<P>
|
1161 |
<CODE>AM_GNU_GETTEXT</CODE> accepts up to three optional arguments. The general |
1162 |
syntax is |
1163 |
|
1164 |
</P>
|
1165 |
|
1166 |
<PRE>
|
1167 |
AM_GNU_GETTEXT([<VAR>intlsymbol</VAR>], [<VAR>needsymbol</VAR>], [<VAR>intldir</VAR>]) |
1168 |
</PRE>
|
1169 |
|
1170 |
<P>
|
1171 |
<VAR>intlsymbol</VAR> can be <SAMP>`external´</SAMP> or <SAMP>`no-libtool´</SAMP>. The default |
1172 |
(if it is not specified or empty) is <SAMP>`no-libtool´</SAMP>. <VAR>intlsymbol</VAR> |
1173 |
should be <SAMP>`external´</SAMP> for packages with no <TT>`intl/´</TT> directory, |
1174 |
and <SAMP>`no-libtool´</SAMP> for packages with an <TT>`intl/´</TT> directory. In |
1175 |
the latter case, a static library <CODE>$(top_builddir)/intl/libintl.a</CODE> |
1176 |
will be created. |
1177 |
|
1178 |
</P>
|
1179 |
<P>
|
1180 |
If <VAR>needsymbol</VAR> is specified and is <SAMP>`need-ngettext´</SAMP>, then GNU |
1181 |
gettext implementations (in libc or libintl) without the <CODE>ngettext()</CODE> |
1182 |
function will be ignored. If <VAR>needsymbol</VAR> is specified and is |
1183 |
<SAMP>`need-formatstring-macros´</SAMP>, then GNU gettext implementations that don't |
1184 |
support the ISO C 99 <TT>`<inttypes.h>´</TT> formatstring macros will be ignored. |
1185 |
Only one <VAR>needsymbol</VAR> can be specified. To specify more than one |
1186 |
requirement, just specify the strongest one among them. The hierarchy among |
1187 |
the various alternatives is as follows: <SAMP>`need-formatstring-macros´</SAMP> |
1188 |
implies <SAMP>`need-ngettext´</SAMP>. |
1189 |
|
1190 |
</P>
|
1191 |
<P>
|
1192 |
<VAR>intldir</VAR> is used to find the intl libraries. If empty, the value |
1193 |
<SAMP>`$(top_builddir)/intl/´</SAMP> is used. |
1194 |
|
1195 |
</P>
|
1196 |
<P>
|
1197 |
The <CODE>AM_GNU_GETTEXT</CODE> macro determines whether GNU gettext is |
1198 |
available and should be used. If so, it sets the <CODE>USE_NLS</CODE> variable |
1199 |
to <SAMP>`yes´</SAMP>; it defines <CODE>ENABLE_NLS</CODE> to 1 in the autoconf |
1200 |
generated configuration file (usually called <TT>`config.h´</TT>); it sets |
1201 |
the variables <CODE>LIBINTL</CODE> and <CODE>LTLIBINTL</CODE> to the linker options |
1202 |
for use in a Makefile (<CODE>LIBINTL</CODE> for use without libtool, |
1203 |
<CODE>LTLIBINTL</CODE> for use with libtool); it adds an <SAMP>`-I´</SAMP> option to |
1204 |
<CODE>CPPFLAGS</CODE> if necessary. In the negative case, it sets |
1205 |
<CODE>USE_NLS</CODE> to <SAMP>`no´</SAMP>; it sets <CODE>LIBINTL</CODE> and <CODE>LTLIBINTL</CODE> |
1206 |
to empty and doesn't change <CODE>CPPFLAGS</CODE>. |
1207 |
|
1208 |
</P>
|
1209 |
<P>
|
1210 |
The complexities that <CODE>AM_GNU_GETTEXT</CODE> deals with are the following: |
1211 |
|
1212 |
</P>
|
1213 |
|
1214 |
<UL>
|
1215 |
<LI>
|
1216 |
|
1217 |
<A NAME="IDX1034"></A> |
1218 |
Some operating systems have <CODE>gettext</CODE> in the C library, for example |
1219 |
glibc. Some have it in a separate library <CODE>libintl</CODE>. GNU <CODE>libintl</CODE> |
1220 |
might have been installed as part of the GNU <CODE>gettext</CODE> package. |
1221 |
|
1222 |
<LI>
|
1223 |
|
1224 |
GNU <CODE>libintl</CODE>, if installed, is not necessarily already in the search |
1225 |
path (<CODE>CPPFLAGS</CODE> for the include file search path, <CODE>LDFLAGS</CODE> for |
1226 |
the library search path). |
1227 |
|
1228 |
<LI>
|
1229 |
|
1230 |
Except for glibc, the operating system's native <CODE>gettext</CODE> cannot |
1231 |
exploit the GNU mo files, doesn't have the necessary locale dependency |
1232 |
features, and cannot convert messages from the catalog's text encoding |
1233 |
to the user's locale encoding. |
1234 |
|
1235 |
<LI>
|
1236 |
|
1237 |
GNU <CODE>libintl</CODE>, if installed, is not necessarily already in the |
1238 |
run time library search path. To avoid the need for setting an environment |
1239 |
variable like <CODE>LD_LIBRARY_PATH</CODE>, the macro adds the appropriate |
1240 |
run time search path options to the <CODE>LIBINTL</CODE> and <CODE>LTLIBINTL</CODE> |
1241 |
variables. This works on most systems, but not on some operating systems |
1242 |
with limited shared library support, like SCO. |
1243 |
|
1244 |
<LI>
|
1245 |
|
1246 |
GNU <CODE>libintl</CODE> relies on POSIX/XSI <CODE>iconv</CODE>. The macro checks for |
1247 |
linker options needed to use iconv and appends them to the <CODE>LIBINTL</CODE> |
1248 |
and <CODE>LTLIBINTL</CODE> variables. |
1249 |
</UL>
|
1250 |
|
1251 |
|
1252 |
|
1253 |
<H3><A NAME="SEC208" HREF="gettext_toc.html#TOC208">12.5.2 AM_GNU_GETTEXT_VERSION in <TT>`gettext.m4´</TT></A></H3> |
1254 |
|
1255 |
<P>
|
1256 |
<A NAME="IDX1035"></A> |
1257 |
The <CODE>AM_GNU_GETTEXT_VERSION</CODE> macro declares the version number of |
1258 |
the GNU gettext infrastructure that is used by the package. |
1259 |
|
1260 |
</P>
|
1261 |
<P>
|
1262 |
The use of this macro is optional; only the <CODE>autopoint</CODE> program makes |
1263 |
use of it (see section <A HREF="gettext_12.html#SEC211">12.6 Integrating with CVS</A>). |
1264 |
|
1265 |
</P>
|
1266 |
|
1267 |
|
1268 |
<H3><A NAME="SEC209" HREF="gettext_toc.html#TOC209">12.5.3 AM_PO_SUBDIRS in <TT>`po.m4´</TT></A></H3> |
1269 |
|
1270 |
<P>
|
1271 |
<A NAME="IDX1036"></A> |
1272 |
The <CODE>AM_PO_SUBDIRS</CODE> macro prepares the <TT>`po/´</TT> directories of the |
1273 |
package for building. This macro should be used in internationalized |
1274 |
programs written in other programming languages than C, C++, Objective C, |
1275 |
for example <CODE>sh</CODE>, <CODE>Python</CODE>, <CODE>Lisp</CODE>. See section <A HREF="gettext_13.html#SEC217">13 Other Programming Languages</A> for a list of programming languages that support localization |
1276 |
through PO files. |
1277 |
|
1278 |
</P>
|
1279 |
<P>
|
1280 |
The <CODE>AM_PO_SUBDIRS</CODE> macro determines whether internationalization |
1281 |
should be used. If so, it sets the <CODE>USE_NLS</CODE> variable to <SAMP>`yes´</SAMP>, |
1282 |
otherwise to <SAMP>`no´</SAMP>. It also determines the right values for Makefile |
1283 |
variables in each <TT>`po/´</TT> directory. |
1284 |
|
1285 |
</P>
|
1286 |
|
1287 |
|
1288 |
<H3><A NAME="SEC210" HREF="gettext_toc.html#TOC210">12.5.4 AM_ICONV in <TT>`iconv.m4´</TT></A></H3> |
1289 |
|
1290 |
<P>
|
1291 |
<A NAME="IDX1037"></A> |
1292 |
The <CODE>AM_ICONV</CODE> macro tests for the presence of the POSIX/XSI |
1293 |
<CODE>iconv</CODE> function family in either the C library or a separate |
1294 |
<CODE>libiconv</CODE> library. If found, it sets the <CODE>am_cv_func_iconv</CODE> |
1295 |
variable to <SAMP>`yes´</SAMP>; it defines <CODE>HAVE_ICONV</CODE> to 1 in the autoconf |
1296 |
generated configuration file (usually called <TT>`config.h´</TT>); it defines |
1297 |
<CODE>ICONV_CONST</CODE> to <SAMP>`const´</SAMP> or to empty, depending on whether the |
1298 |
second argument of <CODE>iconv()</CODE> is of type <SAMP>`const char **´</SAMP> or |
1299 |
<SAMP>`char **´</SAMP>; it sets the variables <CODE>LIBICONV</CODE> and |
1300 |
<CODE>LTLIBICONV</CODE> to the linker options for use in a Makefile |
1301 |
(<CODE>LIBICONV</CODE> for use without libtool, <CODE>LTLIBICONV</CODE> for use with |
1302 |
libtool); it adds an <SAMP>`-I´</SAMP> option to <CODE>CPPFLAGS</CODE> if |
1303 |
necessary. If not found, it sets <CODE>LIBICONV</CODE> and <CODE>LTLIBICONV</CODE> to |
1304 |
empty and doesn't change <CODE>CPPFLAGS</CODE>. |
1305 |
|
1306 |
</P>
|
1307 |
<P>
|
1308 |
The complexities that <CODE>AM_ICONV</CODE> deals with are the following: |
1309 |
|
1310 |
</P>
|
1311 |
|
1312 |
<UL>
|
1313 |
<LI>
|
1314 |
|
1315 |
<A NAME="IDX1038"></A> |
1316 |
Some operating systems have <CODE>iconv</CODE> in the C library, for example |
1317 |
glibc. Some have it in a separate library <CODE>libiconv</CODE>, for example |
1318 |
OSF/1 or FreeBSD. Regardless of the operating system, GNU <CODE>libiconv</CODE> |
1319 |
might have been installed. In that case, it should be used instead of the |
1320 |
operating system's native <CODE>iconv</CODE>. |
1321 |
|
1322 |
<LI>
|
1323 |
|
1324 |
GNU <CODE>libiconv</CODE>, if installed, is not necessarily already in the search |
1325 |
path (<CODE>CPPFLAGS</CODE> for the include file search path, <CODE>LDFLAGS</CODE> for |
1326 |
the library search path). |
1327 |
|
1328 |
<LI>
|
1329 |
|
1330 |
GNU <CODE>libiconv</CODE> is binary incompatible with some operating system's |
1331 |
native <CODE>iconv</CODE>, for example on FreeBSD. Use of an <TT>`iconv.h´</TT> |
1332 |
and <TT>`libiconv.so´</TT> that don't fit together would produce program |
1333 |
crashes. |
1334 |
|
1335 |
<LI>
|
1336 |
|
1337 |
GNU <CODE>libiconv</CODE>, if installed, is not necessarily already in the |
1338 |
run time library search path. To avoid the need for setting an environment |
1339 |
variable like <CODE>LD_LIBRARY_PATH</CODE>, the macro adds the appropriate |
1340 |
run time search path options to the <CODE>LIBICONV</CODE> variable. This works |
1341 |
on most systems, but not on some operating systems with limited shared |
1342 |
library support, like SCO. |
1343 |
</UL>
|
1344 |
|
1345 |
<P>
|
1346 |
<TT>`iconv.m4´</TT> is distributed with the GNU gettext package because |
1347 |
<TT>`gettext.m4´</TT> relies on it. |
1348 |
|
1349 |
</P>
|
1350 |
|
1351 |
|
1352 |
<H2><A NAME="SEC211" HREF="gettext_toc.html#TOC211">12.6 Integrating with CVS</A></H2> |
1353 |
|
1354 |
<P>
|
1355 |
Many projects use CVS for distributed development, version control and |
1356 |
source backup. This section gives some advice how to manage the uses |
1357 |
of <CODE>cvs</CODE>, <CODE>gettextize</CODE>, <CODE>autopoint</CODE> and <CODE>autoconf</CODE>. |
1358 |
|
1359 |
</P>
|
1360 |
|
1361 |
|
1362 |
|
1363 |
<H3><A NAME="SEC212" HREF="gettext_toc.html#TOC212">12.6.1 Avoiding version mismatch in distributed development</A></H3> |
1364 |
|
1365 |
<P>
|
1366 |
In a project development with multiple developers, using CVS, there |
1367 |
should be a single developer who occasionally - when there is desire to |
1368 |
upgrade to a new <CODE>gettext</CODE> version - runs <CODE>gettextize</CODE> and |
1369 |
performs the changes listed in section <A HREF="gettext_12.html#SEC193">12.4 Files You Must Create or Alter</A>, and then commits |
1370 |
his changes to the CVS. |
1371 |
|
1372 |
</P>
|
1373 |
<P>
|
1374 |
It is highly recommended that all developers on a project use the same |
1375 |
version of GNU <CODE>gettext</CODE> in the package. In other words, if a |
1376 |
developer runs <CODE>gettextize</CODE>, he should go the whole way, make the |
1377 |
necessary remaining changes and commit his changes to the CVS. |
1378 |
Otherwise the following damages will likely occur: |
1379 |
|
1380 |
</P>
|
1381 |
|
1382 |
<UL>
|
1383 |
<LI>
|
1384 |
|
1385 |
Apparent version mismatch between developers. Since some <CODE>gettext</CODE> |
1386 |
specific portions in <TT>`configure.in´</TT>, <TT>`configure.ac´</TT> and |
1387 |
<CODE>Makefile.am</CODE>, <CODE>Makefile.in</CODE> files depend on the <CODE>gettext</CODE> |
1388 |
version, the use of infrastructure files belonging to different |
1389 |
<CODE>gettext</CODE> versions can easily lead to build errors. |
1390 |
|
1391 |
<LI>
|
1392 |
|
1393 |
Hidden version mismatch. Such version mismatch can also lead to |
1394 |
malfunctioning of the package, that may be undiscovered by the developers. |
1395 |
The worst case of hidden version mismatch is that internationalization |
1396 |
of the package doesn't work at all. |
1397 |
|
1398 |
<LI>
|
1399 |
|
1400 |
Release risks. All developers implicitly perform constant testing on |
1401 |
a package. This is important in the days and weeks before a release. |
1402 |
If the guy who makes the release tar files uses a different version |
1403 |
of GNU <CODE>gettext</CODE> than the other developers, the distribution will |
1404 |
be less well tested than if all had been using the same <CODE>gettext</CODE> |
1405 |
version. For example, it is possible that a platform specific bug goes |
1406 |
undiscovered due to this constellation. |
1407 |
</UL>
|
1408 |
|
1409 |
|
1410 |
|
1411 |
<H3><A NAME="SEC213" HREF="gettext_toc.html#TOC213">12.6.2 Files to put under CVS version control</A></H3> |
1412 |
|
1413 |
<P>
|
1414 |
There are basically three ways to deal with generated files in the |
1415 |
context of a CVS repository, such as <TT>`configure´</TT> generated from |
1416 |
<TT>`configure.in´</TT>, <CODE><VAR>parser</VAR>.c</CODE> generated from |
1417 |
<CODE><VAR>parser</VAR>.y</CODE>, or <CODE>po/Makefile.in.in</CODE> autoinstalled by |
1418 |
<CODE>gettextize</CODE> or <CODE>autopoint</CODE>. |
1419 |
|
1420 |
</P>
|
1421 |
|
1422 |
<OL>
|
1423 |
<LI>
|
1424 |
|
1425 |
All generated files are always committed into the repository. |
1426 |
|
1427 |
<LI>
|
1428 |
|
1429 |
All generated files are committed into the repository occasionally, |
1430 |
for example each time a release is made. |
1431 |
|
1432 |
<LI>
|
1433 |
|
1434 |
Generated files are never committed into the repository. |
1435 |
</OL>
|
1436 |
|
1437 |
<P>
|
1438 |
Each of these three approaches has different advantages and drawbacks. |
1439 |
|
1440 |
</P>
|
1441 |
|
1442 |
<OL>
|
1443 |
<LI>
|
1444 |
|
1445 |
The advantage is that anyone can check out the CVS at any moment and |
1446 |
gets a working build. The drawbacks are: 1a. It requires some frequent |
1447 |
"cvs commit" actions by the maintainers. 1b. The repository grows in size |
1448 |
quite fast. |
1449 |
|
1450 |
<LI>
|
1451 |
|
1452 |
The advantage is that anyone can check out the CVS, and the usual |
1453 |
"./configure; make" will work. The drawbacks are: 2a. The one who |
1454 |
checks out the repository needs tools like GNU <CODE>automake</CODE>, |
1455 |
GNU <CODE>autoconf</CODE>, GNU <CODE>m4</CODE> installed in his PATH; sometimes |
1456 |
he even needs particular versions of them. 2b. When a release is made |
1457 |
and a commit is made on the generated files, the other developers get |
1458 |
conflicts on the generated files after doing "cvs update". Although |
1459 |
these conflicts are easy to resolve, they are annoying. |
1460 |
|
1461 |
<LI>
|
1462 |
|
1463 |
The advantage is less work for the maintainers. The drawback is that |
1464 |
anyone who checks out the CVS not only needs tools like GNU <CODE>automake</CODE>, |
1465 |
GNU <CODE>autoconf</CODE>, GNU <CODE>m4</CODE> installed in his PATH, but also that |
1466 |
he needs to perform a package specific pre-build step before being able |
1467 |
to "./configure; make". |
1468 |
</OL>
|
1469 |
|
1470 |
<P>
|
1471 |
For the first and second approach, all files modified or brought in |
1472 |
by the occasional <CODE>gettextize</CODE> invocation and update should be |
1473 |
committed into the CVS. |
1474 |
|
1475 |
</P>
|
1476 |
<P>
|
1477 |
For the third approach, the maintainer can omit from the CVS repository |
1478 |
all the files that <CODE>gettextize</CODE> mentions as "copy". Instead, he |
1479 |
adds to the <TT>`configure.in´</TT> or <TT>`configure.ac´</TT> a line of the |
1480 |
form |
1481 |
|
1482 |
</P>
|
1483 |
|
1484 |
<PRE>
|
1485 |
AM_GNU_GETTEXT_VERSION(0.13.1) |
1486 |
</PRE>
|
1487 |
|
1488 |
<P>
|
1489 |
and adds to the package's pre-build script an invocation of |
1490 |
<SAMP>`autopoint´</SAMP>. For everyone who checks out the CVS, this |
1491 |
<CODE>autopoint</CODE> invocation will copy into the right place the |
1492 |
<CODE>gettext</CODE> infrastructure files that have been omitted from the CVS. |
1493 |
|
1494 |
</P>
|
1495 |
|
1496 |
|
1497 |
<H3><A NAME="SEC214" HREF="gettext_toc.html#TOC214">12.6.3 Invoking the <CODE>autopoint</CODE> Program</A></H3> |
1498 |
|
1499 |
<P>
|
1500 |
<A NAME="IDX1039"></A> |
1501 |
<A NAME="IDX1040"></A> |
1502 |
|
1503 |
<PRE>
|
1504 |
autopoint [<VAR>option</VAR>]... |
1505 |
</PRE>
|
1506 |
|
1507 |
<P>
|
1508 |
The <CODE>autopoint</CODE> program copies standard gettext infrastructure files |
1509 |
into a source package. It extracts from a macro call of the form |
1510 |
<CODE>AM_GNU_GETTEXT_VERSION(<VAR>version</VAR>)</CODE>, found in the package's |
1511 |
<TT>`configure.in´</TT> or <TT>`configure.ac´</TT> file, the gettext version |
1512 |
used by the package, and copies the infrastructure files belonging to |
1513 |
this version into the package. |
1514 |
|
1515 |
</P>
|
1516 |
|
1517 |
|
1518 |
<H4><A NAME="SEC215" HREF="gettext_toc.html#TOC215">12.6.3.1 Options</A></H4> |
1519 |
|
1520 |
<DL COMPACT> |
1521 |
|
1522 |
<DT><SAMP>`-f´</SAMP> |
1523 |
<DD>
|
1524 |
<DT><SAMP>`--force´</SAMP> |
1525 |
<DD>
|
1526 |
<A NAME="IDX1041"></A> |
1527 |
<A NAME="IDX1042"></A> |
1528 |
Force overwriting of files that already exist. |
1529 |
|
1530 |
<DT><SAMP>`-n´</SAMP> |
1531 |
<DD>
|
1532 |
<DT><SAMP>`--dry-run´</SAMP> |
1533 |
<DD>
|
1534 |
<A NAME="IDX1043"></A> |
1535 |
<A NAME="IDX1044"></A> |
1536 |
Print modifications but don't perform them. All file copying actions that |
1537 |
<CODE>autopoint</CODE> would normally execute are inhibited and instead only |
1538 |
listed on standard output. |
1539 |
|
1540 |
</DL>
|
1541 |
|
1542 |
|
1543 |
|
1544 |
<H4><A NAME="SEC216" HREF="gettext_toc.html#TOC216">12.6.3.2 Informative output</A></H4> |
1545 |
|
1546 |
<DL COMPACT> |
1547 |
|
1548 |
<DT><SAMP>`--help´</SAMP> |
1549 |
<DD>
|
1550 |
<A NAME="IDX1045"></A> |
1551 |
Display this help and exit. |
1552 |
|
1553 |
<DT><SAMP>`--version´</SAMP> |
1554 |
<DD>
|
1555 |
<A NAME="IDX1046"></A> |
1556 |
Output version information and exit. |
1557 |
|
1558 |
</DL>
|
1559 |
|
1560 |
<P>
|
1561 |
<CODE>autopoint</CODE> supports the GNU <CODE>gettext</CODE> versions from 0.10.35 to |
1562 |
the current one, 0.13.1. In order to apply <CODE>autopoint</CODE> to |
1563 |
a package using a <CODE>gettext</CODE> version newer than 0.13.1, you |
1564 |
need to install this same version of GNU <CODE>gettext</CODE> at least. |
1565 |
|
1566 |
</P>
|
1567 |
<P>
|
1568 |
In packages using GNU <CODE>automake</CODE>, an invocation of <CODE>autopoint</CODE> |
1569 |
should be followed by invocations of <CODE>aclocal</CODE> and then <CODE>autoconf</CODE> |
1570 |
and <CODE>autoheader</CODE>. The reason is that <CODE>autopoint</CODE> installs some |
1571 |
autoconf macro files, which are used by <CODE>aclocal</CODE> to create |
1572 |
<TT>`aclocal.m4´</TT>, and the latter is used by <CODE>autoconf</CODE> to create the |
1573 |
package's <TT>`configure´</TT> script and by <CODE>autoheader</CODE> to create the |
1574 |
package's <TT>`config.h.in´</TT> include file template. |
1575 |
|
1576 |
</P>
|
1577 |
<P>
|
1578 |
The name <SAMP>`autopoint´</SAMP> is an abbreviation of <SAMP>`auto-po-intl-m4´</SAMP>; |
1579 |
the tool copies or updates mostly files in the <TT>`po´</TT>, <TT>`intl´</TT>, |
1580 |
<TT>`m4´</TT> directories. |
1581 |
|
1582 |
</P>
|
1583 |
<P><HR><P> |
1584 |
Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_11.html">previous</A>, <A HREF="gettext_13.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. |
1585 |
</BODY>
|
1586 |
</HTML>
|