csp2: CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext

annotate 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

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

Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_13.html @ 68:5028fdace37b