mingw/share/doc/gettext/gettext_13.html

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