release/src/router/gettext/gettext-tools/doc/gettext_12.html

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