Rename msgexec to msgfilter.

New program msgexec.

5 files changed, 95 insertions, 16 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index c433c09..92b7a49 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,14 @@
 2001-12-08  Bruno Haible  <bruno@clisp.org>
 
+	* msgfilter.texi: Renamed from msgexec.texi.
+	* msgexec.texi: New file.
+	* gettext.texi (msgfilter Invocation): Renamed from msgexec Invocation.
+	(msgexec Invocation): New section.
+	(Manipulating): Update. Mention msgexec.
+	* Makefile.am (gettext_TEXINFOS): Add msgfilter.texi.
+
+2001-12-08  Bruno Haible  <bruno@clisp.org>
+
 	* msgen.texi: Refer to msginit as an alternative.
 
 2001-12-07  Bruno Haible  <bruno@clisp.org>
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f756029..78bd608 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -34,8 +34,8 @@ info_TEXINFOS = gettext.texi
 # List of texinfo sources @included by gettext.texi, excluding version.texi.
 gettext_TEXINFOS = \
   xgettext.texi msginit.texi msgmerge.texi msgcat.texi msgconv.texi \
-  msggrep.texi msgexec.texi msguniq.texi msgcomm.texi msgcmp.texi \
-  msgattrib.texi msgen.texi msgfmt.texi msgunfmt.texi \
+  msggrep.texi msgfilter.texi msguniq.texi msgcomm.texi msgcmp.texi \
+  msgattrib.texi msgen.texi msgexec.texi msgfmt.texi msgunfmt.texi \
   iso-639.texi iso-3166.texi
 
 EXTRA_DIST = iso-639.sed iso-3166.sed ISO_639 ISO_3166 nls.texi matrix.texi $(EXTRA_DIST_html) texi2html
diff --git a/doc/gettext.texi b/doc/gettext.texi
index 06218bd..3446242 100644
--- a/doc/gettext.texi
+++ b/doc/gettext.texi
@@ -155,12 +155,13 @@ Manipulating PO Files
 * msgcat Invocation::           Invoking the @code{msgcat} Program
 * msgconv Invocation::          Invoking the @code{msgconv} Program
 * msggrep Invocation::          Invoking the @code{msggrep} Program
-* msgexec Invocation::          Invoking the @code{msgexec} Program
+* msgfilter Invocation::        Invoking the @code{msgfilter} Program
 * msguniq Invocation::          Invoking the @code{msguniq} Program
 * msgcomm Invocation::          Invoking the @code{msgcomm} Program
 * msgcmp Invocation::           Invoking the @code{msgcmp} Program
 * msgattrib Invocation::        Invoking the @code{msgattrib} Program
 * msgen Invocation::            Invoking the @code{msgen} Program
+* msgexec Invocation::          Invoking the @code{msgexec} Program
 
 Producing Binary MO Files
 
@@ -2972,18 +2973,22 @@ When a translator wants to adjust some translation catalog for a special
 dialect or orthography - for example, German as written in Switzerland
 versus German as written in Germany -, she needs to apply some text
 processing to every message in the catalog.  The tool for doing this is
-@samp{msgexec}.
+@samp{msgfilter}.
 
-Another use of @code{msgexec} is to produce approximately the POT file for
+Another use of @code{msgfilter} is to produce approximately the POT file for
 which a given PO file was made.  This can be done through a filter command
-like @samp{msgexec sed -e d | sed -e '/^# /d'}.  Note that the original
+like @samp{msgfilter sed -e d | sed -e '/^# /d'}.  Note that the original
 POT file may have had different comments and different plural message counts,
 that's why it's better to use the original POT file if available.
 
+When a translator wants to check her translations, for example according
+to orthography rules or using a non-interactive spell checker, she can do
+so using the @samp{msgexec} program.
+
 When third party tools create PO or POT files, sometimes duplicates cannot
 be avoided.  But the GNU @code{gettext} tools give an error when they
 encounter duplicate msgids in the same file and in the same domain.
-To merge duplicates, the @code{msguniq} program can be used.
+To merge duplicates, the @samp{msguniq} program can be used.
 
 @samp{msgcomm} is a more general tool for keeping or throwing away
 duplicates, occurring in different files.
@@ -3001,12 +3006,13 @@ catalogs.  It copies each message's msgid to its msgstr.
 * msgcat Invocation::           Invoking the @code{msgcat} Program
 * msgconv Invocation::          Invoking the @code{msgconv} Program
 * msggrep Invocation::          Invoking the @code{msggrep} Program
-* msgexec Invocation::          Invoking the @code{msgexec} Program
+* msgfilter Invocation::        Invoking the @code{msgfilter} Program
 * msguniq Invocation::          Invoking the @code{msguniq} Program
 * msgcomm Invocation::          Invoking the @code{msgcomm} Program
 * msgcmp Invocation::           Invoking the @code{msgcmp} Program
 * msgattrib Invocation::        Invoking the @code{msgattrib} Program
 * msgen Invocation::            Invoking the @code{msgen} Program
