Mercurial > repos > rliterman > csp2
comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_13.html @ 68:5028fdace37b
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
| author | jpayne |
|---|---|
| date | Tue, 18 Mar 2025 16:23:26 -0400 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 67:0e9998148a16 | 68:5028fdace37b |
|---|---|
| 1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd"> | |
| 2 <html> | |
| 3 <!-- Created on February, 21 2024 by texi2html 1.78a --> | |
| 4 <!-- | |
| 5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) | |
| 6 Karl Berry <karl@freefriends.org> | |
| 7 Olaf Bachmann <obachman@mathematik.uni-kl.de> | |
| 8 and many others. | |
| 9 Maintained by: Many creative people. | |
| 10 Send bugs and suggestions to <texi2html-bug@nongnu.org> | |
| 11 | |
| 12 --> | |
| 13 <head> | |
| 14 <title>GNU gettext utilities: 13. The Maintainer's View</title> | |
| 15 | |
| 16 <meta name="description" content="GNU gettext utilities: 13. The Maintainer's View"> | |
| 17 <meta name="keywords" content="GNU gettext utilities: 13. The Maintainer's View"> | |
| 18 <meta name="resource-type" content="document"> | |
| 19 <meta name="distribution" content="global"> | |
| 20 <meta name="Generator" content="texi2html 1.78a"> | |
| 21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> | |
| 22 <style type="text/css"> | |
| 23 <!-- | |
| 24 a.summary-letter {text-decoration: none} | |
| 25 pre.display {font-family: serif} | |
| 26 pre.format {font-family: serif} | |
| 27 pre.menu-comment {font-family: serif} | |
| 28 pre.menu-preformatted {font-family: serif} | |
| 29 pre.smalldisplay {font-family: serif; font-size: smaller} | |
| 30 pre.smallexample {font-size: smaller} | |
| 31 pre.smallformat {font-family: serif; font-size: smaller} | |
| 32 pre.smalllisp {font-size: smaller} | |
| 33 span.roman {font-family:serif; font-weight:normal;} | |
| 34 span.sansserif {font-family:sans-serif; font-weight:normal;} | |
| 35 ul.toc {list-style: none} | |
| 36 --> | |
| 37 </style> | |
| 38 | |
| 39 | |
| 40 </head> | |
| 41 | |
| 42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> | |
| 43 | |
| 44 <table cellpadding="1" cellspacing="1" border="0"> | |
| 45 <tr><td valign="middle" align="left">[<a href="gettext_12.html#SEC217" title="Beginning of this chapter or previous chapter"> << </a>]</td> | |
| 46 <td valign="middle" align="left">[<a href="gettext_14.html#SEC262" title="Next chapter"> >> </a>]</td> | |
| 47 <td valign="middle" align="left"> </td> | |
| 48 <td valign="middle" align="left"> </td> | |
| 49 <td valign="middle" align="left"> </td> | |
| 50 <td valign="middle" align="left"> </td> | |
| 51 <td valign="middle" align="left"> </td> | |
| 52 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> | |
| 53 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td> | |
| 54 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td> | |
| 55 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td> | |
| 56 </tr></table> | |
| 57 | |
| 58 <hr size="2"> | |
| 59 <a name="Maintainers"></a> | |
| 60 <a name="SEC230"></a> | |
| 61 <h1 class="chapter"> <a href="gettext_toc.html#TOC223">13. The Maintainer's View</a> </h1> | |
| 62 | |
| 63 <p>The maintainer of a package has many responsibilities. One of them | |
| 64 is ensuring that the package will install easily on many platforms, | |
| 65 and that the magic we described earlier (see section <a href="gettext_2.html#SEC7">The User's View</a>) will work | |
| 66 for installers and end users. | |
| 67 </p> | |
| 68 <p>Of course, there are many possible ways by which GNU <code>gettext</code> | |
| 69 might be integrated in a distribution, and this chapter does not cover | |
| 70 them in all generality. Instead, it details one possible approach which | |
| 71 is especially adequate for many free software distributions following GNU | |
| 72 standards, or even better, Gnits standards, because GNU <code>gettext</code> | |
| 73 is purposely for helping the internationalization of the whole GNU | |
| 74 project, and as many other good free packages as possible. So, the | |
| 75 maintainer's view presented here presumes that the package already has | |
| 76 a ‘<tt>configure.ac</tt>’ file and uses GNU Autoconf. | |
| 77 </p> | |
| 78 <p>Nevertheless, GNU <code>gettext</code> may surely be useful for free packages | |
| 79 not following GNU standards and conventions, but the maintainers of such | |
| 80 packages might have to show imagination and initiative in organizing | |
| 81 their distributions so <code>gettext</code> work for them in all situations. | |
| 82 There are surely many, out there. | |
| 83 </p> | |
| 84 <p>Even if <code>gettext</code> methods are now stabilizing, slight adjustments | |
| 85 might be needed between successive <code>gettext</code> versions, so you | |
| 86 should ideally revise this chapter in subsequent releases, looking | |
| 87 for changes. | |
| 88 </p> | |
| 89 | |
| 90 | |
| 91 <a name="Flat-and-Non_002dFlat"></a> | |
| 92 <a name="SEC231"></a> | |
| 93 <h2 class="section"> <a href="gettext_toc.html#TOC224">13.1 Flat or Non-Flat Directory Structures</a> </h2> | |
| 94 | |
| 95 <p>Some free software packages are distributed as <code>tar</code> files which unpack | |
| 96 in a single directory, these are said to be <em>flat</em> distributions. | |
| 97 Other free software packages have a one level hierarchy of subdirectories, using | |
| 98 for example a subdirectory named ‘<tt>doc/</tt>’ for the Texinfo manual and | |
| 99 man pages, another called ‘<tt>lib/</tt>’ for holding functions meant to | |
| 100 replace or complement C libraries, and a subdirectory ‘<tt>src/</tt>’ for | |
| 101 holding the proper sources for the package. These other distributions | |
| 102 are said to be <em>non-flat</em>. | |
| 103 </p> | |
| 104 <p>We cannot say much about flat distributions. A flat | |
| 105 directory structure has the disadvantage of increasing the difficulty | |
| 106 of updating to a new version of GNU <code>gettext</code>. Also, if you have | |
| 107 many PO files, this could somewhat pollute your single directory. | |
| 108 Also, GNU <code>gettext</code>'s libintl sources consist of C sources, shell | |
| 109 scripts, <code>sed</code> scripts and complicated Makefile rules, which don't | |
| 110 fit well into an existing flat structure. For these reasons, we | |
| 111 recommend to use non-flat approach in this case as well. | |
| 112 </p> | |
| 113 <p>Maybe because GNU <code>gettext</code> itself has a non-flat structure, | |
| 114 we have more experience with this approach, and this is what will be | |
| 115 described in the remaining of this chapter. Some maintainers might | |
| 116 use this as an opportunity to unflatten their package structure. | |
| 117 </p> | |
| 118 | |
| 119 <a name="Prerequisites"></a> | |
| 120 <a name="SEC232"></a> | |
| 121 <h2 class="section"> <a href="gettext_toc.html#TOC225">13.2 Prerequisite Works</a> </h2> | |
| 122 | |
| 123 <p>There are some works which are required for using GNU <code>gettext</code> | |
| 124 in one of your package. These works have some kind of generality | |
| 125 that escape the point by point descriptions used in the remainder | |
| 126 of this chapter. So, we describe them here. | |
| 127 </p> | |
| 128 <ul> | |
| 129 <li> | |
| 130 Before attempting to use <code>gettextize</code> you should install some | |
| 131 other packages first. | |
| 132 Ensure that recent versions of GNU <code>m4</code>, GNU Autoconf and GNU | |
| 133 <code>gettext</code> are already installed at your site, and if not, proceed | |
| 134 to do this first. If you get to install these things, beware that | |
| 135 GNU <code>m4</code> must be fully installed before GNU Autoconf is even | |
| 136 <em>configured</em>. | |
| 137 | |
| 138 <p>To further ease the task of a package maintainer the <code>automake</code> | |
| 139 package was designed and implemented. GNU <code>gettext</code> now uses this | |
| 140 tool and the ‘<tt>Makefile</tt>’ in the ‘<tt>po/</tt>’ directory therefore | |
| 141 knows about all the goals necessary for using <code>automake</code>. | |
| 142 </p> | |
| 143 <p>Those four packages are only needed by you, as a maintainer; the | |
| 144 installers of your own package and end users do not really need any of | |
| 145 GNU <code>m4</code>, GNU Autoconf, GNU <code>gettext</code>, or GNU <code>automake</code> | |
| 146 for successfully installing and running your package, with messages | |
| 147 properly translated. But this is not completely true if you provide | |
| 148 internationalized shell scripts within your own package: GNU | |
| 149 <code>gettext</code> shall then be installed at the user site if the end users | |
| 150 want to see the translation of shell script messages. | |
| 151 </p> | |
| 152 </li><li> | |
| 153 Your package should use Autoconf and have a ‘<tt>configure.ac</tt>’ or | |
| 154 ‘<tt>configure.in</tt>’ file. | |
| 155 If it does not, you have to learn how. The Autoconf documentation | |
| 156 is quite well written, it is a good idea that you print it and get | |
| 157 familiar with it. | |
| 158 | |
| 159 </li><li> | |
| 160 Your C sources should have already been modified according to | |
| 161 instructions given earlier in this manual. See section <a href="gettext_4.html#SEC17">Preparing Program Sources</a>. | |
| 162 | |
| 163 </li><li> | |
| 164 Your ‘<tt>po/</tt>’ directory should receive all PO files submitted to you | |
| 165 by the translator teams, each having ‘<tt><var>ll</var>.po</tt>’ as a name. | |
| 166 This is not usually easy to get translation | |
| 167 work done before your package gets internationalized and available! | |
| 168 Since the cycle has to start somewhere, the easiest for the maintainer | |
| 169 is to start with absolutely no PO files, and wait until various | |
| 170 translator teams get interested in your package, and submit PO files. | |
| 171 | |
| 172 </li></ul> | |
| 173 | |
| 174 <p>It is worth adding here a few words about how the maintainer should | |
| 175 ideally behave with PO files submissions. As a maintainer, your role is | |
| 176 to authenticate the origin of the submission as being the representative | |
| 177 of the appropriate translating teams of the Translation Project (forward | |
| 178 the submission to ‘<tt>coordinator@translationproject.org</tt>’ in case of doubt), | |
| 179 to ensure that the PO file format is not severely broken and does not | |
| 180 prevent successful installation, and for the rest, to merely put these | |
| 181 PO files in ‘<tt>po/</tt>’ for distribution. | |
| 182 </p> | |
| 183 <p>As a maintainer, you do not have to take on your shoulders the | |
| 184 responsibility of checking if the translations are adequate or | |
| 185 complete, and should avoid diving into linguistic matters. Translation | |
| 186 teams drive themselves and are fully responsible of their linguistic | |
| 187 choices for the Translation Project. Keep in mind that translator teams are <em>not</em> | |
| 188 driven by maintainers. You can help by carefully redirecting all | |
| 189 communications and reports from users about linguistic matters to the | |
| 190 appropriate translation team, or explain users how to reach or join | |
| 191 their team. | |
| 192 </p> | |
| 193 <p>Maintainers should <em>never ever</em> apply PO file bug reports | |
| 194 themselves, short-cutting translation teams. If some translator has | |
| 195 difficulty to get some of her points through her team, it should not be | |
| 196 an option for her to directly negotiate translations with maintainers. | |
| 197 Teams ought to settle their problems themselves, if any. If you, as | |
| 198 a maintainer, ever think there is a real problem with a team, please | |
| 199 never try to <em>solve</em> a team's problem on your own. | |
| 200 </p> | |
| 201 | |
| 202 <a name="gettextize-Invocation"></a> | |
| 203 <a name="SEC233"></a> | |
| 204 <h2 class="section"> <a href="gettext_toc.html#TOC226">13.3 Invoking the <code>gettextize</code> Program</a> </h2> | |
| 205 | |
| 206 | |
| 207 <p>The <code>gettextize</code> program is an interactive tool that helps the | |
| 208 maintainer of a package internationalized through GNU <code>gettext</code>. | |
| 209 It is used for two purposes: | |
| 210 </p> | |
| 211 <ul> | |
| 212 <li> | |
| 213 As a wizard, when a package is modified to use GNU <code>gettext</code> for | |
| 214 the first time. | |
| 215 | |
| 216 </li><li> | |
| 217 As a migration tool, for upgrading the GNU <code>gettext</code> support in | |
| 218 a package from a previous to a newer version of GNU <code>gettext</code>. | |
| 219 </li></ul> | |
| 220 | |
| 221 <p>This program performs the following tasks: | |
| 222 </p> | |
| 223 <ul> | |
| 224 <li> | |
| 225 It copies into the package some files that are consistently and | |
| 226 identically needed in every package internationalized through | |
| 227 GNU <code>gettext</code>. | |
| 228 | |
| 229 </li><li> It performs as many of the tasks mentioned in the next section | |
| 230 <a href="#SEC234">Files You Must Create or Alter</a> as can be performed automatically. | |
| 231 | |
| 232 </li><li> It removes obsolete files and idioms used for previous GNU | |
| 233 <code>gettext</code> versions to the form recommended for the current GNU | |
| 234 <code>gettext</code> version. | |
| 235 | |
| 236 </li><li> It prints a summary of the tasks that ought to be done manually | |
| 237 and could not be done automatically by <code>gettextize</code>. | |
| 238 </li></ul> | |
| 239 | |
| 240 <p>It can be invoked as follows: | |
| 241 </p> | |
| 242 <a name="IDX1090"></a> | |
| 243 <a name="IDX1091"></a> | |
| 244 <table><tr><td> </td><td><pre class="example">gettextize [ <var>option</var>… ] [ <var>directory</var> ] | |
| 245 </pre></td></tr></table> | |
| 246 | |
| 247 <p>and accepts the following options: | |
| 248 </p> | |
| 249 <dl compact="compact"> | |
| 250 <dt> ‘<samp>-f</samp>’</dt> | |
| 251 <dt> ‘<samp>--force</samp>’</dt> | |
| 252 <dd><a name="IDX1092"></a> | |
| 253 <a name="IDX1093"></a> | |
| 254 <p>Force replacement of files which already exist. | |
| 255 </p> | |
| 256 </dd> | |
| 257 <dt> ‘<samp>--po-dir=<var>dir</var></samp>’</dt> | |
| 258 <dd><a name="IDX1094"></a> | |
| 259 <p>Specify a directory containing PO files. Such a directory contains the | |
| 260 translations into various languages of a particular POT file. This | |
| 261 option can be specified multiple times, once for each translation domain. | |
| 262 If it is not specified, the directory named ‘<tt>po/</tt>’ is updated. | |
| 263 </p> | |
| 264 </dd> | |
| 265 <dt> ‘<samp>--no-changelog</samp>’</dt> | |
| 266 <dd><a name="IDX1095"></a> | |
| 267 <p>Don't update or create ChangeLog files. By default, <code>gettextize</code> | |
| 268 logs all changes (file additions, modifications and removals) in a | |
| 269 file called ‘<samp>ChangeLog</samp>’ in each affected directory. | |
| 270 </p> | |
| 271 </dd> | |
| 272 <dt> ‘<samp>--symlink</samp>’</dt> | |
| 273 <dd><a name="IDX1096"></a> | |
| 274 <p>Make symbolic links instead of copying the needed files. This can be | |
| 275 useful to save a few kilobytes of disk space, but it requires extra | |
| 276 effort to create self-contained tarballs, it may disturb some mechanism | |
| 277 the maintainer applies to the sources, and it is likely to introduce | |
| 278 bugs when a newer version of <code>gettext</code> is installed on the system. | |
| 279 </p> | |
| 280 </dd> | |
| 281 <dt> ‘<samp>-n</samp>’</dt> | |
| 282 <dt> ‘<samp>--dry-run</samp>’</dt> | |
| 283 <dd><a name="IDX1097"></a> | |
| 284 <a name="IDX1098"></a> | |
| 285 <p>Print modifications but don't perform them. All actions that | |
| 286 <code>gettextize</code> would normally execute are inhibited and instead only | |
| 287 listed on standard output. | |
| 288 </p> | |
| 289 </dd> | |
| 290 <dt> ‘<samp>--help</samp>’</dt> | |
| 291 <dd><a name="IDX1099"></a> | |
| 292 <p>Display this help and exit. | |
| 293 </p> | |
| 294 </dd> | |
| 295 <dt> ‘<samp>--version</samp>’</dt> | |
| 296 <dd><a name="IDX1100"></a> | |
| 297 <p>Output version information and exit. | |
| 298 </p> | |
| 299 </dd> | |
| 300 </dl> | |
| 301 | |
| 302 <p>If <var>directory</var> is given, this is the top level directory of a | |
| 303 package to prepare for using GNU <code>gettext</code>. If not given, it | |
| 304 is assumed that the current directory is the top level directory of | |
| 305 such a package. | |
| 306 </p> | |
| 307 <p>The program <code>gettextize</code> provides the following files. However, | |
| 308 no existing file will be replaced unless the option <code>--force</code> | |
| 309 (<code>-f</code>) is specified. | |
| 310 </p> | |
| 311 <ol> | |
| 312 <li> | |
| 313 The ‘<tt>ABOUT-NLS</tt>’ file is copied in the main directory of your package, | |
| 314 the one being at the top level. This file contains a reference to the | |
| 315 GNU gettext documentation. It also avoids an error from Automake in | |
| 316 packages that use the Automake option ‘<samp>gnu</samp>’ or ‘<samp>gnits</samp>’: | |
| 317 “error: required file './ABOUT-NLS' not found”. | |
| 318 | |
| 319 </li><li> | |
| 320 A ‘<tt>po/</tt>’ directory is created for eventually holding | |
| 321 all translation files, but initially only containing the file | |
| 322 ‘<tt>po/Makefile.in.in</tt>’ from the GNU <code>gettext</code> distribution | |
| 323 (beware the double ‘<samp>.in</samp>’ in the file name) and a few auxiliary | |
| 324 files. If the ‘<tt>po/</tt>’ directory already exists, it will be preserved | |
| 325 along with the files it contains, and only ‘<tt>Makefile.in.in</tt>’ and | |
| 326 the auxiliary files will be overwritten. | |
| 327 | |
| 328 <p>If ‘<samp>--po-dir</samp>’ has been specified, this holds for every directory | |
| 329 specified through ‘<samp>--po-dir</samp>’, instead of ‘<tt>po/</tt>’. | |
| 330 </p> | |
| 331 </li><li> | |
| 332 The file ‘<tt>config.rpath</tt>’ is copied into the directory containing | |
| 333 configuration support files. It is needed by the <code>AM_GNU_GETTEXT</code> | |
| 334 autoconf macro. | |
| 335 | |
| 336 </li><li> | |
| 337 Only if the project is using GNU <code>automake</code>: | |
| 338 A set of <code>autoconf</code> macro files is copied into the package's | |
| 339 <code>autoconf</code> macro repository, usually in a directory called ‘<tt>m4/</tt>’. | |
| 340 </li></ol> | |
| 341 | |
| 342 <p>If your site support symbolic links, <code>gettextize</code> will not | |
| 343 actually copy the files into your package, but establish symbolic | |
| 344 links instead. This avoids duplicating the disk space needed in | |
| 345 all packages. Merely using the ‘<samp>-h</samp>’ option while creating the | |
| 346 <code>tar</code> archive of your distribution will resolve each link by an | |
| 347 actual copy in the distribution archive. So, to insist, you really | |
| 348 should use ‘<samp>-h</samp>’ option with <code>tar</code> within your <code>dist</code> | |
| 349 goal of your main ‘<tt>Makefile.in</tt>’. | |
| 350 </p> | |
| 351 <p>Furthermore, <code>gettextize</code> will update all ‘<tt>Makefile.am</tt>’ files | |
| 352 in each affected directory, as well as the top level ‘<tt>configure.ac</tt>’ | |
| 353 or ‘<tt>configure.in</tt>’ file. | |
| 354 </p> | |
| 355 <p>It is interesting to understand that most new files for supporting | |
| 356 GNU <code>gettext</code> facilities in one package go in ‘<tt>po/</tt>’ and | |
| 357 ‘<tt>m4/</tt>’ subdirectories. Still, these directories will mostly | |
| 358 contain package dependent files. | |
| 359 </p> | |
| 360 <p>The <code>gettextize</code> program makes backup files for all files it | |
| 361 replaces or changes, and also write ChangeLog entries about these | |
| 362 changes. This way, the careful maintainer can check after running | |
| 363 <code>gettextize</code> whether its changes are acceptable to him, and | |
| 364 possibly adjust them. An exception to this rule is the ‘<tt>intl/</tt>’ | |
| 365 directory, which is removed as a whole if it still existed. | |
| 366 </p> | |
| 367 <p>It is important to understand that <code>gettextize</code> can not do the | |
| 368 entire job of adapting a package for using GNU <code>gettext</code>. The | |
| 369 amount of remaining work depends on whether the package uses GNU | |
| 370 <code>automake</code> or not. But in any case, the maintainer should still | |
| 371 read the section <a href="#SEC234">Files You Must Create or Alter</a> after invoking <code>gettextize</code>. | |
| 372 </p> | |
| 373 <p>In particular, if after using ‘<samp>gettexize</samp>’, you get an error | |
| 374 ‘<samp>AC_COMPILE_IFELSE was called before AC_GNU_SOURCE</samp>’ or | |
| 375 ‘<samp>AC_RUN_IFELSE was called before AC_GNU_SOURCE</samp>’, you can fix it | |
| 376 by modifying ‘<tt>configure.ac</tt>’, as described in <a href="#SEC239">‘<tt>configure.ac</tt>’ at top level</a>. | |
| 377 </p> | |
| 378 <p>It is also important to understand that <code>gettextize</code> is not part | |
| 379 of the GNU build system, in the sense that it should not be invoked | |
| 380 automatically, and not be invoked by someone who doesn't assume the | |
| 381 responsibilities of a package maintainer. For the latter purpose, a | |
| 382 separate tool is provided, see <a href="#SEC258">Invoking the <code>autopoint</code> Program</a>. | |
| 383 </p> | |
| 384 | |
| 385 <a name="Adjusting-Files"></a> | |
| 386 <a name="SEC234"></a> | |
| 387 <h2 class="section"> <a href="gettext_toc.html#TOC227">13.4 Files You Must Create or Alter</a> </h2> | |
| 388 | |
| 389 <p>Besides files which are automatically added through <code>gettextize</code>, | |
| 390 there are many files needing revision for properly interacting with | |
| 391 GNU <code>gettext</code>. If you are closely following GNU standards for | |
| 392 Makefile engineering and auto-configuration, the adaptations should | |
| 393 be easier to achieve. Here is a point by point description of the | |
| 394 changes needed in each. | |
| 395 </p> | |
| 396 <p>So, here comes a list of files, each one followed by a description of | |
| 397 all alterations it needs. Many examples are taken out from the GNU | |
| 398 <code>gettext</code> 0.22.5 distribution itself, or from the GNU | |
| 399 <code>hello</code> distribution (<a href="https://www.gnu.org/software/hello">https://www.gnu.org/software/hello</a>). | |
| 400 You may indeed refer to the source code of the GNU <code>gettext</code> and | |
| 401 GNU <code>hello</code> packages, as they are intended to be good examples for | |
| 402 using GNU gettext functionality. | |
| 403 </p> | |
| 404 | |
| 405 | |
| 406 <a name="po_002fPOTFILES_002ein"></a> | |
| 407 <a name="SEC235"></a> | |
| 408 <h3 class="subsection"> <a href="gettext_toc.html#TOC228">13.4.1 ‘<tt>POTFILES.in</tt>’ in ‘<tt>po/</tt>’</a> </h3> | |
| 409 | |
| 410 <p>The ‘<tt>po/</tt>’ directory should receive a file named | |
| 411 ‘<tt>POTFILES.in</tt>’. This file tells which files, among all program | |
| 412 sources, have marked strings needing translation. Here is an example | |
| 413 of such a file: | |
| 414 </p> | |
| 415 <table><tr><td> </td><td><pre class="example"># List of source files containing translatable strings. | |
| 416 # Copyright (C) 1995 Free Software Foundation, Inc. | |
| 417 | |
| 418 # Common library files | |
| 419 lib/error.c | |
| 420 lib/getopt.c | |
| 421 lib/xmalloc.c | |
| 422 | |
| 423 # Package source files | |
| 424 src/gettext.c | |
| 425 src/msgfmt.c | |
| 426 src/xgettext.c | |
| 427 </pre></td></tr></table> | |
| 428 | |
| 429 <p>Hash-marked comments and white lines are ignored. All other lines | |
| 430 list those source files containing strings marked for translation | |
| 431 (see section <a href="gettext_4.html#SEC28">How Marks Appear in Sources</a>), in a notation relative to the top level | |
| 432 of your whole distribution, rather than the location of the | |
| 433 ‘<tt>POTFILES.in</tt>’ file itself. | |
| 434 </p> | |
| 435 <p>When a C file is automatically generated by a tool, like <code>flex</code> or | |
| 436 <code>bison</code>, that doesn't introduce translatable strings by itself, | |
| 437 it is recommended to list in ‘<tt>po/POTFILES.in</tt>’ the real source file | |
| 438 (ending in ‘<tt>.l</tt>’ in the case of <code>flex</code>, or in ‘<tt>.y</tt>’ in the | |
| 439 case of <code>bison</code>), not the generated C file. | |
| 440 </p> | |
| 441 | |
| 442 <a name="po_002fLINGUAS"></a> | |
| 443 <a name="SEC236"></a> | |
| 444 <h3 class="subsection"> <a href="gettext_toc.html#TOC229">13.4.2 ‘<tt>LINGUAS</tt>’ in ‘<tt>po/</tt>’</a> </h3> | |
| 445 | |
| 446 <p>The ‘<tt>po/</tt>’ directory should also receive a file named | |
| 447 ‘<tt>LINGUAS</tt>’. This file contains the list of available translations. | |
| 448 It is a whitespace separated list. Hash-marked comments and white lines | |
| 449 are ignored. Here is an example file: | |
| 450 </p> | |
| 451 <table><tr><td> </td><td><pre class="example"># Set of available languages. | |
| 452 de fr | |
| 453 </pre></td></tr></table> | |
| 454 | |
| 455 <p>This example means that German and French PO files are available, so | |
| 456 that these languages are currently supported by your package. If you | |
| 457 want to further restrict, at installation time, the set of installed | |
| 458 languages, this should not be done by modifying the ‘<tt>LINGUAS</tt>’ file, | |
| 459 but rather by using the <code>LINGUAS</code> environment variable | |
| 460 (see section <a href="gettext_14.html#SEC262">The Installer's and Distributor's View</a>). | |
| 461 </p> | |
| 462 <p>It is recommended that you add the "languages" ‘<samp>en@quot</samp>’ and | |
| 463 ‘<samp>en@boldquot</samp>’ to the <code>LINGUAS</code> file. <code>en@quot</code> is a | |
| 464 variant of English message catalogs (<code>en</code>) which uses real quotation | |
| 465 marks instead of the ugly looking asymmetric ASCII substitutes ‘<samp>`</samp>’ | |
| 466 and ‘<samp>'</samp>’. <code>en@boldquot</code> is a variant of <code>en@quot</code> that | |
| 467 additionally outputs quoted pieces of text in a bold font, when used in | |
| 468 a terminal emulator which supports the VT100 escape sequences (such as | |
| 469 <code>xterm</code> or the Linux console, but not Emacs in <kbd>M-x shell</kbd> mode). | |
| 470 </p> | |
| 471 <p>These extra message catalogs ‘<samp>en@quot</samp>’ and ‘<samp>en@boldquot</samp>’ | |
| 472 are constructed automatically, not by translators; to support them, you | |
| 473 need the files ‘<tt>Rules-quot</tt>’, ‘<tt>quot.sed</tt>’, ‘<tt>boldquot.sed</tt>’, | |
| 474 ‘<tt>en@quot.header</tt>’, ‘<tt>en@boldquot.header</tt>’, ‘<tt>insert-header.sin</tt>’ | |
| 475 in the ‘<tt>po/</tt>’ directory. You can copy them from GNU gettext's ‘<tt>po/</tt>’ | |
| 476 directory; they are also installed by running <code>gettextize</code>. | |
| 477 </p> | |
| 478 | |
| 479 <a name="po_002fMakevars"></a> | |
| 480 <a name="SEC237"></a> | |
| 481 <h3 class="subsection"> <a href="gettext_toc.html#TOC230">13.4.3 ‘<tt>Makevars</tt>’ in ‘<tt>po/</tt>’</a> </h3> | |
| 482 | |
| 483 <p>The ‘<tt>po/</tt>’ directory also has a file named ‘<tt>Makevars</tt>’. It | |
| 484 contains variables that are specific to your project. ‘<tt>po/Makevars</tt>’ | |
| 485 gets inserted into the ‘<tt>po/Makefile</tt>’ when the latter is created. | |
| 486 The variables thus take effect when the POT file is created or updated, | |
| 487 and when the message catalogs get installed. | |
| 488 </p> | |
| 489 <p>The first three variables can be left unmodified if your package has a | |
| 490 single message domain and, accordingly, a single ‘<tt>po/</tt>’ directory. | |
| 491 Only packages which have multiple ‘<tt>po/</tt>’ directories at different | |
| 492 locations need to adjust the three first variables defined in | |
| 493 ‘<tt>Makevars</tt>’. | |
| 494 </p> | |
| 495 <p>As an alternative to the <code>XGETTEXT_OPTIONS</code> variable, it is also | |
| 496 possible to specify <code>xgettext</code> options through the | |
| 497 <code>AM_XGETTEXT_OPTION</code> autoconf macro. See <a href="#SEC252">AM_XGETTEXT_OPTION in ‘<tt>po.m4</tt>’</a>. | |
| 498 </p> | |
| 499 | |
| 500 <a name="po_002fRules_002d_002a"></a> | |
| 501 <a name="SEC238"></a> | |
| 502 <h3 class="subsection"> <a href="gettext_toc.html#TOC231">13.4.4 Extending ‘<tt>Makefile</tt>’ in ‘<tt>po/</tt>’</a> </h3> | |
| 503 | |
| 504 <p>All files called ‘<tt>Rules-*</tt>’ in the ‘<tt>po/</tt>’ directory get appended to | |
| 505 the ‘<tt>po/Makefile</tt>’ when it is created. They present an opportunity to | |
| 506 add rules for special PO files to the Makefile, without needing to mess | |
| 507 with ‘<tt>po/Makefile.in.in</tt>’. | |
| 508 </p> | |
| 509 <a name="IDX1101"></a> | |
| 510 <a name="IDX1102"></a> | |
| 511 <p>GNU gettext comes with a ‘<tt>Rules-quot</tt>’ file, containing rules for | |
| 512 building catalogs ‘<tt>en@quot.po</tt>’ and ‘<tt>en@boldquot.po</tt>’. The | |
| 513 effect of ‘<tt>en@quot.po</tt>’ is that people who set their <code>LANGUAGE</code> | |
| 514 environment variable to ‘<samp>en@quot</samp>’ will get messages with proper | |
| 515 looking symmetric Unicode quotation marks instead of abusing the ASCII | |
| 516 grave accent and the ASCII apostrophe for indicating quotations. To | |
| 517 enable this catalog, simply add <code>en@quot</code> to the ‘<tt>po/LINGUAS</tt>’ | |
| 518 file. The effect of ‘<tt>en@boldquot.po</tt>’ is that people who set | |
| 519 <code>LANGUAGE</code> to ‘<samp>en@boldquot</samp>’ will get not only proper quotation | |
| 520 marks, but also the quoted text will be shown in a bold font on terminals | |
| 521 and consoles. This catalog is useful only for command-line programs, not | |
| 522 GUI programs. To enable it, similarly add <code>en@boldquot</code> to the | |
| 523 ‘<tt>po/LINGUAS</tt>’ file. | |
| 524 </p> | |
| 525 <p>Similarly, you can create rules for building message catalogs for the | |
| 526 ‘<tt>sr@latin</tt>’ locale – Serbian written with the Latin alphabet – | |
| 527 from those for the ‘<tt>sr</tt>’ locale – Serbian written with Cyrillic | |
| 528 letters. See <a href="gettext_9.html#SEC110">Invoking the <code>msgfilter</code> Program</a>. | |
| 529 </p> | |
| 530 | |
| 531 <a name="configure_002eac"></a> | |
| 532 <a name="SEC239"></a> | |
| 533 <h3 class="subsection"> <a href="gettext_toc.html#TOC232">13.4.5 ‘<tt>configure.ac</tt>’ at top level</a> </h3> | |
| 534 | |
| 535 <p>‘<tt>configure.ac</tt>’ or ‘<tt>configure.in</tt>’ - this is the source from which | |
| 536 <code>autoconf</code> generates the ‘<tt>configure</tt>’ script. | |
| 537 </p> | |
| 538 <ol> | |
| 539 <li> Declare the package and version. | |
| 540 <a name="IDX1103"></a> | |
| 541 | |
| 542 <p>This is done by a set of lines like these: | |
| 543 </p> | |
| 544 <table><tr><td> </td><td><pre class="example">PACKAGE=gettext | |
| 545 VERSION=0.22.5 | |
| 546 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") | |
| 547 AC_DEFINE_UNQUOTED(VERSION, "$VERSION") | |
| 548 AC_SUBST(PACKAGE) | |
| 549 AC_SUBST(VERSION) | |
| 550 </pre></td></tr></table> | |
| 551 | |
| 552 <p>or, if you are using GNU <code>automake</code>, by a line like this: | |
| 553 </p> | |
| 554 <table><tr><td> </td><td><pre class="example">AM_INIT_AUTOMAKE(gettext, 0.22.5) | |
| 555 </pre></td></tr></table> | |
| 556 | |
| 557 <p>Of course, you replace ‘<samp>gettext</samp>’ with the name of your package, | |
| 558 and ‘<samp>0.22.5</samp>’ by its version numbers, exactly as they | |
| 559 should appear in the packaged <code>tar</code> file name of your distribution | |
| 560 (‘<tt>gettext-0.22.5.tar.gz</tt>’, here). | |
| 561 </p> | |
| 562 </li><li> Check for internationalization support. | |
| 563 | |
| 564 <p>Here is the main <code>m4</code> macro for triggering internationalization | |
| 565 support. Just add this line to ‘<tt>configure.ac</tt>’: | |
| 566 </p> | |
| 567 <table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT([external]) | |
| 568 </pre></td></tr></table> | |
| 569 | |
| 570 <p>This call is purposely simple, even if it generates a lot of configure | |
| 571 time checking and actions. | |
| 572 </p> | |
| 573 </li><li> Have output files created. | |
| 574 | |
| 575 <p>The <code>AC_OUTPUT</code> directive, at the end of your ‘<tt>configure.ac</tt>’ | |
| 576 file, needs to be modified in two ways: | |
| 577 </p> | |
| 578 <table><tr><td> </td><td><pre class="example">AC_OUTPUT([<var>existing configuration files</var> po/Makefile.in], | |
| 579 [<var>existing additional actions</var>]) | |
| 580 </pre></td></tr></table> | |
| 581 | |
| 582 <p>The modification to the first argument to <code>AC_OUTPUT</code> asks | |
| 583 for substitution in the ‘<tt>po/</tt>’ directory. | |
| 584 Note the ‘<samp>.in</samp>’ suffix used for ‘<tt>po/</tt>’ only. This is because | |
| 585 the distributed file is really ‘<tt>po/Makefile.in.in</tt>’. | |
| 586 </p> | |
| 587 </li></ol> | |
| 588 | |
| 589 | |
| 590 <a name="config_002eguess"></a> | |
| 591 <a name="SEC240"></a> | |
| 592 <h3 class="subsection"> <a href="gettext_toc.html#TOC233">13.4.6 ‘<tt>config.guess</tt>’, ‘<tt>config.sub</tt>’ at top level</a> </h3> | |
| 593 | |
| 594 <p>You need to add the GNU ‘<tt>config.guess</tt>’ and ‘<tt>config.sub</tt>’ files | |
| 595 to your distribution. They are needed because the <code>AM_ICONV</code> macro | |
| 596 contains knowledge about specific platforms and therefore needs to | |
| 597 identify the platform. | |
| 598 </p> | |
| 599 <p>You can obtain the newest version of ‘<tt>config.guess</tt>’ and | |
| 600 ‘<tt>config.sub</tt>’ from the ‘<samp>config</samp>’ project at | |
| 601 ‘<tt>https://savannah.gnu.org/</tt>’. The commands to fetch them are | |
| 602 </p><table><tr><td> </td><td><pre class="smallexample">$ wget -O config.guess 'https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD' | |
| 603 $ wget -O config.sub 'https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD' | |
| 604 </pre></td></tr></table> | |
| 605 <p>Less recent versions are also contained in the GNU <code>automake</code> and | |
| 606 GNU <code>libtool</code> packages. | |
| 607 </p> | |
| 608 <p>Normally, ‘<tt>config.guess</tt>’ and ‘<tt>config.sub</tt>’ are put at the | |
| 609 top level of a distribution. But it is also possible to put them in a | |
| 610 subdirectory, altogether with other configuration support files like | |
| 611 ‘<tt>install-sh</tt>’, ‘<tt>ltconfig</tt>’, ‘<tt>ltmain.sh</tt>’ or ‘<tt>missing</tt>’. | |
| 612 All you need to do, other than moving the files, is to add the following line | |
| 613 to your ‘<tt>configure.ac</tt>’. | |
| 614 </p> | |
| 615 <table><tr><td> </td><td><pre class="example">AC_CONFIG_AUX_DIR([<var>subdir</var>]) | |
| 616 </pre></td></tr></table> | |
| 617 | |
| 618 | |
| 619 <a name="mkinstalldirs"></a> | |
| 620 <a name="SEC241"></a> | |
| 621 <h3 class="subsection"> <a href="gettext_toc.html#TOC234">13.4.7 ‘<tt>mkinstalldirs</tt>’ at top level</a> </h3> | |
| 622 | |
| 623 <p>With earlier versions of GNU gettext, you needed to add the GNU | |
| 624 ‘<tt>mkinstalldirs</tt>’ script to your distribution. This is not needed any | |
| 625 more. You can remove it. | |
| 626 </p> | |
| 627 | |
| 628 <a name="aclocal"></a> | |
| 629 <a name="SEC242"></a> | |
| 630 <h3 class="subsection"> <a href="gettext_toc.html#TOC235">13.4.8 ‘<tt>aclocal.m4</tt>’ at top level</a> </h3> | |
| 631 | |
| 632 <p>If you do not have an ‘<tt>aclocal.m4</tt>’ file in your distribution, | |
| 633 the simplest is to concatenate the files ‘<tt>build-to-host.m4</tt>’, | |
| 634 ‘<tt>gettext.m4</tt>’, ‘<tt>host-cpu-c-abi.m4</tt>’, ‘<tt>intlmacosx.m4</tt>’, | |
| 635 ‘<tt>iconv.m4</tt>’, ‘<tt>lib-ld.m4</tt>’, ‘<tt>lib-link.m4</tt>’, ‘<tt>lib-prefix.m4</tt>’, | |
| 636 ‘<tt>nls.m4</tt>’, ‘<tt>po.m4</tt>’, ‘<tt>progtest.m4</tt>’ from GNU <code>gettext</code>'s | |
| 637 ‘<tt>m4/</tt>’ directory into a single file. | |
| 638 </p> | |
| 639 <p>If you already have an ‘<tt>aclocal.m4</tt>’ file, then you will have | |
| 640 to merge the said macro files into your ‘<tt>aclocal.m4</tt>’. Note that if | |
| 641 you are upgrading from a previous release of GNU <code>gettext</code>, you | |
| 642 should most probably <em>replace</em> the macros (<code>AM_GNU_GETTEXT</code>, | |
| 643 etc.), as they usually | |
| 644 change a little from one release of GNU <code>gettext</code> to the next. | |
| 645 Their contents may vary as we get more experience with strange systems | |
| 646 out there. | |
| 647 </p> | |
| 648 <p>You should be using GNU <code>automake</code> 1.9 or newer. With it, you need | |
| 649 to copy the files ‘<tt>build-to-host.m4</tt>’, ‘<tt>gettext.m4</tt>’, | |
| 650 ‘<tt>host-cpu-c-abi.m4</tt>’, ‘<tt>intlmacosx.m4</tt>’, ‘<tt>iconv.m4</tt>’, | |
| 651 ‘<tt>lib-ld.m4</tt>’, ‘<tt>lib-link.m4</tt>’, ‘<tt>lib-prefix.m4</tt>’, ‘<tt>nls.m4</tt>’, | |
| 652 ‘<tt>po.m4</tt>’, ‘<tt>progtest.m4</tt>’ from GNU <code>gettext</code>'s ‘<tt>m4/</tt>’ | |
| 653 directory to a subdirectory named ‘<tt>m4/</tt>’ and add the line | |
| 654 </p> | |
| 655 <table><tr><td> </td><td><pre class="example">ACLOCAL_AMFLAGS = -I m4 | |
| 656 </pre></td></tr></table> | |
| 657 | |
| 658 <p>to your top level ‘<tt>Makefile.am</tt>’. | |
| 659 </p> | |
| 660 <p>If you are using GNU <code>automake</code> 1.10 or newer, it is even easier: | |
| 661 Add the line | |
| 662 </p> | |
| 663 <table><tr><td> </td><td><pre class="example">ACLOCAL_AMFLAGS = --install -I m4 | |
| 664 </pre></td></tr></table> | |
| 665 | |
| 666 <p>to your top level ‘<tt>Makefile.am</tt>’, and run ‘<samp>aclocal --install -I m4</samp>’. | |
| 667 This will copy the needed files to the ‘<tt>m4/</tt>’ subdirectory automatically, | |
| 668 before updating ‘<tt>aclocal.m4</tt>’. | |
| 669 </p> | |
| 670 <p>These macros check for the internationalization support functions | |
| 671 and related informations. Hopefully, once stabilized, these macros | |
| 672 might be integrated in the standard Autoconf set, because this | |
| 673 piece of <code>m4</code> code will be the same for all projects using GNU | |
| 674 <code>gettext</code>. | |
| 675 </p> | |
| 676 | |
| 677 <a name="config_002eh_002ein"></a> | |
| 678 <a name="SEC243"></a> | |
| 679 <h3 class="subsection"> <a href="gettext_toc.html#TOC236">13.4.9 ‘<tt>config.h.in</tt>’ at top level</a> </h3> | |
| 680 | |
| 681 <p>The include file template that holds the C macros to be defined by | |
| 682 <code>configure</code> is usually called ‘<tt>config.h.in</tt>’ and may be | |
| 683 maintained either manually or automatically. | |
| 684 </p> | |
| 685 <p>If it is maintained automatically, by use of the ‘<samp>autoheader</samp>’ | |
| 686 program, you need to do nothing about it. This is the case in particular | |
| 687 if you are using GNU <code>automake</code>. | |
| 688 </p> | |
| 689 <p>If it is maintained manually, you can get away by adding the | |
| 690 following lines to ‘<tt>config.h.in</tt>’: | |
| 691 </p> | |
| 692 <table><tr><td> </td><td><pre class="example">/* Define to 1 if translation of program messages to the user's | |
| 693 native language is requested. */ | |
| 694 #undef ENABLE_NLS | |
| 695 </pre></td></tr></table> | |
| 696 | |
| 697 | |
| 698 <a name="Makefile"></a> | |
| 699 <a name="SEC244"></a> | |
| 700 <h3 class="subsection"> <a href="gettext_toc.html#TOC237">13.4.10 ‘<tt>Makefile.in</tt>’ at top level</a> </h3> | |
| 701 | |
| 702 <p>Here are a few modifications you need to make to your main, top-level | |
| 703 ‘<tt>Makefile.in</tt>’ file. | |
| 704 </p> | |
| 705 <ol> | |
| 706 <li> | |
| 707 Add the following lines near the beginning of your ‘<tt>Makefile.in</tt>’, | |
| 708 so the ‘<samp>dist:</samp>’ goal will work properly (as explained further down): | |
| 709 | |
| 710 <table><tr><td> </td><td><pre class="example">PACKAGE = @PACKAGE@ | |
| 711 VERSION = @VERSION@ | |
| 712 </pre></td></tr></table> | |
| 713 | |
| 714 </li><li> | |
| 715 Wherever you process subdirectories in your ‘<tt>Makefile.in</tt>’, be sure | |
| 716 you also process the subdirectory ‘<samp>po</samp>’. Special | |
| 717 rules in the ‘<tt>Makefiles</tt>’ take care for the case where no | |
| 718 internationalization is wanted. | |
| 719 | |
| 720 <p>If you are using Makefiles, either generated by automake, or hand-written | |
| 721 so they carefully follow the GNU coding standards, the effected goals for | |
| 722 which the new subdirectories must be handled include ‘<samp>installdirs</samp>’, | |
| 723 ‘<samp>install</samp>’, ‘<samp>uninstall</samp>’, ‘<samp>clean</samp>’, ‘<samp>distclean</samp>’. | |
| 724 </p> | |
| 725 <p>Here is an example of a canonical order of processing. In this | |
| 726 example, we also define <code>SUBDIRS</code> in <code>Makefile.in</code> for it | |
| 727 to be further used in the ‘<samp>dist:</samp>’ goal. | |
| 728 </p> | |
| 729 <table><tr><td> </td><td><pre class="example">SUBDIRS = doc lib src po | |
| 730 </pre></td></tr></table> | |
| 731 | |
| 732 </li><li> | |
| 733 A delicate point is the ‘<samp>dist:</samp>’ goal, as ‘<tt>po/Makefile</tt>’ will later | |
| 734 assume that the proper directory has been set up from the main ‘<tt>Makefile</tt>’. | |
| 735 Here is an example at what the ‘<samp>dist:</samp>’ goal might look like: | |
| 736 | |
| 737 <table><tr><td> </td><td><pre class="example">distdir = $(PACKAGE)-$(VERSION) | |
| 738 dist: Makefile | |
| 739 rm -fr $(distdir) | |
| 740 mkdir $(distdir) | |
| 741 chmod 777 $(distdir) | |
| 742 for file in $(DISTFILES); do \ | |
| 743 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ | |
| 744 done | |
| 745 for subdir in $(SUBDIRS); do \ | |
| 746 mkdir $(distdir)/$$subdir || exit 1; \ | |
| 747 chmod 777 $(distdir)/$$subdir; \ | |
| 748 (cd $$subdir && $(MAKE) $@) || exit 1; \ | |
| 749 done | |
| 750 tar chozf $(distdir).tar.gz $(distdir) | |
| 751 rm -fr $(distdir) | |
| 752 </pre></td></tr></table> | |
| 753 | |
| 754 </li></ol> | |
| 755 | |
| 756 <p>Note that if you are using GNU <code>automake</code>, ‘<tt>Makefile.in</tt>’ is | |
| 757 automatically generated from ‘<tt>Makefile.am</tt>’, and all needed changes | |
| 758 to ‘<tt>Makefile.am</tt>’ are already made by running ‘<samp>gettextize</samp>’. | |
| 759 </p> | |
| 760 | |
| 761 <a name="src_002fMakefile"></a> | |
| 762 <a name="SEC245"></a> | |
| 763 <h3 class="subsection"> <a href="gettext_toc.html#TOC238">13.4.11 ‘<tt>Makefile.in</tt>’ in ‘<tt>src/</tt>’</a> </h3> | |
| 764 | |
| 765 <p>Some of the modifications made in the main ‘<tt>Makefile.in</tt>’ will | |
| 766 also be needed in the ‘<tt>Makefile.in</tt>’ from your package sources, | |
| 767 which we assume here to be in the ‘<tt>src/</tt>’ subdirectory. Here are | |
| 768 all the modifications needed in ‘<tt>src/Makefile.in</tt>’: | |
| 769 </p> | |
| 770 <ol> | |
| 771 <li> | |
| 772 In view of the ‘<samp>dist:</samp>’ goal, you should have these lines near the | |
| 773 beginning of ‘<tt>src/Makefile.in</tt>’: | |
| 774 | |
| 775 <table><tr><td> </td><td><pre class="example">PACKAGE = @PACKAGE@ | |
| 776 VERSION = @VERSION@ | |
| 777 </pre></td></tr></table> | |
| 778 | |
| 779 </li><li> | |
| 780 If not done already, you should guarantee that <code>top_srcdir</code> | |
| 781 gets defined. This will serve for <code>cpp</code> include files. Just add | |
| 782 the line: | |
| 783 | |
| 784 <table><tr><td> </td><td><pre class="example">top_srcdir = @top_srcdir@ | |
| 785 </pre></td></tr></table> | |
| 786 | |
| 787 </li><li> | |
| 788 You might also want to define <code>subdir</code> as ‘<samp>src</samp>’, later | |
| 789 allowing for almost uniform ‘<samp>dist:</samp>’ goals in all your | |
| 790 ‘<tt>Makefile.in</tt>’. At list, the ‘<samp>dist:</samp>’ goal below assume that | |
| 791 you used: | |
| 792 | |
| 793 <table><tr><td> </td><td><pre class="example">subdir = src | |
| 794 </pre></td></tr></table> | |
| 795 | |
| 796 </li><li> | |
| 797 The <code>main</code> function of your program will normally call | |
| 798 <code>bindtextdomain</code> (see see section <a href="gettext_4.html#SEC19">Triggering <code>gettext</code> Operations</a>), like this: | |
| 799 | |
| 800 <table><tr><td> </td><td><pre class="example">bindtextdomain (<var>PACKAGE</var>, LOCALEDIR); | |
| 801 textdomain (<var>PACKAGE</var>); | |
| 802 </pre></td></tr></table> | |
| 803 | |
| 804 <p>On native Windows platforms, the <code>main</code> function may call | |
| 805 <code>wbindtextdomain</code> instead of <code>bindtextdomain</code>. | |
| 806 </p> | |
| 807 <p>To make LOCALEDIR known to the program, add the following lines to | |
| 808 ‘<tt>Makefile.in</tt>’: | |
| 809 </p> | |
| 810 <table><tr><td> </td><td><pre class="example">datadir = @datadir@ | |
| 811 datarootdir= @datarootdir@ | |
| 812 localedir = @localedir@ | |
| 813 DEFS = -DLOCALEDIR=$(localedir_c_make) @DEFS@ | |
| 814 </pre></td></tr></table> | |
| 815 | |
| 816 <p><code>$(localedir_c_make)</code> expands to the value of <code>localedir</code>, in | |
| 817 C syntax, escaped for use in a <code>Makefile</code>. | |
| 818 Note that <code>@datadir@</code> defaults to ‘<samp>$(prefix)/share</samp>’, and | |
| 819 <code>$(localedir)</code> defaults to ‘<samp>$(prefix)/share/locale</samp>’. | |
| 820 </p> | |
| 821 </li><li> | |
| 822 You should ensure that the final linking will use <code>@LIBINTL@</code> or | |
| 823 <code>@LTLIBINTL@</code> as a library. <code>@LIBINTL@</code> is for use without | |
| 824 <code>libtool</code>, <code>@LTLIBINTL@</code> is for use with <code>libtool</code>. An | |
| 825 easy way to achieve this is to manage that it gets into <code>LIBS</code>, like | |
| 826 this: | |
| 827 | |
| 828 <table><tr><td> </td><td><pre class="example">LIBS = @LIBINTL@ @LIBS@ | |
| 829 </pre></td></tr></table> | |
| 830 | |
| 831 <p>In most packages internationalized with GNU <code>gettext</code>, one will | |
| 832 find a directory ‘<tt>lib/</tt>’ in which a library containing some helper | |
| 833 functions will be build. (You need at least the few functions which the | |
| 834 GNU <code>gettext</code> Library itself needs.) However some of the functions | |
| 835 in the ‘<tt>lib/</tt>’ also give messages to the user which of course should be | |
| 836 translated, too. Taking care of this, the support library (say | |
| 837 ‘<tt>libsupport.a</tt>’) should be placed before <code>@LIBINTL@</code> and | |
| 838 <code>@LIBS@</code> in the above example. So one has to write this: | |
| 839 </p> | |
| 840 <table><tr><td> </td><td><pre class="example">LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ | |
| 841 </pre></td></tr></table> | |
| 842 | |
| 843 </li><li> | |
| 844 Your ‘<samp>dist:</samp>’ goal has to conform with others. Here is a | |
| 845 reasonable definition for it: | |
| 846 | |
| 847 <table><tr><td> </td><td><pre class="example">distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) | |
| 848 dist: Makefile $(DISTFILES) | |
| 849 for file in $(DISTFILES); do \ | |
| 850 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \ | |
| 851 done | |
| 852 </pre></td></tr></table> | |
| 853 | |
| 854 </li></ol> | |
| 855 | |
| 856 <p>Note that if you are using GNU <code>automake</code>, ‘<tt>Makefile.in</tt>’ is | |
| 857 automatically generated from ‘<tt>Makefile.am</tt>’, and the first three | |
| 858 changes and the last change are not necessary. The remaining needed | |
| 859 ‘<tt>Makefile.am</tt>’ modifications are the following: | |
| 860 </p> | |
| 861 <ol> | |
| 862 <li> | |
| 863 To make LOCALEDIR known to the program, add the following to | |
| 864 ‘<tt>Makefile.am</tt>’: | |
| 865 | |
| 866 <table><tr><td> </td><td><pre class="example"><module>_CPPFLAGS = -DLOCALEDIR=$(localedir_c_make) | |
| 867 </pre></td></tr></table> | |
| 868 | |
| 869 <p>for each specific module or compilation unit, or | |
| 870 </p> | |
| 871 <table><tr><td> </td><td><pre class="example">AM_CPPFLAGS = -DLOCALEDIR=$(localedir_c_make) | |
| 872 </pre></td></tr></table> | |
| 873 | |
| 874 <p>for all modules and compilation units together. | |
| 875 </p> | |
| 876 </li><li> | |
| 877 To ensure that the final linking will use <code>@LIBINTL@</code> or | |
| 878 <code>@LTLIBINTL@</code> as a library, add the following to | |
| 879 ‘<tt>Makefile.am</tt>’: | |
| 880 | |
| 881 <table><tr><td> </td><td><pre class="example"><program>_LDADD = @LIBINTL@ | |
| 882 </pre></td></tr></table> | |
| 883 | |
| 884 <p>for each specific program, or | |
| 885 </p> | |
| 886 <table><tr><td> </td><td><pre class="example">LDADD = @LIBINTL@ | |
| 887 </pre></td></tr></table> | |
| 888 | |
| 889 <p>for all programs together. Remember that when you use <code>libtool</code> | |
| 890 to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ | |
| 891 for that program. | |
| 892 </p> | |
| 893 </li></ol> | |
| 894 | |
| 895 | |
| 896 <a name="lib_002fgettext_002eh"></a> | |
| 897 <a name="SEC246"></a> | |
| 898 <h3 class="subsection"> <a href="gettext_toc.html#TOC239">13.4.12 ‘<tt>gettext.h</tt>’ in ‘<tt>lib/</tt>’</a> </h3> | |
| 899 | |
| 900 <p>Internationalization of packages, as provided by GNU <code>gettext</code>, is | |
| 901 optional. It can be turned off in two situations: | |
| 902 </p> | |
| 903 <ul> | |
| 904 <li> | |
| 905 When the installer has specified ‘<samp>./configure --disable-nls</samp>’. This | |
| 906 can be useful when small binaries are more important than features, for | |
| 907 example when building utilities for boot diskettes. It can also be useful | |
| 908 in order to get some specific C compiler warnings about code quality with | |
| 909 some older versions of GCC (older than 3.0). | |
| 910 | |
| 911 </li><li> | |
| 912 When the libintl.h header (with its associated libintl library, if any) is | |
| 913 not already installed on the system, it is preferable that the package builds | |
| 914 without internationalization support, rather than to give a compilation | |
| 915 error. | |
| 916 </li></ul> | |
| 917 | |
| 918 <p>A C preprocessor macro can be used to detect these two cases. Usually, | |
| 919 when <code>libintl.h</code> was found and not explicitly disabled, the | |
| 920 <code>ENABLE_NLS</code> macro will be defined to 1 in the autoconf generated | |
| 921 configuration file (usually called ‘<tt>config.h</tt>’). In the two negative | |
| 922 situations, however, this macro will not be defined, thus it will evaluate | |
| 923 to 0 in C preprocessor expressions. | |
| 924 </p> | |
| 925 <a name="IDX1104"></a> | |
| 926 <p>‘<tt>gettext.h</tt>’ is a convenience header file for conditional use of | |
| 927 ‘<tt><libintl.h></tt>’, depending on the <code>ENABLE_NLS</code> macro. If | |
| 928 <code>ENABLE_NLS</code> is set, it includes ‘<tt><libintl.h></tt>’; otherwise it | |
| 929 defines no-op substitutes for the libintl.h functions. We recommend | |
| 930 the use of <code>"gettext.h"</code> over direct use of ‘<tt><libintl.h></tt>’, | |
| 931 so that portability to older systems is guaranteed and installers can | |
| 932 turn off internationalization if they want to. In the C code, you will | |
| 933 then write | |
| 934 </p> | |
| 935 <table><tr><td> </td><td><pre class="example">#include "gettext.h" | |
| 936 </pre></td></tr></table> | |
| 937 | |
| 938 <p>instead of | |
| 939 </p> | |
| 940 <table><tr><td> </td><td><pre class="example">#include <libintl.h> | |
| 941 </pre></td></tr></table> | |
| 942 | |
| 943 <p>The location of <code>gettext.h</code> is usually in a directory containing | |
| 944 auxiliary include files. In many GNU packages, there is a directory | |
| 945 ‘<tt>lib/</tt>’ containing helper functions; ‘<tt>gettext.h</tt>’ fits there. | |
| 946 In other packages, it can go into the ‘<tt>src</tt>’ directory. | |
| 947 </p> | |
| 948 <p>Do not install the <code>gettext.h</code> file in public locations. Every | |
| 949 package that needs it should contain a copy of it on its own. | |
| 950 </p> | |
| 951 | |
| 952 <a name="autoconf-macros"></a> | |
| 953 <a name="SEC247"></a> | |
| 954 <h2 class="section"> <a href="gettext_toc.html#TOC240">13.5 Autoconf macros for use in ‘<tt>configure.ac</tt>’</a> </h2> | |
| 955 | |
| 956 <p>GNU <code>gettext</code> installs macros for use in a package's | |
| 957 ‘<tt>configure.ac</tt>’ or ‘<tt>configure.in</tt>’. | |
| 958 See <a href="../autoconf/index.html#Top">(autoconf)Top</a> section `Introduction' in <cite>The Autoconf Manual</cite>. | |
| 959 The primary macro is, of course, <code>AM_GNU_GETTEXT</code>. | |
| 960 </p> | |
| 961 | |
| 962 | |
| 963 <a name="AM_005fGNU_005fGETTEXT"></a> | |
| 964 <a name="SEC248"></a> | |
| 965 <h3 class="subsection"> <a href="gettext_toc.html#TOC241">13.5.1 AM_GNU_GETTEXT in ‘<tt>gettext.m4</tt>’</a> </h3> | |
| 966 | |
| 967 <p>The <code>AM_GNU_GETTEXT</code> macro tests for the presence of the GNU gettext | |
| 968 function family in either the C library or a separate <code>libintl</code> | |
| 969 library (shared or static libraries are both supported). It also invokes | |
| 970 <code>AM_PO_SUBDIRS</code>, thus preparing the ‘<tt>po/</tt>’ directories of the | |
| 971 package for building. | |
| 972 </p> | |
| 973 <p><code>AM_GNU_GETTEXT</code> accepts up to two optional arguments. The general | |
| 974 syntax is | |
| 975 </p> | |
| 976 <table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT([<var>intlsymbol</var>], [<var>needsymbol</var>]) | |
| 977 </pre></td></tr></table> | |
| 978 | |
| 979 <p><var>intlsymbol</var> should always be ‘<samp>external</samp>’. | |
| 980 </p> | |
| 981 <p>If <var>needsymbol</var> is specified and is ‘<samp>need-ngettext</samp>’, then GNU | |
| 982 gettext implementations (in libc or libintl) without the <code>ngettext()</code> | |
| 983 function will be ignored. If <var>needsymbol</var> is specified and is | |
| 984 ‘<samp>need-formatstring-macros</samp>’, then GNU gettext implementations that don't | |
| 985 support the ISO C 99 ‘<tt><inttypes.h></tt>’ formatstring macros will be ignored. | |
| 986 Only one <var>needsymbol</var> can be specified. These requirements can also be | |
| 987 specified by using the macro <code>AM_GNU_GETTEXT_NEED</code> elsewhere. To specify | |
| 988 more than one requirement, just specify the strongest one among them, or | |
| 989 invoke the <code>AM_GNU_GETTEXT_NEED</code> macro several times. The hierarchy | |
| 990 among the various alternatives is as follows: ‘<samp>need-formatstring-macros</samp>’ | |
| 991 implies ‘<samp>need-ngettext</samp>’. | |
| 992 </p> | |
| 993 <p>The <code>AM_GNU_GETTEXT</code> macro determines whether GNU gettext is | |
| 994 available and should be used. If so, it sets the <code>USE_NLS</code> variable | |
| 995 to ‘<samp>yes</samp>’; it defines <code>ENABLE_NLS</code> to 1 in the autoconf | |
| 996 generated configuration file (usually called ‘<tt>config.h</tt>’); it sets | |
| 997 the variables <code>LIBINTL</code> and <code>LTLIBINTL</code> to the linker options | |
| 998 for use in a Makefile (<code>LIBINTL</code> for use without libtool, | |
| 999 <code>LTLIBINTL</code> for use with libtool); it adds an ‘<samp>-I</samp>’ option to | |
| 1000 <code>CPPFLAGS</code> if necessary. In the negative case, it sets | |
| 1001 <code>USE_NLS</code> to ‘<samp>no</samp>’; it sets <code>LIBINTL</code> and <code>LTLIBINTL</code> | |
| 1002 to empty and doesn't change <code>CPPFLAGS</code>. | |
| 1003 </p> | |
| 1004 <p>The complexities that <code>AM_GNU_GETTEXT</code> deals with are the following: | |
| 1005 </p> | |
| 1006 <ul> | |
| 1007 <li> | |
| 1008 <a name="IDX1105"></a> | |
| 1009 Some operating systems have <code>gettext</code> in the C library, for example | |
| 1010 glibc. Some have it in a separate library <code>libintl</code>. GNU <code>libintl</code> | |
| 1011 might have been installed as part of the GNU <code>gettext</code> package. | |
| 1012 | |
| 1013 </li><li> | |
| 1014 GNU <code>libintl</code>, if installed, is not necessarily already in the search | |
| 1015 path (<code>CPPFLAGS</code> for the include file search path, <code>LDFLAGS</code> for | |
| 1016 the library search path). | |
| 1017 | |
| 1018 </li><li> | |
| 1019 Except for glibc and the Solaris 11 libc, the operating system's native | |
| 1020 <code>gettext</code> cannot exploit the GNU mo files, doesn't have the | |
| 1021 necessary locale dependency features, and cannot convert messages from | |
| 1022 the catalog's text encoding to the user's locale encoding. | |
| 1023 | |
| 1024 </li><li> | |
| 1025 GNU <code>libintl</code>, if installed, is not necessarily already in the | |
| 1026 run time library search path. To avoid the need for setting an environment | |
| 1027 variable like <code>LD_LIBRARY_PATH</code>, the macro adds the appropriate | |
| 1028 run time search path options to the <code>LIBINTL</code> and <code>LTLIBINTL</code> | |
| 1029 variables. This works on most systems, but not on some operating systems | |
| 1030 with limited shared library support, like SCO. | |
| 1031 | |
| 1032 </li><li> | |
| 1033 GNU <code>libintl</code> relies on POSIX/XSI <code>iconv</code>. The macro checks for | |
| 1034 linker options needed to use iconv and appends them to the <code>LIBINTL</code> | |
| 1035 and <code>LTLIBINTL</code> variables. | |
| 1036 </li></ul> | |
| 1037 | |
| 1038 <p>Additionally, the <code>AM_GNU_GETTEXT</code> macro sets two variables, for | |
| 1039 convenience. Both are derived from the <code>--localedir</code> configure | |
| 1040 option. They are correct even on native Windows, where directories | |
| 1041 frequently contain backslashes. | |
| 1042 </p><dl compact="compact"> | |
| 1043 <dt> <code>localedir_c</code></dt> | |
| 1044 <dd><p>This is the value of <code>localedir</code>, in C syntax. This variable is | |
| 1045 meant to be substituted into C or C++ code through | |
| 1046 <code>AC_CONFIG_FILES</code>. | |
| 1047 </p> | |
| 1048 </dd> | |
| 1049 <dt> <code>localedir_c_make</code></dt> | |
| 1050 <dd><p>This is the value of <code>localedir</code>, in C syntax, escaped for use in | |
| 1051 a <code>Makefile</code>. This variable is meant to be used in Makefiles, | |
| 1052 for example for defining a C macro named <code>LOCALEDIR</code>: | |
| 1053 </p><table><tr><td> </td><td><pre class="smallexample">AM_CPPFLAGS = ... -DLOCALEDIR=$(localedir_c_make) ... | |
| 1054 </pre></td></tr></table> | |
| 1055 </dd> | |
| 1056 </dl> | |
| 1057 | |
| 1058 | |
| 1059 <a name="AM_005fGNU_005fGETTEXT_005fVERSION"></a> | |
| 1060 <a name="SEC249"></a> | |
| 1061 <h3 class="subsection"> <a href="gettext_toc.html#TOC242">13.5.2 AM_GNU_GETTEXT_VERSION in ‘<tt>gettext.m4</tt>’</a> </h3> | |
| 1062 | |
| 1063 <p>The <code>AM_GNU_GETTEXT_VERSION</code> macro declares the version number of | |
| 1064 the GNU gettext infrastructure that is used by the package. | |
| 1065 </p> | |
| 1066 <p>The use of this macro is optional; only the <code>autopoint</code> program makes | |
| 1067 use of it (see section <a href="#SEC254">Integrating with Version Control Systems</a>). | |
| 1068 </p> | |
| 1069 | |
| 1070 <a name="AM_005fGNU_005fGETTEXT_005fNEED"></a> | |
| 1071 <a name="SEC250"></a> | |
| 1072 <h3 class="subsection"> <a href="gettext_toc.html#TOC243">13.5.3 AM_GNU_GETTEXT_NEED in ‘<tt>gettext.m4</tt>’</a> </h3> | |
| 1073 | |
| 1074 <p>The <code>AM_GNU_GETTEXT_NEED</code> macro declares a constraint regarding the | |
| 1075 GNU gettext implementation. The syntax is | |
| 1076 </p> | |
| 1077 <table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT_NEED([<var>needsymbol</var>]) | |
| 1078 </pre></td></tr></table> | |
| 1079 | |
| 1080 <p>If <var>needsymbol</var> is ‘<samp>need-ngettext</samp>’, then GNU gettext implementations | |
| 1081 (in libc or libintl) without the <code>ngettext()</code> function will be ignored. | |
| 1082 If <var>needsymbol</var> is ‘<samp>need-formatstring-macros</samp>’, then GNU gettext | |
| 1083 implementations that don't support the ISO C 99 ‘<tt><inttypes.h></tt>’ | |
| 1084 formatstring macros will be ignored. | |
| 1085 </p> | |
| 1086 <p>The optional second argument of <code>AM_GNU_GETTEXT</code> is also taken into | |
| 1087 account. | |
| 1088 </p> | |
| 1089 <p>The <code>AM_GNU_GETTEXT_NEED</code> invocations can occur before or after | |
| 1090 the <code>AM_GNU_GETTEXT</code> invocation; the order doesn't matter. | |
| 1091 </p> | |
| 1092 | |
| 1093 <a name="AM_005fPO_005fSUBDIRS"></a> | |
| 1094 <a name="SEC251"></a> | |
| 1095 <h3 class="subsection"> <a href="gettext_toc.html#TOC244">13.5.4 AM_PO_SUBDIRS in ‘<tt>po.m4</tt>’</a> </h3> | |
| 1096 | |
| 1097 <p>The <code>AM_PO_SUBDIRS</code> macro prepares the ‘<tt>po/</tt>’ directories of the | |
| 1098 package for building. This macro should be used in internationalized | |
| 1099 programs written in other programming languages than C, C++, Objective C, | |
| 1100 for example <code>sh</code>, <code>Python</code>, <code>Lisp</code>. See <a href="gettext_15.html#SEC263">Other Programming Languages</a> for a list of programming languages that support localization | |
| 1101 through PO files. | |
| 1102 </p> | |
| 1103 <p>The <code>AM_PO_SUBDIRS</code> macro determines whether internationalization | |
| 1104 should be used. If so, it sets the <code>USE_NLS</code> variable to ‘<samp>yes</samp>’, | |
| 1105 otherwise to ‘<samp>no</samp>’. It also determines the right values for Makefile | |
| 1106 variables in each ‘<tt>po/</tt>’ directory. | |
| 1107 </p> | |
| 1108 | |
| 1109 <a name="AM_005fXGETTEXT_005fOPTION"></a> | |
| 1110 <a name="SEC252"></a> | |
| 1111 <h3 class="subsection"> <a href="gettext_toc.html#TOC245">13.5.5 AM_XGETTEXT_OPTION in ‘<tt>po.m4</tt>’</a> </h3> | |
| 1112 | |
| 1113 <p>The <code>AM_XGETTEXT_OPTION</code> macro registers a command-line option to be | |
| 1114 used in the invocations of <code>xgettext</code> in the ‘<tt>po/</tt>’ directories | |
| 1115 of the package. | |
| 1116 </p> | |
| 1117 <p>For example, if you have a source file that defines a function | |
| 1118 ‘<samp>error_at_line</samp>’ whose fifth argument is a format string, you can use | |
| 1119 </p><table><tr><td> </td><td><pre class="example">AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format]) | |
| 1120 </pre></td></tr></table> | |
| 1121 <p>to instruct <code>xgettext</code> to mark all translatable strings in ‘<samp>gettext</samp>’ | |
| 1122 invocations that occur as fifth argument to this function as ‘<samp>c-format</samp>’. | |
| 1123 </p> | |
| 1124 <p>See <a href="gettext_5.html#SEC36">Invoking the <code>xgettext</code> Program</a> for the list of options that <code>xgettext</code> | |
| 1125 accepts. | |
| 1126 </p> | |
| 1127 <p>The use of this macro is an alternative to the use of the | |
| 1128 ‘<samp>XGETTEXT_OPTIONS</samp>’ variable in ‘<tt>po/Makevars</tt>’. | |
| 1129 </p> | |
| 1130 | |
| 1131 <a name="AM_005fICONV"></a> | |
| 1132 <a name="SEC253"></a> | |
| 1133 <h3 class="subsection"> <a href="gettext_toc.html#TOC246">13.5.6 AM_ICONV in ‘<tt>iconv.m4</tt>’</a> </h3> | |
| 1134 | |
| 1135 <p>The <code>AM_ICONV</code> macro tests for the presence of the POSIX/XSI | |
| 1136 <code>iconv</code> function family in either the C library or a separate | |
| 1137 <code>libiconv</code> library. If found, it sets the <code>am_cv_func_iconv</code> | |
| 1138 variable to ‘<samp>yes</samp>’; it defines <code>HAVE_ICONV</code> to 1 in the autoconf | |
| 1139 generated configuration file (usually called ‘<tt>config.h</tt>’); it defines | |
| 1140 <code>ICONV_CONST</code> to ‘<samp>const</samp>’ or to empty, depending on whether the | |
| 1141 second argument of <code>iconv()</code> is of type ‘<samp>const char **</samp>’ or | |
| 1142 ‘<samp>char **</samp>’; it sets the variables <code>LIBICONV</code> and | |
| 1143 <code>LTLIBICONV</code> to the linker options for use in a Makefile | |
| 1144 (<code>LIBICONV</code> for use without libtool, <code>LTLIBICONV</code> for use with | |
| 1145 libtool); it adds an ‘<samp>-I</samp>’ option to <code>CPPFLAGS</code> if | |
| 1146 necessary. If not found, it sets <code>LIBICONV</code> and <code>LTLIBICONV</code> to | |
| 1147 empty and doesn't change <code>CPPFLAGS</code>. | |
| 1148 </p> | |
| 1149 <p>The complexities that <code>AM_ICONV</code> deals with are the following: | |
| 1150 </p> | |
| 1151 <ul> | |
| 1152 <li> | |
| 1153 <a name="IDX1106"></a> | |
| 1154 Some operating systems have <code>iconv</code> in the C library, for example | |
| 1155 glibc. Some have it in a separate library <code>libiconv</code>, for example | |
| 1156 OSF/1 or FreeBSD. Regardless of the operating system, GNU <code>libiconv</code> | |
| 1157 might have been installed. In that case, it should be used instead of the | |
| 1158 operating system's native <code>iconv</code>. | |
| 1159 | |
| 1160 </li><li> | |
| 1161 GNU <code>libiconv</code>, if installed, is not necessarily already in the search | |
| 1162 path (<code>CPPFLAGS</code> for the include file search path, <code>LDFLAGS</code> for | |
| 1163 the library search path). | |
| 1164 | |
| 1165 </li><li> | |
| 1166 GNU <code>libiconv</code> is binary incompatible with some operating system's | |
| 1167 native <code>iconv</code>, for example on FreeBSD. Use of an ‘<tt>iconv.h</tt>’ | |
| 1168 and ‘<tt>libiconv.so</tt>’ that don't fit together would produce program | |
| 1169 crashes. | |
| 1170 | |
| 1171 </li><li> | |
| 1172 GNU <code>libiconv</code>, if installed, is not necessarily already in the | |
| 1173 run time library search path. To avoid the need for setting an environment | |
| 1174 variable like <code>LD_LIBRARY_PATH</code>, the macro adds the appropriate | |
| 1175 run time search path options to the <code>LIBICONV</code> variable. This works | |
| 1176 on most systems, but not on some operating systems with limited shared | |
| 1177 library support, like SCO. | |
| 1178 </li></ul> | |
| 1179 | |
| 1180 <p>‘<tt>iconv.m4</tt>’ is distributed with the GNU gettext package because | |
| 1181 ‘<tt>gettext.m4</tt>’ relies on it. | |
| 1182 </p> | |
| 1183 | |
| 1184 <a name="Version-Control-Issues"></a> | |
| 1185 <a name="SEC254"></a> | |
| 1186 <h2 class="section"> <a href="gettext_toc.html#TOC247">13.6 Integrating with Version Control Systems</a> </h2> | |
| 1187 | |
| 1188 <p>Many projects use version control systems for distributed development | |
| 1189 and source backup. This section gives some advice how to manage the | |
| 1190 uses of <code>gettextize</code>, <code>autopoint</code> and <code>autoconf</code> on | |
| 1191 version controlled files. | |
| 1192 </p> | |
| 1193 | |
| 1194 | |
| 1195 <a name="Distributed-Development"></a> | |
| 1196 <a name="SEC255"></a> | |
| 1197 <h3 class="subsection"> <a href="gettext_toc.html#TOC248">13.6.1 Avoiding version mismatch in distributed development</a> </h3> | |
| 1198 | |
| 1199 <p>In a project development with multiple developers, there should be a | |
| 1200 single developer who occasionally - when there is desire to upgrade to | |
| 1201 a new <code>gettext</code> version - runs <code>gettextize</code> and performs the | |
| 1202 changes listed in <a href="#SEC234">Files You Must Create or Alter</a>, and then commits his changes | |
| 1203 to the repository. | |
| 1204 </p> | |
| 1205 <p>It is highly recommended that all developers on a project use the same | |
| 1206 version of GNU <code>gettext</code> in the package. In other words, if a | |
| 1207 developer runs <code>gettextize</code>, he should go the whole way, make the | |
| 1208 necessary remaining changes and commit his changes to the repository. | |
| 1209 Otherwise the following damages will likely occur: | |
| 1210 </p> | |
| 1211 <ul> | |
| 1212 <li> | |
| 1213 Apparent version mismatch between developers. Since some <code>gettext</code> | |
| 1214 specific portions in ‘<tt>configure.ac</tt>’, ‘<tt>configure.in</tt>’ and | |
| 1215 <code>Makefile.am</code>, <code>Makefile.in</code> files depend on the <code>gettext</code> | |
| 1216 version, the use of infrastructure files belonging to different | |
| 1217 <code>gettext</code> versions can easily lead to build errors. | |
| 1218 | |
| 1219 </li><li> | |
| 1220 Hidden version mismatch. Such version mismatch can also lead to | |
| 1221 malfunctioning of the package, that may be undiscovered by the developers. | |
| 1222 The worst case of hidden version mismatch is that internationalization | |
| 1223 of the package doesn't work at all. | |
| 1224 | |
| 1225 </li><li> | |
| 1226 Release risks. All developers implicitly perform constant testing on | |
| 1227 a package. This is important in the days and weeks before a release. | |
| 1228 If the guy who makes the release tar files uses a different version | |
| 1229 of GNU <code>gettext</code> than the other developers, the distribution will | |
| 1230 be less well tested than if all had been using the same <code>gettext</code> | |
| 1231 version. For example, it is possible that a platform specific bug goes | |
| 1232 undiscovered due to this constellation. | |
| 1233 </li></ul> | |
| 1234 | |
| 1235 | |
| 1236 <a name="Files-under-Version-Control"></a> | |
| 1237 <a name="SEC256"></a> | |
| 1238 <h3 class="subsection"> <a href="gettext_toc.html#TOC249">13.6.2 Files to put under version control</a> </h3> | |
| 1239 | |
| 1240 <p>There are basically three ways to deal with generated files in the | |
| 1241 context of a version controlled repository, such as ‘<tt>configure</tt>’ | |
| 1242 generated from ‘<tt>configure.ac</tt>’, <code><var>parser</var>.c</code> generated | |
| 1243 from <code><var>parser</var>.y</code>, or <code>po/Makefile.in.in</code> autoinstalled | |
| 1244 by <code>gettextize</code> or <code>autopoint</code>. | |
| 1245 </p> | |
| 1246 <ol> | |
| 1247 <li> | |
| 1248 All generated files are always committed into the repository. | |
| 1249 | |
| 1250 </li><li> | |
| 1251 All generated files are committed into the repository occasionally, | |
| 1252 for example each time a release is made. | |
| 1253 | |
| 1254 </li><li> | |
| 1255 Generated files are never committed into the repository. | |
| 1256 </li></ol> | |
| 1257 | |
| 1258 <p>Each of these three approaches has different advantages and drawbacks. | |
| 1259 </p> | |
| 1260 <ol> | |
| 1261 <li> | |
| 1262 The advantage is that anyone can check out the source at any moment and | |
| 1263 gets a working build. The drawbacks are: 1a. It requires some frequent | |
| 1264 "push" actions by the maintainers. 1b. The repository grows in size | |
| 1265 quite fast. | |
| 1266 | |
| 1267 </li><li> | |
| 1268 The advantage is that anyone can check out the source, and the usual | |
| 1269 "./configure; make" will work. The drawbacks are: 2a. The one who | |
| 1270 checks out the repository needs tools like GNU <code>automake</code>, GNU | |
| 1271 <code>autoconf</code>, GNU <code>m4</code> installed in his PATH; sometimes he | |
| 1272 even needs particular versions of them. 2b. When a release is made | |
| 1273 and a commit is made on the generated files, the other developers get | |
| 1274 conflicts on the generated files when merging the local work back to | |
| 1275 the repository. Although these conflicts are easy to resolve, they | |
| 1276 are annoying. | |
| 1277 | |
| 1278 </li><li> | |
| 1279 The advantage is less work for the maintainers. The drawback is that | |
| 1280 anyone who checks out the source not only needs tools like GNU | |
| 1281 <code>automake</code>, GNU <code>autoconf</code>, GNU <code>m4</code> installed in his | |
| 1282 PATH, but also that he needs to perform a package specific pre-build | |
| 1283 step before being able to "./configure; make". | |
| 1284 </li></ol> | |
| 1285 | |
| 1286 <p>For the first and second approach, all files modified or brought in | |
| 1287 by the occasional <code>gettextize</code> invocation and update should be | |
| 1288 committed into the repository. | |
| 1289 </p> | |
| 1290 <p>For the third approach, the maintainer can omit from the repository | |
| 1291 all the files that <code>gettextize</code> mentions as "copy". Instead, he | |
| 1292 adds to the ‘<tt>configure.ac</tt>’ or ‘<tt>configure.in</tt>’ a line of the | |
| 1293 form | |
| 1294 </p> | |
| 1295 <table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT_VERSION(0.22.4) | |
| 1296 </pre></td></tr></table> | |
| 1297 | |
| 1298 <p>and adds to the package's pre-build script an invocation of | |
| 1299 ‘<samp>autopoint</samp>’. For everyone who checks out the source, this | |
| 1300 <code>autopoint</code> invocation will copy into the right place the | |
| 1301 <code>gettext</code> infrastructure files that have been omitted from the repository. | |
| 1302 </p> | |
| 1303 <p>The version number used as argument to <code>AM_GNU_GETTEXT_VERSION</code> is | |
| 1304 the version of the <code>gettext</code> infrastructure that the package wants | |
| 1305 to use. It is also the minimum version number of the ‘<samp>autopoint</samp>’ | |
| 1306 program. So, if you write <code>AM_GNU_GETTEXT_VERSION(0.11.5)</code> then the | |
| 1307 developers can have any version >= 0.11.5 installed; the package will work | |
| 1308 with the 0.11.5 infrastructure in all developers' builds. When the | |
| 1309 maintainer then runs gettextize from, say, version 0.12.1 on the package, | |
| 1310 the occurrence of <code>AM_GNU_GETTEXT_VERSION(0.11.5)</code> will be changed | |
| 1311 into <code>AM_GNU_GETTEXT_VERSION(0.12.1)</code>, and all other developers that | |
| 1312 use the CVS will henceforth need to have GNU <code>gettext</code> 0.12.1 or newer | |
| 1313 installed. | |
| 1314 </p> | |
| 1315 | |
| 1316 <a name="Translations-under-Version-Control"></a> | |
| 1317 <a name="SEC257"></a> | |
| 1318 <h3 class="subsection"> <a href="gettext_toc.html#TOC250">13.6.3 Put PO Files under Version Control</a> </h3> | |
| 1319 | |
| 1320 <p>Since translations are valuable assets as well as the source code, it | |
| 1321 would make sense to put them under version control. The GNU gettext | |
| 1322 infrastructure supports two ways to deal with translations in the | |
| 1323 context of a version controlled repository. | |
| 1324 </p> | |
| 1325 <ol> | |
| 1326 <li> | |
| 1327 Both POT file and PO files are committed into the repository. | |
| 1328 | |
| 1329 </li><li> | |
| 1330 Only PO files are committed into the repository. | |
| 1331 | |
| 1332 </li></ol> | |
| 1333 | |
| 1334 <p>If a POT file is absent when building, it will be generated by | |
| 1335 scanning the source files with <code>xgettext</code>, and then the PO files | |
| 1336 are regenerated as a dependency. On the other hand, some maintainers | |
| 1337 want to keep the POT file unchanged during the development phase. So, | |
| 1338 even if a POT file is present and older than the source code, it won't | |
| 1339 be updated automatically. You can manually update it with <code>make | |
| 1340 $(DOMAIN).pot-update</code>, and commit it at certain point. | |
| 1341 </p> | |
| 1342 <p>Special advices for particular version control systems: | |
| 1343 </p> | |
| 1344 <ul> | |
| 1345 <li> | |
| 1346 Recent version control systems, Git for instance, ignore file's | |
| 1347 timestamp. In that case, PO files can be accidentally updated even if | |
| 1348 a POT file is not updated. To prevent this, you can set | |
| 1349 ‘<samp>PO_DEPENDS_ON_POT</samp>’ variable to <code>no</code> in the ‘<tt>Makevars</tt>’ | |
| 1350 file and do <code>make update-po</code> manually. | |
| 1351 | |
| 1352 </li><li> | |
| 1353 Location comments such as <code>#: lib/error.c:116</code> are sometimes | |
| 1354 annoying, since these comments are volatile and may introduce unwanted | |
| 1355 change to the working copy when building. To mitigate this, you can | |
| 1356 decide to omit those comments from the PO files in the repository. | |
| 1357 | |
| 1358 <p>This is possible with the <code>--no-location</code> option of the | |
| 1359 <code>msgmerge</code> command <a name="DOCF6" href="gettext_fot.html#FOOT6">(6)</a>. The drawback is | |
| 1360 that, if the location information is needed, translators have to | |
| 1361 recover the location comments by running <code>msgmerge</code> again. | |
| 1362 </p> | |
| 1363 </li></ul> | |
| 1364 | |
| 1365 | |
| 1366 <a name="autopoint-Invocation"></a> | |
| 1367 <a name="SEC258"></a> | |
| 1368 <h3 class="subsection"> <a href="gettext_toc.html#TOC251">13.6.4 Invoking the <code>autopoint</code> Program</a> </h3> | |
| 1369 | |
| 1370 | |
| 1371 <table><tr><td> </td><td><pre class="example">autopoint [<var>option</var>]... | |
| 1372 </pre></td></tr></table> | |
| 1373 | |
| 1374 <p>The <code>autopoint</code> program copies standard gettext infrastructure files | |
| 1375 into a source package. It extracts from a macro call of the form | |
| 1376 <code>AM_GNU_GETTEXT_VERSION(<var>version</var>)</code>, found in the package's | |
| 1377 ‘<tt>configure.in</tt>’ or ‘<tt>configure.ac</tt>’ file, the gettext version | |
| 1378 used by the package, and copies the infrastructure files belonging to | |
| 1379 this version into the package. | |
| 1380 </p> | |
| 1381 <p>To extract the latest available infrastructure which satisfies a version | |
| 1382 requirement, then you can use the form | |
| 1383 <code>AM_GNU_GETTEXT_REQUIRE_VERSION(<var>version</var>)</code> instead. For | |
| 1384 example, if gettext 0.22.4 is installed on your system | |
| 1385 and <code>0.19.1</code> is requested, then the infrastructure files of version | |
| 1386 0.22.4 will be copied into a source package. | |
| 1387 </p> | |
| 1388 | |
| 1389 <a name="SEC259"></a> | |
| 1390 <h4 class="subsubsection"> <a href="gettext_toc.html#TOC252">13.6.4.1 Options</a> </h4> | |
| 1391 | |
| 1392 <dl compact="compact"> | |
| 1393 <dt> ‘<samp>-f</samp>’</dt> | |
| 1394 <dt> ‘<samp>--force</samp>’</dt> | |
| 1395 <dd><a name="IDX1107"></a> | |
| 1396 <a name="IDX1108"></a> | |
| 1397 <p>Force overwriting of files that already exist. | |
| 1398 </p> | |
| 1399 </dd> | |
| 1400 <dt> ‘<samp>-n</samp>’</dt> | |
| 1401 <dt> ‘<samp>--dry-run</samp>’</dt> | |
| 1402 <dd><a name="IDX1109"></a> | |
| 1403 <a name="IDX1110"></a> | |
| 1404 <p>Print modifications but don't perform them. All file copying actions that | |
| 1405 <code>autopoint</code> would normally execute are inhibited and instead only | |
| 1406 listed on standard output. | |
| 1407 </p> | |
| 1408 </dd> | |
| 1409 </dl> | |
| 1410 | |
| 1411 | |
| 1412 <a name="SEC260"></a> | |
| 1413 <h4 class="subsubsection"> <a href="gettext_toc.html#TOC253">13.6.4.2 Informative output</a> </h4> | |
| 1414 | |
| 1415 <dl compact="compact"> | |
| 1416 <dt> ‘<samp>--help</samp>’</dt> | |
| 1417 <dd><a name="IDX1111"></a> | |
| 1418 <p>Display this help and exit. | |
| 1419 </p> | |
| 1420 </dd> | |
| 1421 <dt> ‘<samp>--version</samp>’</dt> | |
| 1422 <dd><a name="IDX1112"></a> | |
| 1423 <p>Output version information and exit. | |
| 1424 </p> | |
| 1425 </dd> | |
| 1426 </dl> | |
| 1427 | |
| 1428 <p><code>autopoint</code> supports the GNU <code>gettext</code> versions from 0.10.35 | |
| 1429 to the current one, 0.22.4. In order to apply | |
| 1430 <code>autopoint</code> to a package using a <code>gettext</code> version newer than | |
| 1431 0.22.4, you need to install this same version of GNU | |
| 1432 <code>gettext</code> at least. | |
| 1433 </p> | |
| 1434 <p>In packages using GNU <code>automake</code>, an invocation of <code>autopoint</code> | |
| 1435 should be followed by invocations of <code>aclocal</code> and then <code>autoconf</code> | |
| 1436 and <code>autoheader</code>. The reason is that <code>autopoint</code> installs some | |
| 1437 autoconf macro files, which are used by <code>aclocal</code> to create | |
| 1438 ‘<tt>aclocal.m4</tt>’, and the latter is used by <code>autoconf</code> to create the | |
| 1439 package's ‘<tt>configure</tt>’ script and by <code>autoheader</code> to create the | |
| 1440 package's ‘<tt>config.h.in</tt>’ include file template. | |
| 1441 </p> | |
| 1442 <p>The name ‘<samp>autopoint</samp>’ is an abbreviation of ‘<samp>auto-po-intl-m4</samp>’; | |
| 1443 in earlier versions, the tool copied or updated mostly files in the ‘<tt>po</tt>’, | |
| 1444 ‘<tt>intl</tt>’, ‘<tt>m4</tt>’ directories. | |
| 1445 </p> | |
| 1446 | |
| 1447 <a name="Release-Management"></a> | |
| 1448 <a name="SEC261"></a> | |
| 1449 <h2 class="section"> <a href="gettext_toc.html#TOC254">13.7 Creating a Distribution Tarball</a> </h2> | |
| 1450 | |
| 1451 <p>In projects that use GNU <code>automake</code>, the usual commands for creating | |
| 1452 a distribution tarball, ‘<samp>make dist</samp>’ or ‘<samp>make distcheck</samp>’, | |
| 1453 automatically update the PO files as needed. | |
| 1454 </p> | |
| 1455 <p>If GNU <code>automake</code> is not used, the maintainer needs to perform this | |
| 1456 update before making a release: | |
| 1457 </p> | |
| 1458 <table><tr><td> </td><td><pre class="example">$ ./configure | |
| 1459 $ (cd po; make update-po) | |
| 1460 $ make distclean | |
| 1461 </pre></td></tr></table> | |
| 1462 | |
| 1463 | |
| 1464 <table cellpadding="1" cellspacing="1" border="0"> | |
| 1465 <tr><td valign="middle" align="left">[<a href="#SEC230" title="Beginning of this chapter or previous chapter"> << </a>]</td> | |
| 1466 <td valign="middle" align="left">[<a href="gettext_14.html#SEC262" title="Next chapter"> >> </a>]</td> | |
| 1467 <td valign="middle" align="left"> </td> | |
| 1468 <td valign="middle" align="left"> </td> | |
| 1469 <td valign="middle" align="left"> </td> | |
| 1470 <td valign="middle" align="left"> </td> | |
| 1471 <td valign="middle" align="left"> </td> | |
| 1472 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> | |
| 1473 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td> | |
| 1474 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td> | |
| 1475 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td> | |
| 1476 </tr></table> | |
| 1477 <p> | |
| 1478 <font size="-1"> | |
| 1479 This document was generated by <em>Bruno Haible</em> on <em>February, 21 2024</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>. | |
| 1480 </font> | |
| 1481 <br> | |
| 1482 | |
| 1483 </p> | |
| 1484 </body> | |
| 1485 </html> |