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