+* msgexec Invocation::          Invoking the @code{msgexec} Program
 @end menu
 
 @node msgcat Invocation, msgconv Invocation, Manipulating, Manipulating
@@ -3019,17 +3025,17 @@ catalogs.  It copies each message's msgid to its msgstr.
 
 @include msgconv.texi
 
-@node msggrep Invocation, msgexec Invocation, msgconv Invocation, Manipulating
+@node msggrep Invocation, msgfilter Invocation, msgconv Invocation, Manipulating
 @section Invoking the @code{msggrep} Program
 
 @include msggrep.texi
 
-@node msgexec Invocation, msguniq Invocation, msggrep Invocation, Manipulating
-@section Invoking the @code{msgexec} Program
+@node msgfilter Invocation, msguniq Invocation, msggrep Invocation, Manipulating
+@section Invoking the @code{msgfilter} Program
 
-@include msgexec.texi
+@include msgfilter.texi
 
-@node msguniq Invocation, msgcomm Invocation, msgexec Invocation, Manipulating
+@node msguniq Invocation, msgcomm Invocation, msgfilter Invocation, Manipulating
 @section Invoking the @code{msguniq} Program
 
 @include msguniq.texi
@@ -3049,11 +3055,16 @@ catalogs.  It copies each message's msgid to its msgstr.
 
 @include msgattrib.texi
 
-@node msgen Invocation,  , msgattrib Invocation, Manipulating
+@node msgen Invocation, msgexec Invocation, msgattrib Invocation, Manipulating
 @section Invoking the @code{msgen} Program
 
 @include msgen.texi
 
+@node msgexec Invocation,  , msgen Invocation, Manipulating
+@section Invoking the @code{msgexec} Program
+
+@include msgexec.texi
+
 @node Binaries, Users, Manipulating, Top
 @chapter Producing Binary MO Files
 
diff --git a/doc/msgexec.texi b/doc/msgexec.texi
new file mode 100644
index 0000000..031c426
--- /dev/null
+++ b/doc/msgexec.texi
@@ -0,0 +1,59 @@
+@example
+msgexec [@var{option}] @var{command} [@var{command-option}]
+@end example
+
+The @code{msgexec} program applies a command to all translations of a
+translation catalog.
+The @var{command} can be any program that reads a translation from standard
+input.  It is invoked once for each translation.  Its output becomes
+msgexec's output.  @code{msgexec}'s return code is the maximum return code
+across all invocations.
+
+A special builtin command called @samp{0} outputs the translation, followed
+by a null byte.  The output of @samp{msgexec 0} is suitable as input for
+@samp{xargs -0}.
+
+During each @var{command} invocation, the environment variable
+@code{MSGEXEC_MSGID} is bound to the message's msgid, and the environment
+variable @code{MSGEXEC_LOCATION} is bound to the location in the PO file
+of the message.
+
+Note: It is your responsibility to ensure that the @var{command} can cope
+with input encoded in the translation catalog's encoding.  If the
+@var{command} wants input in a particular encoding, you can in a first step
+convert the translation catalog to that encoding using the @samp{msgconv}
+program, before invoking @samp{msgexec}.  If the @var{command} wants input
+in the locale's encoding, but you want to avoid the locale's encoding, then
+you can first convert the translation catalog to UTF-8 using the
+@samp{msgconv} program and then make @samp{msgexec} work in an UTF-8
+locale, by using the @code{LC_ALL} environment variable.
+
+@subsection Input file location
+
+@table @samp
+@item -i @var{inputfile}
+@itemx --input=@var{inputfile}
+Input PO file.
+
+@item -D @var{directory}
+@itemx --directory=@var{directory}
+Add @var{directory} to the list of directories.  Source files are
+searched relative to this list of directories.  The resulting @file{.po}
+file will be written relative to the current directory, though.
+
+@end table
+
+If no @var{inputfile} is given or if it is @samp{-}, standard input is read.
+
+@subsection Informative output
+
+@table @samp
+@item -h
+@itemx --help
+Display this help and exit.
+
+@item -V
+@itemx --version
+Output version information and exit.
+
+@end table
diff --git a/doc/msgfilter.texi b/doc/msgfilter.texi
index 2ced8d5..b6dc7bf 100644
--- a/doc/msgfilter.texi
+++ b/doc/msgfilter.texi
@@ -1,8 +1,8 @@
 @example
-msgexec [@var{option}] @var{filter} [@var{filter-option}]
+msgfilter [@var{option}] @var{filter} [@var{filter-option}]
 @end example
 
-The @code{msgexec} program applies a filter to all translations of a
+The @code{msgfilter} program applies a filter to all translations of a
 translation catalog.
 
 @subsection Input file location