release/src/router/gettext/gettext-tools/doc/gettextize.texi

   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:
   4
   5 @itemize @bullet
   6 @item
   7 As a wizard, when a package is modified to use GNU @code{gettext} for
   8 the first time.
   9
  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
  14
  15 This program performs the following tasks:
  16
  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}.
  22
  23 @item It performs as many of the tasks mentioned in the next section
  24 @ref{Adjusting Files} as can be performed automatically.
  25
  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.
  29
  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
  33
  34 It can be invoked as follows:
  35
  36 @pindex gettextize
  37 @cindex @code{gettextize} program, usage
  38 @example
  39 gettextize [ @var{option}@dots{} ] [ @var{directory} ]
  40 @end example
  41
  42 @noindent
  43 and accepts the following options:
  44
  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.
  55
  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.
  61
  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.
  70
  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.
  76
  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.
  84
  85 @item --help
  86 @opindex --help@r{, @code{gettextize} option}
  87 Display this help and exit.
  88
  89 @item --version
  90 @opindex --version@r{, @code{gettextize} option}
  91 Output version information and exit.
  92
  93 @end table
  94
  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.
  99
 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.
 103
 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.
 114
 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.
 123
 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.
 130
 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.
 135
 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
 141
 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}.
 150
 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.
 154
 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.
 162
 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.
 169
 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}.
 175
 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}.