transmision: upgrade 2.22 -> 2.31
[tomato.git] / release / src / router / gettext / gettext-tools / doc / gettextize.texi
blobc4dfd679ff83b10f0093c480db3e9852a84c85e1
1 The @code{gettextize} program is an interactive tool that helps the
2 maintainer of a package internationalized through GNU @code{gettext}.
3 It is used for two purposes:
5 @itemize @bullet
6 @item
7 As a wizard, when a package is modified to use GNU @code{gettext} for
8 the first time.
10 @item
11 As a migration tool, for upgrading the GNU @code{gettext} support in
12 a package from a previous to a newer version of GNU @code{gettext}.
13 @end itemize
15 This program performs the following tasks:
17 @itemize @bullet
18 @item
19 It copies into the package some files that are consistently and
20 identically needed in every package internationalized through
21 GNU @code{gettext}.
23 @item It performs as many of the tasks mentioned in the next section
24 @ref{Adjusting Files} as can be performed automatically.
26 @item It removes obsolete files and idioms used for previous GNU
27 @code{gettext} versions to the form recommended for the current GNU
28 @code{gettext} version.
30 @item It prints a summary of the tasks that ought to be done manually
31 and could not be done automatically by @code{gettextize}.
32 @end itemize
34 It can be invoked as follows:
36 @pindex gettextize
37 @cindex @code{gettextize} program, usage
38 @example
39 gettextize [ @var{option}@dots{} ] [ @var{directory} ]
40 @end example
42 @noindent
43 and accepts the following options:
45 @table @samp
46 @item -c
47 @itemx --copy
48 @opindex -c@r{, @code{gettextize} option}
49 @opindex --copy@r{, @code{gettextize} option}
50 Copy the needed files instead of making symbolic links.  Using links
51 would allow the package to always use the latest @code{gettext} code
52 available on the system, but it might disturb some mechanism the
53 maintainer is used to apply to the sources.  Because running
54 @code{gettextize} is easy there shouldn't be problems with using copies.
56 @item -f
57 @itemx --force
58 @opindex -f@r{, @code{gettextize} option}
59 @opindex --force@r{, @code{gettextize} option}
60 Force replacement of files which already exist.
62 @item --intl
63 @opindex --intl@r{, @code{gettextize} option}
64 Install the libintl sources in a subdirectory named @file{intl/}.
65 This libintl will be used to provide internationalization on systems
66 that don't have GNU libintl installed.  If this option is omitted,
67 the call to @code{AM_GNU_GETTEXT} in @file{configure.in} should read:
68 @samp{AM_GNU_GETTEXT([external])}, and internationalization will not
69 be enabled on systems lacking GNU gettext.
71 @item --no-changelog
72 @opindex --no-changelog@r{, @code{gettextize} option}
73 Don't update or create ChangeLog files.  By default, @code{gettextize}
74 logs all changes (file additions, modifications and removals) in a
75 file called @samp{ChangeLog} in each affected directory.
77 @item -n
78 @itemx --dry-run
79 @opindex -d@r{, @code{gettextize} option}
80 @opindex --dry-run@r{, @code{gettextize} option}
81 Print modifications but don't perform them.  All actions that
82 @code{gettextize} would normally execute are inhibited and instead only
83 listed on standard output.
85 @item --help
86 @opindex --help@r{, @code{gettextize} option}
87 Display this help and exit.
89 @item --version
90 @opindex --version@r{, @code{gettextize} option}
91 Output version information and exit.
93 @end table
95 If @var{directory} is given, this is the top level directory of a
96 package to prepare for using GNU @code{gettext}.  If not given, it
97 is assumed that the current directory is the top level directory of
98 such a package.
100 The program @code{gettextize} provides the following files.  However,
101 no existing file will be replaced unless the option @code{--force}
102 (@code{-f}) is specified.
104 @enumerate
105 @item
106 The @file{ABOUT-NLS} file is copied in the main directory of your package,
107 the one being at the top level.  This file gives the main indications
108 about how to install and use the Native Language Support features
109 of your program.  You might elect to use a more recent copy of this
110 @file{ABOUT-NLS} file than the one provided through @code{gettextize},
111 if you have one handy.  You may also fetch a more recent copy of file
112 @file{ABOUT-NLS} from Translation Project sites, and from most GNU
113 archive sites.
115 @item
116 A @file{po/} directory is created for eventually holding
117 all translation files, but initially only containing the file
118 @file{po/Makefile.in.in} from the GNU @code{gettext} distribution
119 (beware the double @samp{.in} in the file name) and a few auxiliary
120 files.  If the @file{po/} directory already exists, it will be preserved
121 along with the files it contains, and only @file{Makefile.in.in} and
122 the auxiliary files will be overwritten.
124 @item
125 Only if @samp{--intl} has been specified:
126 A @file{intl/} directory is created and filled with most of the files
127 originally in the @file{intl/} directory of the GNU @code{gettext}
128 distribution.  Also, if option @code{--force} (@code{-f}) is given,
129 the @file{intl/} directory is emptied first.
131 @item
132 The files @file{config.rpath} and @file{mkinstalldirs} are copied into
133 the directory containing configuration support files.  It is needed by
134 the @code{AM_GNU_GETTEXT} autoconf macro.
136 @item
137 Only if the project is using GNU @code{automake}:
138 A set of @code{autoconf} macro files is copied into the package's
139 @code{autoconf} macro repository, usually in a directory called @file{m4/}.
140 @end enumerate
142 If your site support symbolic links, @code{gettextize} will not
143 actually copy the files into your package, but establish symbolic
144 links instead.  This avoids duplicating the disk space needed in
145 all packages.  Merely using the @samp{-h} option while creating the
146 @code{tar} archive of your distribution will resolve each link by an
147 actual copy in the distribution archive.  So, to insist, you really
148 should use @samp{-h} option with @code{tar} within your @code{dist}
149 goal of your main @file{Makefile.in}.
151 Furthermore, @code{gettextize} will update all @file{Makefile.am} files
152 in each affected directory, as well as the top level @file{configure.in}
153 or @file{configure.ac} file.
155 It is interesting to understand that most new files for supporting
156 GNU @code{gettext} facilities in one package go in @file{intl/},
157 @file{po/} and @file{m4/} subdirectories.  One distinction between
158 @file{intl/} and the two other directories is that @file{intl/} is
159 meant to be completely identical in all packages using GNU @code{gettext},
160 while the other directories will mostly contain package dependent
161 files.
163 The @code{gettextize} program makes backup files for all files it
164 replaces or changes, and also write ChangeLog entries about these
165 changes.  This way, the careful maintainer can check after running
166 @code{gettextize} whether its changes are acceptable to him, and
167 possibly adjust them.  An exception to this rule is the @file{intl/}
168 directory, which is added or replaced or removed as a whole.
170 It is important to understand that @code{gettextize} can not do the
171 entire job of adapting a package for using GNU @code{gettext}.  The
172 amount of remaining work depends on whether the package uses GNU
173 @code{automake} or not.  But in any case, the maintainer should still
174 read the section @ref{Adjusting Files} after invoking @code{gettextize}.
176 It is also important to understand that @code{gettextize} is not part
177 of the GNU build system, in the sense that it should not be invoked
178 automatically, and not be invoked by someone who doesn't assume the
179 responsibilities of a package maintainer.  For the latter purpose, a
180 separate tool is provided, see @ref{autopoint Invocation}.