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